INSTALL: Add a note about backward compatibility and "make variables"

[openssl.git] / INSTALL

diff --git a/INSTALL b/INSTALL
index 48c25e6519134351450b0c3f551b065db7e161f3..e99b1f00b8e4b72c3e350f07582bb5a41b58b098 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -482,27 +482,24 @@
                    likely to complement configuration command line with
                    suitable compiler-specific option.
 
-  enable-tls1_3
-                   TODO(TLS1.3): Make this enabled by default
-                   Build support for TLS1.3. Note: This is a WIP feature and
-                   only a single draft version is supported.  Implementations
-                   of different draft versions will negotiate TLS 1.2 instead
-                   of (draft) TLS 1.3.  Use with caution!!
-
   no-<prot>
                    Don't build support for negotiating the specified SSL/TLS
-                   protocol (one of ssl, ssl3, tls, tls1, tls1_1, tls1_2, dtls,
-                   dtls1 or dtls1_2). If "no-tls" is selected then all of tls1,
-                   tls1_1 and tls1_2 are disabled. Similarly "no-dtls" will
-                   disable dtls1 and dtls1_2. The "no-ssl" option is synonymous
-                   with "no-ssl3". Note this only affects version negotiation.
-                   OpenSSL will still provide the methods for applications to
-                   explicitly select the individual protocol versions.
+                   protocol (one of ssl, ssl3, tls, tls1, tls1_1, tls1_2,
+                   tls1_3, dtls, dtls1 or dtls1_2). If "no-tls" is selected then
+                   all of tls1, tls1_1, tls1_2 and tls1_3 are disabled.
+                   Similarly "no-dtls" will disable dtls1 and dtls1_2. The
+                   "no-ssl" option is synonymous with "no-ssl3". Note this only
+                   affects version negotiation. OpenSSL will still provide the
+                   methods for applications to explicitly select the individual
+                   protocol versions.
 
   no-<prot>-method
                    As for no-<prot> but in addition do not build the methods for
                    applications to explicitly select individual protocol
-                   versions.
+                   versions. Note that there is no "no-tls1_3-method" option
+                   because there is no application method for TLSv1.3. Using
+                   individual protocol methods directly is deprecated.
+                   Applications should use TLS_method() instead.
 
   enable-<alg>
                    Build with support for the specified algorithm, where <alg>
@@ -539,7 +536,7 @@
                    these flags interact with those variables.
 
   VAR=value
-                   Assignment if environment variable for Configure.  These
+                   Assignment of environment variable for Configure.  These
                    work just like normal environment variable assignments,
                    but are supported on all platforms and are confined to
                    the configuration scripts only.  These assignments override
@@ -584,29 +581,29 @@
                    RCFLAGS         Flags for the Windows reources manipulator.
                    RM              The command to remove files and directories.
 
-                   These can be mixed with flags given on the command line.
-                   Any variable assignment resets any corresponding flags
-                   given before it, so for example:
+                   These cannot be mixed with compiling / linking flags given
+                   on the command line.  In other words, something like this
+                   isn't permitted.
 
                        ./config -DFOO CPPFLAGS=-DBAR -DCOOKIE
 
-                   Will end up having 'CPPFLAGS=-DBAR -DCOOKIE'.
-
-                   Here is how the flags documented above are collected as
-                   augmentation of these variables:
-
-                   -Dxxx           xxx is collected in CPPDEFINES
-                   -Ixxx           xxx is collected in CPPINCLUDES
-                   -Wp,xxx         collected in CPPFLAGS
-                   -Lxxx           collected in LDFLAGS
-                   -lxxx           collected in LDLIBS
-                   -Wp,xxx         collected in LDLIBS
-                   -rpath xxx      collected in LDLIBS
-                   -R xxx          collected in LDLIBS
-                   -framework xxx  collected in LDLIBS
-                   -static         collected in LDLIBS
-                   -xxx            collected in CFLAGS
-                   +xxx            collected in CFLAGS
+                   Backward compatibility note:
+
+                   To be compatible with older configuration scripts, the
+                   environment variables are ignored if compiling / linking
+                   flags are given on the command line, except for these:
+
+                   AR, CC, CXX, CROSS_COMPILE, HASHBANGPERL, PERL, RANLIB, RC
+                   and WINDRES
+
+                   For example, the following command will not see -DBAR:
+
+                        CPPFLAGS=-DBAR ./config -DCOOKIE
+
+                   However, the following will see both set variables:
+
+                        CC=gcc CROSS_COMPILE=x86_64-w64-mingw32- \
+                        ./config -DCOOKIE
 
   reconf
   reconfigure