X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=INSTALL;h=6066fddc4a15ac44e2918e054a07725f54833ffe;hp=6ce69da7e36aad916e25856d3e767a7dd19626dd;hb=a32640b0f4c681c69c97def95c3e7995c80c77f3;hpb=dd56626ecc7c5101c87d5d92156fedd530f8cef9 diff --git a/INSTALL b/INSTALL index 6ce69da7e3..6066fddc4a 100644 --- a/INSTALL +++ b/INSTALL @@ -1,156 +1,260 @@ -Installing OpenSSL on Unix --------------------------- -[For instructions for compiling OpenSSL on Windows systems, see -INSTALL.W32]. + INSTALLATION ON THE UNIX PLATFORM + --------------------------------- -To install OpenSSL, you will need: + [See INSTALL.W32 for instructions for compiling OpenSSL on Windows systems, + and INSTALL.VMS for installing on OpenVMS systems.] - * Perl - * C compiler - * A supported operating system + To install OpenSSL, you will need: -Quick Start ------------ + * Perl 5 + * an ANSI C compiler + * a supported Unix operating system -If you want to just get on with it, do: + Quick Start + ----------- - sh config [if this fails, go to step 1b below] - make - make rehash - make test - make install + If you want to just get on with it, do: -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 : + $ ./config + $ make + $ make test + $ make install - perl util/ssldir.pl /new/install/path + [If any of these steps fails, see section Installation in Detail below.] -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. + 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: -Installation in Detail ----------------------- + $ ./config --prefix=/usr/local --openssldir=/usr/local/openssl - 1a. Configure OpenSSL for your operation system automatically - Run + Configuration Options + --------------------- - sh config + There are several options to ./config to customize the build: - 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. + --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. - 1b. Configure OpenSSL for your operating system manually + --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. + + + Installation in Detail + ---------------------- - OpenSSL knows about a range of different operating system, hardware - and compiler combinations. To see the ones it knows about, run + 1a. Configure OpenSSL for your operation system automatically: - ./Configure + $ ./config [options] - Pick a suitable name from the list that matches your system. For - most operating systems there is a choice between using "cc" or - "gcc". + This guesses at your operating system (and compiler, if necessary) and + 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. - 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: + On some systems, you can include debugging information as follows: - ./Configure linux-elf + $ ./config -d [options] + + 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 + + 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 [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 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: + + $ 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. + + 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.] + + Compiling parts of OpenSSL with gcc and others with the system + compiler will result in unresolved symbols on some systems. + + 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 , 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 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 - 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: + instead of "#include ", which was used with library versions + up to OpenSSL 0.9.2b. - 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 + If you install a new version of OpenSSL over an old library version, + you should delete the old header files in the include directory. - 2. Set the install directory + Compatibility issues: - If the install directory will be the default of /usr/local/ssl, - skip to the next stage. Otherwise, run + * COMPILING existing applications - perl util/ssldir.pl /new/install/path + 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 - 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. + -I/usr/local/ssl/include/openssl - 3. Build OpenSSL + to it. - Now run + But don't delete the existing -I option that points to + the ..../include directory! Otherwise, OpenSSL header files + could not #include each other. - make + * WRITING applications - 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. + 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: - 4. After a successful build, the libraries should be tested. Run + - Always use the new filename of OpenSSL header files, + e.g. #include . - make rehash - make test + - 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: - (The first line makes the test certificates in the "certs" - directory accessable via an hash name, which is required for some - of the tests). + incl/openssl: + -mkdir incl + cd $(OPENSSLDIR) # Check whether the directory really exists + -ln -s `cd $(OPENSSLDIR); pwd`/include incl/openssl - 5. If everything tests ok, install OpenSSL with + You will have to add "incl/openssl" to the dependencies + of those C files that include some OpenSSL header file. - make install + - Add "-Iincl" to your CFLAGS. - This will create the installation directory (if it does not - exist) and then create the following subdirectories: + 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 . - 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. - 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". - private Initially empty, this is the default location - for private key files. ----------------------------------------------------------------------- + Note on multi-threading + ----------------------- -Additional Compilation Notes ----------------------------- + 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). -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). + 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.) -# 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 :-)