Fix many MarkDown issues in {NOTES*,README*,HACKING,LICENSE}.md files
[openssl.git] / NOTES-Unix.md
1 NOTES FOR UNIX-LIKE PLATFORMS
2 =============================
3
4  For Unix/POSIX runtime systems on Windows,
5  please see [NOTES-Windows.txt](NOTES-Windows.txt).
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
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:
59
60     $ ./Configure --prefix=/usr/local/ssl --openssldir=/usr/local/ssl \
61         '-Wl,-rpath,$(LIBRPATH)'
62
63  On modern ELF based systems, there are two runtime search paths tags to
64  consider, `DT_RPATH` and `DT_RUNPATH`.  Shared objects are searched for in
65  this order:
66
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.
71
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).
75
76  Exactly which of `DT_RPATH` or `DT_RUNPATH` is set by default appears to
77  depend on the system.  For example, according to documentation,
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
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
84  system.  As an example, the way to ensure the `DT_RUNPATH` is set on
85  Debian GNU/Linux systems rather than DT_RPATH is to tell the linker to
86  set new dtags, like this:
87
88     $ ./Configure --prefix=/usr/local/ssl --openssldir=/usr/local/ssl \
89         '-Wl,--enable-new-dtags,-rpath,$(LIBRPATH)'
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
93  executable, by interpreting `$ORIGIN` along with some other internal
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
104  "naturally", i.e. with `-L/whatever/path -lssl -lcrypto`. But there are
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
114  differently, add `_a` suffix to link with them, e.g. `-lcrypto_a`.