A local copy of OpenSSL from GitHub
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

115 lines
5.6 KiB

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