NOTES.UNIX

   1
   2  NOTES FOR UNIX LIKE PLATFORMS
   3  =============================
   4
   5  For Unix/POSIX runtime systems on Windows, please see NOTES.WIN.
   6
   7
   8  OpenSSL uses the compiler to link programs and shared libraries
   9  ---------------------------------------------------------------
  10
  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.
  19
  20
  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
  27  binaries will not find them and therefore fail to run unless they get a
  28  bit of help from a defined runtime shared library search path.
  29
  30  For OpenSSL's application (the 'openssl' command), our configuration
  31  scripts do NOT generally set the runtime shared library search path for
  32  you.  It's therefore advisable to set it explicitly when configuring
  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
  45     -Wl,-rpath,/whatever/path
  46     -R /whatever/path
  47     -rpath /whatever/path
  48
  49  OpenSSL's configuration scripts recognise all these options and pass
  50  them to the Makefile that they build.  (In fact, it recognises anything
  51  starting with '-Wl,' as a linker option, so for example, HP-UX'
  52  '-Wl,+b,/whatever/path' would be used correctly)
  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     $ ./config --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
  69        also set.
  70     2. Using the environment variable LD_LIBRARY_PATH
  71     3. Using directories specified in DT_RUNPATH.
  72     4. Using system shared object caches and default directories.
  73
  74  This means that the values in the environment variable LD_LIBRARY_PATH
  75  won't matter if the library is found in the paths given by DT_RPATH
  76  (and DT_RUNPATH isn't set).
  77
  78  Exactly which of DT_RPATH or DT_RUNPATH is set by default appears to
  79  depend on the system.  For example, according to documentation,
  80  DT_RPATH appears to be deprecated on Solaris in favor of DT_RUNPATH,
  81  while on Debian GNU/Linux, either can be set, and DT_RPATH is the
  82  default at the time of writing.
  83
  84  How to choose which runtime search path tag is to be set depends on
  85  your system, please refer to ld(1) for the exact information on your
  86  system.  As an example, the way to ensure the DT_RUNPATH is set on
  87  Debian GNU/Linux systems rather than DT_RPATH is to tell the linker to
  88  set new dtags, like this:
  89
  90     $ ./config --prefix=/usr/local/ssl --openssldir=/usr/local/ssl \
  91         '-Wl,--enable-new-dtags,-rpath,$(LIBRPATH)'