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`.