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