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<}>
174 Attributes are passed as they are to the build file generators, and
175 the exact interpretation of those attributes is entirely up to them
176 (see L</Known attributes> below for details).
180 LIBS{noinst,has_main}=libtestutil.a
182 This says that the static library C<libtestutil.a> should not be
183 installed (C<noinst>), and that it includes an object file that has
184 the C<main> symbol (C<has_main>). Most platforms don't need to know
185 the latter, but there are some where the program linker will not look
186 for C<main> in libraries unless it's explicitly told so, so this is
187 way to tell the build file generator to emit the necessary command
188 options to make that happen.
190 Attributes are accumulated globally. This means that a library could
191 be given like this in different places:
197 LIBS{noinst}=libwhatever
200 LIBS{has_main}=libwhatever
202 The end result is that the library C<libwhatever> will have the
203 attributes C<noinst> and C<has_main> attached to it.
205 =head3 Quoting and tokens
207 Statement values are normally split into a list of tokens, separated
210 To avoid having a value split up into several tokens, they may be
211 quoted with double (C<">) or single (C<'>) quotes.
215 PROGRAMS=foo "space cadet" bar
217 This says that we sant to build three programs, C<foo>, C<space cadet>
222 F<build.info> files include a very simple condition system, involving
223 the following keywords:
229 =item B<ELSIF[>0|1B<]>
237 This works like any condition system with similar syntax, and the
238 condition value in B<IF> and B<ELSIF> can really be any literal value
239 that perl can interpret as true or false.
241 Conditional statements are nesting.
243 In itself, this is not very powerful, but together with L</Perl nuggets>,
248 F<build.info> handles simple variables. They are defined by
253 =item B<$>I<NAME> B<=> I<value>
257 These variables can then be used as part of any statement value or
258 indexed statement item. This should be used with some care, as
259 I<variables are expanded into their values before the value they are
260 part of is tokenized>.
262 I<Variable assignment values are not tokenized.>
266 Most of the statement values are accumulated globally from all the
267 F<build.info> files that are digested. There are two exceptions,
268 F<build.info> variables and B<SUBDIRS> statement, for which the scope
269 is the F<build.info> file they are in.
273 Whenever a F<build.info> file is read, it is passed through the Perl
274 template processor L<OpenSSL::Template>, which is a small extension of
277 Perl nuggets are anything between C<{-> and C<-}>, and whatever the
278 result from such a nugget is, that value will replace the nugget in
279 text form. This is useful to get dynamically generated F<build.info>
280 statements, and is most often seen used together with the B<IF> and
281 B<ELSIF> conditional statements.
285 IF[{- $disabled{something} -}]
286 # do whatever's needed when "something" is disabled
287 ELSIF[{- $somethingelse eq 'blah' -}]
288 # do whatever's needed to satisfy this condition
293 Normal Perl scope applies, so it's possible to have an initial perl
294 nugget that sets diverse global variables that are used in later
295 nuggets. Each nugget is a Perl block of its own, so B<my> definitions
296 are only in scope within the same nugget, while B<our> definitions are
297 in scope within the whole F<build.info> file.
307 If the condition is true (represented as C<1> here), everything
308 between this B<IF> and the next corresponding B<ELSIF> or B<ELSE>
309 applies, and the rest until the corresponding B<ENDIF> is skipped
312 If the condition is false (represented as C<0> here), everything
313 from this B<IF> is skipped over until the next corresponding B<ELSIF>
314 or B<ELSE>, at which point processing continues.
318 If F<build.info> statements have been skipped over to this point since
319 the corresponding B<IF> or B<ELSIF>, F<build.info> processing starts
320 again following this line.
322 =item B<ELSIF[>0|1B<]>
324 This is B<ELSE> and B<IF> combined.
328 Marks the end of a conditional.
332 =head2 Plain statements
336 =item B<SUBDIRS=> I<dir> ...
338 This instructs the F<build.info> reader to also read the F<build.info>
339 file in every specified directory. All directories should be given
340 relative to the location of the current F<build.info> file.
342 =item B<PROGRAMS=> I<name> ...
344 Collects names of programs that should be built.
346 B<PROGRAMS> statements may have attributes, which apply to all the
347 programs given in such a statement. For example:
352 With those two lines, the program C<foo> will not have the attribute
353 C<noinst>, while the program C<bar> will.
355 =item B<LIBS=> I<name> ...
357 Collects names of libraries that should be built.
359 The normal case is that libraries are built in both static and shared
360 form. However, if a name ends with C<.a>, only the static form will
363 Similarly, libraries may be referred in indexed statements as just the
364 plain name, or the name including the ending C<.a>. If given without
365 the ending C<.a>, any form available will be used, but if given with
366 the ending C<.a>, the static library form is used unconditionally.
368 B<LIBS> statements may have attributes, which apply to all the
369 libraries given in such a statement. For example:
374 With those two lines, the library C<libfoo> will not have the
375 attribute C<noinst>, while the library C<libbar> will.
377 =item B<MODULES=> I<name>
379 Collects names of dynamically loadable modules that should be built.
381 B<MODULES> statements may have attributes, which apply to all the
382 modules given in such a statement. For example:
387 With those two lines, the module C<foo> will not have the attribute
388 C<noinst>, while the module C<bar> will.
390 =item B<SCRIPTS=> I<name>
392 Collects names of scripts that should be built, or that just exist.
393 That is how they differ from programs, as programs are always expected
394 to be compiled from multiple sources.
396 B<SCRIPTS> statements may have attributes, which apply to all the
397 scripts given in such a statement. For example:
402 With those two lines, the script C<foo> will not have the attribute
403 C<noinst>, while the script C<bar> will.
407 =head2 Indexed statements
411 =item B<DEPEND[>I<item>B<]> B<=> I<file> ...
413 Collects dependencies, where I<item> depends on the given I<file>s.
415 As a special case, the I<item> may be empty, for which the build file
416 generators should make the whole build depend on the given I<file>s,
417 rather than some specific I<item>.
419 The I<item> may be any program, library, module, script, or any
420 filename used as a value anywhere.
422 =item B<GENERATE[>I<item>B<]> B<=> I<generator> I<generator-arg> ...
424 This specifies that the I<item> is generated using the I<generator>
425 with the I<generator-arg>s as arguments, plus the name of the output
426 file as last argument.
428 For I<generator>s where this is applicable, any B<INCLUDE> statement
429 for the same I<item> will be given to the I<generator> as its
430 inclusion directories.
432 The build file generators must be able to recognise the I<generator>.
433 Currently, they at least recognise files ending in C<.pl>, and will
434 execute them to generate the I<item>, and files ending in C<.in>,
435 which will be used as input for L<OpenSSL::Template> to generate
436 I<item> (in other words, we use the exact same style of
437 L</Perl nuggets> mechanism that is used to read F<build.info> files).
439 =item B<SOURCE[>I<item>B<]> B<=> I<file> ...
441 Collects filenames that will be used as source files for I<item>.
443 The I<item> must be a singular item, and may be any program, library,
444 module or script given with B<PROGRAMS>, B<LIBS>, B<MODULES> and
447 =item B<SHARED_SOURCE[>I<item>B<]> B<=> I<file> ...
449 Collects filenames that will be used as source files for I<item>.
451 The I<item> must be a singular item, and may be any library or module
452 given with B<LIBS> or B<MODULES>. For libraries, the given filenames
453 are only used for their shared form, so if the item is a library name
454 ending with C<.a>, the filenames will be ignored.
456 =item B<DEFINE[>I<item>B<]> B<=> I<name>[B<=>I<value>] ...
458 Collects I<name> / I<value> pairs (or just I<name> with no defined
459 value if no I<value> is given) associated with I<item>.
461 The build file generators will decide what to do with them. For
462 example, these pairs should become C macro definitions whenever a
463 C<.c> file is built into an object file.
465 =item B<INCLUDE[>I<item>B<]> B<=> I<dir> ...
467 Collects inclusion directories that will be used when building the
468 I<item> components (object files and whatever else). This is used at
469 the discretion of the build file generators.
473 =head2 Known attributes
475 Note: this will never be a complete list of attributes.
481 This is used to specify that the end products this is set for should
482 not be installed, that they are only internal. This is applicable on
483 internal static libraries, or on test programs.
487 This is used with B<SCRIPTS>, to specify that some scripts should be
488 installed in the "misc" directory rather than the normal program
493 This is used with B<MODULES>, to specify what modules are engines and
494 should be installed in the engines directory instead of the modules
505 This is any platform specific file that describes the complete build,
506 with platform specific commands. On Unix, this is typically
507 F<Makefile>; on VMS, this is typically F<descrip.mms>.
509 =item "build file generator"
511 Perl code that generates build files, given configuration data and
512 data collected from F<build.info> files.
514 =item "plain statement"
516 Any F<build.info> statement of the form B<I<KEYWORD>>=I<values>, with
517 the exception of conditional statements and variable assignments.
519 =item "indexed statement"
521 Any F<build.info> statement of the form B<I<KEYWORD>[>I<item>B<]=>I<values>,
522 with the exception of conditional statements.
524 =item "intermediate file"
526 Any file that's an intermediate between a source file and an end
531 Any file that is mentioned in the B<PROGRAMS>, B<LIBS>, B<MODULES> or
538 For OpenSSL::Template documentation,
539 C<perldoc -o man util/perl/OpenSSL/Template.pm>
541 L<Text::Temlate|https://metacpan.org/pod/Text::Template>
545 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
547 Licensed under the Apache License 2.0 (the "License"). You may not use this
548 file except in compliance with the License. You can obtain a copy in the file
549 LICENSE in the source distribution or at
550 L<https://www.openssl.org/source/license.html>.