X-Git-Url: https://git.openssl.org/?p=openssl.git;a=blobdiff_plain;f=INSTALL;h=20071481608f1fe4550bf8325e5454a3eff6ae4c;hp=ed7849e7cbdc0c85b82dc1efeca8b9b769220055;hb=93880ce1338280aa048c4c65886fcd07c6147491;hpb=ea24fe29968299ee68c70467ef4dd2cbc53bbee9 diff --git a/INSTALL b/INSTALL index ed7849e7cb..2007148160 100644 --- a/INSTALL +++ b/INSTALL @@ -15,8 +15,8 @@ header files * a supported operating system - For additional platform specific requirements and other details, - please read one of these: + For additional platform specific requirements, solutions to specific + issues and other details, please read one of these: * NOTES.VMS (OpenVMS) * NOTES.WIN (any supported Windows) @@ -310,6 +310,13 @@ no-err Don't compile in any error strings. + enable-external-tests + Enable building of integration with external test suites. + This is a developer option and may not work on all platforms. + The only supported external test suite at the current time is + the BoringSSL test suite. See the file test/README.external + for further details. + no-filenames Don't compile in filename and line number information (e.g. for errors and memory allocation). @@ -326,9 +333,6 @@ available if the GOST algorithms are also available through loading an externally supplied engine. - enable-heartbeats - Build support for DTLS heartbeats. - no-hw-padlock Don't build the padlock engine. @@ -408,6 +412,9 @@ the OpenSSL tests also use the command line applications the tests will also be skipped. + no-tests + Don't build test programs or run any test. + no-threads Don't try to build with support for multi-threaded applications. @@ -457,6 +464,12 @@ specific configuration, e.g. "-m32" to build x86 code on an x64 system. + enable-tls1_3 + TODO(TLS1.3): Make this enabled by default + Build support for TLS1.3. Note: This is a WIP feature and + does not currently interoperate with other TLS1.3 + implementations! Use with caution!! + no- Don't build support for negotiating the specified SSL/TLS protocol (one of ssl, ssl3, tls, tls1, tls1_1, tls1_2, dtls, @@ -479,10 +492,9 @@ no- Build without support for the specified algorithm, where is one of: bf, blake2, camellia, cast, chacha, cmac, - des, dh, dsa, ecdh, ecdsa, idea, md4, md5, mdc2, ocb, - ploy1305, rc2, rc4, rmd160, scrypt, seed or whirlpool. The - "ripemd" algorithm is deprecated and if used is synonymous - with rmd160. + des, dh, dsa, ecdh, ecdsa, idea, md4, mdc2, ocb, poly1305, + rc2, rc4, rmd160, scrypt, seed or whirlpool. The "ripemd" + algorithm is deprecated and if used is synonymous with rmd160. -Dxxx, -lxxx, -Lxxx, -fxxx, -mXXX, -Kxxx These system specific options will be passed through to the @@ -602,17 +614,14 @@ ("openssl"). The libraries will be built in the top-level directory, and the binary will be in the "apps" subdirectory. - If the build fails, look at the output. There may be reasons for - the failure that aren't problems in OpenSSL itself (like missing - standard headers). If you are having problems you can get help by - sending an email to the openssl-users email list (see - https://www.openssl.org/community/mailinglists.html for details). If it - is a bug with OpenSSL itself, please report the problem to - (note that your message will be recorded in the request - tracker publicly readable at - https://www.openssl.org/community/index.html#bugs and will be - forwarded to a public mailing list). Please check out the request - tracker. Maybe the bug was already reported or has already been + If the build fails, look at the output. There may be reasons + for the failure that aren't problems in OpenSSL itself (like + missing standard headers). If you are having problems you can + get help by sending an email to the openssl-users email list (see + https://www.openssl.org/community/mailinglists.html for details). If + it is a bug with OpenSSL itself, please open an issue on GitHub, at + https://github.com/openssl/openssl/issues. Please review the existing + ones first; maybe the bug was already reported or has already been fixed. (If you encounter assembler error messages, try the "no-asm" @@ -667,6 +676,9 @@ Please send bug reports to . + For more details on how the make variables TESTS can be used, + see section TESTS in Detail below. + 4. If everything tests ok, install OpenSSL with $ make install # Unix @@ -770,6 +782,13 @@ AR The name of the ar executable to use. + BUILDFILE + Use a different build file name than the platform default + ("Makefile" on Unixly platforms, "makefile" on native Windows, + "descrip.mms" on OpenVMS). This requires that there is a + corresponding build file template. See Configurations/README + for further information. + CC The compiler to use. Configure will attempt to pick a default compiler for your platform but this choice can be overridden @@ -786,16 +805,25 @@ OPENSSL_LOCAL_CONFIG_DIR OpenSSL comes with a database of information about how it - should be built on different platforms. This information is - held in ".conf" files in the Configurations directory. See the + should be built on different platforms as well as build file + templates for those platforms. The database is comprised of + ".conf" files in the Configurations directory. The build + file templates reside there as well as ".tmpl" files. See the file Configurations/README for further information about the - format of ".conf" files. As well as the standard ".conf" files - it is possible to create your own ".conf" files and store them - locally, outside the OpenSSL source tree. This environment - variable can be set to the directory where these files are held. + format of ".conf" files as well as information on the ".tmpl" + files. + In addition to the standard ".conf" and ".tmpl" files, it is + possible to create your own ".conf" and ".tmpl" files and store + them locally, outside the OpenSSL source tree. This environment + variable can be set to the directory where these files are held + and will be considered by Configure before it looks in the + standard directories. PERL The name of the Perl executable to use when building OpenSSL. + This variable is used in config script only. Configure on the + other hand imposes the interpreter by which it itself was + executed on the whole build procedure. HASHBANGPERL The command string for the Perl executable to insert in the @@ -866,6 +894,38 @@ automatically generated files; add new error codes or add new (or change the visibility of) public API functions. (Unix only). + TESTS in Detail + --------------- + + The make variable TESTS supports a versatile set of space separated tokens + with which you can specify a set of tests to be performed. With a "current + set of tests" in mind, initially being empty, here are the possible tokens: + + alltests The current set of tests becomes the whole set of available + tests (as listed when you do 'make list-tests' or similar). + xxx Adds the test 'xxx' to the current set of tests. + -xxx Removes 'xxx' from the current set of tests. If this is the + first token in the list, the current set of tests is first + assigned the whole set of available tests, effectively making + this token equivalent to TESTS="alltests -xxx" + + Also, all tokens except for "alltests" may have wildcards, such as *. + (on Unix and Windows, BSD style wildcards are supported, while on VMS, + it's VMS style wildcards) + + Example: All tests except for the fuzz tests: + + $ make TESTS=-test_fuzz test + + or (if you want to be explicit) + + $ make TESTS='alltests -test_fuzz' test + + Example: All tests that have a name starting with "test_ssl" but not those + starting with "test_ssl_": + + $ make TESTS='test_ssl* -test_ssl_*' test + Note on multi-threading ----------------------- @@ -887,8 +947,8 @@ supported. If your platform does not provide pthreads or Windows threads then you should Configure with the "no-threads" option. - Note on shared libraries - ------------------------ + Notes on shared libraries + ------------------------- For most systems the OpenSSL Configure script knows what is needed to build shared libraries for libcrypto and libssl. On these systems @@ -897,6 +957,31 @@ where OpenSSL does not know how to build shared libraries the "no-shared" option will be forced and only static libraries will be created. + Shared libraries are named a little differently on different platforms. + One way or another, they all have the major OpenSSL version number as + part of the file name, i.e. for OpenSSL 1.1.x, 1.1 is somehow part of + the name. + + On most POSIXly platforms, shared libraries are named libcrypto.so.1.1 + and libssl.so.1.1. + + on Cygwin, shared libraries are named cygcrypto-1.1.dll and cygssl-1.1.dll + with import libraries libcrypto.dll.a and libssl.dll.a. + + On Windows build with MSVC or using MingW, shared libraries are named + libcrypto-1_1.dll and libssl-1_1.dll for 32-bit Windows, libcrypto-1_1-x64.dll + and libssl-1_1-x64.dll for 64-bit x86_64 Windows, and libcrypto-1_1-ia64.dll + and libssl-1_1-ia64.dll for IA64 Windows. With MSVC, the import libraries + are named libcrypto.lib and libssl.lib, while with MingW, they are named + libcrypto.dll.a and libssl.dll.a. + + On VMS, shareable images (VMS speak for shared libraries) are named + ossl$libcrypto0101_shr.exe and ossl$libssl0101_shr.exe. However, when + OpenSSL is specifically built for 32-bit pointers, the shareable images + are named ossl$libcrypto0101_shr32.exe and ossl$libssl0101_shr32.exe + instead, and when built for 64-bit pointers, they are named + ossl$libcrypto0101_shr64.exe and ossl$libssl0101_shr64.exe. + Note on random number generation --------------------------------