]>
Commit | Line | Data |
---|---|---|
1dc1ea18 DDO |
1 | NOTES FOR UNIX-LIKE PLATFORMS |
2 | ============================= | |
45632ee3 | 3 | |
1dc1ea18 DDO |
4 | For Unix/POSIX runtime systems on Windows, |
5 | please see [NOTES-Windows.txt](NOTES-Windows.txt). | |
45632ee3 | 6 | |
445bc808 RL |
7 | OpenSSL uses the compiler to link programs and shared libraries |
8 | --------------------------------------------------------------- | |
45632ee3 | 9 | |
445bc808 RL |
10 | OpenSSL's generated Makefile uses the C compiler command line to |
11 | link programs, shared libraries and dynamically loadable shared | |
12 | objects. Because of this, any linking option that's given to the | |
13 | configuration scripts MUST be in a form that the compiler can accept. | |
14 | This varies between systems, where some have compilers that accept | |
1dc1ea18 | 15 | linker flags directly, while others take them in `-Wl,` form. You need |
445bc808 | 16 | to read your compiler documentation to figure out what is acceptable, |
1dc1ea18 | 17 | and `ld(1)` to figure out what linker options are available. |
45632ee3 | 18 | |
445bc808 RL |
19 | Shared libraries and installation in non-default locations |
20 | ---------------------------------------------------------- | |
21 | ||
22 | Every Unix system has its own set of default locations for shared | |
1dc1ea18 | 23 | libraries, such as `/lib`, `/usr/lib` or possibly `/usr/local/lib`. If |
445bc808 | 24 | libraries are installed in non-default locations, dynamically linked |
2c879241 AP |
25 | binaries will not find them and therefore fail to run, unless they get |
26 | a bit of help from a defined runtime shared library search path. | |
445bc808 | 27 | |
1dc1ea18 | 28 | For OpenSSL's application (the `openssl` command), our configuration |
445bc808 | 29 | scripts do NOT generally set the runtime shared library search path for |
2c879241 | 30 | you. It's therefore advisable to set it explicitly when configuring, |
445bc808 RL |
31 | unless the libraries are to be installed in directories that you know |
32 | to be in the default list. | |
33 | ||
34 | Runtime shared library search paths are specified with different | |
35 | linking options depending on operating system and versions thereof, and | |
36 | are talked about differently in their respective documentation; | |
37 | variations of RPATH are the most usual (note: ELF systems have two such | |
38 | tags, more on that below). | |
39 | ||
40 | Possible options to set the runtime shared library search path include | |
41 | the following: | |
42 | ||
1dc1ea18 DDO |
43 | -Wl,-rpath,/whatever/path # Linux, *BSD, etc. |
44 | -R /whatever/path # Solaris | |
45 | -Wl,-R,/whatever/path # AIX (-bsvr4 is passed internally) | |
46 | -Wl,+b,/whatever/path # HP-UX | |
47 | -rpath /whatever/path # Tru64, IRIX | |
c3d76bb2 | 48 | |
445bc808 | 49 | OpenSSL's configuration scripts recognise all these options and pass |
2c879241 | 50 | them to the Makefile that they build. (In fact, all arguments starting |
1dc1ea18 | 51 | with `-Wl,` are recognised as linker options.) |
445bc808 RL |
52 | |
53 | Please do not use verbatim directories in your runtime shared library | |
54 | search path! Some OpenSSL config targets add an extra directory level | |
55 | for multilib installations. To help with that, the produced Makefile | |
56 | includes the variable LIBRPATH, which is a convenience variable to be | |
57 | used with the runtime shared library search path options, as shown in | |
58 | this example: | |
c3d76bb2 | 59 | |
16b0e0fc | 60 | $ ./Configure --prefix=/usr/local/ssl --openssldir=/usr/local/ssl \ |
445bc808 RL |
61 | '-Wl,-rpath,$(LIBRPATH)' |
62 | ||
63 | On modern ELF based systems, there are two runtime search paths tags to | |
1dc1ea18 | 64 | consider, `DT_RPATH` and `DT_RUNPATH`. Shared objects are searched for in |
445bc808 RL |
65 | this order: |
66 | ||
1dc1ea18 DDO |
67 | 1. Using directories specified in DT_RPATH, unless DT_RUNPATH is also set. |
68 | 2. Using the environment variable LD_LIBRARY_PATH | |
69 | 3. Using directories specified in DT_RUNPATH. | |
70 | 4. Using system shared object caches and default directories. | |
445bc808 | 71 | |
1dc1ea18 DDO |
72 | This means that the values in the environment variable `LD_LIBRARY_PATH` |
73 | won't matter if the library is found in the paths given by `DT_RPATH` | |
74 | (and `DT_RUNPATH` isn't set). | |
c3d76bb2 | 75 | |
1dc1ea18 | 76 | Exactly which of `DT_RPATH` or `DT_RUNPATH` is set by default appears to |
445bc808 | 77 | depend on the system. For example, according to documentation, |
1dc1ea18 DDO |
78 | `DT_RPATH` appears to be deprecated on Solaris in favor of `DT_RUNPATH`, |
79 | while on Debian GNU/Linux, either can be set, and `DT_RPATH` is the | |
445bc808 RL |
80 | default at the time of writing. |
81 | ||
82 | How to choose which runtime search path tag is to be set depends on | |
83 | your system, please refer to ld(1) for the exact information on your | |
1dc1ea18 | 84 | system. As an example, the way to ensure the `DT_RUNPATH` is set on |
445bc808 RL |
85 | Debian GNU/Linux systems rather than DT_RPATH is to tell the linker to |
86 | set new dtags, like this: | |
87 | ||
16b0e0fc | 88 | $ ./Configure --prefix=/usr/local/ssl --openssldir=/usr/local/ssl \ |
445bc808 | 89 | '-Wl,--enable-new-dtags,-rpath,$(LIBRPATH)' |
2c879241 AP |
90 | |
91 | It might be worth noting that some/most ELF systems implement support | |
92 | for runtime search path relative to the directory containing current | |
1dc1ea18 | 93 | executable, by interpreting `$ORIGIN` along with some other internal |
2c879241 AP |
94 | variables. Consult your system documentation. |
95 | ||
96 | Linking your application | |
97 | ------------------------ | |
98 | ||
99 | Third-party applications dynamically linked with OpenSSL (or any other) | |
100 | shared library face exactly the same problem with non-default locations. | |
101 | The OpenSSL config options mentioned above might or might not have bearing | |
102 | on linking of the target application. "Might" means that under some | |
103 | circumstances it would be sufficient to link with OpenSSL shared library | |
1dc1ea18 | 104 | "naturally", i.e. with `-L/whatever/path -lssl -lcrypto`. But there are |
2c879241 AP |
105 | also cases when you'd have to explicitly specify runtime search path |
106 | when linking your application. Consult your system documentation and use | |
107 | above section as inspiration... | |
108 | ||
109 | Shared OpenSSL builds also install static libraries. Linking with the | |
110 | latter is likely to require special care, because linkers usually look | |
111 | for shared libraries first and tend to remain "blind" to static OpenSSL | |
112 | libraries. Referring to system documentation would suffice, if not for | |
113 | a corner case. On AIX static libraries (in shared build) are named | |
1dc1ea18 | 114 | differently, add `_a` suffix to link with them, e.g. `-lcrypto_a`. |