DOC: Mention Configure consistently

'config' is now a mere wrapper for backward compatibility.
All documentation is changed accordingly.

Reviewed-by: Tim Hudson <tjh@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11230)

7 files changed, 86 insertions, 101 deletions

diff --git a/CHANGES.md b/CHANGES.md
index 7da5ccd55c..585a451d18 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -23,6 +23,13 @@ OpenSSL 3.0
 
 ### Changes between 1.1.1 and 3.0 [xx XXX xxxx]
 
+ * 'Configure' has been changed to figure out the configuration target if
+   none is given on the command line.  Consequently, the 'config' script is
+   now only a mere wrapper.  All documentation is changed to only mention
+   'Configure'.
+
+   *Rich Salz and Richard Levitte*
+
  * Added a library context that applications as well as other
    libraries can use to form a separate context within which libcrypto
    operations are performed.
diff --git a/Configure b/Configure
index 5bd7abca92..3129a23f9d 100755
--- a/Configure
+++ b/Configure
@@ -3050,7 +3050,6 @@ sub usage
                         }
                 print STDERR $i . " ";
                 }
-        print STDERR "\n\nNOTE: If in doubt, on Unix-ish systems use './config'.\n";
         exit(1);
         }
 
diff --git a/HACKING b/HACKING
index a9e39d0258..abf199f541 100644
--- a/HACKING
+++ b/HACKING
@@ -8,7 +8,7 @@
 
  After that perform the following steps:
 
-    ./config -Werror --strict-warnings [your-options]
+    ./Configure -Werror --strict-warnings [your-options]
     make update
     make
     make test
diff --git a/INSTALL.md b/INSTALL.md
index 445c28b127..b6106ba6d2 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -151,7 +151,7 @@ OpenSSL for production use.
 
 ### Unix / Linux / macOS
 
-    $ ./config
+    $ ./Configure
     $ make
     $ make test
 
@@ -159,7 +159,7 @@ OpenSSL for production use.
 
 Use the following commands to build OpenSSL:
 
-    $ @config
+    $ perl Configure
     $ mms
     $ mms test
 
@@ -168,7 +168,7 @@ Use the following commands to build OpenSSL:
 If you are using Visual Studio, open a Developer Command Prompt and
 and issue the following commands to build OpenSSL.
 
-    $ perl Configure { VC-WIN32 | VC-WIN64A | VC-WIN64I | VC-CE }
+    $ perl Configure
     $ nmake
     $ nmake test
 
@@ -262,16 +262,16 @@ for 32bit binaries on 64bit Windows (WOW64).
 #### Installing to a different location
 
 To install OpenSSL to a different location (for example into your home
-directory for testing purposes) run config as shown in the following
+directory for testing purposes) run Configure as shown in the following
 examples.
 
 On Unix:
 
-    $ ./config --prefix=/opt/openssl --openssldir=/usr/local/ssl
+    $ ./Configure --prefix=/opt/openssl --openssldir=/usr/local/ssl
 
 On OpenVMS:
 
-    $ @config --prefix=PROGRAM:[INSTALLS] --openssldir=SYS$MANAGER:[OPENSSL]
+    $ perl Configure --prefix=PROGRAM:[INSTALLS] --openssldir=SYS$MANAGER:[OPENSSL]
 
 Note: if you do add options to the configuration command, please make sure
 you've read more than just this Quick Start, such as relevant `NOTES.*` files,
@@ -281,10 +281,10 @@ in otherwise unexpected ways.
 Configuration Options
 =====================
 
-There are several options to ./config (or ./Configure) to customize
-the build (note that for Windows, the defaults for `--prefix` and
-`--openssldir` depend in what configuration is used and what Windows
-implementation OpenSSL is built on.  More notes on this in NOTES.WIN):
+There are several options to ./Configure to customize the build (note that
+for Windows, the defaults for `--prefix` and `--openssldir` depend in what
+configuration is used and what Windows implementation OpenSSL is built on.
+More notes on this in NOTES.WIN):
 
 API Level
 ---------
@@ -311,20 +311,22 @@ Cross Compile Prefix
 
 The PREFIX to include in front of commands for your toolchain.
 
-It is likely to have to end with dash, e.g.  a-b-c- would invoke GNU compiler as
-a-b-c-gcc, etc.  Unfortunately cross-compiling is too case-specific to put
+It is likely to have to end with dash, e.g.  a-b-c- would invoke GNU compiler
+as a-b-c-gcc, etc.  Unfortunately cross-compiling is too case-specific to put
 together one-size-fits-all instructions.  You might have to pass more flags or
-set up environment variables to actually make it work.  Android and iOS cases are
-discussed in corresponding `Configurations/15-*.conf` files.  But there are cases
-when this option alone is sufficient.  For example to build the mingw64 target on
-Linux `--cross-compile-prefix=x86_64-w64-mingw32-` works.  Naturally provided
-that mingw packages are installed.  Today Debian and Ubuntu users have option to
-install a number of prepackaged cross-compilers along with corresponding
-run-time and development packages for "alien" hardware.  To give another example
-`--cross-compile-prefix=mipsel-linux-gnu-` suffices in such case.  Needless to
-mention that you have to invoke `./Configure`, not `./config`, and pass your target
-name explicitly.  Also, note that `--openssldir` refers to target's file system,
-not one you are building on.
+set up environment variables to actually make it work.  Android and iOS cases
+are discussed in corresponding `Configurations/15-*.conf` files.  But there are
+cases when this option alone is sufficient.  For example to build the mingw64
+target on Linux `--cross-compile-prefix=x86_64-w64-mingw32-` works.  Naturally
+provided that mingw packages are installed.  Today Debian and Ubuntu users
+have option to install a number of prepackaged cross-compilers along with
+corresponding run-time and development packages for "alien" hardware.  To give
+another example `--cross-compile-prefix=mipsel-linux-gnu-` suffices in such
+case.
+
+For cross compilation, you must [configure manually](#manual-configuration).
+Also, note that `--openssldir` refers to target's file system, not one you are
+building on.
 
 Build Type
 ----------
@@ -1026,7 +1028,7 @@ configuration.  The following variables are supported:
 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
+    $ ./Configure -DFOO CPPFLAGS=-DBAR -DCOOKIE
 
 Backward compatibility note:
 
@@ -1038,11 +1040,11 @@ for the following:
 
 For example, the following command will not see -DBAR:
 
-    $ CPPFLAGS=-DBAR ./config -DCOOKIE
+    $ CPPFLAGS=-DBAR ./Configure -DCOOKIE
 
 However, the following will see both set variables:
 
-    $ CC=gcc CROSS_COMPILE=x86_64-w64-mingw32- ./config -DCOOKIE
+    $ CC=gcc CROSS_COMPILE=x86_64-w64-mingw32- ./Configure -DCOOKIE
 
 If CC is set, it is advisable to also set CXX to ensure both the C and C++
 compiler are in the same "family".  This becomes relevant with
@@ -1055,15 +1057,14 @@ compiler are in the same "family".  This becomes relevant with
 
 Reconfigure from earlier data.
 
-This fetches the previous command line options and environment from data saved
-in "configdata.pm" and runs the configuration process again, using these
-options and environment.  Note: NO other option is permitted together with
-"reconf".  This means that you also MUST use "./Configure" (or what corresponds
-to that on non-Unix platforms) directly to invoke this option.  Note: The
-original configuration saves away values for ALL environment variables that were
-used, and if they weren't defined, they are still saved away with information
-that they weren't originally defined.  This information takes precedence over
-environment variables that are defined when reconfiguring.
+This fetches the previous command line options and environment from data
+saved in "configdata.pm" and runs the configuration process again, using
+these options and environment.  Note: NO other option is permitted together
+with "reconf".  Note: The original configuration saves away values for ALL
+environment variables that were used, and if they weren't defined, they are
+still saved away with information that they weren't originally defined.
+This information takes precedence over environment variables that are
+defined when reconfiguring.
 
 Displaying configuration data
 -----------------------------
@@ -1097,42 +1098,26 @@ script.
 
 #### Unix / Linux / macOS
 
-    $ ./config [[ options ]]
+    $ ./Configure [[ options ]]
 
 #### OpenVMS
 
-    $ @config [[ options ]]
+    $ perl Configure [[ options ]]
 
 #### Windows
 
-Automatic configuration is not available on Windows.
-
-For the remainder of this text, the Unix form will be used in all examples,
-please use the appropriate form for your platform.
-
-You can run
-
-    $ ./config -t
-
-to see whether your target is guessed correctly.  If you want to use a different
-compiler, you  are cross-compiling for another platform, or the ./config guess
-was wrong for other reasons, see the [Manual Configuration](#manual-configuration)
-section.  Oherwise continue with the [Build OpenSSL](#build-openssl) section below.
-
-On some systems, you can include debugging information as follows:
-
-      $ ./config -d [[ options ]]
+    $ perl Configure [[ options ]]
 
 ### Manual Configuration
 
 OpenSSL knows about a range of different operating system, hardware and
 compiler combinations.  To see the ones it knows about, run
 
-    $ ./Configure                                    # Unix
+    $ ./Configure LIST                               # Unix
 
 or
 
-    $ perl Configure                                 # All other platforms
+    $ perl Configure LIST                            # All other platforms
 
 For the remainder of this text, the Unix form will be used in all examples.
 Please use the appropriate form for your platform.
@@ -1171,29 +1156,21 @@ directory and invoking the configuration commands from there.
 
     $ mkdir /var/tmp/openssl-build
     $ cd /var/tmp/openssl-build
-    $ /PATH/TO/OPENSSL/SOURCE/config [[ options ]]
-
-or
-
-    $ /PATH/TO/OPENSSL/SOURCE/Configure {{ target }} [[ options ]]
+    $ /PATH/TO/OPENSSL/SOURCE/Configure [[ options ]]
 
 #### OpenVMS example
 
     $ set default sys$login:
     $ create/dir [.tmp.openssl-build]
     $ set default [.tmp.openssl-build]
-    $ @[PATH.TO.OPENSSL.SOURCE]config [[ options ]]
-
-or
-
-    $ @[PATH.TO.OPENSSL.SOURCE]Configure {{ target }} [[ options ]]
+    $ perl D:[PATH.TO.OPENSSL.SOURCE]Configure [[ options ]]
 
 #### Windows example
 
     $ C:
     $ mkdir \temp-openssl
     $ cd \temp-openssl
-    $ perl d:\PATH\TO\OPENSSL\SOURCE\Configure {{ target }} [[ options ]]
+    $ perl d:\PATH\TO\OPENSSL\SOURCE\Configure [[ options ]]
 
 Paths can be relative just as well as absolute.  Configure will do its best
 to translate them to relative paths whenever possible.
@@ -1356,8 +1333,7 @@ Environment Variables
 
 A number of environment variables can be used to provide additional control
 over the build process.  Typically these should be defined prior to running
-config or Configure.  Not all environment variables are relevant to all
-platforms.
+Configure.  Not all environment variables are relevant to all platforms.
 
     AR
                    The name of the ar executable to use.
@@ -1401,9 +1377,8 @@ platforms.
 
     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.
+                   Only needed if builing should use a different Perl executable
+                   than what is used to run the Configure script.
 
     HASHBANGPERL
                    The command string for the Perl executable to insert in the
@@ -1557,14 +1532,14 @@ Configuration Problems
 
 ### Selecting the correct target
 
-The `./config` script tries hard to guess your operating system, but in some
+The `./Configure` script tries hard to guess your operating system, but in some
 cases it does not succeed. You will see a message like the following:
 
-    $ ./config
+    $ ./Configure
     Operating system: x86-whatever-minix
     This system (minix) is not supported. See file INSTALL for details.
 
-Even if the automatic target selection by the `./config` script fails, chances
+Even if the automatic target selection by the `./Configure` script fails, chances
 are that you still might find a suitable target in the Configurations directory,
 which you can supply to the `./Configure` command, possibly after some adjustment.
 
@@ -1586,7 +1561,7 @@ a Perl list `my %targets = ( ... )`.
     ...
     )
 
-If you call `.\Configure` without arguments, it will give you a list of all
+If you call `./Configure` without arguments, it will give you a list of all
 known targets. Using `grep`, you can lookup the target definition in the
 Configurations directory. For example the "android-x86_64" can be found in
 Configurations/15-android.conf.
@@ -1605,7 +1580,7 @@ More about our support resources can be found in the [SUPPORT][] file.
 
 ### Configuration Errors
 
-If the `./config` or `./Configure`  command fails with an error message,
+If the `./Configure` or `./Configure` command fails with an error message,
 read the error message carefully and try to figure out whether you made
 a mistake (e.g., by providing a wrong option), or whether the script is
 working incorrectly. If you think you encountered a bug, please
diff --git a/NOTES.ANDROID b/NOTES.ANDROID
index 57c1ee9d1b..0173eca73b 100644
--- a/NOTES.ANDROID
+++ b/NOTES.ANDROID
@@ -15,19 +15,22 @@
  Configuration
  -------------
 
- Android is a naturally cross-compiled target and you can't use ./config.
- You have to use ./Configure and name your target explicitly; there are
- android-arm, android-arm64, android-mips, android-mip64, android-x86
- and android-x86_64 (*MIPS targets are no longer supported with NDK R20+).
- Do not pass --cross-compile-prefix (as you might be tempted), as it will
- be "calculated" automatically based on chosen platform. Though you still
- need to know the prefix to extend your PATH, in order to invoke
- $(CROSS_COMPILE)clang [*gcc on NDK 19 and lower] and company. (Configure
- will fail and give you a hint if you get it wrong.) Apart from PATH
- adjustment you need to set ANDROID_NDK_ROOT environment to point at the
- NDK directory. If you're using a side-by-side NDK the path will look
- something like /some/where/android-sdk/ndk/<ver>, and for a standalone
- NDK the path will be something like /some/where/android-ndk-<ver>.
+ Android is a cross-compiled target and you can't rely on ./Configure
+ to find out the configuration target for you.  You have to name your
+ target explicitly; there are android-arm, android-arm64, android-mips,
+ android-mip64, android-x86 and android-x86_64 (*MIPS targets are no
+ longer supported with NDK R20+).
+
+ Do not pass --cross-compile-prefix (as you might be tempted), as it
+ will be "calculated" automatically based on chosen platform. However,
+ you still need to know the prefix to extend your PATH, in order to
+ invoke $(CROSS_COMPILE)clang [*gcc on NDK 19 and lower] and company.
+ (Configure will fail and give you a hint if you get it wrong.)
+
+ Apart from PATH adjustment you need to set ANDROID_NDK_ROOT environment
+ to point at the NDK directory. If you're using a side-by-side NDK the path
+ will look something like /some/where/android-sdk/ndk/<ver>, and for a
+ standalone NDK the path will be something like /some/where/android-ndk-<ver>.
  Both variables are significant at both configuration and compilation times.
  The NDK customarily supports multiple Android API levels, e.g. android-14,
  android-21, etc. By default latest API level is chosen. If you need to
@@ -35,13 +38,14 @@
  with N being the numerical value of the target platform version. For example,
  to compile for Android 10 arm64 with a side-by-side NDK r20.0.5594570
 
-	export ANDROID_NDK_ROOT=/home/whoever/Android/android-sdk/ndk/20.0.5594570
-	PATH=$ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/bin:$ANDROID_NDK_ROOT/toolchains/arm-linux-androideabi-4.9/prebuilt/linux-x86_64/bin:$PATH
-	./Configure android-arm64 -D__ANDROID_API__=29
-	make
+    export ANDROID_NDK_ROOT=/home/whoever/Android/android-sdk/ndk/20.0.5594570
+    PATH=$ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/bin:$ANDROID_NDK_ROOT/toolchains/arm-linux-androideabi-4.9/prebuilt/linux-x86_64/bin:$PATH
+    ./Configure android-arm64 -D__ANDROID_API__=29
+    make
 
- Older versions of the NDK have GCC under their common prebuilt tools directory, so the bin path
- will be slightly different. EG: to compile for ICS on ARM with NDK 10d:
+ Older versions of the NDK have GCC under their common prebuilt tools
+ directory, so the bin path will be slightly different. EG: to compile
+ for ICS on ARM with NDK 10d:
 
     export ANDROID_NDK_ROOT=/some/where/android-ndk-10d
     PATH=$ANDROID_NDK_ROOT/toolchains/arm-linux-androideabi-4.8/prebuilt/linux-x86_64/bin:$PATH
diff --git a/NOTES.UNIX b/NOTES.UNIX
index 6c291cbab6..0e3c099ea2 100644
--- a/NOTES.UNIX
+++ b/NOTES.UNIX
@@ -59,7 +59,7 @@
  used with the runtime shared library search path options, as shown in
  this example:
 
-    $ ./config --prefix=/usr/local/ssl --openssldir=/usr/local/ssl \
+    $ ./Configure --prefix=/usr/local/ssl --openssldir=/usr/local/ssl \
         '-Wl,-rpath,$(LIBRPATH)'
 
  On modern ELF based systems, there are two runtime search paths tags to
@@ -88,7 +88,7 @@
  Debian GNU/Linux systems rather than DT_RPATH is to tell the linker to
  set new dtags, like this:
 
-    $ ./config --prefix=/usr/local/ssl --openssldir=/usr/local/ssl \
+    $ ./Configure --prefix=/usr/local/ssl --openssldir=/usr/local/ssl \
         '-Wl,--enable-new-dtags,-rpath,$(LIBRPATH)'
 
  It might be worth noting that some/most ELF systems implement support
diff --git a/NOTES.WIN b/NOTES.WIN
index bc6e3d2c32..a5792647af 100644
--- a/NOTES.WIN
+++ b/NOTES.WIN
@@ -140,7 +140,7 @@
    or
      ./Configure mingw64 ...
    or
-     ./config ...
+     ./Configure ...
    for the default architecture.
 
    Apart from that, follow the Unix / Linux instructions in INSTALL.md.