5 build.info - Building information files
17 B<SUBDIRS=> I<dir> ...
19 B<PROGRAMS=> I<name> ...
23 B<MODULES=> I<name> ...
25 B<SCRIPTS=> I<name> ...
27 B<DEPEND[>I<items>B<]=> I<otheritem> ...
29 B<GENERATE[>I<item>B<]=> I<generator> I<generator-args> ...
31 B<SOURCE[>I<item>B<]=> I<file> ...
33 B<SHARED_SOURCE[>I<item>B<]=> I<file> ...
35 B<DEFINE[>I<items>B<]=> I<name>[B<=>I<value>] ...
37 B<INCLUDE[>I<items>B<]=> I<dir> ...
39 B<$>I<VARIABLE>B<=>I<value>
43 OpenSSL's build system revolves around three questions:
47 =item What to build for?
49 This is about choice of platform (combination of hardware, operating
50 system, and toolchain).
54 This is about having all the information on what needs to be built and
57 =item How to build it?
59 This is about build file generation.
63 This document is all about the second item, "What to build?", and most
64 of all, how to specify that information.
66 For some terms used in this document, please see the L</GLOSSARY> at
69 =head2 F<build.info> files
71 F<build.info> files are meta data files for OpenSSL's built file
72 generators, and are used to specify exactly what end product files
73 (programs, libraries, modules or scripts) are to be produced, and from
76 Intermediate files, such as object files, are seldom referred to at
77 all. They sometimes can be, if there's a need, but this should happen
78 very rarely, and support for that sort of thing is added on as-needed
81 Any time a directory or file is expected in a statement value, Unix
82 syntax must be used, which means that the slash C</> must be used as
83 the directory separator.
89 Comments are any line that start with a hash sign (C<#>). The hash
90 sign may be preceded by any number of horizontal spaces.
94 F<build.info> files are platform agnostic. This means that there is
95 some information in them that is representative rather than specific.
97 This is particularly visible with end product names, they work more
98 like a tag than as the actual filename that's going to be produced.
99 This is because different platforms have different decorations on
100 different types of files.
102 For example, if we say that we want to produce a program C<foo>, it
103 would look like this:
107 However, the program filename may end up being just C<foo> (typical
108 for Unix), or C<foo.exe> (typical for Windows), or even C<BLAH$FOO.EXE>
109 (possible on VMS, depending on policy).
111 These platform specific decorations are not the concern of
112 F<build.info> files. The build file generators are responsible for
113 transforming these platform agnostic names to their platform specific
118 With the exception of variables and conditions, the general statement
123 =item B<I<KEYWORD>> B<=> I<value> ...
125 =item B<I<KEYWORD>[>I<items>B<]> B<=> I<value> ...
129 Every B<I<KEYWORD>> represents some particular type of information.
131 The first form (sometimes called "plain statement") is used to specify
132 information on what end products need to be built, for example:
135 LIBS=libpoly libcookie
136 MODULES=awesome-plugin
140 This says that we want to build programs C<foo> and C<bar>, the
141 libraries C<libpoly> and C<libcookie>, an awesome plugin module
142 C<awesome-plugin>, a couple of scripts C<tool1> and C<tool2>, and
143 finally that there are more F<build.info> files in subdirectories
146 The second form (sometimes called "indexed statement") is used to
147 specify further details for existing items, for example:
149 SOURCE[foo]=foo.c details.c
150 DEPEND[foo]=libcookie
152 This says that the program C<foo> is built from the source files
153 F<foo.c> and F<details.c>, and that it depends on the library
154 C<libcookie> (in other words, the library will be included when
155 linking that program together).
157 Multiple space separated items are allowed too:
160 SOURCE[details]=details.c
161 DEPEND[foo details]=libcookie
163 For any indexed statement for which the items haven't been specified
164 through any plain statement, or where the items exists but the indexed
165 statement does not apply, the value is simply ignored by the build
168 =head3 Statement attributes
170 Some statements can have attributes added to them, to allow for
171 variations on how they are treated.
175 =item B<I<KEYWORD>{> I<attrib> | I<attrib>B<=>I<attrib-value> [,...]B<}>
178 =item B<I<KEYWORD>[>I<items>B<]{> I<attrib> | I<attrib>B<=>I<attrib-value>
179 [,...]B<}> B<=> I<value> ...
183 Attributes are passed as they are to the build file generators, and
184 the exact interpretation of those attributes is entirely up to them
185 (see L</Known attributes> below for details).
189 LIBS{noinst,has_main}=libtestutil.a
191 This says that the static library C<libtestutil.a> should not be
192 installed (C<noinst>), and that it includes an object file that has
193 the C<main> symbol (C<has_main>). Most platforms don't need to know
194 the latter, but there are some where the program linker will not look
195 for C<main> in libraries unless it's explicitly told so, so this is
196 way to tell the build file generator to emit the necessary command
197 options to make that happen.
199 Attributes are accumulated globally. This means that a library could
200 be given like this in different places:
206 LIBS{noinst}=libwhatever
209 LIBS{has_main}=libwhatever
211 The end result is that the library C<libwhatever> will have the
212 attributes C<noinst> and C<has_main> attached to it.
214 =head3 Quoting and tokens
216 Statement values are normally split into a list of tokens, separated
219 To avoid having a value split up into several tokens, they may be
220 quoted with double (C<">) or single (C<'>) quotes.
224 PROGRAMS=foo "space cadet" bar
226 This says that we sant to build three programs, C<foo>, C<space cadet>
231 F<build.info> files include a very simple condition system, involving
232 the following keywords:
238 =item B<ELSIF[>0|1B<]>
246 This works like any condition system with similar syntax, and the
247 condition value in B<IF> and B<ELSIF> can really be any literal value
248 that perl can interpret as true or false.
250 Conditional statements are nesting.
252 In itself, this is not very powerful, but together with L</Perl nuggets>,
257 F<build.info> handles simple variables. They are defined by
262 =item B<$>I<NAME> B<=> I<value>
266 These variables can then be used as part of any statement value or
267 indexed statement item. This should be used with some care, as
268 I<variables are expanded into their values before the value they are
269 part of is tokenized>.
271 I<Variable assignment values are not tokenized.>
273 Variable references can be one of:
277 =item B<$>I<NAME> or B<${>I<NAME>B<}>
279 Simple reference; the variable reference is replaced with its value,
282 =item B<${>I<NAME>B</>I<str>B</>I<subst>B<}>
284 Substitution reference; the variable reference is replaced with its
285 value, modified by replacing all occurrences of I<str> with I<subst>.
291 Most of the statement values are accumulated globally from all the
292 F<build.info> files that are digested. There are two exceptions,
293 F<build.info> variables and B<SUBDIRS> statement, for which the scope
294 is the F<build.info> file they are in.
298 Whenever a F<build.info> file is read, it is passed through the Perl
299 template processor L<OpenSSL::Template>, which is a small extension of
302 Perl nuggets are anything between C<{-> and C<-}>, and whatever the
303 result from such a nugget is, that value will replace the nugget in
304 text form. This is useful to get dynamically generated F<build.info>
305 statements, and is most often seen used together with the B<IF> and
306 B<ELSIF> conditional statements.
310 IF[{- $disabled{something} -}]
311 # do whatever's needed when "something" is disabled
312 ELSIF[{- $somethingelse eq 'blah' -}]
313 # do whatever's needed to satisfy this condition
318 Normal Perl scope applies, so it's possible to have an initial perl
319 nugget that sets diverse global variables that are used in later
320 nuggets. Each nugget is a Perl block of its own, so B<my> definitions
321 are only in scope within the same nugget, while B<our> definitions are
322 in scope within the whole F<build.info> file.
332 If the condition is true (represented as C<1> here), everything
333 between this B<IF> and the next corresponding B<ELSIF> or B<ELSE>
334 applies, and the rest until the corresponding B<ENDIF> is skipped
337 If the condition is false (represented as C<0> here), everything
338 from this B<IF> is skipped over until the next corresponding B<ELSIF>
339 or B<ELSE>, at which point processing continues.
343 If F<build.info> statements have been skipped over to this point since
344 the corresponding B<IF> or B<ELSIF>, F<build.info> processing starts
345 again following this line.
347 =item B<ELSIF[>0|1B<]>
349 This is B<ELSE> and B<IF> combined.
353 Marks the end of a conditional.
357 =head2 Plain statements
361 =item B<SUBDIRS=> I<dir> ...
363 This instructs the F<build.info> reader to also read the F<build.info>
364 file in every specified directory. All directories should be given
365 relative to the location of the current F<build.info> file.
367 =item B<PROGRAMS=> I<name> ...
369 Collects names of programs that should be built.
371 B<PROGRAMS> statements may have attributes, which apply to all the
372 programs given in such a statement. For example:
377 With those two lines, the program C<foo> will not have the attribute
378 C<noinst>, while the program C<bar> will.
380 =item B<LIBS=> I<name> ...
382 Collects names of libraries that should be built.
384 The normal case is that libraries are built in both static and shared
385 form. However, if a name ends with C<.a>, only the static form will
388 Similarly, libraries may be referred in indexed statements as just the
389 plain name, or the name including the ending C<.a>. If given without
390 the ending C<.a>, any form available will be used, but if given with
391 the ending C<.a>, the static library form is used unconditionally.
393 B<LIBS> statements may have attributes, which apply to all the
394 libraries given in such a statement. For example:
399 With those two lines, the library C<libfoo> will not have the
400 attribute C<noinst>, while the library C<libbar> will.
402 =item B<MODULES=> I<name>
404 Collects names of dynamically loadable modules that should be built.
406 B<MODULES> statements may have attributes, which apply to all the
407 modules given in such a statement. For example:
412 With those two lines, the module C<foo> will not have the attribute
413 C<noinst>, while the module C<bar> will.
415 =item B<SCRIPTS=> I<name>
417 Collects names of scripts that should be built, or that just exist.
418 That is how they differ from programs, as programs are always expected
419 to be compiled from multiple sources.
421 B<SCRIPTS> statements may have attributes, which apply to all the
422 scripts given in such a statement. For example:
427 With those two lines, the script C<foo> will not have the attribute
428 C<noinst>, while the script C<bar> will.
432 =head2 Indexed statements
436 =item B<DEPEND[>I<items>B<]> B<=> I<file> ...
438 Collects dependencies, where I<items> depend on the given I<file>s.
440 As a special case, the I<items> may be empty, for which the build file
441 generators should make the whole build depend on the given I<file>s,
442 rather than the specific I<items>.
444 The I<items> may be any program, library, module, script, or any
445 filename used as a value anywhere.
447 The I<items> may also be literal build file targets. Those are
448 recognised by being surrounded be vertical bars (also known as the
449 "pipe" character), C<|>. For example:
451 DEPEND[|tests|]=fipsmodule.cnf
453 B<DEPEND> statements may have attributes, which apply to each
454 individual dependency in such a statement. For example:
456 DEPEND[libfoo.a]=libmandatory.a
457 DEPEND[libfoo.a]{weak}=libbar.a libcookie.a
459 With those statements, the dependency between C<libfoo.a> and
460 C<libmandatory.a> is strong, while the dependency between C<libfoo.a>
461 and C<libbar.a> and C<libcookie.a> is weak. See the description of
462 B<weak> in L</Known attributes> for more information.
464 B<DEPEND> is a bit more involving when used with I<item>s that are
465 generated with B<GENERATE>. This is described more in depth below.
467 =item B<GENERATE[>I<item>B<]> B<=> I<generator> I<generator-arg> ...
469 This specifies that the I<item> is generated using the I<generator>
470 with the I<generator-arg>s as arguments, plus the name of the output
471 file as last argument.
473 The build file generators must be able to recognise the I<generator>.
474 Currently, they at least recognise files ending in C<.pl>, and will
475 execute them to generate the I<item>, and files ending in C<.in>,
476 which will be used as input for L<OpenSSL::Template> to generate
477 I<item> (in other words, we use the exact same style of
478 L</Perl nuggets> mechanism that is used to read F<build.info> files).
480 For I<generator>s where this is applicable, any B<INCLUDE> statement
481 for the same I<item> will be given to the I<generator> as its
482 inclusion directories.
484 Likewise, For I<generator>s where this is applicable, any B<DEPEND>
485 statement for the same I<item> will be given to the I<generator> as an
486 extra file or module to load, where this is applicable.
490 =item The B<DEPEND> statement may be problematic:
492 Depending on what generator is used, a B<DEPEND> statement also acts
493 as an B<INCLUDE> statement for the directory where the I<file> is
494 located. In some cases, that's not quite feasible, because a module
495 isn't meant to be loaded by filename only and may require a nondefault
496 separation between the implied inclusion directory and the intended module
499 =item ... but there is a solution:
501 To enable that sort of separation, B<DEPEND> can use a slightly
502 different I<file> syntax, that looks like this:
504 B<DEPEND[>I<items>B<]> B<=> I<dir>|I<module>
506 The I<module> must be specified in a way that makes sense for the generator.
507 For example, when the generator implies perl (ends with C<.in>) and depends
508 on the module F<OpenSSL::foo> - a.k.a. F<OpenSSL/foo.pm> - which lives in
509 F<util/perl>, it feasible to have something like this:
511 GENERATE[something.c]=something.c.in
512 DEPEND[something.c]=util/perl|OpenSSL/foo.pm
516 =item B<SOURCE[>I<item>B<]> B<=> I<file> ...
518 Collects filenames that will be used as source files for I<item>.
520 The I<item> must be a singular item, and may be any program, library,
521 module or script given with B<PROGRAMS>, B<LIBS>, B<MODULES> and
524 Static libraries may be sources. In that case, its object files are
525 used directly when building I<item> instead of relying on library
526 dependency and symbol resolution (through B<DEPEND> statements).
528 B<SOURCE> statements may have attributes, which apply to each
529 individual dependency in such a statement. For example:
531 SOURCE[prog]=prog_a.c
532 SOURCE[prog]{check}=prog_b.c prog_c.c
534 With those statements, the association between C<prog> and C<prog_a.c>
535 comes with no extra attributes, while the association between C<prog>
536 and C<prog_b.c> as well as C<prog_c.c> comes with the extra attribute
539 =item B<SHARED_SOURCE[>I<item>B<]> B<=> I<file> ...
541 Collects filenames that will be used as source files for I<item>.
543 The I<item> must be a singular item, and may be any library or module
544 given with B<LIBS> or B<MODULES>. For libraries, the given filenames
545 are only used for their shared form, so if the item is a library name
546 ending with C<.a>, the filenames will be ignored.
548 B<SHARED_SOURCE> statements may have attributes, just as B<SOURCE>
551 =item B<DEFINE[>I<items>B<]> B<=> I<name>[B<=>I<value>] ...
553 Collects I<name> / I<value> pairs (or just I<name> with no defined
554 value if no I<value> is given) associated with I<items>.
556 The build file generators will decide what to do with them. For
557 example, these pairs should become C macro definitions whenever a
558 C<.c> file is built into an object file.
560 =item B<INCLUDE[>I<items>B<]> B<=> I<dir> ...
562 Collects inclusion directories that will be used when building the
563 I<items> components (object files and whatever else). This is used at
564 the discretion of the build file generators.
568 =head2 Known attributes
570 Note: this will never be a complete list of attributes.
576 This is used to specify that the end products this is set for should
577 not be installed, that they are only internal. This is applicable on
578 internal static libraries, or on test programs.
582 This is used with B<SCRIPTS>, to specify that some scripts should be
583 installed in the "misc" directory rather than the normal program
588 This is used with B<MODULES>, to specify what modules are engines and
589 should be installed in the engines directory instead of the modules
594 This is used with B<DEPEND> where libraries are involved, to specify
595 that the dependency between two libraries is weak and is only there to
598 Without this attribute, a dependency between two libraries, expressed
599 like this, means that if C<libfoo.a> appears in a linking command
600 line, so will C<libmandatory.a>:
602 DEPEND[libfoo.a]=libmandatory.a
604 With this attribute, a dependency between two libraries, expressed
605 like this, means that if I<both> C<libfoo.a> and C<libmandatory.a>
606 appear in a linking command line (because of recursive dependencies
607 through other libraries), they will be ordered in such a way that this
608 dependency is maintained:
610 DEPEND[libfoo.a]{weak}=libfoo.a libcookie.a
612 This is useful in complex dependency trees where two libraries can be
613 used as alternatives for each other. In this example, C<lib1.a> and
614 C<lib2.a> have alternative implementations of the same thing, and
615 C<libmandatory.a> has unresolved references to that same thing, and is
616 therefore depending on either of them, but not both at the same time:
618 DEPEND[program1]=libmandatory.a lib1.a
619 DEPEND[program2]=libmandatory.a lib2.a
620 DEPEND[libmandatory]{weak}=lib1.a lib2.a
630 This is any platform specific file that describes the complete build,
631 with platform specific commands. On Unix, this is typically
632 F<Makefile>; on VMS, this is typically F<descrip.mms>.
634 =item "build file generator"
636 Perl code that generates build files, given configuration data and
637 data collected from F<build.info> files.
639 =item "plain statement"
641 Any F<build.info> statement of the form B<I<KEYWORD>>=I<values>, with
642 the exception of conditional statements and variable assignments.
644 =item "indexed statement"
646 Any F<build.info> statement of the form B<I<KEYWORD>[>I<items>B<]=>I<values>,
647 with the exception of conditional statements.
649 =item "intermediate file"
651 Any file that's an intermediate between a source file and an end
656 Any file that is mentioned in the B<PROGRAMS>, B<LIBS>, B<MODULES> or
663 For OpenSSL::Template documentation,
664 C<perldoc -o man util/perl/OpenSSL/Template.pm>
666 L<Text::Template|https://metacpan.org/pod/Text::Template>
670 Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.
672 Licensed under the Apache License 2.0 (the "License"). You may not use this
673 file except in compliance with the License. You can obtain a copy in the file
674 LICENSE in the source distribution or at
675 L<https://www.openssl.org/source/license.html>.