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