X-Git-Url: https://git.openssl.org/gitweb/?a=blobdiff_plain;f=INSTALL;h=36f271787d69c939aeae8f24d8062d442efce8e2;hb=0a054d2a0b1ccab07587185245455093454fe353;hp=16de9b886d07b081b5b811ab25549d51b0ec8965;hpb=5ded1ca6dade13e093086573f4cebe400bff9f4d;p=openssl.git diff --git a/INSTALL b/INSTALL index 16de9b886d..36f271787d 100644 --- a/INSTALL +++ b/INSTALL @@ -99,6 +99,9 @@ $ nmake test $ nmake install + Note that in order to perform the install step above you need to have + appropriate permissions to write to the installation directory. + If any of these steps fails, see section Installation in Detail below. This will build and install OpenSSL in the default location, which is: @@ -108,6 +111,12 @@ OpenSSL version number with underscores instead of periods. Windows: C:\Program Files\OpenSSL or C:\Program Files (x86)\OpenSSL + The installation directory should be appropriately protected to ensure + unprivileged users cannot make changes to OpenSSL binaries or files, or install + engines. If you already have a pre-installed version of OpenSSL as part of + your Operating System it is recommended that you do not overwrite the system + version and instead install to somewhere else. + If you want to install it anywhere else, run config like this: On Unix: @@ -132,11 +141,20 @@ --openssldir depend in what configuration is used and what Windows implementation OpenSSL is built on. More notes on this in NOTES.WIN): - --api=x.y.z - Don't build with support for deprecated APIs below the - specified version number. For example "--api=1.1.0" will - remove support for all APIS that were deprecated in OpenSSL - version 1.1.0 or below. + --api=x.y[.z] + Build the OpenSSL libraries to support the API for + the specified version. If "no-deprecated" is also + given, don't build with support for deprecated APIs + in or below the specified version number. For example + "--api=1.1.0" with "no-deprecated" will remove + support for all APIS that were deprecated in + OpenSSL version 1.1.0 or below. + This is a rather specialized option for developers. + If you just intend to remove all deprecated APIs + entirely (up to the current version), only specify + "-no-deprecated" (see below). + If "--api" isn't given, it defaults to the current + OpenSSL minor version. --cross-compile-prefix=PREFIX The PREFIX to include in front of commands for your @@ -230,7 +248,7 @@ source exists. getrandom: Use the L or equivalent system call. - devrandom: Use the the first device from the DEVRANDOM list + devrandom: Use the first device from the DEVRANDOM list which can be opened to read random bytes. The DEVRANDOM preprocessor constant expands to "/dev/urandom","/dev/random","/dev/srandom" on @@ -326,32 +344,28 @@ work if the zlib or zlib-dynamic options are also chosen. enable-crypto-mdebug - Build support for debugging memory allocated via - OPENSSL_malloc() or OPENSSL_zalloc(). + This now only enables the failed-malloc feature. enable-crypto-mdebug-backtrace - As for crypto-mdebug, but additionally provide backtrace - information for allocated memory. - TO BE USED WITH CARE: this uses GNU C functionality, and - is therefore not usable for non-GNU config targets. If - your build complains about the use of '-rdynamic' or the - lack of header file execinfo.h, this option is not for you. - ALSO NOTE that even though execinfo.h is available on your - system (through Gnulib), the functions might just be stubs - that do nothing. + This is a no-op; the project uses the compiler's + address/leak sanitizer instead. no-ct Don't build support for Certificate Transparency. no-deprecated - Don't build with support for any deprecated APIs. This is the - same as using "--api" and supplying the latest version - number. + Don't build with support for deprecated APIs up + until and including the version given with + "--api" (or the current version of "--api" wasn't + given). no-dgram Don't build support for datagram based BIOs. Selecting this option will also force the disabling of DTLS. + no-dso + Don't build support for loading Dynamic Shared Objects. + enable-devcryptoeng Build the /dev/crypto engine. It is automatically selected on BSD implementations, in which case it can be disabled with @@ -626,10 +640,19 @@ Take note of the VAR=value documentation below and how these flags interact with those variables. - -xxx, +xxx + -xxx, +xxx, /xxx Additional options that are not otherwise recognised are - passed through as they are to the compiler as well. Again, - consult your compiler documentation. + passed through as they are to the compiler as well. + Unix-style options beginning with a '-' or '+' and + Windows-style options beginning with a '/' are recognized. + Again, consult your compiler documentation. + + If the option contains arguments separated by spaces, + then the URL-style notation %20 can be used for the space + character in order to avoid having to quote the option. + For example, -opt%20arg gets expanded to -opt arg. + In fact, any ASCII character can be encoded as %xx using its + hexadecimal encoding. Take note of the VAR=value documentation below and how these flags interact with those variables. @@ -805,8 +828,8 @@ Configure creates a build file ("Makefile" on Unix, "makefile" on Windows and "descrip.mms" on OpenVMS) from a suitable template in Configurations, - and defines various macros in include/openssl/opensslconf.h (generated from - include/openssl/opensslconf.h.in). + and defines various macros in include/openssl/configuration.h (generated + from include/openssl/configuration.h.in). 1c. Configure OpenSSL for building outside of the source tree. @@ -899,11 +922,17 @@ malfunction with Perl). You may want increased verbosity, that can be accomplished like this: - $ make VERBOSE=1 test # Unix + Verbosity on failure only (make macro VERBOSE_FAILURE or VF): + + $ make VF=1 test # Unix + $ mms /macro=(VF=1) test ! OpenVMS + $ nmake VF=1 test # Windows - $ mms /macro=(VERBOSE=1) test ! OpenVMS + Full verbosity (make macro VERBOSE or V): - $ nmake VERBOSE=1 test # Windows + $ make V=1 test # Unix + $ mms /macro=(V=1) test ! OpenVMS + $ nmake V=1 test # Windows If you want to run just one or a few specific tests, you can use the make variable TESTS to specify them, like this: @@ -914,7 +943,7 @@ And of course, you can combine (Unix example shown): - $ make VERBOSE=1 TESTS='test_rsa test_dsa' test + $ make VF=1 TESTS='test_rsa test_dsa' test You can find the list of available tests like this: @@ -941,8 +970,11 @@ $ mms install ! OpenVMS $ nmake install # Windows - This will install all the software components in this directory - tree under PREFIX (the directory given with --prefix or its + Note that in order to perform the install step above you need to have + appropriate permissions to write to the installation directory. + + The above commands will install all the software components in this + directory tree under PREFIX (the directory given with --prefix or its default): Unix: @@ -998,6 +1030,12 @@ for private key files. misc Various scripts. + The installation directory should be appropriately protected to ensure + unprivileged users cannot make changes to OpenSSL binaries or files, or + install engines. If you already have a pre-installed version of OpenSSL as + part of your Operating System it is recommended that you do not overwrite + the system version and instead install to somewhere else. + 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 @@ -1083,7 +1121,7 @@ HASHBANGPERL The command string for the Perl executable to insert in the - #! line of perl scripts that will be publically installed. + #! line of perl scripts that will be publicly installed. Default: /usr/bin/env perl Note: the value of this variable is added to the same scripts on all platforms, but it's only relevant on Unix-like platforms. @@ -1110,7 +1148,15 @@ described here. Examine the Makefiles themselves for the full list. all - The default target to build all the software components. + The target to build all the software components and + documentation. + + build_sw + Build all the software components. + THIS IS THE DEFAULT TARGET. + + build_docs + Build all documentation components. clean Remove all build artefacts and return the directory to a "clean"