+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 with '.o'
+ extension, src2obj() is expected to change it to
+ something more suitable for the platform.
+ '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 to build this library.
+
+ libobj2shlib - backward compatibility function that's used the
+ same way as obj2shlib (described next), and was
+ expected to build the shared library from the
+ corresponding static library when that was suitable.
+ NOTE: building a shared library from a static
+ library is now DEPRECATED, as they no longer share
+ object files. Attempting to do this will fail.
+
+ obj2shlib - function that produces build file lines to build a
+ shareable object library file ("libfoo.so" in Unix
+ terms) from the corresponding object files.
+
+ called like this:
+
+ obj2shlib(shlib => "PATH/TO/shlibfile",
+ lib => "PATH/TO/libfile",
+ objs => [ "PATH/TO/objectfile", ... ],
+ deps => [ "PATH/TO/otherlibfile", ... ]);
+
+ 'lib' has the base (static) library ffile name
+ *without* extension. This is useful in case
+ supporting files are needed (such as import
+ libraries on Windows).
+ '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 to build this library.
+
+ 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 obj2shlib, but the
+ intent is to build a shareable library that can be
+ loaded in runtime (a "plugin"...).
+
+ 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 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`.