75c19a6857e1d5e1624c5fd44c593a70ef9e91cd
[openssl.git] / 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, ENGINES 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, engines 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 engine '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     ENGINES=dasync
124     SOURCE[dasync]=e_dasync.c
125     DEPEND[dasync]=../libcrypto
126     INCLUDE[dasync]=../include
127
128     ENGINES_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 engines
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 engines.
138 Also, both engines 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     ENGINES=engines/dasync
160     SOURCE[engines/dasync]=engines/e_dasync.c
161     DEPEND[engines/dasync]=libcrypto
162     INCLUDE[engines/dasync]=include
163
164     ENGINES_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 ENGINES may be used to declare engines only.
181
182 The indexes for SOURCE must only be end product files, such as
183 libraries, programs or engines.  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   engines   => a list of engines.  These are directly inferred from
213                the ENGINES 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', 'engines' 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         "engines" =>
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                 "engines" =>
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 engine
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.