Configurations/README.design

   1 Design document for the unified scheme data
   2 ===========================================
   3
   4 How are things connected?
   5 -------------------------
   6
   7 The unified scheme takes all its data from the build.info files seen
   8 throughout the source tree.  These files hold the minimum information
   9 needed to build end product files from diverse sources.  See the
  10 section on build.info files below.
  11
  12 From the information in build.info files, Configure builds up an
  13 information database as a hash table called %unified_info, which is
  14 stored in configdata.pm, found at the top of the build tree (which may
  15 or may not be the same as the source tree).
  16
  17 Configurations/common.tmpl uses the data from %unified_info to
  18 generate the rules for building end product files as well as
  19 intermediary files with the help of a few functions found in the
  20 build-file templates.  See the section on build-file templates further
  21 down for more information.
  22
  23 build.info files
  24 ----------------
  25
  26 As mentioned earlier, build.info files are meant to hold the minimum
  27 information needed to build output files, and therefore only (with a
  28 few possible exceptions [1]) have information about end products (such
  29 as scripts, library files and programs) and source files (such as C
  30 files, C header files, assembler files, etc).  Intermediate files such
  31 as object files are rarely directly referred to in build.info files (and
  32 when they are, it's always with the file name extension .o), they are
  33 inferred by Configure.  By the same rule of minimalism, end product
  34 file name extensions (such as .so, .a, .exe, etc) are never mentioned
  35 in build.info.  Their file name extensions will be inferred by the
  36 build-file templates, adapted for the platform they are meant for (see
  37 sections on %unified_info and build-file templates further down).
  38
  39 The variables PROGRAMS, LIBS, MODULES and SCRIPTS are used to declare
  40 end products.  There are variants for them with '_NO_INST' as suffix
  41 (PROGRAM_NO_INST etc) to specify end products that shouldn't get
  42 installed.
  43
  44 The variables SOURCE, DEPEND, INCLUDE and DEFINE are indexed by a
  45 produced file, and their values are the source used to produce that
  46 particular produced file, extra dependencies, include directories
  47 needed, or C macros to be defined.
  48
  49 All their values in all the build.info throughout the source tree are
  50 collected together and form a set of programs, libraries, modules and
  51 scripts to be produced, source files, dependencies, etc etc etc.
  52
  53 Let's have a pretend example, a very limited contraption of OpenSSL,
  54 composed of the program 'apps/openssl', the libraries 'libssl' and
  55 'libcrypto', an module 'engines/ossltest' and their sources and
  56 dependencies.
  57
  58     # build.info
  59     LIBS=libcrypto libssl
  60     INCLUDE[libcrypto]=include
  61     INCLUDE[libssl]=include
  62     DEPEND[libssl]=libcrypto
  63
  64 This is the top directory build.info file, and it tells us that two
  65 libraries are to be built, the include directory 'include/' shall be
  66 used throughout when building anything that will end up in each
  67 library, and that the library 'libssl' depend on the library
  68 'libcrypto' to function properly.
  69
  70     # apps/build.info
  71     PROGRAMS=openssl
  72     SOURCE[openssl]=openssl.c
  73     INCLUDE[openssl]=.. ../include
  74     DEPEND[openssl]=../libssl
  75
  76 This is the build.info file in 'apps/', one may notice that all file
  77 paths mentioned are relative to the directory the build.info file is
  78 located in.  This one tells us that there's a program to be built
  79 called 'apps/openssl' (the file name extension will depend on the
  80 platform and is therefore not mentioned in the build.info file).  It's
  81 built from one source file, 'apps/openssl.c', and building it requires
  82 the use of '.' and 'include' include directories (both are declared
  83 from the point of view of the 'apps/' directory), and that the program
  84 depends on the library 'libssl' to function properly.
  85
  86     # crypto/build.info
  87     LIBS=../libcrypto
  88     SOURCE[../libcrypto]=aes.c evp.c cversion.c
  89     DEPEND[cversion.o]=buildinf.h
  90
  91     GENERATE[buildinf.h]=../util/mkbuildinf.pl "$(CC) $(CFLAGS)" "$(PLATFORM)"
  92     DEPEND[buildinf.h]=../Makefile
  93     DEPEND[../util/mkbuildinf.pl]=../util/Foo.pm
  94
  95 This is the build.info file in 'crypto', and it tells us a little more
  96 about what's needed to produce 'libcrypto'.  LIBS is used again to
  97 declare that 'libcrypto' is to be produced.  This declaration is
  98 really unnecessary as it's already mentioned in the top build.info
  99 file, but can make the info file easier to understand.  This is to
 100 show that duplicate information isn't an issue.
 101
 102 This build.info file informs us that 'libcrypto' is built from a few
 103 source files, 'crypto/aes.c', 'crypto/evp.c' and 'crypto/cversion.c'.
 104 It also shows us that building the object file inferred from
 105 'crypto/cversion.c' depends on 'crypto/buildinf.h'.  Finally, it
 106 also shows the possibility to declare how some files are generated
 107 using some script, in this case a perl script, and how such scripts
 108 can be declared to depend on other files, in this case a perl module.
 109
 110 Two things are worth an extra note:
 111
 112 'DEPEND[cversion.o]' mentions an object file.  DEPEND indexes is the
 113 only location where it's valid to mention them
 114
 115     # ssl/build.info
 116     LIBS=../libssl
 117     SOURCE[../libssl]=tls.c
 118
 119 This is the build.info file in 'ssl/', and it tells us that the
 120 library 'libssl' is built from the source file 'ssl/tls.c'.
 121
 122     # engines/build.info
 123     MODULES=dasync
 124     SOURCE[dasync]=e_dasync.c
 125     DEPEND[dasync]=../libcrypto
 126     INCLUDE[dasync]=../include
 127
 128     MODULES_NO_INST=ossltest
 129     SOURCE[ossltest]=e_ossltest.c
 130     DEPEND[ossltest]=../libcrypto.a
 131     INCLUDE[ossltest]=../include
 132
 133 This is the build.info file in 'engines/', telling us that two modules
 134 called 'engines/dasync' and 'engines/ossltest' shall be built, that
 135 dasync's source is 'engines/e_dasync.c' and ossltest's source is
 136 'engines/e_ossltest.c' and that the include directory 'include/' may
 137 be used when building anything that will be part of these modules.
 138 Also, both modules depend on the library 'libcrypto' to function
 139 properly.  ossltest is explicitly linked with the static variant of
 140 the library 'libcrypto'.  Finally, only dasync is being installed, as
 141 ossltest is only for internal testing.
 142
 143 When Configure digests these build.info files, the accumulated
 144 information comes down to this:
 145
 146     LIBS=libcrypto libssl
 147     SOURCE[libcrypto]=crypto/aes.c crypto/evp.c crypto/cversion.c
 148     DEPEND[crypto/cversion.o]=crypto/buildinf.h
 149     INCLUDE[libcrypto]=include
 150     SOURCE[libssl]=ssl/tls.c
 151     INCLUDE[libssl]=include
 152     DEPEND[libssl]=libcrypto
 153
 154     PROGRAMS=apps/openssl
 155     SOURCE[apps/openssl]=apps/openssl.c
 156     INCLUDE[apps/openssl]=. include
 157     DEPEND[apps/openssl]=libssl
 158
 159     MODULES=engines/dasync
 160     SOURCE[engines/dasync]=engines/e_dasync.c
 161     DEPEND[engines/dasync]=libcrypto
 162     INCLUDE[engines/dasync]=include
 163
 164     MODULES_NO_INST=engines/ossltest
 165     SOURCE[engines/ossltest]=engines/e_ossltest.c
 166     DEPEND[engines/ossltest]=libcrypto.a
 167     INCLUDE[engines/ossltest]=include
 168
 169     GENERATE[crypto/buildinf.h]=util/mkbuildinf.pl "$(CC) $(CFLAGS)" "$(PLATFORM)"
 170     DEPEND[crypto/buildinf.h]=Makefile
 171     DEPEND[util/mkbuildinf.pl]=util/Foo.pm
 172
 173
 174 A few notes worth mentioning:
 175
 176 LIBS may be used to declare routine libraries only.
 177
 178 PROGRAMS may be used to declare programs only.
 179
 180 MODULES may be used to declare modules only.
 181
 182 The indexes for SOURCE must only be end product files, such as
 183 libraries, programs or modules.  The values of SOURCE variables must
 184 only be source files (possibly generated).
 185
 186 INCLUDE and DEPEND shows a relationship between different files
 187 (usually produced files) or between files and directories, such as a
 188 program depending on a library, or between an object file and some
 189 extra source file.
 190
 191 When Configure processes the build.info files, it will take it as
 192 truth without question, and will therefore perform very few checks.
 193 If the build tree is separate from the source tree, it will assume
 194 that all built files and up in the build directory and that all source
 195 files are to be found in the source tree, if they can be found there.
 196 Configure will assume that source files that can't be found in the
 197 source tree (such as 'crypto/bildinf.h' in the example above) are
 198 generated and will be found in the build tree.
 199
 200
 201 The %unified_info database
 202 --------------------------
 203
 204 The information in all the build.info get digested by Configure and
 205 collected into the %unified_info database, divided into the following
 206 indexes:
 207
 208   depends   => a hash table containing 'file' => [ 'dependency' ... ]
 209                pairs.  These are directly inferred from the DEPEND
 210                variables in build.info files.
 211
 212   modules   => a list of modules.  These are directly inferred from
 213                the MODULES variable in build.info files.
 214
 215   generate  => a hash table containing 'file' => [ 'generator' ... ]
 216                pairs.  These are directly inferred from the GENERATE
 217                variables in build.info files.
 218
 219   includes  => a hash table containing 'file' => [ 'include' ... ]
 220                pairs.  These are directly inferred from the INCLUDE
 221                variables in build.info files.
 222
 223   install   => a hash table containing 'type' => [ 'file' ... ] pairs.
 224                The types are 'programs', 'libraries', 'modules' and
 225                'scripts', and the array of files list the files of
 226                that type that should be installed.
 227
 228   libraries => a list of libraries.  These are directly inferred from
 229                the LIBS variable in build.info files.
 230
 231   programs  => a list of programs.  These are directly inferred from
 232                the PROGRAMS variable in build.info files.
 233
 234   scripts   => a list of scripts.  There are directly inferred from
 235                the SCRIPTS variable in build.info files.
 236
 237   sources   => a hash table containing 'file' => [ 'sourcefile' ... ]
 238                pairs.  These are indirectly inferred from the SOURCE
 239                variables in build.info files.  Object files are
 240                mentioned in this hash table, with source files from
 241                SOURCE variables, and AS source files for programs and
 242                libraries.
 243
 244   shared_sources =>
 245                a hash table just like 'sources', but only as source
 246                files (object files) for building shared libraries.
 247
 248 As an example, here is how the build.info files example from the
 249 section above would be digested into a %unified_info table:
 250
 251     our %unified_info = (
 252         "depends" =>
 253             {
 254                 "apps/openssl" =>
 255                     [
 256                         "libssl",
 257                     ],
 258                 "crypto/buildinf.h" =>
 259                     [
 260                         "Makefile",
 261                     ],
 262                 "crypto/cversion.o" =>
 263                     [
 264                         "crypto/buildinf.h",
 265                     ],
 266                 "engines/dasync" =>
 267                     [
 268                         "libcrypto",
 269                     ],
 270                 "engines/ossltest" =>
 271                     [
 272                         "libcrypto.a",
 273                     ],
 274                 "libssl" =>
 275                     [
 276                         "libcrypto",
 277                     ],
 278                 "util/mkbuildinf.pl" =>
 279                     [
 280                         "util/Foo.pm",
 281                     ],
 282             },
 283         "modules" =>
 284             [
 285                 "engines/dasync",
 286                 "engines/ossltest",
 287             ],
 288         "generate" =>
 289             {
 290                 "crypto/buildinf.h" =>
 291                     [
 292                         "util/mkbuildinf.pl",
 293                         "\"\$(CC)",
 294                         "\$(CFLAGS)\"",
 295                         "\"$(PLATFORM)\"",
 296                     ],
 297             },
 298         "includes" =>
 299             {
 300                 "apps/openssl" =>
 301                     [
 302                         ".",
 303                         "include",
 304                     ],
 305                 "engines/ossltest" =>
 306                     [
 307                         "include"
 308                     ],
 309                 "libcrypto" =>
 310                     [
 311                         "include",
 312                     ],
 313                 "libssl" =>
 314                     [
 315                         "include",
 316                     ],
 317                 "util/mkbuildinf.pl" =>
 318                     [
 319                         "util",
 320                     ],
 321             }
 322         "install" =>
 323             {
 324                 "modules" =>
 325                     [
 326                         "engines/dasync",
 327                     ],
 328                 "libraries" =>
 329                     [
 330                         "libcrypto",
 331                         "libssl",
 332                     ],
 333                 "programs" =>
 334                     [
 335                         "apps/openssl",
 336                     ],
 337            },
 338         "libraries" =>
 339             [
 340                 "libcrypto",
 341                 "libssl",
 342             ],
 343         "programs" =>
 344             [
 345                 "apps/openssl",
 346             ],
 347         "sources" =>
 348             {
 349                 "apps/openssl" =>
 350                     [
 351                         "apps/openssl.o",
 352                     ],
 353                 "apps/openssl.o" =>
 354                     [
 355                         "apps/openssl.c",
 356                     ],
 357                 "crypto/aes.o" =>
 358                     [
 359                         "crypto/aes.c",
 360                     ],
 361                 "crypto/cversion.o" =>
 362                     [
 363                         "crypto/cversion.c",
 364                     ],
 365                 "crypto/evp.o" =>
 366                     [
 367                         "crypto/evp.c",
 368                     ],
 369                 "engines/e_dasync.o" =>
 370                     [
 371                         "engines/e_dasync.c",
 372                     ],
 373                 "engines/dasync" =>
 374                     [
 375                         "engines/e_dasync.o",
 376                     ],
 377                 "engines/e_ossltest.o" =>
 378                     [
 379                         "engines/e_ossltest.c",
 380                     ],
 381                 "engines/ossltest" =>
 382                     [
 383                         "engines/e_ossltest.o",
 384                     ],
 385                 "libcrypto" =>
 386                     [
 387                         "crypto/aes.c",
 388                         "crypto/cversion.c",
 389                         "crypto/evp.c",
 390                     ],
 391                 "libssl" =>
 392                     [
 393                         "ssl/tls.c",
 394                     ],
 395                 "ssl/tls.o" =>
 396                     [
 397                         "ssl/tls.c",
 398                     ],
 399             },
 400     );
 401
 402 As can be seen, everything in %unified_info is fairly simple suggest
 403 of information.  Still, it tells us that to build all programs, we
 404 must build 'apps/openssl', and to build the latter, we will need to
 405 build all its sources ('apps/openssl.o' in this case) and all the
 406 other things it depends on (such as 'libssl').  All those dependencies
 407 need to be built as well, using the same logic, so to build 'libssl',
 408 we need to build 'ssl/tls.o' as well as 'libcrypto', and to build the
 409 latter...
 410
 411
 412 Build-file templates
 413 --------------------
 414
 415 Build-file templates are essentially build-files (such as Makefile on
 416 Unix) with perl code fragments mixed in.  Those perl code fragment
 417 will generate all the configuration dependent data, including all the
 418 rules needed to build end product files and intermediary files alike.
 419 At a minimum, there must be a perl code fragment that defines a set of
 420 functions that are used to generates specific build-file rules, to
 421 build static libraries from object files, to build shared libraries
 422 from static libraries, to programs from object files and libraries,
 423 etc.
 424
 425     generatesrc - function that produces build file lines to generate
 426                   a source file from some input.
 427
 428                   It's called like this:
 429
 430                         generatesrc(src => "PATH/TO/tobegenerated",
 431                                     generator => [ "generatingfile", ... ]
 432                                     generator_incs => [ "INCL/PATH", ... ]
 433                                     generator_deps => [ "dep1", ... ]
 434                                     incs => [ "INCL/PATH", ... ],
 435                                     deps => [ "dep1", ... ],
 436                                     intent => one of "libs", "dso", "bin" );
 437
 438                   'src' has the name of the file to be generated.
 439                   'generator' is the command or part of command to
 440                   generate the file, of which the first item is
 441                   expected to be the file to generate from.
 442                   generatesrc() is expected to analyse and figure out
 443                   exactly how to apply that file and how to capture
 444                   the result.  'generator_incs' and 'generator_deps'
 445                   are include directories and files that the generator
 446                   file itself depends on.  'incs' and 'deps' are
 447                   include directories and files that are used if $(CC)
 448                   is used as an intermediary step when generating the
 449                   end product (the file indicated by 'src').  'intent'
 450                   indicates what the generated file is going to be
 451                   used for.
 452
 453     src2obj     - function that produces build file lines to build an
 454                   object file from source files and associated data.
 455
 456                   It's called like this:
 457
 458                         src2obj(obj => "PATH/TO/objectfile",
 459                                 srcs => [ "PATH/TO/sourcefile", ... ],
 460                                 deps => [ "dep1", ... ],
 461                                 incs => [ "INCL/PATH", ... ]
 462                                 intent => one of "lib", "dso", "bin" );
 463
 464                   'obj' has the intended object file with '.o'
 465                   extension, src2obj() is expected to change it to
 466                   something more suitable for the platform.
 467                   'srcs' has the list of source files to build the
 468                   object file, with the first item being the source
 469                   file that directly corresponds to the object file.
 470                   'deps' is a list of explicit dependencies.  'incs'
 471                   is a list of include file directories.  Finally,
 472                   'intent' indicates what this object file is going
 473                   to be used for.
 474
 475     obj2lib     - function that produces build file lines to build a
 476                   static library file ("libfoo.a" in Unix terms) from
 477                   object files.
 478
 479                   called like this:
 480
 481                         obj2lib(lib => "PATH/TO/libfile",
 482                                 objs => [ "PATH/TO/objectfile", ... ]);
 483
 484                   'lib' has the intended library file name *without*
 485                   extension, obj2lib is expected to add that.  'objs'
 486                   has the list of object files to build this library.
 487
 488     libobj2shlib - backward compatibility function that's used the
 489                   same way as obj2shlib (described next), and was
 490                   expected to build the shared library from the
 491                   corresponding static library when that was suitable.
 492                   NOTE: building a shared library from a static
 493                   library is now DEPRECATED, as they no longer share
 494                   object files.  Attempting to do this will fail.
 495
 496     obj2shlib   - function that produces build file lines to build a
 497                   shareable object library file ("libfoo.so" in Unix
 498                   terms) from the corresponding object files.
 499
 500                   called like this:
 501
 502                         obj2shlib(shlib => "PATH/TO/shlibfile",
 503                                   lib => "PATH/TO/libfile",
 504                                   objs => [ "PATH/TO/objectfile", ... ],
 505                                   deps => [ "PATH/TO/otherlibfile", ... ]);
 506
 507                   'lib' has the base (static) library file name
 508                   *without* extension.  This is useful in case
 509                   supporting files are needed (such as import
 510                   libraries on Windows).
 511                   'shlib' has the corresponding shared library name
 512                   *without* extension.  'deps' has the list of other
 513                   libraries (also *without* extension) this library
 514                   needs to be linked with.  'objs' has the list of
 515                   object files to build this library.
 516
 517     obj2dso     - function that produces build file lines to build a
 518                   dynamic shared object file from object files.
 519
 520                   called like this:
 521
 522                         obj2dso(lib => "PATH/TO/libfile",
 523                                 objs => [ "PATH/TO/objectfile", ... ],
 524                                 deps => [ "PATH/TO/otherlibfile",
 525                                 ... ]);
 526
 527                   This is almost the same as obj2shlib, but the
 528                   intent is to build a shareable library that can be
 529                   loaded in runtime (a "plugin"...).
 530
 531     obj2bin     - function that produces build file lines to build an
 532                   executable file from object files.
 533
 534                   called like this:
 535
 536                         obj2bin(bin => "PATH/TO/binfile",
 537                                 objs => [ "PATH/TO/objectfile", ... ],
 538                                 deps => [ "PATH/TO/libfile", ... ]);
 539
 540                   'bin' has the intended executable file name
 541                   *without* extension, obj2bin is expected to add
 542                   that.  'objs' has the list of object files to build
 543                   this library.  'deps' has the list of library files
 544                   (also *without* extension) that the programs needs
 545                   to be linked with.
 546
 547     in2script   - function that produces build file lines to build a
 548                   script file from some input.
 549
 550                   called like this:
 551
 552                         in2script(script => "PATH/TO/scriptfile",
 553                                   sources => [ "PATH/TO/infile", ... ]);
 554
 555                   'script' has the intended script file name.
 556                   'sources' has the list of source files to build the
 557                   resulting script from.
 558
 559 Along with the build-file templates is the driving template
 560 Configurations/common.tmpl, which looks through all the information in
 561 %unified_info and generates all the rulesets to build libraries,
 562 programs and all intermediate files, using the rule generating
 563 functions defined in the build-file template.
 564
 565 As an example with the smaller build.info set we've seen as an
 566 example, producing the rules to build 'libcrypto' would result in the
 567 following calls:
 568
 569     # Note: obj2shlib will only be called if shared libraries are
 570     # to be produced.
 571     # Note 2: obj2shlib must convert the '.o' extension to whatever
 572     # is suitable on the local platform.
 573     obj2shlib(shlib => "libcrypto",
 574               objs => [ "crypto/aes.o", "crypto/evp.o", "crypto/cversion.o" ],
 575               deps => [  ]);
 576
 577     obj2lib(lib => "libcrypto"
 578             objs => [ "crypto/aes.o", "crypto/evp.o", "crypto/cversion.o" ]);
 579
 580     src2obj(obj => "crypto/aes.o"
 581             srcs => [ "crypto/aes.c" ],
 582             deps => [ ],
 583             incs => [ "include" ],
 584             intent => "lib");
 585
 586     src2obj(obj => "crypto/evp.o"
 587             srcs => [ "crypto/evp.c" ],
 588             deps => [ ],
 589             incs => [ "include" ],
 590             intent => "lib");
 591
 592     src2obj(obj => "crypto/cversion.o"
 593             srcs => [ "crypto/cversion.c" ],
 594             deps => [ "crypto/buildinf.h" ],
 595             incs => [ "include" ],
 596             intent => "lib");
 597
 598     generatesrc(src => "crypto/buildinf.h",
 599                 generator => [ "util/mkbuildinf.pl", "\"$(CC)",
 600                                "$(CFLAGS)\"", "\"$(PLATFORM)\"" ],
 601                 generator_incs => [ "util" ],
 602                 generator_deps => [ "util/Foo.pm" ],
 603                 incs => [ ],
 604                 deps => [ ],
 605                 intent => "lib");
 606
 607 The returned strings from all those calls are then concatenated
 608 together and written to the resulting build-file.