X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=INSTALL;h=b604fa2a005478dae553131f5158dd4160d3431d;hp=9e0eaddb011115e1535ec49e060a16d38f34bac6;hb=436a376bb048453990e19eb236ffff4ebfcd42ad;hpb=abb3e53f9b5ede6d1cf86e46949f4856fa2b3004 diff --git a/INSTALL b/INSTALL index 9e0eaddb01..b604fa2a00 100644 --- a/INSTALL +++ b/INSTALL @@ -2,54 +2,88 @@ 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: * Perl 5 - * ANSI C compiler - * A supported Unix operating system + * an ANSI C compiler + * a supported Unix operating system Quick Start ----------- If you want to just get on with it, do: - $ ./config [if this fails, go to step 1b below] + $ ./config $ make - $ make rehash $ 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, - do this after running `./config': + run config like this: + + $ ./config --prefix=/usr/local --openssldir=/usr/local/openssl - $ perl util/ssldir.pl /new/install/path + + Configuration Options + --------------------- 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/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 (this assumes that + librsaref.a is in the library search path). + + no-threads Don't try to build with support for multi-threaded + applications. + + threads Build with support for multi-threaded applications. + This will usually require additional system-dependent options! + See "Note on multi-threading" below. + + 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). + + no- Build without the specified cipher (bf, cast, des, dh, dsa, + hmac, md2, md5, mdc2, rc2, rc4, rc5, rsa, sha). + The crypto/ 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. - 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: - $ ./config + $ ./config [options] 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 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 @@ -63,42 +97,17 @@ as the argument to ./Configure. For example, a "linux-elf" user would run: - $ ./Configure linux-elf + $ ./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. + program and add the correct configuration for your system. The + generic configurations "cc" or "gcc" should usually work. - 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 creates the file Makefile.ssl from Makefile.org and + defines various macros in crypto/opensslconf.h (generated from + crypto/opensslconf.h.in). - 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 - - $ 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. - - 3. Build OpenSSL by running: + 2. Build OpenSSL by running: $ make @@ -106,31 +115,137 @@ 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: + If "make" fails, please report the problem to . + 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 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). + 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 , including the + output of "openssl version -a" and of the failed test. - 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: - - 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. + 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. + + 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 + it can easily be packaged, can use + + $ make INSTALL_PREFIX=/tmp/package-root install + + (or specify "--install_prefix=/tmp/package-root" as a configure + option). The specified prefix will be prepended to all + installation target filenames. + + + 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 + + instead of "#include ", 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 " --, 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 . + + - 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 , + while the header files still are able to #include each other + with names of the form . + + + Note on multi-threading + ----------------------- + + For some systems, the OpenSSL Configure script knows what compiler options + are needed to generate a library that is suitable for multi-threaded + applications. On these systems, support for multi-threading is enabled + by default; use the "no-threads" option to disable (this should never be + necessary). + + On other systems, to enable support for multi-threading, you will have + 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 + from the Configure script.) --------------------------------------------------------------------------------