1Notes for UNIX-like platforms 2============================= 3 4 For Unix/POSIX runtime systems on Windows, 5 please see the [Notes for Windows platforms](NOTES-WINDOWS.md). 6 7 OpenSSL uses the compiler to link programs and shared libraries 8 --------------------------------------------------------------- 9 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 15 linker flags directly, while others take them in `-Wl,` form. You need 16 to read your compiler documentation to figure out what is acceptable, 17 and `ld(1)` to figure out what linker options are available. 18 19 Shared libraries and installation in non-default locations 20 ---------------------------------------------------------- 21 22 Every Unix system has its own set of default locations for shared 23 libraries, such as `/lib`, `/usr/lib` or possibly `/usr/local/lib`. If 24 libraries are installed in non-default locations, dynamically linked 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. 27 28 For OpenSSL's application (the `openssl` command), our configuration 29 scripts do NOT generally set the runtime shared library search path for 30 you. It's therefore advisable to set it explicitly when configuring, 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 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 48 49 OpenSSL's configuration scripts recognise all these options and pass 50 them to the Makefile that they build. (In fact, all arguments starting 51 with `-Wl,` are recognised as linker options.) 52 Please note that 'l' in '-Wl' is lowercase L and not 1. 53 54 Please do not use verbatim directories in your runtime shared library 55 search path! Some OpenSSL config targets add an extra directory level 56 for multilib installations. To help with that, the produced Makefile 57 includes the variable LIBRPATH, which is a convenience variable to be 58 used with the runtime shared library search path options, as shown in 59 this example: 60 61 $ ./Configure --prefix=/usr/local/ssl --openssldir=/usr/local/ssl \ 62 '-Wl,-rpath,$(LIBRPATH)' 63 64 On modern ELF based systems, there are two runtime search paths tags to 65 consider, `DT_RPATH` and `DT_RUNPATH`. Shared objects are searched for in 66 this order: 67 68 1. Using directories specified in DT_RPATH, unless DT_RUNPATH is also set. 69 2. Using the environment variable LD_LIBRARY_PATH 70 3. Using directories specified in DT_RUNPATH. 71 4. Using system shared object caches and default directories. 72 73 This means that the values in the environment variable `LD_LIBRARY_PATH` 74 won't matter if the library is found in the paths given by `DT_RPATH` 75 (and `DT_RUNPATH` isn't set). 76 77 Exactly which of `DT_RPATH` or `DT_RUNPATH` is set by default appears to 78 depend on the system. For example, according to documentation, 79 `DT_RPATH` appears to be deprecated on Solaris in favor of `DT_RUNPATH`, 80 while on Debian GNU/Linux, either can be set, and `DT_RPATH` is the 81 default at the time of writing. 82 83 How to choose which runtime search path tag is to be set depends on 84 your system, please refer to ld(1) for the exact information on your 85 system. As an example, the way to ensure the `DT_RUNPATH` is set on 86 Debian GNU/Linux systems rather than DT_RPATH is to tell the linker to 87 set new dtags, like this: 88 89 $ ./Configure --prefix=/usr/local/ssl --openssldir=/usr/local/ssl \ 90 '-Wl,--enable-new-dtags,-rpath,$(LIBRPATH)' 91 92 It might be worth noting that some/most ELF systems implement support 93 for runtime search path relative to the directory containing current 94 executable, by interpreting `$ORIGIN` along with some other internal 95 variables. Consult your system documentation. 96 97 Linking your application 98 ------------------------ 99 100 Third-party applications dynamically linked with OpenSSL (or any other) 101 shared library face exactly the same problem with non-default locations. 102 The OpenSSL config options mentioned above might or might not have bearing 103 on linking of the target application. "Might" means that under some 104 circumstances it would be sufficient to link with OpenSSL shared library 105 "naturally", i.e. with `-L/whatever/path -lssl -lcrypto`. But there are 106 also cases when you'd have to explicitly specify runtime search path 107 when linking your application. Consult your system documentation and use 108 above section as inspiration... 109 110 Shared OpenSSL builds also install static libraries. Linking with the 111 latter is likely to require special care, because linkers usually look 112 for shared libraries first and tend to remain "blind" to static OpenSSL 113 libraries. Referring to system documentation would suffice, if not for 114 a corner case. On AIX static libraries (in shared build) are named 115 differently, add `_a` suffix to link with them, e.g. `-lcrypto_a`. 116