+Intro
+=====
+
+This directory contains a few sets of files that are used for
+configuration in diverse ways:
+
+ *.conf Target platform configurations, please read
+ 'Configurations of OpenSSL target platforms' for more
+ information.
+ *.tmpl Build file templates, please read 'Build-file
+ programming with the "unified" build system' as well
+ as 'Build info files' for more information.
+ *.pm Helper scripts / modules for the main `Configure`
+ script. See 'Configure helper scripts for more
+ information.
+
+
Configurations of OpenSSL target platforms
==========================================
sys_id => System identity for systems where that
is difficult to determine automatically.
- cc => The compiler command, usually one of "cc",
+ enable => Enable specific configuration features.
+ This MUST be an array of words.
+ disable => Disable specific configuration features.
+ This MUST be an array of words.
+ Note: if the same feature is both enabled
+ and disabled, disable wins.
+
+ cc => The C compiler command, usually one of "cc",
"gcc" or "clang". This command is normally
also used to link object files and
libraries into the final program.
+ cxx => The C++ compiler command, usually one of
+ "c++", "g++" or "clang++". This command is
+ also used when linking a program where at
+ least one of the object file is made from
+ C++ source.
cflags => Flags that are used at all times when
- compiling.
+ compiling C object files.
+ cxxflags => Flags that are used at all times when
+ compiling C++ object files. If unset, it
+ gets the same value as cflags.
defines => As an alternative, macro definitions may be
present here instead of in `cflags'. If
given here, they MUST be as an array of the
files. On unix, this defaults to "" (NOTE:
this is here for future use, it's not
implemented yet)
+ shlib_variant => A "variant" identifier inserted between the base
+ shared library name and the extension. On "unixy"
+ platforms (BSD, Linux, Solaris, MacOS/X, ...) this
+ supports installation of custom OpenSSL libraries
+ that don't conflict with other builds of OpenSSL
+ installed on the system. The variant identifier
+ becomes part of the SONAME of the library and also
+ any symbol versions (symbol versions are not used or
+ needed with MacOS/X). For example, on a system
+ where a default build would normally create the SSL
+ shared library as 'libssl.so -> libssl.so.1.1' with
+ the value of the symlink as the SONAME, a target
+ definition that sets 'shlib_variant => "-abc"' will
+ create 'libssl.so -> libssl-abc.so.1.1', again with
+ an SONAME equal to the value of the symlink. The
+ symbol versions associated with the variant library
+ would then be 'OPENSSL_ABC_<version>' rather than
+ the default 'OPENSSL_<version>'. The string inserted
+ into symbol versions is obtained by mapping all
+ letters in the "variant" identifier to upper case
+ and all non-alphanumeric characters to '_'.
thread_scheme => The type of threads is used on the
configured platform. Currently known
to have the different variants in different
directories.
- bn_ops => Building options (was just bignum options
- in the earlier history of this option,
- hence the name). This a string of words
- that describe properties on the designated
- target platform, such as the type of
- integers used to build up the bitnum,
- different ways to implement certain ciphers
- and so on. To fully comprehend the
+ bn_ops => Building options (was just bignum options in
+ the earlier history of this option, hence the
+ name). This is a string of words that describe
+ algorithms' implementation parameters that
+ are optimal for the designated target platform,
+ such as the type of integers used to build up
+ the bignum, different ways to implement certain
+ ciphers and so on. To fully comprehend the
meaning, the best is to read the affected
source.
The valid words are:
- BN_LLONG use 'unsigned long long' in
- some bignum calculations.
- This has no value when
- SIXTY_FOUR_BIT or
- SIXTY_FOUR_BIT_LONG is given.
- RC4_CHAR makes the basic RC4 unit of
- calculation an unsigned char.
- SIXTY_FOUR_BIT processor registers
- are 64 bits, long is
- 32 bits, long long is
- 64 bits.
- SIXTY_FOUR_BIT_LONG processor registers
- are 64 bits, long is
- 64 bits.
- THIRTY_TWO_BIT processor registers
- are 32 bits.
+ THIRTY_TWO_BIT bignum limbs are 32 bits,
+ this is default if no
+ option is specified, it
+ works on any supported
+ system [unless "wider"
+ limb size is implied in
+ assembly code];
+ BN_LLONG bignum limbs are 32 bits,
+ but 64-bit 'unsigned long
+ long' is used internally
+ in calculations;
+ SIXTY_FOUR_BIT_LONG bignum limbs are 64 bits
+ and sizeof(long) is 8;
+ SIXTY_FOUR_BIT bignums limbs are 64 bits,
+ but execution environment
+ is ILP32;
+ RC4_CHAR RC4 key schedule is made
+ up of 'unsigned char's;
+ RC4_INT RC4 key schedule is made
+ up of 'unsigned int's;
EXPORT_VAR_AS_FN for shared libraries,
export vars as
accessor functions.
to be located in the source tree while files given through DEPEND are
expected to be located in the build tree)
+It's also possible to depend on static libraries explicitly:
+
+ DEPEND[foo]=libsomething.a
+ DEPEND[libbar]=libsomethingelse.a
+
+This should be rarely used, and care should be taken to make sure it's
+only used when supported. For example, native Windows build doesn't
+support build static libraries and DLLs at the same time, so using
+static libraries on Windows can only be done when configured
+'no-shared'.
+
For some libraries, we maintain files with public symbols and their
slot in a transfer vector (important on some platforms). It can be
declared like this:
""; # Make sure no lingering values end up in the Makefile
-}
+
+
+Configure helper scripts
+========================
+
+Configure uses helper scripts in this directory:
+
+Checker scripts
+---------------
+
+These scripts are per platform family, to check the integrity of the
+tools used for configuration and building. The checker script used is
+either {build_platform}-{build_file}-checker.pm or
+{build_platform}-checker.pm, where {build_platform} is the second
+'build_scheme' list element from the configuration target data, and
+{build_file} is 'build_file' from the same target data.
+
+If the check succeeds, the script is expected to end with a non-zero
+expression. If the check fails, the script can end with a zero, or
+with a `die`.