README
1Intro
2=====
3
4This directory contains a few sets of files that are used for
5configuration 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
18Configurations of OpenSSL target platforms
19==========================================
20
21Configuration targets are a collection of facts that we know about
22different platforms and their capabilities. We organise them in a
23hash table, where each entry represent a specific target.
24
25Note that configuration target names must be unique across all config
26files. The Configure script does check that a config file doesn't
27have config targets that shadow config targets from other files.
28
29In each table entry, the following keys are significant:
30
31 inherit_from => Other targets to inherit values from.
32 Explained further below. [1]
33 template => Set to 1 if this isn't really a platform
34 target. Instead, this target is a template
35 upon which other targets can be built.
36 Explained further below. [1]
37
38 sys_id => System identity for systems where that
39 is difficult to determine automatically.
40
41 enable => Enable specific configuration features.
42 This MUST be an array of words.
43 disable => Disable specific configuration features.
44 This MUST be an array of words.
45 Note: if the same feature is both enabled
46 and disabled, disable wins.
47
48 as => The assembler command. This is not always
49 used (for example on Unix, where the C
50 compiler is used instead).
51 asflags => Default assembler command flags [4].
52 cpp => The C preprocessor command, normally not
53 given, as the build file defaults are
54 usually good enough.
55 cppflags => Default C preprocessor flags [4].
56 defines => As an alternative, macro definitions may be
57 given here instead of in `cppflags' [4].
58 If given here, they MUST be as an array of
59 the string such as "MACRO=value", or just
60 "MACRO" for definitions without value.
61 includes => As an alternative, inclusion directories
62 may be given here instead of in `cppflags'
63 [4]. If given here, the MUST be an array
64 of strings, one directory specification
65 each.
66 cc => The C compiler command, usually one of "cc",
67 "gcc" or "clang". This command is normally
68 also used to link object files and
69 libraries into the final program.
70 cxx => The C++ compiler command, usually one of
71 "c++", "g++" or "clang++". This command is
72 also used when linking a program where at
73 least one of the object file is made from
74 C++ source.
75 cflags => Defaults C compiler flags [4].
76 cxxflags => Default C++ compiler flags [4]. If unset,
77 it gets the same value as cflags.
78
79 (linking is a complex thing, see [3] below)
80 ld => Linker command, usually not defined
81 (meaning the compiler command is used
82 instead).
83 (NOTE: this is here for future use, it's
84 not implemented yet)
85 lflags => Default flags used when linking apps,
86 shared libraries or DSOs [4].
87 ex_libs => Extra libraries that are needed when
88 linking shared libraries, DSOs or programs.
89 The value is also assigned to Libs.private
90 in $(libdir)/pkgconfig/libcrypto.pc.
91
92 shared_cppflags => Extra C preprocessor flags used when
93 processing C files for shared libraries.
94 shared_cflag => Extra C compiler flags used when compiling
95 for shared libraries, typically something
96 like "-fPIC".
97 shared_ldflag => Extra linking flags used when linking
98 shared libraries.
99 module_cppflags
100 module_cflags
101 module_ldflags => Has the same function as the corresponding
102 `shared_' attributes, but for building DSOs.
103 When unset, they get the same values as the
104 corresponding `shared_' attributes.
105
106 ar => The library archive command, the default is
107 "ar".
108 (NOTE: this is here for future use, it's
109 not implemented yet)
110 arflags => Flags to be used with the library archive
111 command. On Unix, this includes the
112 command letter, 'r' by default.
113
114 ranlib => The library archive indexing command, the
115 default is 'ranlib' it it exists.
116
117 unistd => An alternative header to the typical
118 '<unistd.h>'. This is very rarely needed.
119
120 shared_extension => File name extension used for shared
121 libraries.
122 obj_extension => File name extension used for object files.
123 On unix, this defaults to ".o" (NOTE: this
124 is here for future use, it's not
125 implemented yet)
126 exe_extension => File name extension used for executable
127 files. On unix, this defaults to "" (NOTE:
128 this is here for future use, it's not
129 implemented yet)
130 shlib_variant => A "variant" identifier inserted between the base
131 shared library name and the extension. On "unixy"
132 platforms (BSD, Linux, Solaris, MacOS/X, ...) this
133 supports installation of custom OpenSSL libraries
134 that don't conflict with other builds of OpenSSL
135 installed on the system. The variant identifier
136 becomes part of the SONAME of the library and also
137 any symbol versions (symbol versions are not used or
138 needed with MacOS/X). For example, on a system
139 where a default build would normally create the SSL
140 shared library as 'libssl.so -> libssl.so.1.1' with
141 the value of the symlink as the SONAME, a target
142 definition that sets 'shlib_variant => "-abc"' will
143 create 'libssl.so -> libssl-abc.so.1.1', again with
144 an SONAME equal to the value of the symlink. The
145 symbol versions associated with the variant library
146 would then be 'OPENSSL_ABC_<version>' rather than
147 the default 'OPENSSL_<version>'. The string inserted
148 into symbol versions is obtained by mapping all
149 letters in the "variant" identifier to upper case
150 and all non-alphanumeric characters to '_'.
151
152 thread_scheme => The type of threads is used on the
153 configured platform. Currently known
154 values are "(unknown)", "pthreads",
155 "uithreads" (a.k.a solaris threads) and
156 "winthreads". Except for "(unknown)", the
157 actual value is currently ignored but may
158 be used in the future. See further notes
159 below [2].
160 dso_scheme => The type of dynamic shared objects to build
161 for. This mostly comes into play with
162 engines, but can be used for other purposes
163 as well. Valid values are "DLFCN"
164 (dlopen() et al), "DLFCN_NO_H" (for systems
165 that use dlopen() et al but do not have
166 fcntl.h), "DL" (shl_load() et al), "WIN32"
167 and "VMS".
168 perlasm_scheme => The perlasm method used to create the
169 assembler files used when compiling with
170 assembler implementations.
171 shared_target => The shared library building method used.
172 This is a target found in Makefile.shared.
173 build_scheme => The scheme used to build up a Makefile.
174 In its simplest form, the value is a string
175 with the name of the build scheme.
176 The value may also take the form of a list
177 of strings, if the build_scheme is to have
178 some options. In this case, the first
179 string in the list is the name of the build
180 scheme.
181 Currently recognised build scheme is "unified".
182 For the "unified" build scheme, this item
183 *must* be an array with the first being the
184 word "unified" and the second being a word
185 to identify the platform family.
186
187 multilib => On systems that support having multiple
188 implementations of a library (typically a
189 32-bit and a 64-bit variant), this is used
190 to have the different variants in different
191 directories.
192
193 bn_ops => Building options (was just bignum options in
194 the earlier history of this option, hence the
195 name). This is a string of words that describe
196 algorithms' implementation parameters that
197 are optimal for the designated target platform,
198 such as the type of integers used to build up
199 the bignum, different ways to implement certain
200 ciphers and so on. To fully comprehend the
201 meaning, the best is to read the affected
202 source.
203 The valid words are:
204
205 THIRTY_TWO_BIT bignum limbs are 32 bits,
206 this is default if no
207 option is specified, it
208 works on any supported
209 system [unless "wider"
210 limb size is implied in
211 assembly code];
212 BN_LLONG bignum limbs are 32 bits,
213 but 64-bit 'unsigned long
214 long' is used internally
215 in calculations;
216 SIXTY_FOUR_BIT_LONG bignum limbs are 64 bits
217 and sizeof(long) is 8;
218 SIXTY_FOUR_BIT bignums limbs are 64 bits,
219 but execution environment
220 is ILP32;
221 RC4_CHAR RC4 key schedule is made
222 up of 'unsigned char's;
223 RC4_INT RC4 key schedule is made
224 up of 'unsigned int's;
225 EXPORT_VAR_AS_FN for shared libraries,
226 export vars as
227 accessor functions.
228
229 apps_aux_src => Extra source to build apps/openssl and other
230 apps, as needed by the target and that can be
231 collected in a library.
232 apps_init_src => Init source to build apps/openssl and other
233 apps, as needed by the target. This code
234 cannot be placed in a library, as the rest
235 of the code isn't expected to link to it
236 explicitly.
237 cpuid_asm_src => assembler implementation of cpuid code as
238 well as OPENSSL_cleanse().
239 Default to mem_clr.c
240 bn_asm_src => Assembler implementation of core bignum
241 functions.
242 Defaults to bn_asm.c
243 ec_asm_src => Assembler implementation of core EC
244 functions.
245 des_asm_src => Assembler implementation of core DES
246 encryption functions.
247 Defaults to 'des_enc.c fcrypt_b.c'
248 aes_asm_src => Assembler implementation of core AES
249 functions.
250 Defaults to 'aes_core.c aes_cbc.c'
251 bf_asm_src => Assembler implementation of core BlowFish
252 functions.
253 Defaults to 'bf_enc.c'
254 md5_asm_src => Assembler implementation of core MD5
255 functions.
256 sha1_asm_src => Assembler implementation of core SHA1,
257 functions, and also possibly SHA256 and
258 SHA512 ones.
259 cast_asm_src => Assembler implementation of core CAST
260 functions.
261 Defaults to 'c_enc.c'
262 rc4_asm_src => Assembler implementation of core RC4
263 functions.
264 Defaults to 'rc4_enc.c rc4_skey.c'
265 rmd160_asm_src => Assembler implementation of core RMD160
266 functions.
267 rc5_asm_src => Assembler implementation of core RC5
268 functions.
269 Defaults to 'rc5_enc.c'
270 wp_asm_src => Assembler implementation of core WHIRLPOOL
271 functions.
272 cmll_asm_src => Assembler implementation of core CAMELLIA
273 functions.
274 Defaults to 'camellia.c cmll_misc.c cmll_cbc.c'
275 modes_asm_src => Assembler implementation of cipher modes,
276 currently the functions gcm_gmult_4bit and
277 gcm_ghash_4bit.
278 padlock_asm_src => Assembler implementation of core parts of
279 the padlock engine. This is mandatory on
280 any platform where the padlock engine might
281 actually be built.
282
283
284[1] as part of the target configuration, one can have a key called
285 'inherit_from' that indicate what other configurations to inherit
286 data from. These are resolved recursively.
287
288 Inheritance works as a set of default values that can be overridden
289 by corresponding key values in the inheriting configuration.
290
291 Note 1: any configuration table can be used as a template.
292 Note 2: pure templates have the attribute 'template => 1' and
293 cannot be used as build targets.
294
295 If several configurations are given in the 'inherit_from' array,
296 the values of same attribute are concatenated with space
297 separation. With this, it's possible to have several smaller
298 templates for different configuration aspects that can be combined
299 into a complete configuration.
300
301 instead of a scalar value or an array, a value can be a code block
302 of the form 'sub { /* your code here */ }'. This code block will
303 be called with the list of inherited values for that key as
304 arguments. In fact, the concatenation of strings is really done
305 by using 'sub { join(" ",@_) }' on the list of inherited values.
306
307 An example:
308
309 "foo" => {
310 template => 1,
311 haha => "ha ha",
312 hoho => "ho",
313 ignored => "This should not appear in the end result",
314 },
315 "bar" => {
316 template => 1,
317 haha => "ah",
318 hoho => "haho",
319 hehe => "hehe"
320 },
321 "laughter" => {
322 inherit_from => [ "foo", "bar" ],
323 hehe => sub { join(" ",(@_,"!!!")) },
324 ignored => "",
325 }
326
327 The entry for "laughter" will become as follows after processing:
328
329 "laughter" => {
330 haha => "ha ha ah",
331 hoho => "ho haho",
332 hehe => "hehe !!!",
333 ignored => ""
334 }
335
336[2] OpenSSL is built with threading capabilities unless the user
337 specifies 'no-threads'. The value of the key 'thread_scheme' may
338 be "(unknown)", in which case the user MUST give some compilation
339 flags to Configure.
340
341[3] OpenSSL has three types of things to link from object files or
342 static libraries:
343
344 - shared libraries; that would be libcrypto and libssl.
345 - shared objects (sometimes called dynamic libraries); that would
346 be the engines.
347 - applications; those are apps/openssl and all the test apps.
348
349 Very roughly speaking, linking is done like this (words in braces
350 represent the configuration settings documented at the beginning
351 of this file):
352
353 shared libraries:
354 {ld} $(CFLAGS) {lflags} {shared_ldflag} -o libfoo.so \
355 foo/something.o foo/somethingelse.o {ex_libs}
356
357 shared objects:
358 {ld} $(CFLAGS) {lflags} {module_ldflags} -o libeng.so \
359 blah1.o blah2.o -lcrypto {ex_libs}
360
361 applications:
362 {ld} $(CFLAGS) {lflags} -o app \
363 app1.o utils.o -lssl -lcrypto {ex_libs}
364
365[4] There are variants of these attribute, prefixed with `lib_',
366 `dso_' or `bin_'. Those variants replace the unprefixed attribute
367 when building library, DSO or program modules specifically.
368
369Historically, the target configurations came in form of a string with
370values separated by colons. This use is deprecated. The string form
371looked like this:
372
373 "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}"
374
375
376Build info files
377================
378
379The build.info files that are spread over the source tree contain the
380minimum information needed to build and distribute OpenSSL. It uses a
381simple and yet fairly powerful language to determine what needs to be
382built, from what sources, and other relationships between files.
383
384For every build.info file, all file references are relative to the
385directory of the build.info file for source files, and the
386corresponding build directory for built files if the build tree
387differs from the source tree.
388
389When processed, every line is processed with the perl module
390Text::Template, using the delimiters "{-" and "-}". The hashes
391%config and %target are passed to the perl fragments, along with
392$sourcedir and $builddir, which are the locations of the source
393directory for the current build.info file and the corresponding build
394directory, all relative to the top of the build tree.
395
396To begin with, things to be built are declared by setting specific
397variables:
398
399 PROGRAMS=foo bar
400 LIBS=libsomething
401 ENGINES=libeng
402 SCRIPTS=myhack
403 EXTRA=file1 file2
404
405Note that the files mentioned for PROGRAMS, LIBS and ENGINES *must* be
406without extensions. The build file templates will figure them out.
407
408For each thing to be built, it is then possible to say what sources
409they are built from:
410
411 PROGRAMS=foo bar
412 SOURCE[foo]=foo.c common.c
413 SOURCE[bar]=bar.c extra.c common.c
414
415It's also possible to tell some other dependencies:
416
417 DEPEND[foo]=libsomething
418 DEPEND[libbar]=libsomethingelse
419
420(it could be argued that 'libsomething' and 'libsomethingelse' are
421source as well. However, the files given through SOURCE are expected
422to be located in the source tree while files given through DEPEND are
423expected to be located in the build tree)
424
425It's also possible to depend on static libraries explicitly:
426
427 DEPEND[foo]=libsomething.a
428 DEPEND[libbar]=libsomethingelse.a
429
430This should be rarely used, and care should be taken to make sure it's
431only used when supported. For example, native Windows build doesn't
432support building static libraries and DLLs at the same time, so using
433static libraries on Windows can only be done when configured
434'no-shared'.
435
436One some platforms, shared libraries come with a name that's different
437from their static counterpart. That's declared as follows:
438
439 SHARED_NAME[libfoo]=cygfoo-{- $config{shlibver} -}
440
441The example is from Cygwin, which has a required naming convention.
442
443Sometimes, it makes sense to rename an output file, for example a
444library:
445
446 RENAME[libfoo]=libbar
447
448That line has "libfoo" renamed to "libbar". While it makes no
449sense at all to just have a rename like that (why not just use
450"libbar" everywhere?), it does make sense when it can be used
451conditionally. See a little further below for an example.
452
453In some cases, it's desirable to include some source files in the
454shared form of a library only:
455
456 SHARED_SOURCE[libfoo]=dllmain.c
457
458For any file to be built, it's also possible to tell what extra
459include paths the build of their source files should use:
460
461 INCLUDE[foo]=include
462
463In some cases, one might want to generate some source files from
464others, that's done as follows:
465
466 GENERATE[foo.s]=asm/something.pl $(CFLAGS)
467 GENERATE[bar.s]=asm/bar.S
468
469The value of each GENERATE line is a command line or part of it.
470Configure places no rules on the command line, except that the first
471item must be the generator file. It is, however, entirely up to the
472build file template to define exactly how those command lines should
473be handled, how the output is captured and so on.
474
475Sometimes, the generator file itself depends on other files, for
476example if it is a perl script that depends on other perl modules.
477This can be expressed using DEPEND like this:
478
479 DEPEND[asm/something.pl]=../perlasm/Foo.pm
480
481There may also be cases where the exact file isn't easily specified,
482but an inclusion directory still needs to be specified. INCLUDE can
483be used in that case:
484
485 INCLUDE[asm/something.pl]=../perlasm
486
487NOTE: GENERATE lines are limited to one command only per GENERATE.
488
489As a last resort, it's possible to have raw build file lines, between
490BEGINRAW and ENDRAW lines as follows:
491
492 BEGINRAW[Makefile(unix)]
493 haha.h: {- $builddir -}/Makefile
494 echo "/* haha */" > haha.h
495 ENDRAW[Makefile(unix)]
496
497The word within square brackets is the build_file configuration item
498or the build_file configuration item followed by the second word in the
499build_scheme configuration item for the configured target within
500parenthesis as shown above. For example, with the following relevant
501configuration items:
502
503 build_file => "build.ninja"
504 build_scheme => [ "unified", "unix" ]
505
506... these lines will be considered:
507
508 BEGINRAW[build.ninja]
509 build haha.h: echo "/* haha */" > haha.h
510 ENDRAW[build.ninja]
511
512 BEGINRAW[build.ninja(unix)]
513 build hoho.h: echo "/* hoho */" > hoho.h
514 ENDRAW[build.ninja(unix)]
515
516Should it be needed because the recipes within a RAW section might
517clash with those generated by Configure, it's possible to tell it
518not to generate them with the use of OVERRIDES, for example:
519
520 SOURCE[libfoo]=foo.c bar.c
521
522 OVERRIDES=bar.o
523 BEGINRAW[Makefile(unix)]
524 bar.o: bar.c
525 $(CC) $(CFLAGS) -DSPECIAL -c -o $@ $<
526 ENDRAW[Makefile(unix)]
527
528See the documentation further up for more information on configuration
529items.
530
531Finally, you can have some simple conditional use of the build.info
532information, looking like this:
533
534 IF[1]
535 something
536 ELSIF[2]
537 something other
538 ELSE
539 something else
540 ENDIF
541
542The expression in square brackets is interpreted as a string in perl,
543and will be seen as true if perl thinks it is, otherwise false. For
544example, the above would have "something" used, since 1 is true.
545
546Together with the use of Text::Template, this can be used as
547conditions based on something in the passed variables, for example:
548
549 IF[{- $disabled{shared} -}]
550 LIBS=libcrypto
551 SOURCE[libcrypto]=...
552 ELSE
553 LIBS=libfoo
554 SOURCE[libfoo]=...
555 ENDIF
556
557or:
558
559 # VMS has a cultural standard where all libraries are prefixed.
560 # For OpenSSL, the choice is 'ossl_'
561 IF[{- $config{target} =~ /^vms/ -}]
562 RENAME[libcrypto]=ossl_libcrypto
563 RENAME[libssl]=ossl_libssl
564 ENDIF
565
566
567Build-file programming with the "unified" build system
568======================================================
569
570"Build files" are called "Makefile" on Unix-like operating systems,
571"descrip.mms" for MMS on VMS, "makefile" for nmake on Windows, etc.
572
573To use the "unified" build system, the target configuration needs to
574set the three items 'build_scheme', 'build_file' and 'build_command'.
575In the rest of this section, we will assume that 'build_scheme' is set
576to "unified" (see the configurations documentation above for the
577details).
578
579For any name given by 'build_file', the "unified" system expects a
580template file in Configurations/ named like the build file, with
581".tmpl" appended, or in case of possible ambiguity, a combination of
582the second 'build_scheme' list item and the 'build_file' name. For
583example, if 'build_file' is set to "Makefile", the template could be
584Configurations/Makefile.tmpl or Configurations/unix-Makefile.tmpl.
585In case both Configurations/unix-Makefile.tmpl and
586Configurations/Makefile.tmpl are present, the former takes
587precedence.
588
589The build-file template is processed with the perl module
590Text::Template, using "{-" and "-}" as delimiters that enclose the
591perl code fragments that generate configuration-dependent content.
592Those perl fragments have access to all the hash variables from
593configdata.pem.
594
595The build-file template is expected to define at least the following
596perl functions in a perl code fragment enclosed with "{-" and "-}".
597They are all expected to return a string with the lines they produce.
598
599 generatesrc - function that produces build file lines to generate
600 a source file from some input.
601
602 It's called like this:
603
604 generatesrc(src => "PATH/TO/tobegenerated",
605 generator => [ "generatingfile", ... ]
606 generator_incs => [ "INCL/PATH", ... ]
607 generator_deps => [ "dep1", ... ]
608 generator => [ "generatingfile", ... ]
609 incs => [ "INCL/PATH", ... ],
610 deps => [ "dep1", ... ],
611 intent => one of "libs", "dso", "bin" );
612
613 'src' has the name of the file to be generated.
614 'generator' is the command or part of command to
615 generate the file, of which the first item is
616 expected to be the file to generate from.
617 generatesrc() is expected to analyse and figure out
618 exactly how to apply that file and how to capture
619 the result. 'generator_incs' and 'generator_deps'
620 are include directories and files that the generator
621 file itself depends on. 'incs' and 'deps' are
622 include directories and files that are used if $(CC)
623 is used as an intermediary step when generating the
624 end product (the file indicated by 'src'). 'intent'
625 indicates what the generated file is going to be
626 used for.
627
628 src2obj - function that produces build file lines to build an
629 object file from source files and associated data.
630
631 It's called like this:
632
633 src2obj(obj => "PATH/TO/objectfile",
634 srcs => [ "PATH/TO/sourcefile", ... ],
635 deps => [ "dep1", ... ],
636 incs => [ "INCL/PATH", ... ]
637 intent => one of "lib", "dso", "bin" );
638
639 'obj' has the intended object file *without*
640 extension, src2obj() is expected to add that.
641 'srcs' has the list of source files to build the
642 object file, with the first item being the source
643 file that directly corresponds to the object file.
644 'deps' is a list of explicit dependencies. 'incs'
645 is a list of include file directories. Finally,
646 'intent' indicates what this object file is going
647 to be used for.
648
649 obj2lib - function that produces build file lines to build a
650 static library file ("libfoo.a" in Unix terms) from
651 object files.
652
653 called like this:
654
655 obj2lib(lib => "PATH/TO/libfile",
656 objs => [ "PATH/TO/objectfile", ... ]);
657
658 'lib' has the intended library file name *without*
659 extension, obj2lib is expected to add that. 'objs'
660 has the list of object files (also *without*
661 extension) to build this library.
662
663 libobj2shlib - function that produces build file lines to build a
664 shareable object library file ("libfoo.so" in Unix
665 terms) from the corresponding static library file
666 or object files.
667
668 called like this:
669
670 libobj2shlib(shlib => "PATH/TO/shlibfile",
671 lib => "PATH/TO/libfile",
672 objs => [ "PATH/TO/objectfile", ... ],
673 deps => [ "PATH/TO/otherlibfile", ... ]);
674
675 'lib' has the intended library file name *without*
676 extension, libobj2shlib is expected to add that.
677 'shlib' has the corresponding shared library name
678 *without* extension. 'deps' has the list of other
679 libraries (also *without* extension) this library
680 needs to be linked with. 'objs' has the list of
681 object files (also *without* extension) to build
682 this library.
683
684 This function has a choice; it can use the
685 corresponding static library as input to make the
686 shared library, or the list of object files.
687
688 obj2dso - function that produces build file lines to build a
689 dynamic shared object file from object files.
690
691 called like this:
692
693 obj2dso(lib => "PATH/TO/libfile",
694 objs => [ "PATH/TO/objectfile", ... ],
695 deps => [ "PATH/TO/otherlibfile",
696 ... ]);
697
698 This is almost the same as libobj2shlib, but the
699 intent is to build a shareable library that can be
700 loaded in runtime (a "plugin"...). The differences
701 are subtle, one of the most visible ones is that the
702 resulting shareable library is produced from object
703 files only.
704
705 obj2bin - function that produces build file lines to build an
706 executable file from object files.
707
708 called like this:
709
710 obj2bin(bin => "PATH/TO/binfile",
711 objs => [ "PATH/TO/objectfile", ... ],
712 deps => [ "PATH/TO/libfile", ... ]);
713
714 'bin' has the intended executable file name
715 *without* extension, obj2bin is expected to add
716 that. 'objs' has the list of object files (also
717 *without* extension) to build this library. 'deps'
718 has the list of library files (also *without*
719 extension) that the programs needs to be linked
720 with.
721
722 in2script - function that produces build file lines to build a
723 script file from some input.
724
725 called like this:
726
727 in2script(script => "PATH/TO/scriptfile",
728 sources => [ "PATH/TO/infile", ... ]);
729
730 'script' has the intended script file name.
731 'sources' has the list of source files to build the
732 resulting script from.
733
734In all cases, file file paths are relative to the build tree top, and
735the build file actions run with the build tree top as current working
736directory.
737
738Make sure to end the section with these functions with a string that
739you thing is appropriate for the resulting build file. If nothing
740else, end it like this:
741
742 ""; # Make sure no lingering values end up in the Makefile
743 -}
744
745
746Configure helper scripts
747========================
748
749Configure uses helper scripts in this directory:
750
751Checker scripts
752---------------
753
754These scripts are per platform family, to check the integrity of the
755tools used for configuration and building. The checker script used is
756either {build_platform}-{build_file}-checker.pm or
757{build_platform}-checker.pm, where {build_platform} is the second
758'build_scheme' list element from the configuration target data, and
759{build_file} is 'build_file' from the same target data.
760
761If the check succeeds, the script is expected to end with a non-zero
762expression. If the check fails, the script can end with a zero, or
763with a `die`.
764
README.design
1Design document for the unified scheme data
2===========================================
3
4How are things connected?
5-------------------------
6
7The unified scheme takes all its data from the build.info files seen
8throughout the source tree. These files hold the minimum information
9needed to build end product files from diverse sources. See the
10section on build.info files below.
11
12From the information in build.info files, Configure builds up an
13information database as a hash table called %unified_info, which is
14stored in configdata.pm, found at the top of the build tree (which may
15or may not be the same as the source tree).
16
17Configurations/common.tmpl uses the data from %unified_info to
18generate the rules for building end product files as well as
19intermediary files with the help of a few functions found in the
20build-file templates. See the section on build-file templates further
21down for more information.
22
23build.info files
24----------------
25
26As mentioned earlier, build.info files are meant to hold the minimum
27information needed to build output files, and therefore only (with a
28few possible exceptions [1]) have information about end products (such
29as scripts, library files and programs) and source files (such as C
30files, C header files, assembler files, etc). Intermediate files such
31as object files are rarely directly referred to in build.info files (and
32when they are, it's always with the file name extension .o), they are
33inferred by Configure. By the same rule of minimalism, end product
34file name extensions (such as .so, .a, .exe, etc) are never mentioned
35in build.info. Their file name extensions will be inferred by the
36build-file templates, adapted for the platform they are meant for (see
37sections on %unified_info and build-file templates further down).
38
39The variables PROGRAMS, LIBS, ENGINES and SCRIPTS are used to declare
40end products. There are variants for them with '_NO_INST' as suffix
41(PROGRAM_NO_INST etc) to specify end products that shouldn't get
42installed.
43
44The variables SOURCE, DEPEND and INCLUDE are indexed by a produced
45file, and their values are the source used to produce that particular
46produced file, extra dependencies, and include directories needed.
47
48All their values in all the build.info throughout the source tree are
49collected together and form a set of programs, libraries, engines and
50scripts to be produced, source files, dependencies, etc etc etc.
51
52Let's have a pretend example, a very limited contraption of OpenSSL,
53composed of the program 'apps/openssl', the libraries 'libssl' and
54'libcrypto', an engine 'engines/ossltest' and their sources and
55dependencies.
56
57 # build.info
58 LIBS=libcrypto libssl
59 INCLUDE[libcrypto]=include
60 INCLUDE[libssl]=include
61 DEPEND[libssl]=libcrypto
62
63This is the top directory build.info file, and it tells us that two
64libraries are to be built, the include directory 'include/' shall be
65used throughout when building anything that will end up in each
66library, and that the library 'libssl' depend on the library
67'libcrypto' to function properly.
68
69 # apps/build.info
70 PROGRAMS=openssl
71 SOURCE[openssl]=openssl.c
72 INCLUDE[openssl]=.. ../include
73 DEPEND[openssl]=../libssl
74
75This is the build.info file in 'apps/', one may notice that all file
76paths mentioned are relative to the directory the build.info file is
77located in. This one tells us that there's a program to be built
78called 'apps/openssl' (the file name extension will depend on the
79platform and is therefore not mentioned in the build.info file). It's
80built from one source file, 'apps/openssl.c', and building it requires
81the use of '.' and 'include' include directories (both are declared
82from the point of view of the 'apps/' directory), and that the program
83depends on the library 'libssl' to function properly.
84
85 # crypto/build.info
86 LIBS=../libcrypto
87 SOURCE[../libcrypto]=aes.c evp.c cversion.c
88 DEPEND[cversion.o]=buildinf.h
89
90 GENERATE[buildinf.h]=../util/mkbuildinf.pl "$(CC) $(CFLAGS)" "$(PLATFORM)"
91 DEPEND[buildinf.h]=../Makefile
92 DEPEND[../util/mkbuildinf.pl]=../util/Foo.pm
93
94This is the build.info file in 'crypto', and it tells us a little more
95about what's needed to produce 'libcrypto'. LIBS is used again to
96declare that 'libcrypto' is to be produced. This declaration is
97really unnecessary as it's already mentioned in the top build.info
98file, but can make the info file easier to understand. This is to
99show that duplicate information isn't an issue.
100
101This build.info file informs us that 'libcrypto' is built from a few
102source files, 'crypto/aes.c', 'crypto/evp.c' and 'crypto/cversion.c'.
103It also shows us that building the object file inferred from
104'crypto/cversion.c' depends on 'crypto/buildinf.h'. Finally, it
105also shows the possibility to declare how some files are generated
106using some script, in this case a perl script, and how such scripts
107can be declared to depend on other files, in this case a perl module.
108
109Two things are worth an extra note:
110
111'DEPEND[cversion.o]' mentions an object file. DEPEND indexes is the
112only location where it's valid to mention them
113
114Lines in 'BEGINRAW'..'ENDRAW' sections must always mention files as
115seen from the top directory, no exception.
116
117 # ssl/build.info
118 LIBS=../libssl
119 SOURCE[../libssl]=tls.c
120
121This is the build.info file in 'ssl/', and it tells us that the
122library 'libssl' is built from the source file 'ssl/tls.c'.
123
124 # engines/build.info
125 ENGINES=dasync
126 SOURCE[dasync]=e_dasync.c
127 DEPEND[dasync]=../libcrypto
128 INCLUDE[dasync]=../include
129
130 ENGINES_NO_INST=ossltest
131 SOURCE[ossltest]=e_ossltest.c
132 DEPEND[ossltest]=../libcrypto.a
133 INCLUDE[ossltest]=../include
134
135This is the build.info file in 'engines/', telling us that two engines
136called 'engines/dasync' and 'engines/ossltest' shall be built, that
137dasync's source is 'engines/e_dasync.c' and ossltest's source is
138'engines/e_ossltest.c' and that the include directory 'include/' may
139be used when building anything that will be part of these engines.
140Also, both engines depend on the library 'libcrypto' to function
141properly. ossltest is explicitly linked with the static variant of
142the library 'libcrypto'. Finally, only dasync is being installed, as
143ossltest is only for internal testing.
144
145When Configure digests these build.info files, the accumulated
146information comes down to this:
147
148 LIBS=libcrypto libssl
149 SOURCE[libcrypto]=crypto/aes.c crypto/evp.c crypto/cversion.c
150 DEPEND[crypto/cversion.o]=crypto/buildinf.h
151 INCLUDE[libcrypto]=include
152 SOURCE[libssl]=ssl/tls.c
153 INCLUDE[libssl]=include
154 DEPEND[libssl]=libcrypto
155
156 PROGRAMS=apps/openssl
157 SOURCE[apps/openssl]=apps/openssl.c
158 INCLUDE[apps/openssl]=. include
159 DEPEND[apps/openssl]=libssl
160
161 ENGINES=engines/dasync
162 SOURCE[engines/dasync]=engines/e_dasync.c
163 DEPEND[engines/dasync]=libcrypto
164 INCLUDE[engines/dasync]=include
165
166 ENGINES_NO_INST=engines/ossltest
167 SOURCE[engines/ossltest]=engines/e_ossltest.c
168 DEPEND[engines/ossltest]=libcrypto.a
169 INCLUDE[engines/ossltest]=include
170
171 GENERATE[crypto/buildinf.h]=util/mkbuildinf.pl "$(CC) $(CFLAGS)" "$(PLATFORM)"
172 DEPEND[crypto/buildinf.h]=Makefile
173 DEPEND[util/mkbuildinf.pl]=util/Foo.pm
174
175
176A few notes worth mentioning:
177
178LIBS may be used to declare routine libraries only.
179
180PROGRAMS may be used to declare programs only.
181
182ENGINES may be used to declare engines only.
183
184The indexes for SOURCE must only be end product files, such as
185libraries, programs or engines. The values of SOURCE variables must
186only be source files (possibly generated).
187
188INCLUDE and DEPEND shows a relationship between different files
189(usually produced files) or between files and directories, such as a
190program depending on a library, or between an object file and some
191extra source file.
192
193When Configure processes the build.info files, it will take it as
194truth without question, and will therefore perform very few checks.
195If the build tree is separate from the source tree, it will assume
196that all built files and up in the build directory and that all source
197files are to be found in the source tree, if they can be found there.
198Configure will assume that source files that can't be found in the
199source tree (such as 'crypto/bildinf.h' in the example above) are
200generated and will be found in the build tree.
201
202
203The %unified_info database
204--------------------------
205
206The information in all the build.info get digested by Configure and
207collected into the %unified_info database, divided into the following
208indexes:
209
210 depends => a hash table containing 'file' => [ 'dependency' ... ]
211 pairs. These are directly inferred from the DEPEND
212 variables in build.info files.
213
214 engines => a list of engines. These are directly inferred from
215 the ENGINES variable in build.info files.
216
217 generate => a hash table containing 'file' => [ 'generator' ... ]
218 pairs. These are directly inferred from the GENERATE
219 variables in build.info files.
220
221 includes => a hash table containing 'file' => [ 'include' ... ]
222 pairs. These are directly inferred from the INCLUDE
223 variables in build.info files.
224
225 install => a hash table containing 'type' => [ 'file' ... ] pairs.
226 The types are 'programs', 'libraries', 'engines' and
227 'scripts', and the array of files list the files of
228 that type that should be installed.
229
230 libraries => a list of libraries. These are directly inferred from
231 the LIBS variable in build.info files.
232
233 programs => a list of programs. These are directly inferred from
234 the PROGRAMS variable in build.info files.
235
236 rawlines => a list of build-file lines. These are a direct copy of
237 the BEGINRAW..ENDRAW lines in build.info files. Note:
238 only the BEGINRAW..ENDRAW section for the current
239 platform are copied, the rest are ignored.
240
241 scripts => a list of scripts. There are directly inferred from
242 the SCRIPTS variable in build.info files.
243
244 sources => a hash table containing 'file' => [ 'sourcefile' ... ]
245 pairs. These are indirectly inferred from the SOURCE
246 variables in build.info files. Object files are
247 mentioned in this hash table, with source files from
248 SOURCE variables, and AS source files for programs and
249 libraries.
250
251 shared_sources =>
252 a hash table just like 'sources', but only as source
253 files (object files) for building shared libraries.
254
255As an example, here is how the build.info files example from the
256section above would be digested into a %unified_info table:
257
258 our %unified_info = (
259 "depends" =>
260 {
261 "apps/openssl" =>
262 [
263 "libssl",
264 ],
265 "crypto/buildinf.h" =>
266 [
267 "Makefile",
268 ],
269 "crypto/cversion.o" =>
270 [
271 "crypto/buildinf.h",
272 ],
273 "engines/dasync" =>
274 [
275 "libcrypto",
276 ],
277 "engines/ossltest" =>
278 [
279 "libcrypto.a",
280 ],
281 "libssl" =>
282 [
283 "libcrypto",
284 ],
285 "util/mkbuildinf.pl" =>
286 [
287 "util/Foo.pm",
288 ],
289 },
290 "engines" =>
291 [
292 "engines/dasync",
293 "engines/ossltest",
294 ],
295 "generate" =>
296 {
297 "crypto/buildinf.h" =>
298 [
299 "util/mkbuildinf.pl",
300 "\"\$(CC)",
301 "\$(CFLAGS)\"",
302 "\"$(PLATFORM)\"",
303 ],
304 },
305 "includes" =>
306 {
307 "apps/openssl" =>
308 [
309 ".",
310 "include",
311 ],
312 "engines/ossltest" =>
313 [
314 "include"
315 ],
316 "libcrypto" =>
317 [
318 "include",
319 ],
320 "libssl" =>
321 [
322 "include",
323 ],
324 "util/mkbuildinf.pl" =>
325 [
326 "util",
327 ],
328 }
329 "install" =>
330 {
331 "engines" =>
332 [
333 "engines/dasync",
334 ],
335 "libraries" =>
336 [
337 "libcrypto",
338 "libssl",
339 ],
340 "programs" =>
341 [
342 "apps/openssl",
343 ],
344 },
345 "libraries" =>
346 [
347 "libcrypto",
348 "libssl",
349 ],
350 "programs" =>
351 [
352 "apps/openssl",
353 ],
354 "rawlines" =>
355 [
356 ],
357 "sources" =>
358 {
359 "apps/openssl" =>
360 [
361 "apps/openssl.o",
362 ],
363 "apps/openssl.o" =>
364 [
365 "apps/openssl.c",
366 ],
367 "crypto/aes.o" =>
368 [
369 "crypto/aes.c",
370 ],
371 "crypto/cversion.o" =>
372 [
373 "crypto/cversion.c",
374 ],
375 "crypto/evp.o" =>
376 [
377 "crypto/evp.c",
378 ],
379 "engines/e_dasync.o" =>
380 [
381 "engines/e_dasync.c",
382 ],
383 "engines/dasync" =>
384 [
385 "engines/e_dasync.o",
386 ],
387 "engines/e_ossltest.o" =>
388 [
389 "engines/e_ossltest.c",
390 ],
391 "engines/ossltest" =>
392 [
393 "engines/e_ossltest.o",
394 ],
395 "libcrypto" =>
396 [
397 "crypto/aes.c",
398 "crypto/cversion.c",
399 "crypto/evp.c",
400 ],
401 "libssl" =>
402 [
403 "ssl/tls.c",
404 ],
405 "ssl/tls.o" =>
406 [
407 "ssl/tls.c",
408 ],
409 },
410 );
411
412As can be seen, everything in %unified_info is fairly simple suggest
413of information. Still, it tells us that to build all programs, we
414must build 'apps/openssl', and to build the latter, we will need to
415build all its sources ('apps/openssl.o' in this case) and all the
416other things it depends on (such as 'libssl'). All those dependencies
417need to be built as well, using the same logic, so to build 'libssl',
418we need to build 'ssl/tls.o' as well as 'libcrypto', and to build the
419latter...
420
421
422Build-file templates
423--------------------
424
425Build-file templates are essentially build-files (such as Makefile on
426Unix) with perl code fragments mixed in. Those perl code fragment
427will generate all the configuration dependent data, including all the
428rules needed to build end product files and intermediary files alike.
429At a minimum, there must be a perl code fragment that defines a set of
430functions that are used to generates specific build-file rules, to
431build static libraries from object files, to build shared libraries
432from static libraries, to programs from object files and libraries,
433etc.
434
435 generatesrc - function that produces build file lines to generate
436 a source file from some input.
437
438 It's called like this:
439
440 generatesrc(src => "PATH/TO/tobegenerated",
441 generator => [ "generatingfile", ... ]
442 generator_incs => [ "INCL/PATH", ... ]
443 generator_deps => [ "dep1", ... ]
444 incs => [ "INCL/PATH", ... ],
445 deps => [ "dep1", ... ],
446 intent => one of "libs", "dso", "bin" );
447
448 'src' has the name of the file to be generated.
449 'generator' is the command or part of command to
450 generate the file, of which the first item is
451 expected to be the file to generate from.
452 generatesrc() is expected to analyse and figure out
453 exactly how to apply that file and how to capture
454 the result. 'generator_incs' and 'generator_deps'
455 are include directories and files that the generator
456 file itself depends on. 'incs' and 'deps' are
457 include directories and files that are used if $(CC)
458 is used as an intermediary step when generating the
459 end product (the file indicated by 'src'). 'intent'
460 indicates what the generated file is going to be
461 used for.
462
463 src2obj - function that produces build file lines to build an
464 object file from source files and associated data.
465
466 It's called like this:
467
468 src2obj(obj => "PATH/TO/objectfile",
469 srcs => [ "PATH/TO/sourcefile", ... ],
470 deps => [ "dep1", ... ],
471 incs => [ "INCL/PATH", ... ]
472 intent => one of "lib", "dso", "bin" );
473
474 'obj' has the intended object file *without*
475 extension, src2obj() is expected to add that.
476 'srcs' has the list of source files to build the
477 object file, with the first item being the source
478 file that directly corresponds to the object file.
479 'deps' is a list of explicit dependencies. 'incs'
480 is a list of include file directories. Finally,
481 'intent' indicates what this object file is going
482 to be used for.
483
484 obj2lib - function that produces build file lines to build a
485 static library file ("libfoo.a" in Unix terms) from
486 object files.
487
488 called like this:
489
490 obj2lib(lib => "PATH/TO/libfile",
491 objs => [ "PATH/TO/objectfile", ... ]);
492
493 'lib' has the intended library file name *without*
494 extension, obj2lib is expected to add that. 'objs'
495 has the list of object files (also *without*
496 extension) to build this library.
497
498 libobj2shlib - function that produces build file lines to build a
499 shareable object library file ("libfoo.so" in Unix
500 terms) from the corresponding static library file
501 or object files.
502
503 called like this:
504
505 libobj2shlib(shlib => "PATH/TO/shlibfile",
506 lib => "PATH/TO/libfile",
507 objs => [ "PATH/TO/objectfile", ... ],
508 deps => [ "PATH/TO/otherlibfile", ... ]);
509
510 'lib' has the intended library file name *without*
511 extension, libobj2shlib is expected to add that.
512 'shlib' has the corresponding shared library name
513 *without* extension. 'deps' has the list of other
514 libraries (also *without* extension) this library
515 needs to be linked with. 'objs' has the list of
516 object files (also *without* extension) to build
517 this library.
518
519 This function has a choice; it can use the
520 corresponding static library as input to make the
521 shared library, or the list of object files.
522
523 obj2dynlib - function that produces build file lines to build a
524 dynamically loadable library file ("libfoo.so" on
525 Unix) from object files.
526
527 called like this:
528
529 obj2dynlib(lib => "PATH/TO/libfile",
530 objs => [ "PATH/TO/objectfile", ... ],
531 deps => [ "PATH/TO/otherlibfile",
532 ... ]);
533
534 This is almost the same as libobj2shlib, but the
535 intent is to build a shareable library that can be
536 loaded in runtime (a "plugin"...). The differences
537 are subtle, one of the most visible ones is that the
538 resulting shareable library is produced from object
539 files only.
540
541 obj2bin - function that produces build file lines to build an
542 executable file from object files.
543
544 called like this:
545
546 obj2bin(bin => "PATH/TO/binfile",
547 objs => [ "PATH/TO/objectfile", ... ],
548 deps => [ "PATH/TO/libfile", ... ]);
549
550 'bin' has the intended executable file name
551 *without* extension, obj2bin is expected to add
552 that. 'objs' has the list of object files (also
553 *without* extension) to build this library. 'deps'
554 has the list of library files (also *without*
555 extension) that the programs needs to be linked
556 with.
557
558 in2script - function that produces build file lines to build a
559 script file from some input.
560
561 called like this:
562
563 in2script(script => "PATH/TO/scriptfile",
564 sources => [ "PATH/TO/infile", ... ]);
565
566 'script' has the intended script file name.
567 'sources' has the list of source files to build the
568 resulting script from.
569
570Along with the build-file templates is the driving engine
571Configurations/common.tmpl, which looks through all the information in
572%unified_info and generates all the rulesets to build libraries,
573programs and all intermediate files, using the rule generating
574functions defined in the build-file template.
575
576As an example with the smaller build.info set we've seen as an
577example, producing the rules to build 'libcrypto' would result in the
578following calls:
579
580 # Note: libobj2shlib will only be called if shared libraries are
581 # to be produced.
582 # Note 2: libobj2shlib gets both the name of the static library
583 # and the names of all the object files that go into it. It's up
584 # to the implementation to decide which to use as input.
585 # Note 3: common.tmpl peals off the ".o" extension from all object
586 # files, as the platform at hand may have a different one.
587 libobj2shlib(shlib => "libcrypto",
588 lib => "libcrypto",
589 objs => [ "crypto/aes", "crypto/evp", "crypto/cversion" ],
590 deps => [ ]);
591
592 obj2lib(lib => "libcrypto"
593 objs => [ "crypto/aes", "crypto/evp", "crypto/cversion" ]);
594
595 src2obj(obj => "crypto/aes"
596 srcs => [ "crypto/aes.c" ],
597 deps => [ ],
598 incs => [ "include" ],
599 intent => "lib");
600
601 src2obj(obj => "crypto/evp"
602 srcs => [ "crypto/evp.c" ],
603 deps => [ ],
604 incs => [ "include" ],
605 intent => "lib");
606
607 src2obj(obj => "crypto/cversion"
608 srcs => [ "crypto/cversion.c" ],
609 deps => [ "crypto/buildinf.h" ],
610 incs => [ "include" ],
611 intent => "lib");
612
613 generatesrc(src => "crypto/buildinf.h",
614 generator => [ "util/mkbuildinf.pl", "\"$(CC)",
615 "$(CFLAGS)\"", "\"$(PLATFORM)\"" ],
616 generator_incs => [ "util" ],
617 generator_deps => [ "util/Foo.pm" ],
618 incs => [ ],
619 deps => [ ],
620 intent => "lib");
621
622The returned strings from all those calls are then concatenated
623together and written to the resulting build-file.
624