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<item>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<item>B<]=> I<name>[B<=>I<value>] ...
37 B<INCLUDE[>I<item>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 refered 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<item>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 For any indexed statement for which the item hasn't been specified
158 through any plain statement, or where the item exists but the indexed
159 statement does not apply, the value is simply ignored by the build
162 =head3 Statement attributes
164 Some statements can have attributes added to them, to allow for
165 variations on how they are treated.
169 =item B<I<KEYWORD>{> I<attrib> | I<attrib>B<=>I<attrib-value> [,...]B<}>
172 =item B<I<KEYWORD>[>I<item>B<]{> I<attrib> | I<attrib>B<=>I<attrib-value>
173 [,...]B<}> B<=> I<value> ...
177 Attributes are passed as they are to the build file generators, and
178 the exact interpretation of those attributes is entirely up to them
179 (see L</Known attributes> below for details).
183 LIBS{noinst,has_main}=libtestutil.a
185 This says that the static library C<libtestutil.a> should not be
186 installed (C<noinst>), and that it includes an object file that has
187 the C<main> symbol (C<has_main>). Most platforms don't need to know
188 the latter, but there are some where the program linker will not look
189 for C<main> in libraries unless it's explicitly told so, so this is
190 way to tell the build file generator to emit the necessary command
191 options to make that happen.
193 Attributes are accumulated globally. This means that a library could
194 be given like this in different places:
200 LIBS{noinst}=libwhatever
203 LIBS{has_main}=libwhatever
205 The end result is that the library C<libwhatever> will have the
206 attributes C<noinst> and C<has_main> attached to it.
208 =head3 Quoting and tokens
210 Statement values are normally split into a list of tokens, separated
213 To avoid having a value split up into several tokens, they may be
214 quoted with double (C<">) or single (C<'>) quotes.
218 PROGRAMS=foo "space cadet" bar
220 This says that we sant to build three programs, C<foo>, C<space cadet>
225 F<build.info> files include a very simple condition system, involving
226 the following keywords:
232 =item B<ELSIF[>0|1B<]>
240 This works like any condition system with similar syntax, and the
241 condition value in B<IF> and B<ELSIF> can really be any literal value
242 that perl can interpret as true or false.
244 Conditional statements are nesting.
246 In itself, this is not very powerful, but together with L</Perl nuggets>,
251 F<build.info> handles simple variables. They are defined by
256 =item B<$>I<NAME> B<=> I<value>
260 These variables can then be used as part of any statement value or
261 indexed statement item. This should be used with some care, as
262 I<variables are expanded into their values before the value they are
263 part of is tokenized>.
265 I<Variable assignment values are not tokenized.>
269 Most of the statement values are accumulated globally from all the
270 F<build.info> files that are digested. There are two exceptions,
271 F<build.info> variables and B<SUBDIRS> statement, for which the scope
272 is the F<build.info> file they are in.
276 Whenever a F<build.info> file is read, it is passed through the Perl
277 template processor L<OpenSSL::Template>, which is a small extension of
280 Perl nuggets are anything between C<{-> and C<-}>, and whatever the
281 result from such a nugget is, that value will replace the nugget in
282 text form. This is useful to get dynamically generated F<build.info>
283 statements, and is most often seen used together with the B<IF> and
284 B<ELSIF> conditional statements.
288 IF[{- $disabled{something} -}]
289 # do whatever's needed when "something" is disabled
290 ELSIF[{- $somethingelse eq 'blah' -}]
291 # do whatever's needed to satisfy this condition
296 Normal Perl scope applies, so it's possible to have an initial perl
297 nugget that sets diverse global variables that are used in later
298 nuggets. Each nugget is a Perl block of its own, so B<my> definitions
299 are only in scope within the same nugget, while B<our> definitions are
300 in scope within the whole F<build.info> file.
310 If the condition is true (represented as C<1> here), everything
311 between this B<IF> and the next corresponding B<ELSIF> or B<ELSE>
312 applies, and the rest until the corresponding B<ENDIF> is skipped
315 If the condition is false (represented as C<0> here), everything
316 from this B<IF> is skipped over until the next corresponding B<ELSIF>
317 or B<ELSE>, at which point processing continues.
321 If F<build.info> statements have been skipped over to this point since
322 the corresponding B<IF> or B<ELSIF>, F<build.info> processing starts
323 again following this line.
325 =item B<ELSIF[>0|1B<]>
327 This is B<ELSE> and B<IF> combined.
331 Marks the end of a conditional.
335 =head2 Plain statements
339 =item B<SUBDIRS=> I<dir> ...
341 This instructs the F<build.info> reader to also read the F<build.info>
342 file in every specified directory. All directories should be given
343 relative to the location of the current F<build.info> file.
345 =item B<PROGRAMS=> I<name> ...
347 Collects names of programs that should be built.
349 B<PROGRAMS> statements may have attributes, which apply to all the
350 programs given in such a statement. For example:
355 With those two lines, the program C<foo> will not have the attribute
356 C<noinst>, while the program C<bar> will.
358 =item B<LIBS=> I<name> ...
360 Collects names of libraries that should be built.
362 The normal case is that libraries are built in both static and shared
363 form. However, if a name ends with C<.a>, only the static form will
366 Similarly, libraries may be referred in indexed statements as just the
367 plain name, or the name including the ending C<.a>. If given without
368 the ending C<.a>, any form available will be used, but if given with
369 the ending C<.a>, the static library form is used unconditionally.
371 B<LIBS> statements may have attributes, which apply to all the
372 libraries given in such a statement. For example:
377 With those two lines, the library C<libfoo> will not have the
378 attribute C<noinst>, while the library C<libbar> will.
380 =item B<MODULES=> I<name>
382 Collects names of dynamically loadable modules that should be built.
384 B<MODULES> statements may have attributes, which apply to all the
385 modules given in such a statement. For example:
390 With those two lines, the module C<foo> will not have the attribute
391 C<noinst>, while the module C<bar> will.
393 =item B<SCRIPTS=> I<name>
395 Collects names of scripts that should be built, or that just exist.
396 That is how they differ from programs, as programs are always expected
397 to be compiled from multiple sources.
399 B<SCRIPTS> statements may have attributes, which apply to all the
400 scripts given in such a statement. For example:
405 With those two lines, the script C<foo> will not have the attribute
406 C<noinst>, while the script C<bar> will.
410 =head2 Indexed statements
414 =item B<DEPEND[>I<item>B<]> B<=> I<file> ...
416 Collects dependencies, where I<item> depends on the given I<file>s.
418 As a special case, the I<item> may be empty, for which the build file
419 generators should make the whole build depend on the given I<file>s,
420 rather than some specific I<item>.
422 The I<item> may be any program, library, module, script, or any
423 filename used as a value anywhere.
425 B<DEPEND> statements may have attributes, which apply to each
426 individual dependency in such a statement. For example:
428 DEPEND[libfoo.a]=libmandatory.a
429 DEPEND[libfoo.a]{weak}=libbar.a libcookie.a
431 With those statements, the dependency between C<libfoo.a> and
432 C<libmandatory.a> is strong, while the dependency between C<libfoo.a>
433 and C<libbar.a> and C<libcookie.a> is weak. See the description of
434 B<weak> in L</Known attributes> for more information.
436 =item B<GENERATE[>I<item>B<]> B<=> I<generator> I<generator-arg> ...
438 This specifies that the I<item> is generated using the I<generator>
439 with the I<generator-arg>s as arguments, plus the name of the output
440 file as last argument.
442 For I<generator>s where this is applicable, any B<INCLUDE> statement
443 for the same I<item> will be given to the I<generator> as its
444 inclusion directories.
446 The build file generators must be able to recognise the I<generator>.
447 Currently, they at least recognise files ending in C<.pl>, and will
448 execute them to generate the I<item>, and files ending in C<.in>,
449 which will be used as input for L<OpenSSL::Template> to generate
450 I<item> (in other words, we use the exact same style of
451 L</Perl nuggets> mechanism that is used to read F<build.info> files).
453 =item B<SOURCE[>I<item>B<]> B<=> I<file> ...
455 Collects filenames that will be used as source files for I<item>.
457 The I<item> must be a singular item, and may be any program, library,
458 module or script given with B<PROGRAMS>, B<LIBS>, B<MODULES> and
461 Static libraries may be sources. In that case, its object files are
462 used directly when building I<item> instead of relying on library
463 dependency and symbol resolution (through B<DEPEND> statements).
465 =item B<SHARED_SOURCE[>I<item>B<]> B<=> I<file> ...
467 Collects filenames that will be used as source files for I<item>.
469 The I<item> must be a singular item, and may be any library or module
470 given with B<LIBS> or B<MODULES>. For libraries, the given filenames
471 are only used for their shared form, so if the item is a library name
472 ending with C<.a>, the filenames will be ignored.
474 =item B<DEFINE[>I<item>B<]> B<=> I<name>[B<=>I<value>] ...
476 Collects I<name> / I<value> pairs (or just I<name> with no defined
477 value if no I<value> is given) associated with I<item>.
479 The build file generators will decide what to do with them. For
480 example, these pairs should become C macro definitions whenever a
481 C<.c> file is built into an object file.
483 =item B<INCLUDE[>I<item>B<]> B<=> I<dir> ...
485 Collects inclusion directories that will be used when building the
486 I<item> components (object files and whatever else). This is used at
487 the discretion of the build file generators.
491 =head2 Known attributes
493 Note: this will never be a complete list of attributes.
499 This is used to specify that the end products this is set for should
500 not be installed, that they are only internal. This is applicable on
501 internal static libraries, or on test programs.
505 This is used with B<SCRIPTS>, to specify that some scripts should be
506 installed in the "misc" directory rather than the normal program
511 This is used with B<MODULES>, to specify what modules are engines and
512 should be installed in the engines directory instead of the modules
517 This is used with B<DEPEND> where libraries are involved, to specify
518 that the dependency between two libraries is weak and is only there to
521 Without this attribute, a dependency between two libraries, expressed
522 like this, means that if C<libfoo.a> appears in a linking command
523 line, so will C<libmandatory.a>:
525 DEPEND[libfoo.a]=libmandatory.a
527 With this attribute, a dependency between two libraries, expressed
528 like this, means that if I<both> C<libfoo.a> and C<libmandatory.a>
529 appear in a linking command line (because of recursive dependencies
530 through other libraries), they will be ordered in such a way that this
531 dependency is maintained:
533 DEPEND[libfoo.a]{weak}=libfoo.a libcookie.a
535 This is useful in complex dependecy trees where two libraries can be
536 used as alternatives for each other. In this example, C<lib1.a> and
537 C<lib2.a> have alternative implementations of the same thing, and
538 C<libmandatory.a> has unresolved references to that same thing, and is
539 therefore depending on either of them, but not both at the same time:
541 DEPEND[program1]=libmandatory.a lib1.a
542 DEPEND[program2]=libmandatory.a lib2.a
543 DEPEND[libmandatory]{weak}=lib1.a lib2.a
553 This is any platform specific file that describes the complete build,
554 with platform specific commands. On Unix, this is typically
555 F<Makefile>; on VMS, this is typically F<descrip.mms>.
557 =item "build file generator"
559 Perl code that generates build files, given configuration data and
560 data collected from F<build.info> files.
562 =item "plain statement"
564 Any F<build.info> statement of the form B<I<KEYWORD>>=I<values>, with
565 the exception of conditional statements and variable assignments.
567 =item "indexed statement"
569 Any F<build.info> statement of the form B<I<KEYWORD>[>I<item>B<]=>I<values>,
570 with the exception of conditional statements.
572 =item "intermediate file"
574 Any file that's an intermediate between a source file and an end
579 Any file that is mentioned in the B<PROGRAMS>, B<LIBS>, B<MODULES> or
586 For OpenSSL::Template documentation,
587 C<perldoc -o man util/perl/OpenSSL/Template.pm>
589 L<Text::Temlate|https://metacpan.org/pod/Text::Template>
593 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
595 Licensed under the Apache License 2.0 (the "License"). You may not use this
596 file except in compliance with the License. You can obtain a copy in the file
597 LICENSE in the source distribution or at
598 L<https://www.openssl.org/source/license.html>.