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. Likewise, any B<DEPEND> statement for the same
445 I<item> will be given to the I<generator> as an extra file or module
446 to load, where this is applicable.
448 The build file generators must be able to recognise the I<generator>.
449 Currently, they at least recognise files ending in C<.pl>, and will
450 execute them to generate the I<item>, and files ending in C<.in>,
451 which will be used as input for L<OpenSSL::Template> to generate
452 I<item> (in other words, we use the exact same style of
453 L</Perl nuggets> mechanism that is used to read F<build.info> files).
455 =item B<SOURCE[>I<item>B<]> B<=> I<file> ...
457 Collects filenames that will be used as source files for I<item>.
459 The I<item> must be a singular item, and may be any program, library,
460 module or script given with B<PROGRAMS>, B<LIBS>, B<MODULES> and
463 Static libraries may be sources. In that case, its object files are
464 used directly when building I<item> instead of relying on library
465 dependency and symbol resolution (through B<DEPEND> statements).
467 =item B<SHARED_SOURCE[>I<item>B<]> B<=> I<file> ...
469 Collects filenames that will be used as source files for I<item>.
471 The I<item> must be a singular item, and may be any library or module
472 given with B<LIBS> or B<MODULES>. For libraries, the given filenames
473 are only used for their shared form, so if the item is a library name
474 ending with C<.a>, the filenames will be ignored.
476 =item B<DEFINE[>I<item>B<]> B<=> I<name>[B<=>I<value>] ...
478 Collects I<name> / I<value> pairs (or just I<name> with no defined
479 value if no I<value> is given) associated with I<item>.
481 The build file generators will decide what to do with them. For
482 example, these pairs should become C macro definitions whenever a
483 C<.c> file is built into an object file.
485 =item B<INCLUDE[>I<item>B<]> B<=> I<dir> ...
487 Collects inclusion directories that will be used when building the
488 I<item> components (object files and whatever else). This is used at
489 the discretion of the build file generators.
493 =head2 Known attributes
495 Note: this will never be a complete list of attributes.
501 This is used to specify that the end products this is set for should
502 not be installed, that they are only internal. This is applicable on
503 internal static libraries, or on test programs.
507 This is used with B<SCRIPTS>, to specify that some scripts should be
508 installed in the "misc" directory rather than the normal program
513 This is used with B<MODULES>, to specify what modules are engines and
514 should be installed in the engines directory instead of the modules
519 This is used with B<DEPEND> where libraries are involved, to specify
520 that the dependency between two libraries is weak and is only there to
523 Without this attribute, a dependency between two libraries, expressed
524 like this, means that if C<libfoo.a> appears in a linking command
525 line, so will C<libmandatory.a>:
527 DEPEND[libfoo.a]=libmandatory.a
529 With this attribute, a dependency between two libraries, expressed
530 like this, means that if I<both> C<libfoo.a> and C<libmandatory.a>
531 appear in a linking command line (because of recursive dependencies
532 through other libraries), they will be ordered in such a way that this
533 dependency is maintained:
535 DEPEND[libfoo.a]{weak}=libfoo.a libcookie.a
537 This is useful in complex dependecy trees where two libraries can be
538 used as alternatives for each other. In this example, C<lib1.a> and
539 C<lib2.a> have alternative implementations of the same thing, and
540 C<libmandatory.a> has unresolved references to that same thing, and is
541 therefore depending on either of them, but not both at the same time:
543 DEPEND[program1]=libmandatory.a lib1.a
544 DEPEND[program2]=libmandatory.a lib2.a
545 DEPEND[libmandatory]{weak}=lib1.a lib2.a
555 This is any platform specific file that describes the complete build,
556 with platform specific commands. On Unix, this is typically
557 F<Makefile>; on VMS, this is typically F<descrip.mms>.
559 =item "build file generator"
561 Perl code that generates build files, given configuration data and
562 data collected from F<build.info> files.
564 =item "plain statement"
566 Any F<build.info> statement of the form B<I<KEYWORD>>=I<values>, with
567 the exception of conditional statements and variable assignments.
569 =item "indexed statement"
571 Any F<build.info> statement of the form B<I<KEYWORD>[>I<item>B<]=>I<values>,
572 with the exception of conditional statements.
574 =item "intermediate file"
576 Any file that's an intermediate between a source file and an end
581 Any file that is mentioned in the B<PROGRAMS>, B<LIBS>, B<MODULES> or
588 For OpenSSL::Template documentation,
589 C<perldoc -o man util/perl/OpenSSL/Template.pm>
591 L<Text::Temlate|https://metacpan.org/pod/Text::Template>
595 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
597 Licensed under the Apache License 2.0 (the "License"). You may not use this
598 file except in compliance with the License. You can obtain a copy in the file
599 LICENSE in the source distribution or at
600 L<https://www.openssl.org/source/license.html>.