Some assembler-related clean-ups.
[openssl.git] / INSTALL
diff --git a/INSTALL b/INSTALL
index 5ee2225..b604fa2 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -2,7 +2,8 @@
  INSTALLATION ON THE UNIX PLATFORM
  ---------------------------------
 
- [For instructions for compiling OpenSSL on Windows systems, see INSTALL.W32].
+ [See INSTALL.W32 for instructions for compiling OpenSSL on Windows systems,
+  and INSTALL.VMS for installing on OpenVMS systems.]
 
  To install OpenSSL, you will need:
 
 
  If you want to just get on with it, do:
 
-  $ ./config                  [if this fails, go to step 1b below]
+  $ ./config
   $ make
   $ make test
   $ make install
 
+ [If any of these steps fails, see section Installation in Detail below.]
+
  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,
  run config like this:
 
   $ ./config --prefix=/usr/local --openssldir=/usr/local/openssl
 
+
+ Configuration Options
+ ---------------------
+
  There are several options to ./config to customize the build:
 
-  --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.
+  --prefix=DIR  Install in DIR/bin, DIR/lib, DIR/include/openssl.
+               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.
+  rsaref        Build with RSADSI's RSAREF toolkit (this assumes that
+                librsaref.a is in the library search path).
 
   no-threads    Don't try to build with support for multi-threaded
                 applications.
                 This will usually require additional system-dependent options!
                 See "Note on multi-threading" below.
 
-  no-asm        Build with no assembler code.
+  no-asm        Do not use 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
- porting to a new system.
+  no-<cipher>   Build without the specified cipher (bf, cast, des, dh, dsa,
+                hmac, md2, md5, mdc2, rc2, rc4, rc5, rsa, sha).
+                The crypto/<cipher> directory can be removed after running
+                "make depend".
+
+  -Dxxx, -lxxx, -Lxxx, -fxxx, -Kxxx These system specific options will
+                be passed through to the compiler to allow you to
+                define preprocessor symbols, specify additional libraries,
+                library directories or other compiler options.
+
 
  Installation in Detail
  ----------------------
 
  1a. Configure OpenSSL for your operation system automatically:
 
-       $ ./config
+       $ ./config [options]
 
      This guesses at your operating system (and compiler, if necessary) and
-     configures OpenSSL based on this guess. Run ./config -t -v to see
+     configures OpenSSL based on this guess. Run ./config -t 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.
 
+     On some systems, you can include debugging information as follows:
+
+       $ ./config -d [options]
+
  1b. Configure OpenSSL for your operating system manually
 
      OpenSSL knows about a range of different operating system, hardware and
      as the argument to ./Configure. For example, a "linux-elf" user would
      run:
 
-       $ ./Configure linux-elf [--prefix=DIR] [--openssldir=OPENSSLDIR]
+       $ ./Configure linux-elf [options]
 
      If your system is not available, you will have to edit the Configure
      program and add the correct configuration for your system. The
      generic configurations "cc" or "gcc" should usually work.
 
-     Configure creates the Makefile.ssl from Makefile.org and defines
-     various macros in crypto/opensslconf.h (generated from
+     Configure creates the file Makefile.ssl from Makefile.org and
+     defines various macros in crypto/opensslconf.h (generated from
      crypto/opensslconf.h.in).
 
   2. Build OpenSSL by running:
      OpenSSL binary ("openssl"). The libraries will be built in the top-level
      directory, and the binary will be in the "apps" directory.
 
+     If "make" fails, please report the problem to <openssl-bugs@openssl.org>.
+     Include the output of "./config -t" and the OpenSSL version
+     number in your message.
+
+     [If you encounter assembler error messages, try the "no-asm"
+     configuration option as an immediate fix.  Note that on Solaris x86
+     (not on Sparcs!) you may have to install the GNU assembler to use
+     OpenSSL assembler code -- /usr/ccs/bin/as won't do.]
+
   3. After a successful build, the libraries should be tested. Run:
 
        $ make test
 
+    If a test fails, try removing any compiler optimization flags from
+    the CFLAGS line in Makefile.ssl and run "make clean; make". Please
+    send a bug report to <openssl-bugs@openssl.org>, including the
+    output of "openssl version -a" and of the failed test.
+
   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:
+     then the following subdirectories:
 
        certs           Initially empty, this is the default location
                        for certificate files.
+       misc            Various scripts.
        private         Initially empty, this is the default location
                        for private key files.
-       lib             Contains the OpenSSL configuration file "openssl.cnf".
-       misc            Various scripts.
 
-     If you didn't chose a different installation prefix, lib also contains
-     the library files themselves, and the following additional subdirectories
-     will be created:
+     If you didn't chose a different installation prefix, 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.
+       lib             Contains the OpenSSL library files themselves.
 
      Package builders who want to configure the library for standard
      locations, but have the package installed somewhere else so that
  necessary).
 
  On other systems, to enable support for multi-threading, you will have
- to specifiy at least two options: "threads", and a system-dependent option.
+ to specify at least two options: "threads", and a system-dependent option.
  (The latter is "-D_REENTRANT" on various systems.)  The default in this
  case, obviously, is not to include support for multi-threading (but
  you can still use "no-threads" to suppress an annoying warning message