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