initial/final commitHEADmaster

1 files changed, 721 insertions, 0 deletions

diff --git a/openssl-1.1.0h/Configurations/README b/openssl-1.1.0h/Configurations/README
new file mode 100644
index 0000000..6e13645
--- /dev/null
+++ b/openssl-1.1.0h/Configurations/README
@@ -0,0 +1,721 @@
+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
+==========================================
+
+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.
+                           Explained further below. [1]
+        template        => Set to 1 if this isn't really a platform
+                           target.  Instead, this target is a template
+                           upon which other targets can be built.
+                           Explained further below.  [1]
+
+        sys_id          => System identity for systems where that
+                           is difficult to determine automatically.
+
+        cc              => The 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.
+        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
+                           string such as "MACRO=value", or just
+                           "MACRO" for definitions without value.
+        shared_cflag    => Extra compilation flags used when
+                           compiling for shared libraries, typically
+                           something like "-fPIC".
+
+        (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          => Flags that are used when linking apps.
+        shared_ldflag   => Flags that are used when linking shared
+                           or dynamic libraries.
+        plib_lflags     => Extra linking flags to appear just before
+                           the libraries on the command line.
+        ex_libs         => Extra libraries that are needed when
+                           linking.
+
+        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.
+
+        ranlib          => The library archive indexing command, the
+                           default is 'ranlib' it it exists.
+
+        unistd          => An alternative header to the typical
+                           '<unistd.h>'.  This is very rarely needed.
+
+        shared_extension => File name extension used for shared
+                            libraries. 
+        obj_extension   => File name extension used for object files.
+                           On unix, this defaults to ".o" (NOTE: this
+                           is here for future use, it's not
+                           implemented yet)
+        exe_extension   => File name extension used for executable
+                           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
+                           as well.  Valid values are "DLFCN"
+                           (dlopen() et al), "DLFCN_NO_H" (for systems
+                           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
+                           assembler files used when compiling with
+                           assembler implementations.
+        shared_target   => The shared library building method used.
+                           This is a target found in Makefile.shared.
+        build_scheme    => The scheme used to build up a Makefile.
+                           In its simplest form, the value is a string
+                           with the name of the build scheme.
+                           The value may also take the form of a list
+                           of strings, if the build_scheme is to have
+                           some options.  In this case, the first
+                           string in the list is the name of the build
+                           scheme.
+                           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
+                           32-bit and a 64-bit variant), this is used
+                           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 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:
+
+                           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.
+
+        apps_extra_src  => Extra source to build apps/openssl, as
+                           needed by the target.
+        cpuid_asm_src   => assembler implementation of cpuid code as
+                           well as OPENSSL_cleanse().
+                           Default to mem_clr.c
+        bn_asm_src      => Assembler implementation of core bignum
+                           functions.
+                           Defaults to bn_asm.c
+        ec_asm_src      => Assembler implementation of core EC
+                           functions.
+        des_asm_src     => Assembler implementation of core DES
+                           encryption functions.
+                           Defaults to 'des_enc.c fcrypt_b.c'
+        aes_asm_src     => Assembler implementation of core AES
+                           functions.
+                           Defaults to 'aes_core.c aes_cbc.c'
+        bf_asm_src      => Assembler implementation of core BlowFish
+                           functions.
+                           Defaults to 'bf_enc.c'
+        md5_asm_src     => Assembler implementation of core MD5
+                           functions.
+        sha1_asm_src    => Assembler implementation of core SHA1,
+                           functions, and also possibly SHA256 and
+                           SHA512 ones.
+        cast_asm_src    => Assembler implementation of core CAST
+                           functions.
+                           Defaults to 'c_enc.c'
+        rc4_asm_src     => Assembler implementation of core RC4
+                           functions.
+                           Defaults to 'rc4_enc.c rc4_skey.c'
+        rmd160_asm_src  => Assembler implementation of core RMD160
+                           functions.
+        rc5_asm_src     => Assembler implementation of core RC5
+                           functions.
+                           Defaults to 'rc5_enc.c'
+        wp_asm_src      => Assembler implementation of core WHIRLPOOL
+                           functions.
+        cmll_asm_src    => Assembler implementation of core CAMELLIA
+                           functions.
+                           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.
+
+
+[1] as part of the target configuration, one can have a key called
+    '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 overridden
+    by corresponding key values in the inheriting configuration.
+
+    Note 1: any configuration table can be used as a template.
+    Note 2: pure templates have the attribute 'template => 1' and
+            cannot be used as build targets.
+
+    If several configurations are given in the 'inherit_from' array,
+    the values of same attribute are concatenated with space
+    separation.  With this, it's possible to have several smaller
+    templates for different configuration aspects that can be combined
+    into a complete configuration.
+
+    instead of a scalar value or an array, a value can be a code block
+    of the form 'sub { /* your code here */ }'.  This code block will
+    be called with the list of inherited values for that key as
+    arguments.  In fact, the concatenation of strings is really done
+    by using 'sub { join(" ",@_) }' on the list of inherited values.
+
+    An example:
+
+        "foo" => {
+                template => 1,
+                haha => "ha ha",
+                hoho => "ho",
+                ignored => "This should not appear in the end result",
+        },
+        "bar" => {
+                template => 1,
+                haha => "ah",
+                hoho => "haho",
+                hehe => "hehe"
+        },
+        "laughter" => {
+                inherit_from => [ "foo", "bar" ],
+                hehe => sub { join(" ",(@_,"!!!")) },
+                ignored => "",
+        }
+
+        The entry for "laughter" will become as follows after processing:
+
+        "laughter" => {
+                haha => "ha ha ah",
+                hoho => "ho haho",
+                hehe => "hehe !!!",
+                ignored => ""
+        }
+
+[2] OpenSSL is built with threading capabilities unless the user
+    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) {shared_ldflag} -shared -o libfoo.so \
+            -Wl,--whole-archive libfoo.a -Wl,--no-whole-archive \
+            {plib_lflags} -lcrypto {ex_libs}
+
+    shared objects:
+        {ld} $(CFLAGS) {shared_ldflag} -shared -o libeng.so \
+            blah1.o blah2.o {plib_lflags} -lcrypto {ex_libs}
+
+    applications:
+        {ld} $(CFLAGS) {lflags} -o app \
+            app1.o utils.o {plib_lflags} -lssl -lcrypto {ex_libs}
+
+
+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)
+
+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:
+
+    ORDINALS[libcrypto]=crypto
+
+The value is not the name of the file in question, but rather the
+argument to util/mkdef.pl that indicates which file to use.
+
+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 lines has "libfoo" get 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 the the first
+item muct 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", ... ],
+                                     ordinals => [ "word", "/PATH/TO/ordfile" ]);
+
+                  '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.  'ordinals' MAY be present, and when
+                  it is, its value is an array where the word is
+                  "crypto" or "ssl" and the file is one of the ordinal
+                  files util/libeay.num or util/ssleay.num in the
+                  source directory.
+
+                  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`.