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