Bring style of INSTALL* documents in sync with README file

Installing OpenSSL on Unix

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

 INSTALLATION ON THE UNIX PLATFORM

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

 [For instructions for compiling OpenSSL on Windows systems, see INSTALL.W32].

  * Perl

  * C compiler

  * A supported operating system

  * A supported Unix operating system

 Quick Start

 -----------

 If you want to just get on with it, do:

  sh config                      [if this fails, go to step 1b below]

  make

  make rehash

  make test

  make install

  $ ./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

/usr/local/ssl. If you want to install it anywhere else, do this

after running `sh config':

 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 `sh config':

  perl util/ssldir.pl /new/install/path

  $ perl util/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.

 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

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

 1a. Configure OpenSSL for your operation system automatically

 1a. Configure OpenSSL for your operation system automatically:

     Run

       $ ./config

       sh 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 use a different compiler then

     go to step 1b. Otherwise go to step 2.

     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

     use a different compiler then go to step 1b. Otherwise go to step 2.

 1b. Configure OpenSSL for your operating system manually

     OpenSSL knows about a range of different operating system, hardware

     and compiler combinations. To see the ones it knows about, run

       ./Configure

     OpenSSL knows about a range of different operating system, hardware and

     compiler combinations. To see the ones it knows about, run

     Pick a suitable name from the list that matches your system. For

     most operating systems there is a choice between using "cc" or

     "gcc".

       $ ./Configure

     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:

     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

       $ ./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:

     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

  2. Set the install directory

     If the install directory will be the default of /usr/local/ssl,

     skip to the next stage. Otherwise, run

     If the install directory will be the default of /usr/local/ssl, skip to

     the next stage. Otherwise, run

       perl util/ssldir.pl /new/install/path

        $ perl util/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.

     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

  3. Build OpenSSL by running:

     Now run

       $ make

       make

     This will build the OpenSSL libraries (libcrypto.a and libssl.a) and the

     OpenSSL binary ("openssl"). The libraries will be built in the top-level

     directory, and the binary will be in the "apps" directory.

     This will build the OpenSSL libraries (libcrypto.a and libssl.a)

     and the 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:

  4. After a successful build, the libraries should be tested. Run

       $ make rehash

       $ make test

       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).

     (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

       $ make install

     This will create the installation directory (if it does not

     exist) and then create the following subdirectories:

     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. It also contains symbolic links so

                      that openssl commands can be accessed directly

                      (e.g. so that "s_client" can be used instead of

                      "openssl s_client").

       certs          Initially empty, this is the default location

                      for certificate files.

       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.

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

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

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

The orignal Unix build instructions from SSLeay follow. 

Note: some of this may be out of date and no longer applicable

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

# When bringing the SSLeay distribution back from the evil intel world

# of Windows NT, do the following to make it nice again under unix :-)

Building OpenSSL under Win32.

 INSTALLATION ON THE WIN32 PLATFORM

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

 Heres a few comments about building OpenSSL in Windows environments. Most of

this is tested on Win32 but it may also work in Win 3.1 with some modification.

See the end of this file for Eric's original comments.

 this is tested on Win32 but it may also work in Win 3.1 with some

 modification.  See the end of this file for Eric's original comments.

 Note: the default Win32 environment is to leave out any Windows NT specific

 features: (currently only BIO_s_log()) if you want NT specific features see

 the "Tweaks" section later.

You will need perl for Win32 (which can be got from various sources) and Visual

C++. 

 You will need perl for Win32 (which can be got from various sources) and

 Visual C++. 

If you are compiling from a tarball or a CVS snapshot then the Win32 files may

well be not up to date. This may mean that some "tweaking" is required to get

it all to work. See the trouble shooting section later on for if (when?) it

goes wrong.

 If you are compiling from a tarball or a CVS snapshot then the Win32 files

 may well be not up to date. This may mean that some "tweaking" is required to

 get it all to work. See the trouble shooting section later on for if (when?)

 it goes wrong.

 Firstly you should run Configure:

perl Configure VC-WIN32

 > perl Configure VC-WIN32

 Then rebuild the Win32 Makefiles and friends:

ms\do_ms

 > ms\do_ms

if you get errors about things not having numbers assigned then check the

troubleshooting section: you probably wont be able to compile it as it stands.

 If you get errors about things not having numbers assigned then check the

 troubleshooting section: you probably wont be able to compile it as it

 stands.

then from the VC++ environment at a prompt do:

 Then from the VC++ environment at a prompt do:

nmake -f ms\ntdll.mak

 > nmake -f ms\ntdll.mak

 If all is well it should compile and you will have some DLLs and executables

in out32dll. If you want to try the tests then cd to out32dll and run ..\ms\test

 in out32dll. If you want to try the tests then do:

Troubleshooting.

 > cd out32dll

 > ..\ms\test

Since the Win32 build is only occasionally tested it may not always compile

cleanly.

 Troubleshooting

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

If you get an error about functions not having numbers assigned when you

run ms\do_ms then this means the Win32 ordinal files are not up to date. You

can do:

 Since the Win32 build is only occasionally tested it may not always compile

 cleanly.  If you get an error about functions not having numbers assigned

 when you run ms\do_ms then this means the Win32 ordinal files are not up to

 date. You can do:

perl util\mkdef.pl crypto ssl update

 > perl util\mkdef.pl crypto ssl update

then ms\do_ms should not give a warning any more. However the numbers that get

assigned by this technique may not match those that eventually get assigned

in the CVS tree: so anything linked against this version of the library

may need to be recompiled.

 then ms\do_ms should not give a warning any more. However the numbers that

 get assigned by this technique may not match those that eventually get

 assigned in the CVS tree: so anything linked against this version of the

 library may need to be recompiled.

 If you get errors about unresolved externals then this means that either you

 didn't read the note above about functions not having numbers assigned or

 someone forgot to add a function to the header file.

In this latter case check out the header file to see if the function is defined

in the header file: it should be defined twice: once with ANSI prototypes and

once without. If its missing from the non ASNI section then add an entry for

it: check that ms\do_ms now reports missing numbers and update the numbers as

above.

 In this latter case check out the header file to see if the function is

 defined in the header file: it should be defined twice: once with ANSI

 prototypes and once without. If its missing from the non ASNI section then

 add an entry for it: check that ms\do_ms now reports missing numbers and

 update the numbers as above.

 If you get warnings in the code then the compilation will halt.

 The default Makefile for Win32 halts whenever any warnings occur. Since VC++

 has its own ideas about warnings which don't always match up to other

environments this can happen. The best fix is to edit the file with the warning

in and fix it. Alternatively you can turn off the halt on warnings by editing

the CFLAG line in the Makefile and deleting the /WX option.

 environments this can happen. The best fix is to edit the file with the

 warning in and fix it. Alternatively you can turn off the halt on warnings by

 editing the CFLAG line in the Makefile and deleting the /WX option.

You might get compilation errors. Again you will have to fix these or

report them.

 You might get compilation errors. Again you will have to fix these or report

 them.

 One final comment about compiling applications linked to the OpenSSL library.

 If you don't use the multithreaded DLL runtime library (/MD option) your

program will almost certainly crash: see the original SSLeay description below

for more details.

 program will almost certainly crash: see the original SSLeay description

 below for more details.

Tweaks.

 Tweaks

 ------

There are various changes you can make to the Win32 compile environment. If you

have the MASM assembler 'ml' then you can try the assembly language code. To

do this remove the 'no-asm' part from do_ms.bat. You can also add 'debug' here

to make a debugging version of the library.

 There are various changes you can make to the Win32 compile environment. If

 you have the MASM assembler 'ml' then you can try the assembly language code.

 To do this remove the 'no-asm' part from do_ms.bat. You can also add 'debug'

 here to make a debugging version of the library.

If you want to enable the NT specific features of OpenSSL (currently only

the logging BIO) follow the instructions above but call the batch file

do_nt.bat instead of do_ms.bat.

 If you want to enable the NT specific features of OpenSSL (currently only the

 logging BIO) follow the instructions above but call the batch file do_nt.bat

 instead of do_ms.bat.

You can also build a static version of the library using the Makefile ms\nt.mak

 You can also build a static version of the library using the Makefile

 ms\nt.mak

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

The orignal Windows build instructions from SSLeay follow. Note: some of this

may be out of date and no longer applicable

The orignal Windows build instructions from SSLeay follow. 

Note: some of this may be out of date and no longer applicable

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

The Microsoft World.