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 occurences 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 B<DEPEND> statements may have attributes, which apply to each
448 individual dependency in such a statement. For example:
450 DEPEND[libfoo.a]=libmandatory.a
451 DEPEND[libfoo.a]{weak}=libbar.a libcookie.a
453 With those statements, the dependency between C<libfoo.a> and
454 C<libmandatory.a> is strong, while the dependency between C<libfoo.a>
455 and C<libbar.a> and C<libcookie.a> is weak. See the description of
456 B<weak> in L</Known attributes> for more information.
458 =item B<GENERATE[>I<item>B<]> B<=> I<generator> I<generator-arg> ...
460 This specifies that the I<item> is generated using the I<generator>
461 with the I<generator-arg>s as arguments, plus the name of the output
462 file as last argument.
464 For I<generator>s where this is applicable, any B<INCLUDE> statement
465 for the same I<item> will be given to the I<generator> as its
466 inclusion directories. Likewise, any B<DEPEND> statement for the same
467 I<item> will be given to the I<generator> as an extra file or module
468 to load, where this is applicable.
470 The build file generators must be able to recognise the I<generator>.
471 Currently, they at least recognise files ending in C<.pl>, and will
472 execute them to generate the I<item>, and files ending in C<.in>,
473 which will be used as input for L<OpenSSL::Template> to generate
474 I<item> (in other words, we use the exact same style of
475 L</Perl nuggets> mechanism that is used to read F<build.info> files).
477 =item B<SOURCE[>I<item>B<]> B<=> I<file> ...
479 Collects filenames that will be used as source files for I<item>.
481 The I<item> must be a singular item, and may be any program, library,
482 module or script given with B<PROGRAMS>, B<LIBS>, B<MODULES> and
485 Static libraries may be sources. In that case, its object files are
486 used directly when building I<item> instead of relying on library
487 dependency and symbol resolution (through B<DEPEND> statements).
489 =item B<SHARED_SOURCE[>I<item>B<]> B<=> I<file> ...
491 Collects filenames that will be used as source files for I<item>.
493 The I<item> must be a singular item, and may be any library or module
494 given with B<LIBS> or B<MODULES>. For libraries, the given filenames
495 are only used for their shared form, so if the item is a library name
496 ending with C<.a>, the filenames will be ignored.
498 =item B<DEFINE[>I<items>B<]> B<=> I<name>[B<=>I<value>] ...
500 Collects I<name> / I<value> pairs (or just I<name> with no defined
501 value if no I<value> is given) associated with I<items>.
503 The build file generators will decide what to do with them. For
504 example, these pairs should become C macro definitions whenever a
505 C<.c> file is built into an object file.
507 =item B<INCLUDE[>I<items>B<]> B<=> I<dir> ...
509 Collects inclusion directories that will be used when building the
510 I<items> components (object files and whatever else). This is used at
511 the discretion of the build file generators.
515 =head2 Known attributes
517 Note: this will never be a complete list of attributes.
523 This is used to specify that the end products this is set for should
524 not be installed, that they are only internal. This is applicable on
525 internal static libraries, or on test programs.
529 This is used with B<SCRIPTS>, to specify that some scripts should be
530 installed in the "misc" directory rather than the normal program
535 This is used with B<MODULES>, to specify what modules are engines and
536 should be installed in the engines directory instead of the modules
541 This is used with B<DEPEND> where libraries are involved, to specify
542 that the dependency between two libraries is weak and is only there to
545 Without this attribute, a dependency between two libraries, expressed
546 like this, means that if C<libfoo.a> appears in a linking command
547 line, so will C<libmandatory.a>:
549 DEPEND[libfoo.a]=libmandatory.a
551 With this attribute, a dependency between two libraries, expressed
552 like this, means that if I<both> C<libfoo.a> and C<libmandatory.a>
553 appear in a linking command line (because of recursive dependencies
554 through other libraries), they will be ordered in such a way that this
555 dependency is maintained:
557 DEPEND[libfoo.a]{weak}=libfoo.a libcookie.a
559 This is useful in complex dependency trees where two libraries can be
560 used as alternatives for each other. In this example, C<lib1.a> and
561 C<lib2.a> have alternative implementations of the same thing, and
562 C<libmandatory.a> has unresolved references to that same thing, and is
563 therefore depending on either of them, but not both at the same time:
565 DEPEND[program1]=libmandatory.a lib1.a
566 DEPEND[program2]=libmandatory.a lib2.a
567 DEPEND[libmandatory]{weak}=lib1.a lib2.a
577 This is any platform specific file that describes the complete build,
578 with platform specific commands. On Unix, this is typically
579 F<Makefile>; on VMS, this is typically F<descrip.mms>.
581 =item "build file generator"
583 Perl code that generates build files, given configuration data and
584 data collected from F<build.info> files.
586 =item "plain statement"
588 Any F<build.info> statement of the form B<I<KEYWORD>>=I<values>, with
589 the exception of conditional statements and variable assignments.
591 =item "indexed statement"
593 Any F<build.info> statement of the form B<I<KEYWORD>[>I<items>B<]=>I<values>,
594 with the exception of conditional statements.
596 =item "intermediate file"
598 Any file that's an intermediate between a source file and an end
603 Any file that is mentioned in the B<PROGRAMS>, B<LIBS>, B<MODULES> or
610 For OpenSSL::Template documentation,
611 C<perldoc -o man util/perl/OpenSSL/Template.pm>
613 L<Text::Temlate|https://metacpan.org/pod/Text::Template>
617 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
619 Licensed under the Apache License 2.0 (the "License"). You may not use this
620 file except in compliance with the License. You can obtain a copy in the file
621 LICENSE in the source distribution or at
622 L<https://www.openssl.org/source/license.html>.