Configurations/README

   1 Intro
   2 =====
   3
   4 This directory contains a few sets of files that are used for
   5 configuration in diverse ways:
   6
   7     *.conf      Target platform configurations, please read
   8                 'Configurations of OpenSSL target platforms' for more
   9                 information.
  10     *.tmpl      Build file templates, please read 'Build-file
  11                 programming with the "unified" build system' as well
  12                 as 'Build info files' for more information.
  13     *.pm        Helper scripts / modules for the main `Configure`
  14                 script.  See 'Configure helper scripts for more
  15                 information.
  16
  17
  18 Configurations of OpenSSL target platforms
  19 ==========================================
  20
  21 Configuration targets are a collection of facts that we know about
  22 different platforms and their capabilities.  We organise them in a
  23 hash table, where each entry represent a specific target.
  24
  25 Note that configuration target names must be unique across all config
  26 files.  The Configure script does check that a config file doesn't
  27 have config targets that shadow config targets from other files.
  28
  29 In each table entry, the following keys are significant:
  30
  31         inherit_from    => Other targets to inherit values from.
  32                            Explained further below. [1]
  33         template        => Set to 1 if this isn't really a platform
  34                            target.  Instead, this target is a template
  35                            upon which other targets can be built.
  36                            Explained further below.  [1]
  37
  38         sys_id          => System identity for systems where that
  39                            is difficult to determine automatically.
  40
  41         enable          => Enable specific configuration features.
  42                            This MUST be an array of words.
  43         disable         => Disable specific configuration features.
  44                            This MUST be an array of words.
  45                            Note: if the same feature is both enabled
  46                            and disabled, disable wins.
  47
  48         cpp             => The C preprocessor command, normally not
  49                            given, as the build file defaults are
  50                            usually good enough.
  51         cppflags        => The C preprocessor flags.
  52         defines         => As an alternative, macro definitions may be
  53                            given here instead of in `cppflags'.  If
  54                            given here, they MUST be as an array of the
  55                            string such as "MACRO=value", or just
  56                            "MACRO" for definitions without value.
  57         includes        => As an alternative, inclusion directories
  58                            may be given here instead of in `cppflags'.
  59                            If given here, the MUST be an array of
  60                            strings, one directory specification each.
  61         cc              => The C compiler command, usually one of "cc",
  62                            "gcc" or "clang".  This command is normally
  63                            also used to link object files and
  64                            libraries into the final program.
  65         cxx             => The C++ compiler command, usually one of
  66                            "c++", "g++" or "clang++".  This command is
  67                            also used when linking a program where at
  68                            least one of the object file is made from
  69                            C++ source.
  70         cflags          => Flags that are used at all times when
  71                            compiling C object files.
  72         cxxflags        => Flags that are used at all times when
  73                            compiling C++ object files.  If unset, it
  74                            gets the same value as cflags.
  75         shared_cflag    => Extra compilation flags used when
  76                            compiling for shared libraries, typically
  77                            something like "-fPIC".
  78
  79         (linking is a complex thing, see [3] below)
  80         ld              => Linker command, usually not defined
  81                            (meaning the compiler command is used
  82                            instead).
  83                            (NOTE: this is here for future use, it's
  84                            not implemented yet)
  85         lflags          => Flags that are used when linking apps.
  86         shared_ldflag   => Flags that are used when linking shared
  87                            or dynamic libraries.
  88         ex_libs         => Extra libraries that are needed when
  89                            linking.
  90
  91         ar              => The library archive command, the default is
  92                            "ar".
  93                            (NOTE: this is here for future use, it's
  94                            not implemented yet)
  95         arflags         => Flags to be used with the library archive
  96                            command.  On Unix, this includes the
  97                            command letter, 'r' by default.
  98
  99         ranlib          => The library archive indexing command, the
 100                            default is 'ranlib' it it exists.
 101
 102         unistd          => An alternative header to the typical
 103                            '<unistd.h>'.  This is very rarely needed.
 104
 105         shared_extension => File name extension used for shared
 106                             libraries.
 107         obj_extension   => File name extension used for object files.
 108                            On unix, this defaults to ".o" (NOTE: this
 109                            is here for future use, it's not
 110                            implemented yet)
 111         exe_extension   => File name extension used for executable
 112                            files.  On unix, this defaults to "" (NOTE:
 113                            this is here for future use, it's not
 114                            implemented yet)
 115         shlib_variant   => A "variant" identifier inserted between the base
 116                            shared library name and the extension.  On "unixy"
 117                            platforms (BSD, Linux, Solaris, MacOS/X, ...) this
 118                            supports installation of custom OpenSSL libraries
 119                            that don't conflict with other builds of OpenSSL
 120                            installed on the system.  The variant identifier
 121                            becomes part of the SONAME of the library and also
 122                            any symbol versions (symbol versions are not used or
 123                            needed with MacOS/X).  For example, on a system
 124                            where a default build would normally create the SSL
 125                            shared library as 'libssl.so -> libssl.so.1.1' with
 126                            the value of the symlink as the SONAME, a target
 127                            definition that sets 'shlib_variant => "-abc"' will
 128                            create 'libssl.so -> libssl-abc.so.1.1', again with
 129                            an SONAME equal to the value of the symlink.  The
 130                            symbol versions associated with the variant library
 131                            would then be 'OPENSSL_ABC_<version>' rather than
 132                            the default 'OPENSSL_<version>'. The string inserted
 133                            into symbol versions is obtained by mapping all
 134                            letters in the "variant" identifier to upper case
 135                            and all non-alphanumeric characters to '_'.
 136
 137         thread_scheme   => The type of threads is used on the
 138                            configured platform.  Currently known
 139                            values are "(unknown)", "pthreads",
 140                            "uithreads" (a.k.a solaris threads) and
 141                            "winthreads".  Except for "(unknown)", the
 142                            actual value is currently ignored but may
 143                            be used in the future.  See further notes
 144                            below [2].
 145         dso_scheme      => The type of dynamic shared objects to build
 146                            for.  This mostly comes into play with
 147                            engines, but can be used for other purposes
 148                            as well.  Valid values are "DLFCN"
 149                            (dlopen() et al), "DLFCN_NO_H" (for systems
 150                            that use dlopen() et al but do not have
 151                            fcntl.h), "DL" (shl_load() et al), "WIN32"
 152                            and "VMS".
 153         perlasm_scheme  => The perlasm method used to created the
 154                            assembler files used when compiling with
 155                            assembler implementations.
 156         shared_target   => The shared library building method used.
 157                            This is a target found in Makefile.shared.
 158         build_scheme    => The scheme used to build up a Makefile.
 159                            In its simplest form, the value is a string
 160                            with the name of the build scheme.
 161                            The value may also take the form of a list
 162                            of strings, if the build_scheme is to have
 163                            some options.  In this case, the first
 164                            string in the list is the name of the build
 165                            scheme.
 166                            Currently recognised build scheme is "unified".
 167                            For the "unified" build scheme, this item
 168                            *must* be an array with the first being the
 169                            word "unified" and the second being a word
 170                            to identify the platform family.
 171
 172         multilib        => On systems that support having multiple
 173                            implementations of a library (typically a
 174                            32-bit and a 64-bit variant), this is used
 175                            to have the different variants in different
 176                            directories.
 177
 178         bn_ops          => Building options (was just bignum options in
 179                            the earlier history of this option, hence the
 180                            name). This is a string of words that describe
 181                            algorithms' implementation parameters that
 182                            are optimal for the designated target platform,
 183                            such as the type of integers used to build up
 184                            the bignum, different ways to implement certain
 185                            ciphers and so on. To fully comprehend the
 186                            meaning, the best is to read the affected
 187                            source.
 188                            The valid words are:
 189
 190                            THIRTY_TWO_BIT       bignum limbs are 32 bits,
 191                                                 this is default if no
 192                                                 option is specified, it
 193                                                 works on any supported
 194                                                 system [unless "wider"
 195                                                 limb size is implied in
 196                                                 assembly code];
 197                            BN_LLONG             bignum limbs are 32 bits,
 198                                                 but 64-bit 'unsigned long
 199                                                 long' is used internally
 200                                                 in calculations;
 201                            SIXTY_FOUR_BIT_LONG  bignum limbs are 64 bits
 202                                                 and sizeof(long) is 8;
 203                            SIXTY_FOUR_BIT       bignums limbs are 64 bits,
 204                                                 but execution environment
 205                                                 is ILP32;
 206                            RC4_CHAR             RC4 key schedule is made
 207                                                 up of 'unsigned char's;
 208                            RC4_INT              RC4 key schedule is made
 209                                                 up of 'unsigned int's;
 210                            EXPORT_VAR_AS_FN     for shared libraries,
 211                                                 export vars as
 212                                                 accessor functions.
 213
 214         apps_aux_src    => Extra source to build apps/openssl and other
 215                            apps, as needed by the target and that can be
 216                            collected in a library.
 217         apps_init_src   => Init source to build apps/openssl and other
 218                            apps, as needed by the target.  This code
 219                            cannot be placed in a library, as the rest
 220                            of the code isn't expected to link to it
 221                            explicitely.
 222         cpuid_asm_src   => assembler implementation of cpuid code as
 223                            well as OPENSSL_cleanse().
 224                            Default to mem_clr.c
 225         bn_asm_src      => Assembler implementation of core bignum
 226                            functions.
 227                            Defaults to bn_asm.c
 228         ec_asm_src      => Assembler implementation of core EC
 229                            functions.
 230         des_asm_src     => Assembler implementation of core DES
 231                            encryption functions.
 232                            Defaults to 'des_enc.c fcrypt_b.c'
 233         aes_asm_src     => Assembler implementation of core AES
 234                            functions.
 235                            Defaults to 'aes_core.c aes_cbc.c'
 236         bf_asm_src      => Assembler implementation of core BlowFish
 237                            functions.
 238                            Defaults to 'bf_enc.c'
 239         md5_asm_src     => Assembler implementation of core MD5
 240                            functions.
 241         sha1_asm_src    => Assembler implementation of core SHA1,
 242                            functions, and also possibly SHA256 and
 243                            SHA512 ones.
 244         cast_asm_src    => Assembler implementation of core CAST
 245                            functions.
 246                            Defaults to 'c_enc.c'
 247         rc4_asm_src     => Assembler implementation of core RC4
 248                            functions.
 249                            Defaults to 'rc4_enc.c rc4_skey.c'
 250         rmd160_asm_src  => Assembler implementation of core RMD160
 251                            functions.
 252         rc5_asm_src     => Assembler implementation of core RC5
 253                            functions.
 254                            Defaults to 'rc5_enc.c'
 255         wp_asm_src      => Assembler implementation of core WHIRLPOOL
 256                            functions.
 257         cmll_asm_src    => Assembler implementation of core CAMELLIA
 258                            functions.
 259                            Defaults to 'camellia.c cmll_misc.c cmll_cbc.c'
 260         modes_asm_src   => Assembler implementation of cipher modes,
 261                            currently the functions gcm_gmult_4bit and
 262                            gcm_ghash_4bit.
 263         padlock_asm_src => Assembler implementation of core parts of
 264                            the padlock engine.  This is mandatory on
 265                            any platform where the padlock engine might
 266                            actually be built.
 267
 268
 269 [1] as part of the target configuration, one can have a key called
 270     'inherit_from' that indicate what other configurations to inherit
 271     data from.  These are resolved recursively.
 272
 273     Inheritance works as a set of default values that can be overridden
 274     by corresponding key values in the inheriting configuration.
 275
 276     Note 1: any configuration table can be used as a template.
 277     Note 2: pure templates have the attribute 'template => 1' and
 278             cannot be used as build targets.
 279
 280     If several configurations are given in the 'inherit_from' array,
 281     the values of same attribute are concatenated with space
 282     separation.  With this, it's possible to have several smaller
 283     templates for different configuration aspects that can be combined
 284     into a complete configuration.
 285
 286     instead of a scalar value or an array, a value can be a code block
 287     of the form 'sub { /* your code here */ }'.  This code block will
 288     be called with the list of inherited values for that key as
 289     arguments.  In fact, the concatenation of strings is really done
 290     by using 'sub { join(" ",@_) }' on the list of inherited values.
 291
 292     An example:
 293
 294         "foo" => {
 295                 template => 1,
 296                 haha => "ha ha",
 297                 hoho => "ho",
 298                 ignored => "This should not appear in the end result",
 299         },
 300         "bar" => {
 301                 template => 1,
 302                 haha => "ah",
 303                 hoho => "haho",
 304                 hehe => "hehe"
 305         },
 306         "laughter" => {
 307                 inherit_from => [ "foo", "bar" ],
 308                 hehe => sub { join(" ",(@_,"!!!")) },
 309                 ignored => "",
 310         }
 311
 312         The entry for "laughter" will become as follows after processing:
 313
 314         "laughter" => {
 315                 haha => "ha ha ah",
 316                 hoho => "ho haho",
 317                 hehe => "hehe !!!",
 318                 ignored => ""
 319         }
 320
 321 [2] OpenSSL is built with threading capabilities unless the user
 322     specifies 'no-threads'.  The value of the key 'thread_scheme' may
 323     be "(unknown)", in which case the user MUST give some compilation
 324     flags to Configure.
 325
 326 [3] OpenSSL has three types of things to link from object files or
 327     static libraries:
 328
 329     - shared libraries; that would be libcrypto and libssl.
 330     - shared objects (sometimes called dynamic libraries);  that would
 331       be the engines.
 332     - applications; those are apps/openssl and all the test apps.
 333
 334     Very roughly speaking, linking is done like this (words in braces
 335     represent the configuration settings documented at the beginning
 336     of this file):
 337
 338     shared libraries:
 339         {ld} $(CFLAGS) {shared_ldflag} -shared -o libfoo.so \
 340             -Wl,--whole-archive libfoo.a -Wl,--no-whole-archive \
 341             -lcrypto {ex_libs}
 342
 343     shared objects:
 344         {ld} $(CFLAGS) {lflags} {module_lflags} -o libeng.so \
 345             blah1.o blah2.o -lcrypto {ex_libs}
 346
 347     applications:
 348         {ld} $(CFLAGS) {lflags} -o app \
 349             app1.o utils.o -lssl -lcrypto {ex_libs}
 350
 351
 352 Historically, the target configurations came in form of a string with
 353 values separated by colons.  This use is deprecated.  The string form
 354 looked like this:
 355
 356    "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}"
 357
 358
 359 Build info files
 360 ================
 361
 362 The build.info files that are spread over the source tree contain the
 363 minimum information needed to build and distribute OpenSSL.  It uses a
 364 simple and yet fairly powerful language to determine what needs to be
 365 built, from what sources, and other relationships between files.
 366
 367 For every build.info file, all file references are relative to the
 368 directory of the build.info file for source files, and the
 369 corresponding build directory for built files if the build tree
 370 differs from the source tree.
 371
 372 When processed, every line is processed with the perl module
 373 Text::Template, using the delimiters "{-" and "-}".  The hashes
 374 %config and %target are passed to the perl fragments, along with
 375 $sourcedir and $builddir, which are the locations of the source
 376 directory for the current build.info file and the corresponding build
 377 directory, all relative to the top of the build tree.
 378
 379 To begin with, things to be built are declared by setting specific
 380 variables:
 381
 382     PROGRAMS=foo bar
 383     LIBS=libsomething
 384     ENGINES=libeng
 385     SCRIPTS=myhack
 386     EXTRA=file1 file2
 387
 388 Note that the files mentioned for PROGRAMS, LIBS and ENGINES *must* be
 389 without extensions.  The build file templates will figure them out.
 390
 391 For each thing to be built, it is then possible to say what sources
 392 they are built from:
 393
 394     PROGRAMS=foo bar
 395     SOURCE[foo]=foo.c common.c
 396     SOURCE[bar]=bar.c extra.c common.c
 397
 398 It's also possible to tell some other dependencies:
 399
 400     DEPEND[foo]=libsomething
 401     DEPEND[libbar]=libsomethingelse
 402
 403 (it could be argued that 'libsomething' and 'libsomethingelse' are
 404 source as well.  However, the files given through SOURCE are expected
 405 to be located in the source tree while files given through DEPEND are
 406 expected to be located in the build tree)
 407
 408 It's also possible to depend on static libraries explicitly:
 409
 410     DEPEND[foo]=libsomething.a
 411     DEPEND[libbar]=libsomethingelse.a
 412
 413 This should be rarely used, and care should be taken to make sure it's
 414 only used when supported.  For example, native Windows build doesn't
 415 support build static libraries and DLLs at the same time, so using
 416 static libraries on Windows can only be done when configured
 417 'no-shared'.
 418
 419 One some platforms, shared libraries come with a name that's different
 420 from their static counterpart.  That's declared as follows:
 421
 422     SHARED_NAME[libfoo]=cygfoo-{- $config{shlibver} -}
 423
 424 The example is from Cygwin, which has a required naming convention.
 425
 426 Sometimes, it makes sense to rename an output file, for example a
 427 library:
 428
 429     RENAME[libfoo]=libbar
 430
 431 That lines has "libfoo" get renamed to "libbar".  While it makes no
 432 sense at all to just have a rename like that (why not just use
 433 "libbar" everywhere?), it does make sense when it can be used
 434 conditionally.  See a little further below for an example.
 435
 436 In some cases, it's desirable to include some source files in the
 437 shared form of a library only:
 438
 439     SHARED_SOURCE[libfoo]=dllmain.c
 440
 441 For any file to be built, it's also possible to tell what extra
 442 include paths the build of their source files should use:
 443
 444     INCLUDE[foo]=include
 445
 446 In some cases, one might want to generate some source files from
 447 others, that's done as follows:
 448
 449     GENERATE[foo.s]=asm/something.pl $(CFLAGS)
 450     GENERATE[bar.s]=asm/bar.S
 451
 452 The value of each GENERATE line is a command line or part of it.
 453 Configure places no rules on the command line, except that the first
 454 item must be the generator file.  It is, however, entirely up to the
 455 build file template to define exactly how those command lines should
 456 be handled, how the output is captured and so on.
 457
 458 Sometimes, the generator file itself depends on other files, for
 459 example if it is a perl script that depends on other perl modules.
 460 This can be expressed using DEPEND like this:
 461
 462     DEPEND[asm/something.pl]=../perlasm/Foo.pm
 463
 464 There may also be cases where the exact file isn't easily specified,
 465 but an inclusion directory still needs to be specified.  INCLUDE can
 466 be used in that case:
 467
 468     INCLUDE[asm/something.pl]=../perlasm
 469
 470 NOTE: GENERATE lines are limited to one command only per GENERATE.
 471
 472 As a last resort, it's possible to have raw build file lines, between
 473 BEGINRAW and ENDRAW lines as follows:
 474
 475     BEGINRAW[Makefile(unix)]
 476     haha.h: {- $builddir -}/Makefile
 477         echo "/* haha */" > haha.h
 478     ENDRAW[Makefile(unix)]
 479
 480 The word within square brackets is the build_file configuration item
 481 or the build_file configuration item followed by the second word in the
 482 build_scheme configuration item for the configured target within
 483 parenthesis as shown above.  For example, with the following relevant
 484 configuration items:
 485
 486    build_file   => "build.ninja"
 487    build_scheme => [ "unified", "unix" ]
 488
 489 ... these lines will be considered:
 490
 491    BEGINRAW[build.ninja]
 492    build haha.h: echo "/* haha */" > haha.h
 493    ENDRAW[build.ninja]
 494
 495    BEGINRAW[build.ninja(unix)]
 496    build hoho.h: echo "/* hoho */" > hoho.h
 497    ENDRAW[build.ninja(unix)]
 498
 499 Should it be needed because the recipes within a RAW section might
 500 clash with those generated by Configure, it's possible to tell it
 501 not to generate them with the use of OVERRIDES, for example:
 502
 503     SOURCE[libfoo]=foo.c bar.c
 504
 505     OVERRIDES=bar.o
 506     BEGINRAW[Makefile(unix)]
 507     bar.o: bar.c
 508         $(CC) $(CFLAGS) -DSPECIAL -c -o $@ $<
 509     ENDRAW[Makefile(unix)]
 510
 511 See the documentation further up for more information on configuration
 512 items.
 513
 514 Finally, you can have some simple conditional use of the build.info
 515 information, looking like this:
 516
 517     IF[1]
 518      something
 519     ELSIF[2]
 520      something other
 521     ELSE
 522      something else
 523     ENDIF
 524
 525 The expression in square brackets is interpreted as a string in perl,
 526 and will be seen as true if perl thinks it is, otherwise false.  For
 527 example, the above would have "something" used, since 1 is true.
 528
 529 Together with the use of Text::Template, this can be used as
 530 conditions based on something in the passed variables, for example:
 531
 532     IF[{- $disabled{shared} -}]
 533       LIBS=libcrypto
 534       SOURCE[libcrypto]=...
 535     ELSE
 536       LIBS=libfoo
 537       SOURCE[libfoo]=...
 538     ENDIF
 539
 540 or:
 541
 542     # VMS has a cultural standard where all libraries are prefixed.
 543     # For OpenSSL, the choice is 'ossl_'
 544     IF[{- $config{target} =~ /^vms/ -}]
 545      RENAME[libcrypto]=ossl_libcrypto
 546      RENAME[libssl]=ossl_libssl
 547     ENDIF
 548
 549
 550 Build-file programming with the "unified" build system
 551 ======================================================
 552
 553 "Build files" are called "Makefile" on Unix-like operating systems,
 554 "descrip.mms" for MMS on VMS, "makefile" for nmake on Windows, etc.
 555
 556 To use the "unified" build system, the target configuration needs to
 557 set the three items 'build_scheme', 'build_file' and 'build_command'.
 558 In the rest of this section, we will assume that 'build_scheme' is set
 559 to "unified" (see the configurations documentation above for the
 560 details).
 561
 562 For any name given by 'build_file', the "unified" system expects a
 563 template file in Configurations/ named like the build file, with
 564 ".tmpl" appended, or in case of possible ambiguity, a combination of
 565 the second 'build_scheme' list item and the 'build_file' name.  For
 566 example, if 'build_file' is set to "Makefile", the template could be
 567 Configurations/Makefile.tmpl or Configurations/unix-Makefile.tmpl.
 568 In case both Configurations/unix-Makefile.tmpl and
 569 Configurations/Makefile.tmpl are present, the former takes
 570 precedence.
 571
 572 The build-file template is processed with the perl module
 573 Text::Template, using "{-" and "-}" as delimiters that enclose the
 574 perl code fragments that generate configuration-dependent content.
 575 Those perl fragments have access to all the hash variables from
 576 configdata.pem.
 577
 578 The build-file template is expected to define at least the following
 579 perl functions in a perl code fragment enclosed with "{-" and "-}".
 580 They are all expected to return a string with the lines they produce.
 581
 582     generatesrc - function that produces build file lines to generate
 583                   a source file from some input.
 584
 585                   It's called like this:
 586
 587                         generatesrc(src => "PATH/TO/tobegenerated",
 588                                     generator => [ "generatingfile", ... ]
 589                                     generator_incs => [ "INCL/PATH", ... ]
 590                                     generator_deps => [ "dep1", ... ]
 591                                     generator => [ "generatingfile", ... ]
 592                                     incs => [ "INCL/PATH", ... ],
 593                                     deps => [ "dep1", ... ],
 594                                     intent => one of "libs", "dso", "bin" );
 595
 596                   'src' has the name of the file to be generated.
 597                   'generator' is the command or part of command to
 598                   generate the file, of which the first item is
 599                   expected to be the file to generate from.
 600                   generatesrc() is expected to analyse and figure out
 601                   exactly how to apply that file and how to capture
 602                   the result.  'generator_incs' and 'generator_deps'
 603                   are include directories and files that the generator
 604                   file itself depends on.  'incs' and 'deps' are
 605                   include directories and files that are used if $(CC)
 606                   is used as an intermediary step when generating the
 607                   end product (the file indicated by 'src').  'intent'
 608                   indicates what the generated file is going to be
 609                   used for.
 610
 611     src2obj     - function that produces build file lines to build an
 612                   object file from source files and associated data.
 613
 614                   It's called like this:
 615
 616                         src2obj(obj => "PATH/TO/objectfile",
 617                                 srcs => [ "PATH/TO/sourcefile", ... ],
 618                                 deps => [ "dep1", ... ],
 619                                 incs => [ "INCL/PATH", ... ]
 620                                 intent => one of "lib", "dso", "bin" );
 621
 622                   'obj' has the intended object file *without*
 623                   extension, src2obj() is expected to add that.
 624                   'srcs' has the list of source files to build the
 625                   object file, with the first item being the source
 626                   file that directly corresponds to the object file.
 627                   'deps' is a list of explicit dependencies.  'incs'
 628                   is a list of include file directories.  Finally,
 629                   'intent' indicates what this object file is going
 630                   to be used for.
 631
 632     obj2lib     - function that produces build file lines to build a
 633                   static library file ("libfoo.a" in Unix terms) from
 634                   object files.
 635
 636                   called like this:
 637
 638                         obj2lib(lib => "PATH/TO/libfile",
 639                                 objs => [ "PATH/TO/objectfile", ... ]);
 640
 641                   'lib' has the intended library file name *without*
 642                   extension, obj2lib is expected to add that.  'objs'
 643                   has the list of object files (also *without*
 644                   extension) to build this library.
 645
 646     libobj2shlib - function that produces build file lines to build a
 647                   shareable object library file ("libfoo.so" in Unix
 648                   terms) from the corresponding static library file
 649                   or object files.
 650
 651                   called like this:
 652
 653                         libobj2shlib(shlib => "PATH/TO/shlibfile",
 654                                      lib => "PATH/TO/libfile",
 655                                      objs => [ "PATH/TO/objectfile", ... ],
 656                                      deps => [ "PATH/TO/otherlibfile", ... ]);
 657
 658                   'lib' has the intended library file name *without*
 659                   extension, libobj2shlib is expected to add that.
 660                   'shlib' has the corresponding shared library name
 661                   *without* extension.  'deps' has the list of other
 662                   libraries (also *without* extension) this library
 663                   needs to be linked with.  'objs' has the list of
 664                   object files (also *without* extension) to build
 665                   this library.
 666
 667                   This function has a choice; it can use the
 668                   corresponding static library as input to make the
 669                   shared library, or the list of object files.
 670
 671     obj2dso     - function that produces build file lines to build a
 672                   dynamic shared object file from object files.
 673
 674                   called like this:
 675
 676                         obj2dso(lib => "PATH/TO/libfile",
 677                                 objs => [ "PATH/TO/objectfile", ... ],
 678                                 deps => [ "PATH/TO/otherlibfile",
 679                                 ... ]);
 680
 681                   This is almost the same as libobj2shlib, but the
 682                   intent is to build a shareable library that can be
 683                   loaded in runtime (a "plugin"...).  The differences
 684                   are subtle, one of the most visible ones is that the
 685                   resulting shareable library is produced from object
 686                   files only.
 687
 688     obj2bin     - function that produces build file lines to build an
 689                   executable file from object files.
 690
 691                   called like this:
 692
 693                         obj2bin(bin => "PATH/TO/binfile",
 694                                 objs => [ "PATH/TO/objectfile", ... ],
 695                                 deps => [ "PATH/TO/libfile", ... ]);
 696
 697                   'bin' has the intended executable file name
 698                   *without* extension, obj2bin is expected to add
 699                   that.  'objs' has the list of object files (also
 700                   *without* extension) to build this library.  'deps'
 701                   has the list of library files (also *without*
 702                   extension) that the programs needs to be linked
 703                   with.
 704
 705     in2script   - function that produces build file lines to build a
 706                   script file from some input.
 707
 708                   called like this:
 709
 710                         in2script(script => "PATH/TO/scriptfile",
 711                                   sources => [ "PATH/TO/infile", ... ]);
 712
 713                   'script' has the intended script file name.
 714                   'sources' has the list of source files to build the
 715                   resulting script from.
 716
 717 In all cases, file file paths are relative to the build tree top, and
 718 the build file actions run with the build tree top as current working
 719 directory.
 720
 721 Make sure to end the section with these functions with a string that
 722 you thing is appropriate for the resulting build file.  If nothing
 723 else, end it like this:
 724
 725       "";       # Make sure no lingering values end up in the Makefile
 726     -}
 727
 728
 729 Configure helper scripts
 730 ========================
 731
 732 Configure uses helper scripts in this directory:
 733
 734 Checker scripts
 735 ---------------
 736
 737 These scripts are per platform family, to check the integrity of the
 738 tools used for configuration and building.  The checker script used is
 739 either {build_platform}-{build_file}-checker.pm or
 740 {build_platform}-checker.pm, where {build_platform} is the second
 741 'build_scheme' list element from the configuration target data, and
 742 {build_file} is 'build_file' from the same target data.
 743
 744 If the check succeeds, the script is expected to end with a non-zero
 745 expression.  If the check fails, the script can end with a zero, or
 746 with a `die`.