xref: /netbsd-src/crypto/external/bsd/openssl.old/dist/NOTES.UNIX (revision 4724848cf0da353df257f730694b7882798e5daf)
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