Configure: print generic advice when dying
[openssl.git] / Configurations / README
index c4a7413..4457b94 100644 (file)
@@ -1,10 +1,31 @@
+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
-------------------------------------------
+==========================================
 
-Target configurations are a collection of facts that we know about
+Configuration targets are a collection of facts that we know about
 different platforms and their capabilities.  We organise them in a
 hash table, where each entry represent a specific target.
 
+Note that configuration target names must be unique across all config
+files.  The Configure script does check that a config file doesn't
+have config targets that shadow config targets from other files.
+
 In each table entry, the following keys are significant:
 
         inherit_from    => Other targets to inherit values from.
@@ -17,54 +38,78 @@ In each table entry, the following keys are significant:
         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.
+
+        as              => The assembler command.  This is not always
+                           used (for example on Unix, where the C
+                           compiler is used instead).
+        asflags         => Default assembler command flags [4].
+        cpp             => The C preprocessor command, normally not
+                           given, as the build file defaults are
+                           usually good enough.
+        cppflags        => Default C preprocessor flags [4].
+        defines         => As an alternative, macro definitions may be
+                           given here instead of in `cppflags' [4].
+                           If given here, they MUST be as an array of
+                           the string such as "MACRO=value", or just
+                           "MACRO" for definitions without value.
+        includes        => As an alternative, inclusion directories
+                           may be given here instead of in `cppflags'
+                           [4].  If given here, the MUST be an array
+                           of strings, one directory specification
+                           each.
+        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.
-        cflags          => Flags that are used at all times when
-                           compiling.
-        debug_cflags    => Extra compilation flags used when making a
-                           debug build (when Configure receives the
-                           --debug option).  Typically something like
-                           "-g -O0".
-        release_cflags  => Extra compilation flags used when making a
-                           release build (when Configure receives the
-                           --release option, or doesn't receive the
-                           --debug option).  Typically something like
-                           "-O" or "-O3".
-        thread_cflags   => Extra compilation flags used when
-                           compiling with threading enabled.
-                           Explained further below.  [2]
-        shared_cflag    => Extra compilation flags used when
-                           compiling for shared libraries, typically
-                           something like "-fPIC".
-
-        ld              => the linker command, usually not defined
+        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          => Defaults C compiler flags [4].
+        cxxflags        => Default  C++ compiler flags [4].  If unset,
+                           it gets the same value as cflags.
+
+        (linking is a complex thing, see [3] below)
+        ld              => Linker command, usually not defined
                            (meaning the compiler command is used
                            instead).
                            (NOTE: this is here for future use, it's
                            not implemented yet)
-        lflags          => the flags that are used at all times when
-                           linking.  These can have a % sign in them
-                           showing where the OpenSSL libraries should
-                           appear, otherwise these flags will come
-                           last.  So in a typical links situation,
-                           this is a quick table of results:
+        lflags          => Default flags used when linking apps,
+                           shared libraries or DSOs [4].
+        ex_libs         => Extra libraries that are needed when
+                           linking shared libraries, DSOs or programs.
+                           The value is also assigned to Libs.private
+                           in $(libdir)/pkgconfig/libcrypto.pc.
 
-                           "-foo%-bar"  > -foo -lssl -lcrypto -bar
-                           "-foo%"      > -foo -lssl -lcrypto
-                           "-foo"       > -lssl -lcrypto -foo
-
-        debug_lflags    => Like debug_cflags, but used when linking.
-        release_lflags  => Like release_cflags, but used when linking.
-        shared_lflags   => Like shared_cflags, but used when linking.
+        shared_cppflags => Extra C preprocessor flags used when
+                           processing C files for shared libraries.
+        shared_cflag    => Extra C compiler flags used when compiling
+                           for shared libraries, typically something
+                           like "-fPIC".
+        shared_ldflag   => Extra linking flags used when linking
+                           shared libraries.
+        module_cppflags
+        module_cflags
+        module_ldflags  => Has the same function as the corresponding
+                           `shared_' attributes, but for building DSOs.
+                           When unset, they get the same values as the
+                           corresponding `shared_' attributes.
 
         ar              => The library archive command, the default is
                            "ar".
                            (NOTE: this is here for future use, it's
                            not implemented yet)
         arflags         => Flags to be used with the library archive
-                           command.
+                           command.  On Unix, this includes the
+                           command letter, 'r' by default.
 
         ranlib          => The library archive indexing command, the
                            default is 'ranlib' it it exists.
@@ -82,7 +127,36 @@ In each table entry, the following keys are significant:
                            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
+                           values are "(unknown)", "pthreads",
+                           "uithreads" (a.k.a solaris threads) and
+                           "winthreads".  Except for "(unknown)", the
+                           actual value is currently ignored but may
+                           be used in the future.  See further notes
+                           below [2].
         dso_scheme      => The type of dynamic shared objects to build
                            for.  This mostly comes into play with
                            engines, but can be used for other purposes
@@ -91,7 +165,7 @@ In each table entry, the following keys are significant:
                            that use dlopen() et al but do not have
                            fcntl.h), "DL" (shl_load() et al), "WIN32"
                            and "VMS".
-        perlasm_scheme  => The perlasm method used to created the
+        perlasm_scheme  => The perlasm method used to create the
                            assembler files used when compiling with
                            assembler implementations.
         shared_target   => The shared library building method used.
@@ -104,9 +178,11 @@ In each table entry, the following keys are significant:
                            some options.  In this case, the first
                            string in the list is the name of the build
                            scheme.
-                           Currently recognised build schemes are
-                           "mk1mf" and "unixmake".  Others may appear
-                           in the future.
+                           Currently recognised build scheme is "unified".
+                           For the "unified" build scheme, this item
+                           *must* be an array with the first being the
+                           word "unified" and the second being a word
+                           to identify the platform family.
 
         multilib        => On systems that support having multiple
                            implementations of a library (typically a
@@ -114,118 +190,92 @@ In each table entry, the following keys are significant:
                            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:
 
-                           DES_PTR      use a pointer to DES_SPtrans
-                                        rather that DES_SPtrans
-                                        directly in D_ENCRYPT.
-                           DES_RISC1    Alternate implementations of
-                           DES_RISC2    D_ENCRYPT for certain RISC
-                                        processors.
-                           DES_UNROLL   do not loop around calls to
-                                        D_ENCRYPT.
-                           DES_INT      have unsigned int as the
-                                        integer type for DES rather
-                                        than unsigned long.
-                           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 unif of
-                                        calculation an unsigned char.
-                           RC4_LONG     makes the basic RC4 unif of
-                                        calculation an unsigned long.
-                           RC4_INDEX    go through input and output
-                                        data by indexing into them
-                                        rather than incrementing the
-                                        pointer.
-                           RC4_CHUNK    sets the chunk type to
-                                        unsigned long.
-                           RC4_CHUNK_LL sets the chunk type to
-                                        unsigned long long.
-                                        both these chunk sizes are for
-                                        handling data in chunks on
-                                        processors that do not have
-                                        byte load/store instructions.
-                           MD2_CHAR     makes the basic MD2 unit of
-                                        calculation an unsigned char.
-                           MD2_LONG     makes the basic MD2 unit of
-                                        calculation an unsigned long.
-                           IDEA_SHORT   makes the basic IDEA unit of
-                                        calculation an unsigned short.
-                           IDEA_LONG    makes the basic IDEA unit of
-                                        calculation an unsigned long.
-                           RC2_SHORT    makes the basic RC2 unit of
-                                        calculation an unsigned short.
-                           RC2_LONG     makes the basic RC2 unit of
-                                        calculation an unsigned long.
-                           BF_PTR       use different pointer based
-                           BF_PTR2      versions of BF_ENC.
-                           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.
 
-        cpuid_obj       => assembler implementation of cpuid code as
+        apps_aux_src    => Extra source to build apps/openssl and other
+                           apps, as needed by the target and that can be
+                           collected in a library.
+        apps_init_src   => Init source to build apps/openssl and other
+                           apps, as needed by the target.  This code
+                           cannot be placed in a library, as the rest
+                           of the code isn't expected to link to it
+                           explicitely.
+        cpuid_asm_src   => assembler implementation of cpuid code as
                            well as OPENSSL_cleanse().
-                           Default to mem_clr.o
-        bn_obj          => assembler implementation of core bignum
+                           Default to mem_clr.c
+        bn_asm_src      => Assembler implementation of core bignum
                            functions.
-                           Defaults to bn_asm.o
-        ec_obj          => assembler implementation of core EC
+                           Defaults to bn_asm.c
+        ec_asm_src      => Assembler implementation of core EC
                            functions.
-        des_obj         => assembler implementation of core DES
+        des_asm_src     => Assembler implementation of core DES
                            encryption functions.
-                           Defaults to 'des_enc.o fcrypt_b.o'
-        aes_obj         => assembler implementation of core AES
+                           Defaults to 'des_enc.c fcrypt_b.c'
+        aes_asm_src     => Assembler implementation of core AES
                            functions.
-                           Defaults to 'aes_core.o aes_cbc.o'
-        bf_obj          => assembler implementation of core BF
+                           Defaults to 'aes_core.c aes_cbc.c'
+        bf_asm_src      => Assembler implementation of core BlowFish
                            functions.
-                           Defaults to 'bf_enc.o'
-        md5_obj         => assembler implementation of core MD5
+                           Defaults to 'bf_enc.c'
+        md5_asm_src     => Assembler implementation of core MD5
                            functions.
-        sha1_obj        => assembler implementation of core SHA1,
+        sha1_asm_src    => Assembler implementation of core SHA1,
                            functions, and also possibly SHA256 and
                            SHA512 ones.
-        cast_obj        => assembler implementation of core BF
+        cast_asm_src    => Assembler implementation of core CAST
                            functions.
-                           Defaults to 'c_enc.o'
-        rc4_obj         => assembler implementation of core BF
+                           Defaults to 'c_enc.c'
+        rc4_asm_src     => Assembler implementation of core RC4
                            functions.
-                           Defaults to 'rc4_enc.o rc4_skey.o'
-        rmd160_obj      => assembler implementation of core RMD160
+                           Defaults to 'rc4_enc.c rc4_skey.c'
+        rmd160_asm_src  => Assembler implementation of core RMD160
                            functions.
-        rc5_obj         => assembler implementation of core RC4
+        rc5_asm_src     => Assembler implementation of core RC5
                            functions.
-                           Defaults to 'rc5_enc.o'
-        wp_obj          => assembler implementation of core WHIRLPOOL
+                           Defaults to 'rc5_enc.c'
+        wp_asm_src      => Assembler implementation of core WHIRLPOOL
                            functions.
-        cmll_obj        => assembler implementation of core CAMELLIA
+        cmll_asm_src    => Assembler implementation of core CAMELLIA
                            functions.
-                           Defaults to 'camellia.o cmll_misc.o cmll_cbc.o'
-        modes_obj       => assembler implementation of the
-                           functions gcm_gmult_4bit and gcm_ghash_4bit.
-        padlock_obj     => assembler implementation of core parts of
+                           Defaults to 'camellia.c cmll_misc.c cmll_cbc.c'
+        modes_asm_src   => Assembler implementation of cipher modes,
+                           currently the functions gcm_gmult_4bit and
+                           gcm_ghash_4bit.
+        padlock_asm_src => Assembler implementation of core parts of
                            the padlock engine.  This is mandatory on
                            any platform where the padlock engine might
                            actually be built.
@@ -235,7 +285,7 @@ In each table entry, the following keys are significant:
     'inherit_from' that indicate what other configurations to inherit
     data from.  These are resolved recursively.
 
-    Inheritance works as a set of default values that can be overriden
+    Inheritance works as a set of default values that can be overridden
     by corresponding key values in the inheriting configuration.
 
     Note 1: any configuration table can be used as a template.
@@ -284,13 +334,430 @@ In each table entry, the following keys are significant:
         }
 
 [2] OpenSSL is built with threading capabilities unless the user
-    specifies 'no-threads'.  The value of the key 'thread_cflags' may
+    specifies 'no-threads'.  The value of the key 'thread_scheme' may
     be "(unknown)", in which case the user MUST give some compilation
     flags to Configure.
 
+[3] OpenSSL has three types of things to link from object files or
+    static libraries:
+
+    - shared libraries; that would be libcrypto and libssl.
+    - shared objects (sometimes called dynamic libraries);  that would
+      be the engines.
+    - applications; those are apps/openssl and all the test apps.
+
+    Very roughly speaking, linking is done like this (words in braces
+    represent the configuration settings documented at the beginning
+    of this file):
+
+    shared libraries:
+        {ld} $(CFLAGS) {lflags} {shared_ldflag} -o libfoo.so \
+            foo/something.o foo/somethingelse.o {ex_libs}
+
+    shared objects:
+        {ld} $(CFLAGS) {lflags} {module_ldflags} -o libeng.so \
+            blah1.o blah2.o -lcrypto {ex_libs}
+
+    applications:
+        {ld} $(CFLAGS) {lflags} -o app \
+            app1.o utils.o -lssl -lcrypto {ex_libs}
+
+[4] There are variants of these attribute, prefixed with `lib_',
+    `dso_' or `bin_'.  Those variants replace the unprefixed attribute
+    when building library, DSO or program modules specifically.
 
 Historically, the target configurations came in form of a string with
 values separated by colons.  This use is deprecated.  The string form
 looked like this:
 
    "target" => "{cc}:{cflags}:{unistd}:{thread_cflag}:{sys_id}:{lflags}:{bn_ops}:{cpuid_obj}:{bn_obj}:{ec_obj}:{des_obj}:{aes_obj}:{bf_obj}:{md5_obj}:{sha1_obj}:{cast_obj}:{rc4_obj}:{rmd160_obj}:{rc5_obj}:{wp_obj}:{cmll_obj}:{modes_obj}:{padlock_obj}:{perlasm_scheme}:{dso_scheme}:{shared_target}:{shared_cflag}:{shared_ldflag}:{shared_extension}:{ranlib}:{arflags}:{multilib}"
+
+
+Build info files
+================
+
+The build.info files that are spread over the source tree contain the
+minimum information needed to build and distribute OpenSSL.  It uses a
+simple and yet fairly powerful language to determine what needs to be
+built, from what sources, and other relationships between files.
+
+For every build.info file, all file references are relative to the
+directory of the build.info file for source files, and the
+corresponding build directory for built files if the build tree
+differs from the source tree.
+
+When processed, every line is processed with the perl module
+Text::Template, using the delimiters "{-" and "-}".  The hashes
+%config and %target are passed to the perl fragments, along with
+$sourcedir and $builddir, which are the locations of the source
+directory for the current build.info file and the corresponding build
+directory, all relative to the top of the build tree.
+
+To begin with, things to be built are declared by setting specific
+variables:
+
+    PROGRAMS=foo bar
+    LIBS=libsomething
+    ENGINES=libeng
+    SCRIPTS=myhack
+    EXTRA=file1 file2
+
+Note that the files mentioned for PROGRAMS, LIBS and ENGINES *must* be
+without extensions.  The build file templates will figure them out.
+
+For each thing to be built, it is then possible to say what sources
+they are built from:
+
+    PROGRAMS=foo bar
+    SOURCE[foo]=foo.c common.c
+    SOURCE[bar]=bar.c extra.c common.c
+
+It's also possible to tell some other dependencies:
+
+    DEPEND[foo]=libsomething
+    DEPEND[libbar]=libsomethingelse
+
+(it could be argued that 'libsomething' and 'libsomethingelse' are
+source as well.  However, the files given through SOURCE are expected
+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 building static libraries and DLLs at the same time, so using
+static libraries on Windows can only be done when configured
+'no-shared'.
+
+One some platforms, shared libraries come with a name that's different
+from their static counterpart.  That's declared as follows:
+
+    SHARED_NAME[libfoo]=cygfoo-{- $config{shlibver} -}
+
+The example is from Cygwin, which has a required naming convention.
+
+Sometimes, it makes sense to rename an output file, for example a
+library:
+
+    RENAME[libfoo]=libbar
+
+That line has "libfoo" renamed to "libbar".  While it makes no
+sense at all to just have a rename like that (why not just use
+"libbar" everywhere?), it does make sense when it can be used
+conditionally.  See a little further below for an example.
+
+In some cases, it's desirable to include some source files in the
+shared form of a library only:
+
+    SHARED_SOURCE[libfoo]=dllmain.c
+
+For any file to be built, it's also possible to tell what extra
+include paths the build of their source files should use:
+
+    INCLUDE[foo]=include
+
+In some cases, one might want to generate some source files from
+others, that's done as follows:
+
+    GENERATE[foo.s]=asm/something.pl $(CFLAGS)
+    GENERATE[bar.s]=asm/bar.S
+
+The value of each GENERATE line is a command line or part of it.
+Configure places no rules on the command line, except that the first
+item must be the generator file.  It is, however, entirely up to the
+build file template to define exactly how those command lines should
+be handled, how the output is captured and so on.
+
+Sometimes, the generator file itself depends on other files, for
+example if it is a perl script that depends on other perl modules.
+This can be expressed using DEPEND like this:
+
+    DEPEND[asm/something.pl]=../perlasm/Foo.pm
+
+There may also be cases where the exact file isn't easily specified,
+but an inclusion directory still needs to be specified.  INCLUDE can
+be used in that case:
+
+    INCLUDE[asm/something.pl]=../perlasm
+
+NOTE: GENERATE lines are limited to one command only per GENERATE.
+
+As a last resort, it's possible to have raw build file lines, between
+BEGINRAW and ENDRAW lines as follows:
+
+    BEGINRAW[Makefile(unix)]
+    haha.h: {- $builddir -}/Makefile
+        echo "/* haha */" > haha.h
+    ENDRAW[Makefile(unix)]
+
+The word within square brackets is the build_file configuration item
+or the build_file configuration item followed by the second word in the
+build_scheme configuration item for the configured target within
+parenthesis as shown above.  For example, with the following relevant
+configuration items:
+
+   build_file   => "build.ninja"
+   build_scheme => [ "unified", "unix" ]
+
+... these lines will be considered:
+
+   BEGINRAW[build.ninja]
+   build haha.h: echo "/* haha */" > haha.h
+   ENDRAW[build.ninja]
+
+   BEGINRAW[build.ninja(unix)]
+   build hoho.h: echo "/* hoho */" > hoho.h
+   ENDRAW[build.ninja(unix)]
+
+Should it be needed because the recipes within a RAW section might
+clash with those generated by Configure, it's possible to tell it
+not to generate them with the use of OVERRIDES, for example:
+
+    SOURCE[libfoo]=foo.c bar.c
+    
+    OVERRIDES=bar.o
+    BEGINRAW[Makefile(unix)]
+    bar.o: bar.c
+       $(CC) $(CFLAGS) -DSPECIAL -c -o $@ $<
+    ENDRAW[Makefile(unix)]
+
+See the documentation further up for more information on configuration
+items.
+
+Finally, you can have some simple conditional use of the build.info
+information, looking like this:
+
+    IF[1]
+     something
+    ELSIF[2]
+     something other
+    ELSE
+     something else
+    ENDIF
+
+The expression in square brackets is interpreted as a string in perl,
+and will be seen as true if perl thinks it is, otherwise false.  For
+example, the above would have "something" used, since 1 is true.
+
+Together with the use of Text::Template, this can be used as
+conditions based on something in the passed variables, for example:
+
+    IF[{- $disabled{shared} -}]
+      LIBS=libcrypto
+      SOURCE[libcrypto]=...
+    ELSE
+      LIBS=libfoo
+      SOURCE[libfoo]=...
+    ENDIF
+
+or:
+
+    # VMS has a cultural standard where all libraries are prefixed.
+    # For OpenSSL, the choice is 'ossl_'
+    IF[{- $config{target} =~ /^vms/ -}]
+     RENAME[libcrypto]=ossl_libcrypto
+     RENAME[libssl]=ossl_libssl
+    ENDIF
+
+
+Build-file programming with the "unified" build system
+======================================================
+
+"Build files" are called "Makefile" on Unix-like operating systems,
+"descrip.mms" for MMS on VMS, "makefile" for nmake on Windows, etc.
+
+To use the "unified" build system, the target configuration needs to
+set the three items 'build_scheme', 'build_file' and 'build_command'.
+In the rest of this section, we will assume that 'build_scheme' is set
+to "unified" (see the configurations documentation above for the
+details).
+
+For any name given by 'build_file', the "unified" system expects a
+template file in Configurations/ named like the build file, with
+".tmpl" appended, or in case of possible ambiguity, a combination of
+the second 'build_scheme' list item and the 'build_file' name.  For
+example, if 'build_file' is set to "Makefile", the template could be
+Configurations/Makefile.tmpl or Configurations/unix-Makefile.tmpl.
+In case both Configurations/unix-Makefile.tmpl and
+Configurations/Makefile.tmpl are present, the former takes
+precedence.
+
+The build-file template is processed with the perl module
+Text::Template, using "{-" and "-}" as delimiters that enclose the
+perl code fragments that generate configuration-dependent content.
+Those perl fragments have access to all the hash variables from
+configdata.pem.
+
+The build-file template is expected to define at least the following
+perl functions in a perl code fragment enclosed with "{-" and "-}".
+They are all expected to return a string with the lines they produce.
+
+    generatesrc - function that produces build file lines to generate
+                  a source file from some input.
+
+                  It's called like this:
+
+                        generatesrc(src => "PATH/TO/tobegenerated",
+                                    generator => [ "generatingfile", ... ]
+                                    generator_incs => [ "INCL/PATH", ... ]
+                                    generator_deps => [ "dep1", ... ]
+                                    generator => [ "generatingfile", ... ]
+                                    incs => [ "INCL/PATH", ... ],
+                                    deps => [ "dep1", ... ],
+                                    intent => one of "libs", "dso", "bin" );
+
+                  'src' has the name of the file to be generated.
+                  'generator' is the command or part of command to
+                  generate the file, of which the first item is
+                  expected to be the file to generate from.
+                  generatesrc() is expected to analyse and figure out
+                  exactly how to apply that file and how to capture
+                  the result.  'generator_incs' and 'generator_deps'
+                  are include directories and files that the generator
+                  file itself depends on.  'incs' and 'deps' are
+                  include directories and files that are used if $(CC)
+                  is used as an intermediary step when generating the
+                  end product (the file indicated by 'src').  'intent'
+                  indicates what the generated file is going to be
+                  used for.
+
+    src2obj     - function that produces build file lines to build an
+                  object file from source files and associated data.
+
+                  It's called like this:
+
+                        src2obj(obj => "PATH/TO/objectfile",
+                                srcs => [ "PATH/TO/sourcefile", ... ],
+                                deps => [ "dep1", ... ],
+                                incs => [ "INCL/PATH", ... ]
+                                intent => one of "lib", "dso", "bin" );
+
+                  'obj' has the intended object file *without*
+                  extension, src2obj() is expected to add that.
+                  'srcs' has the list of source files to build the
+                  object file, with the first item being the source
+                  file that directly corresponds to the object file.
+                  'deps' is a list of explicit dependencies.  'incs'
+                  is a list of include file directories.  Finally,
+                  'intent' indicates what this object file is going
+                  to be used for.
+
+    obj2lib     - function that produces build file lines to build a
+                  static library file ("libfoo.a" in Unix terms) from
+                  object files.
+
+                  called like this:
+
+                        obj2lib(lib => "PATH/TO/libfile",
+                                objs => [ "PATH/TO/objectfile", ... ]);
+
+                  'lib' has the intended library file name *without*
+                  extension, obj2lib is expected to add that.  'objs'
+                  has the list of object files (also *without*
+                  extension) to build this library.
+
+    libobj2shlib - function that produces build file lines to build a
+                  shareable object library file ("libfoo.so" in Unix
+                  terms) from the corresponding static library file
+                  or object files.
+
+                  called like this:
+
+                        libobj2shlib(shlib => "PATH/TO/shlibfile",
+                                     lib => "PATH/TO/libfile",
+                                     objs => [ "PATH/TO/objectfile", ... ],
+                                     deps => [ "PATH/TO/otherlibfile", ... ]);
+
+                  'lib' has the intended library file name *without*
+                  extension, libobj2shlib is expected to add that.
+                  'shlib' has the corresponding shared library name
+                  *without* extension.  'deps' has the list of other
+                  libraries (also *without* extension) this library
+                  needs to be linked with.  'objs' has the list of
+                  object files (also *without* extension) to build
+                  this library.
+
+                  This function has a choice; it can use the
+                  corresponding static library as input to make the
+                  shared library, or the list of object files.
+
+    obj2dso     - function that produces build file lines to build a
+                  dynamic shared object file from object files.
+
+                  called like this:
+
+                        obj2dso(lib => "PATH/TO/libfile",
+                                objs => [ "PATH/TO/objectfile", ... ],
+                                deps => [ "PATH/TO/otherlibfile",
+                                ... ]);
+
+                  This is almost the same as libobj2shlib, but the
+                  intent is to build a shareable library that can be
+                  loaded in runtime (a "plugin"...).  The differences
+                  are subtle, one of the most visible ones is that the
+                  resulting shareable library is produced from object
+                  files only.
+
+    obj2bin     - function that produces build file lines to build an
+                  executable file from object files.
+
+                  called like this:
+
+                        obj2bin(bin => "PATH/TO/binfile",
+                                objs => [ "PATH/TO/objectfile", ... ],
+                                deps => [ "PATH/TO/libfile", ... ]);
+
+                  'bin' has the intended executable file name
+                  *without* extension, obj2bin is expected to add
+                  that.  'objs' has the list of object files (also
+                  *without* extension) to build this library.  'deps'
+                  has the list of library files (also *without*
+                  extension) that the programs needs to be linked
+                  with.
+
+    in2script   - function that produces build file lines to build a
+                  script file from some input.
+
+                  called like this:
+
+                        in2script(script => "PATH/TO/scriptfile",
+                                  sources => [ "PATH/TO/infile", ... ]);
+
+                  'script' has the intended script file name.
+                  'sources' has the list of source files to build the
+                  resulting script from.
+
+In all cases, file file paths are relative to the build tree top, and
+the build file actions run with the build tree top as current working
+directory.
+
+Make sure to end the section with these functions with a string that
+you thing is appropriate for the resulting build file.  If nothing
+else, end it 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`.