Make the installation documentation easier to follow.

diff --git a/CHANGES b/CHANGES
index f15213bda923490a0961a8b35415e38088c0407c..b92853afdc27708845d3d93c00f9159212e49e7c 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -5,6 +5,9 @@
 
  Changes between 0.9.1c and 0.9.2
 
+  *) Make the top-level INSTALL documentation easier to understand.
+     [Paul Sutton]
+
   *) Makefiles updated to exit if an error occurs in a sub-directory
      make (including if user presses ^C) [Paul Sutton]
 

diff --git a/INSTALL b/INSTALL
index 2cddfb93e6922c2567a92a09f118367bdcd2543e..c0324a928af6fb2f7ddf4e179f532dfaa0f123dd 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -1,3 +1,145 @@
+Installing OpenSSL on Unix
+--------------------------
+
+[For instructions for compiling OpenSSL on Windows systems, see
+INSTALL.W32].
+
+To install OpenSSL, you will need:
+
+  * Perl
+  * C compiler
+  * A supported operating system
+
+Quick Start
+-----------
+
+If you want to just get on with it, do:
+
+  ./Configure                           Find a match for your system
+                                        in this output and use it on
+                                        the next line
+  ./Configure <system>
+  make -f Makefile.ssl links
+  make
+  make rehash
+  make test
+  make install
+
+This will build and install OpenSSL in the default location, which is
+/usr/local/ssl. If you want to install it anywhere else, do this
+after running ./Configure <system>:
+
+  utils/ssldir.pl /new/install/path
+
+If anything goes wrong, follow the detailed instructions below. If
+your operating system is not (yet) supported by OpenSSL, see the
+section on porting to a new system.
+
+Installation in Detail
+----------------------
+
+  1. Configure OpenSSL for your operating system
+
+     OpenSSL knows about a range of different operating system, hardware
+     and compiler combinations. To see the ones it knows about, run
+
+       ./Configure
+
+     Pick a suitable name from the list that matches your system. For
+     most operating systems there is a choice between using "cc" or
+     "gcc".
+
+     When you have identified your system (and if necessary compiler)
+     use this name as the argument to ./Configure. For example, a
+     "linux-elf" user would run:
+
+       ./Configure linux-elf
+
+     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
+
+       utils/ssldir.pl /new/install/path
+
+     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
+
+     Now run
+
+       make
+
+     This will build the OpenSSL libraries (libcrypto.a and libssl.a)
+     and the OpenSSL binary ("ssleay"). 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
+
+       make rehash
+       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
+
+       make install
+
+     This will create the installation directory (if it does not
+     exist) and then create the following subdirectories:
+
+       bin            Contains the ssleay binary and a few other utility
+                      programs. It also contains symbolic links so
+                      that ssleay commands can be accessed directly
+                      (e.g. so that "s_client" can be used instead of
+                      "ssleay s_client").
+       certs          Initially empty, this is the default location
+                      for certificate files.
+       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 "ssleay.cnf".
+       private        Initially empty, this is the default location
+                      for private key files.
+
+----------------------------------------------------------------------
+
+Additional Compilation Notes
+----------------------------
+
+These notes come from SSLeay 0.9.1 and cover some more advanced
+facilities (such as building a single makefile for use on Windows
+systems).
+
+
 # Installation of SSLeay.
 # It depends on perl for a few bits but those steps can be skipped and
 # the top level makefile edited by hand