INSTALL

   1
   2  INSTALLATION ON THE UNIX PLATFORM
   3  ---------------------------------
   4
   5  [Installation on Windows, OpenVMS and MacOS (before MacOS X) is described
   6   in INSTALL.W32, INSTALL.VMS and INSTALL.MacOS.]
   7
   8  To install OpenSSL, you will need:
   9
  10   * Perl 5
  11   * an ANSI C compiler
  12   * a supported Unix operating system
  13
  14  Quick Start
  15  -----------
  16
  17  If you want to just get on with it, do:
  18
  19   $ ./config
  20   $ make
  21   $ make test
  22   $ make install
  23
  24  [If any of these steps fails, see section Installation in Detail below.]
  25
  26  This will build and install OpenSSL in the default location, which is (for
  27  historical reasons) /usr/local/ssl. If you want to install it anywhere else,
  28  run config like this:
  29
  30   $ ./config --prefix=/usr/local --openssldir=/usr/local/openssl
  31
  32
  33  Configuration Options
  34  ---------------------
  35
  36  There are several options to ./config to customize the build:
  37
  38   --prefix=DIR  Install in DIR/bin, DIR/lib, DIR/include/openssl.
  39                 Configuration files used by OpenSSL will be in DIR/ssl
  40                 or the directory specified by --openssldir.
  41
  42   --openssldir=DIR Directory for OpenSSL files. If no prefix is specified,
  43                 the library files and binaries are also installed there.
  44
  45   rsaref        Build with RSADSI's RSAREF toolkit (this assumes that
  46                 librsaref.a is in the library search path).
  47
  48   no-threads    Don't try to build with support for multi-threaded
  49                 applications.
  50
  51   threads       Build with support for multi-threaded applications.
  52                 This will usually require additional system-dependent options!
  53                 See "Note on multi-threading" below.
  54
  55   no-asm        Do not use assembler code.
  56
  57   386           Use the 80386 instruction set only (the default x86 code is
  58                 more efficient, but requires at least a 486).
  59
  60   no-<cipher>   Build without the specified cipher (bf, cast, des, dh, dsa,
  61                 hmac, md2, md5, mdc2, rc2, rc4, rc5, rsa, sha).
  62                 The crypto/<cipher> directory can be removed after running
  63                 "make depend".
  64
  65   -Dxxx, -lxxx, -Lxxx, -fxxx, -Kxxx These system specific options will
  66                 be passed through to the compiler to allow you to
  67                 define preprocessor symbols, specify additional libraries,
  68                 library directories or other compiler options.
  69
  70
  71  Installation in Detail
  72  ----------------------
  73
  74  1a. Configure OpenSSL for your operation system automatically:
  75
  76        $ ./config [options]
  77
  78      This guesses at your operating system (and compiler, if necessary) and
  79      configures OpenSSL based on this guess. Run ./config -t to see
  80      if it guessed correctly. If you want to use a different compiler, you
  81      are cross-compiling for another platform, or the ./config guess was
  82      wrong for other reasons, go to step 1b. Otherwise go to step 2.
  83
  84      On some systems, you can include debugging information as follows:
  85
  86        $ ./config -d [options]
  87
  88  1b. Configure OpenSSL for your operating system manually
  89
  90      OpenSSL knows about a range of different operating system, hardware and
  91      compiler combinations. To see the ones it knows about, run
  92
  93        $ ./Configure
  94
  95      Pick a suitable name from the list that matches your system. For most
  96      operating systems there is a choice between using "cc" or "gcc".  When
  97      you have identified your system (and if necessary compiler) use this name
  98      as the argument to ./Configure. For example, a "linux-elf" user would
  99      run:
 100
 101        $ ./Configure linux-elf [options]
 102
 103      If your system is not available, you will have to edit the Configure
 104      program and add the correct configuration for your system. The
 105      generic configurations "cc" or "gcc" should usually work on 32 bit
 106      systems.
 107
 108      Configure creates the file Makefile.ssl from Makefile.org and
 109      defines various macros in crypto/opensslconf.h (generated from
 110      crypto/opensslconf.h.in).
 111
 112   2. Build OpenSSL by running:
 113
 114        $ make
 115
 116      This will build the OpenSSL libraries (libcrypto.a and libssl.a) and the
 117      OpenSSL binary ("openssl"). The libraries will be built in the top-level
 118      directory, and the binary will be in the "apps" directory.
 119
 120      If "make" fails, please report the problem to <openssl-bugs@openssl.org>
 121      (note that your message will be forwarded to a public mailing list).
 122      Include the output of "make report" in your message.
 123
 124      [If you encounter assembler error messages, try the "no-asm"
 125      configuration option as an immediate fix.]
 126
 127      Compiling parts of OpenSSL with gcc and others with the system
 128      compiler will result in unresolved symbols on some systems.
 129
 130   3. After a successful build, the libraries should be tested. Run:
 131
 132        $ make test
 133
 134     If a test fails, try removing any compiler optimization flags from
 135     the CFLAGS line in Makefile.ssl and run "make clean; make". Please
 136     send a bug report to <openssl-bugs@openssl.org>, including the
 137     output of "make report".
 138
 139   4. If everything tests ok, install OpenSSL with
 140
 141        $ make install
 142
 143      This will create the installation directory (if it does not exist) and
 144      then the following subdirectories:
 145
 146        certs           Initially empty, this is the default location
 147                        for certificate files.
 148        man/man1        Manual pages for the 'openssl' command line tool
 149        man/man3        Manual pages for the libraries (very incomplete)
 150        misc            Various scripts.
 151        private         Initially empty, this is the default location
 152                        for private key files.
 153
 154      If you didn't choose a different installation prefix, the
 155      following additional subdirectories will be created:
 156
 157        bin             Contains the openssl binary and a few other
 158                        utility programs.
 159        include/openssl Contains the header files needed if you want to
 160                        compile programs with libcrypto or libssl.
 161        lib             Contains the OpenSSL library files themselves.
 162
 163      Package builders who want to configure the library for standard
 164      locations, but have the package installed somewhere else so that
 165      it can easily be packaged, can use
 166
 167        $ make INSTALL_PREFIX=/tmp/package-root install
 168
 169      (or specify "--install_prefix=/tmp/package-root" as a configure
 170      option).  The specified prefix will be prepended to all
 171      installation target filenames.
 172
 173
 174   NOTE: The header files used to reside directly in the include
 175   directory, but have now been moved to include/openssl so that
 176   OpenSSL can co-exist with other libraries which use some of the
 177   same filenames.  This means that applications that use OpenSSL
 178   should now use C preprocessor directives of the form
 179
 180        #include <openssl/ssl.h>
 181
 182   instead of "#include <ssl.h>", which was used with library versions
 183   up to OpenSSL 0.9.2b.
 184
 185   If you install a new version of OpenSSL over an old library version,
 186   you should delete the old header files in the include directory.
 187
 188   Compatibility issues:
 189
 190   *  COMPILING existing applications
 191
 192      To compile an application that uses old filenames -- e.g.
 193      "#include <ssl.h>" --, it will usually be enough to find
 194      the CFLAGS definition in the application's Makefile and
 195      add a C option such as
 196
 197           -I/usr/local/ssl/include/openssl
 198
 199      to it.
 200
 201      But don't delete the existing -I option that points to
 202      the ..../include directory!  Otherwise, OpenSSL header files
 203      could not #include each other.
 204
 205   *  WRITING applications
 206
 207      To write an application that is able to handle both the new
 208      and the old directory layout, so that it can still be compiled
 209      with library versions up to OpenSSL 0.9.2b without bothering
 210      the user, you can proceed as follows:
 211
 212      -  Always use the new filename of OpenSSL header files,
 213         e.g. #include <openssl/ssl.h>.
 214
 215      -  Create a directory "incl" that contains only a symbolic
 216         link named "openssl", which points to the "include" directory
 217         of OpenSSL.
 218         For example, your application's Makefile might contain the
 219         following rule, if OPENSSLDIR is a pathname (absolute or
 220         relative) of the directory where OpenSSL resides:
 221
 222         incl/openssl:
 223                 -mkdir incl
 224                 cd $(OPENSSLDIR) # Check whether the directory really exists
 225                 -ln -s `cd $(OPENSSLDIR); pwd`/include incl/openssl
 226
 227         You will have to add "incl/openssl" to the dependencies
 228         of those C files that include some OpenSSL header file.
 229
 230      -  Add "-Iincl" to your CFLAGS.
 231
 232      With these additions, the OpenSSL header files will be available
 233      under both name variants if an old library version is used:
 234      Your application can reach them under names like <openssl/foo.h>,
 235      while the header files still are able to #include each other
 236      with names of the form <foo.h>.
 237
 238
 239  Note on multi-threading
 240  -----------------------
 241
 242  For some systems, the OpenSSL Configure script knows what compiler options
 243  are needed to generate a library that is suitable for multi-threaded
 244  applications.  On these systems, support for multi-threading is enabled
 245  by default; use the "no-threads" option to disable (this should never be
 246  necessary).
 247
 248  On other systems, to enable support for multi-threading, you will have
 249  to specify at least two options: "threads", and a system-dependent option.
 250  (The latter is "-D_REENTRANT" on various systems.)  The default in this
 251  case, obviously, is not to include support for multi-threading (but
 252  you can still use "no-threads" to suppress an annoying warning message
 253  from the Configure script.)
 254