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