Do make rehash automatically at make test.

[openssl.git] / INSTALL

diff --git a/INSTALL b/INSTALL
index f1065548974888d553392f4b5826e663bf817104..967c658ad7e9480d60e2162fcd916133b29248b2 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -6,9 +6,9 @@
 
  To install OpenSSL, you will need:
 
 
  To install OpenSSL, you will need:
 

-  * Perl
-  * C compiler
-  * A supported Unix operating system
+  * Perl 5
+  * an ANSI C compiler
+  * a supported Unix operating system

 
  Quick Start
  -----------
 
  Quick Start
  -----------


@@ -17,22 +17,30 @@
 
   $ ./config                  [if this fails, go to step 1b below]
   $ make
 
   $ ./config                  [if this fails, go to step 1b below]
   $ make

-  $ make rehash

   $ make test
   $ make install
 
  This will build and install OpenSSL in the default location, which is (for
  historical reasons) /usr/local/ssl. If you want to install it anywhere else,
   $ make test
   $ make install
 
  This will build and install OpenSSL in the default location, which is (for
  historical reasons) /usr/local/ssl. If you want to install it anywhere else,

- do this after running `./config':
+ run config like this:

 
 

-  $ perl util/ssldir.pl /new/install/path
+  $ ./config --prefix=/usr/local --openssldir=/usr/local/openssl

 
  There are several options to ./config to customize the build:
 
 
  There are several options to ./config to customize the build:
 

-  rsaref    Build with RSADSI's RSAREF toolkit.
-  no-asm    Build with no assembler code.
-  386       Use the 80386 instruction set only (the default x86 code is
-            more efficient, but requires at least a 486).
+  --prefix=DIR  Install in DIR/bin, DIR/lib, DIR/include. Configuration
+                files used by OpenSSL will be in DIR/ssl or the directory
+                specified by --openssldir.
+
+  --openssldir=DIR Directory for OpenSSL files. If no prefix is specified,
+                the library files and binaries are also installed there.
+
+  rsaref        Build with RSADSI's RSAREF toolkit.
+
+  no-asm        Build with no assembler code.
+
+  386           Use the 80386 instruction set only (the default x86 code is
+                more efficient, but requires at least a 486).

 
  If anything goes wrong, follow the detailed instructions below. If your
  operating system is not (yet) supported by OpenSSL, see the section on
 
  If anything goes wrong, follow the detailed instructions below. If your
  operating system is not (yet) supported by OpenSSL, see the section on


@@ -46,8 +54,8 @@
        $ ./config
 
      This guesses at your operating system (and compiler, if necessary) and
        $ ./config
 
      This guesses at your operating system (and compiler, if necessary) and

-     configures OpenSSL based on this guess. Check the first line of output to
-     see if it guessed correctly. If it did not get it correct or you want to
+     configures OpenSSL based on this guess. Run ./config -t -v to see
+     if it guessed correctly. If it did not get it correct or you want to

      use a different compiler then go to step 1b. Otherwise go to step 2.
 
  1b. Configure OpenSSL for your operating system manually
      use a different compiler then go to step 1b. Otherwise go to step 2.
 
  1b. Configure OpenSSL for your operating system manually


@@ -63,42 +71,17 @@
      as the argument to ./Configure. For example, a "linux-elf" user would
      run:
 
      as the argument to ./Configure. For example, a "linux-elf" user would
      run:
 

-       $ ./Configure linux-elf
+       $ ./Configure linux-elf [--prefix=DIR] [--openssldir=OPENSSLDIR]

 
      If your system is not available, you will have to edit the Configure
 
      If your system is not available, you will have to edit the Configure

-     program and add the correct configuration for your system.
-
-     Configure configures various files by converting an existing .org file
-     into the real file. If you edit any files, remember that if a
-     corresponding .org file exists them the next time you run ./Configure
-     your changes will be lost when the file gets re-created from the .org
-     file. The files that are created from .org files are:
-
-       Makefile.ssl
-       crypto/des/des.h
-       crypto/des/des_locl.h
-       crypto/md2/md2.h
-       crypto/rc4/rc4.h
-       crypto/rc4/rc4_enc.c
-       crypto/rc2/rc2.h
-       crypto/bf/bf_locl.h
-       crypto/idea/idea.h
-       crypto/bn/bn.h
-
-  2. Set the install directory
-
-     If the install directory will be the default of /usr/local/ssl, skip to
-     the next stage. Otherwise, run
+     program and add the correct configuration for your system. The
+     generic configurations "cc" or "gcc" should usually work.

 
 

-        $ perl util/ssldir.pl /new/install/path
+     Configure creates the Makefile.ssl from Makefile.org and defines
+     various macros in crypto/opensslconf.h (generated from
+     crypto/opensslconf.h.in).

 
 

-     This configures the installation location into the "install" target of
-     the top-level Makefile, and also updates some defines in an include file
-     so that the default certificate directory is under the proper
-     installation directory. It also updates a few utility files used in the
-     build process.
-
-  3. Build OpenSSL by running:
+  2. Build OpenSSL by running:

 
        $ make
 
 
        $ make
 


@@ -106,31 +89,96 @@
      OpenSSL binary ("openssl"). The libraries will be built in the top-level
      directory, and the binary will be in the "apps" directory.
 
      OpenSSL binary ("openssl"). The libraries will be built in the top-level
      directory, and the binary will be in the "apps" directory.
 

-  4. After a successful build, the libraries should be tested. Run:
+  3. After a successful build, the libraries should be tested. Run:

 
 

-       $ make rehash

        $ make test
 
        $ make test
 

-     (The first line makes the test certificates in the "certs" directory
-     accessable via an hash name, which is required for some of the tests).
-
-  5. If everything tests ok, install OpenSSL with
+  4. If everything tests ok, install OpenSSL with

 
        $ make install
 
      This will create the installation directory (if it does not exist) and
      then create the following subdirectories:
 
 
        $ make install
 
      This will create the installation directory (if it does not exist) and
      then create the following subdirectories:
 

-       bin            Contains the openssl binary and a few other 
-                      utility programs. 
-       include        Contains the header files needed if you want to
-                      compile programs with libcrypto or libssl.
-       lib            Contains the library files themselves and the
-                      OpenSSL configuration file "openssl.cnf".
-       certs          Initially empty, this is the default location
-                      for certificate files.
-       private        Initially empty, this is the default location
-                      for private key files.
+       certs           Initially empty, this is the default location
+                       for certificate files.
+       private         Initially empty, this is the default location
+                       for private key files.
+       lib             Contains the OpenSSL configuration file "openssl.cnf".
+
+     If you didn't chose a different installation prefix, lib also contains
+     the library files themselves, and the following additional subdirectories
+     will be created:
+
+       bin             Contains the openssl binary and a few other 
+                       utility programs. 
+       include/openssl Contains the header files needed if you want to
+                       compile programs with libcrypto or libssl.
+
+  NOTE: The header files used to reside directly in the include
+  directory, but have now been moved to include/openssl so that
+  OpenSSL can co-exist with other libraries which use some of the
+  same filenames.  This means that applications that use OpenSSL
+  should now use C preprocessor directives of the form
+
+       #include <openssl/ssl.h>
+
+  instead of "#include <ssl.h>", which was used with library versions
+  up to OpenSSL 0.9.2b.
+
+  If you install a new version of OpenSSL over an old library version,
+  you should delete the old header files in the include directory.
+
+  Compatibility issues:
+
+  *  COMPILING existing applications
+
+     To compile an application that uses old filenames -- e.g.
+     "#include <ssl.h>" --, it will usually be enough to find
+     the CFLAGS definition in the application's Makefile and
+     add a C option such as
+
+          -I/usr/local/ssl/include/openssl
+
+     to it.
+
+     But don't delete the existing -I option that points to
+     the ..../include directory!  Otherwise, OpenSSL header files
+     could not #include each other.
+
+  *  WRITING applications
+
+     To write an application that is able to handle both the new
+     and the old directory layout, so that it can still be compiled
+     with library versions up to OpenSSL 0.9.2b without bothering
+     the user, you can proceed as follows:
+
+     -  Always use the new filename of OpenSSL header files,
+        e.g. #include <openssl/ssl.h>.
+
+     -  Create a directory "incl" that contains only a symbolic
+        link named "openssl", which points to the "include" directory
+        of OpenSSL.
+        For example, your application's Makefile might contain the
+        following rule, if OPENSSLDIR is a pathname (absolute or
+        relative) of the directory where OpenSSL resides:
+
+        incl/openssl:
+               -mkdir incl
+               cd $(OPENSSLDIR) # Check whether the directory really exists
+               -ln -s `cd $(OPENSSLDIR); pwd`/include incl/openssl
+
+        You will have to add "incl/openssl" to the dependencies
+        of those C files that include some OpenSSL header file.
+
+     -  Add "-Iincl" to your CFLAGS.
+
+     With these additions, the OpenSSL header files will be available
+     under both name variants if an old library version is used:
+     Your application can reach them under names like <openssl/foo.h>,
+     while the header files still are able to #include each other
+     with names of the form <foo.h>.
+

 
 
 --------------------------------------------------------------------------------
 
 
 --------------------------------------------------------------------------------