From e20ba0a51571ce48043e129546deb15be30f287d Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Tue, 8 Oct 2019 10:30:21 +0200 Subject: [PATCH] Document build.info syntax internally Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/10121) --- doc/internal/man7/build.info.pod | 552 +++++++++++++++++++++++++++++++ 1 file changed, 552 insertions(+) create mode 100644 doc/internal/man7/build.info.pod diff --git a/doc/internal/man7/build.info.pod b/doc/internal/man7/build.info.pod new file mode 100644 index 0000000000..7eb2218859 --- /dev/null +++ b/doc/internal/man7/build.info.pod @@ -0,0 +1,552 @@ +=pod + +=head1 NAME + +build.info - Building information files + +=head1 SYNOPSIS + +B0|1B<]> + +B0|1B<]> + +B + +B + +B I ... + +B I ... + +B I ... + +B I ... + +B I ... + +BIB<]=> I ... + +BIB<]=> I I ... + +BIB<]=> I ... + +BIB<]=> I ... + +BIB<]=> I[B<=>I] ... + +BIB<]=> I ... + +B<$>IB<=>I + +=head1 DESCRIPTION + +OpenSSL's build system revolves around three questions: + +=over 4 + +=item What to build for? + +This is about choice of platform (combination of hardware, operating +system, and toolchain). + +=item What to build? + +This is about having all the information on what needs to be built and +from what. + +=item How to build it? + +This is about build file generation. + +=back + +This document is all about the second item, "What to build?", and most +of all, how to specify that information. + +For some terms used in this document, please see the L at +the end. + +=head2 F files + +F files are meta data files for OpenSSL's built file +generators, and are used to specify exactly what end product files +(programs, libraries, modules or scripts) are to be produced, and from +what sources. + +Intermediate files, such as object files, are seldom refered to at +all. They sometimes can be, if there's a need, but this should happen +very rarely, and support for that sort of thing is added on as-needed +basis. + +Any time a directory or file is expected in a statement value, Unix +syntax must be used, which means that the slash C must be used as +the directory separator. + +=head2 General syntax + +=head3 Comments + +Comments are any line that start with a hash sign (C<#>). The hash +sign may be preceded by any number of horizontal spaces. + +=head3 Filenames + +F files are platform agnostic. This means that there is +some information in them that is representative rather than specific. + +This is particularly visible with end product names, they work more +like a tag than as the actual filename that's going to be produced. +This is because different platforms have different decorations on +different types of files. + +For example, if we say that we want to produce a program C, it +would look like this: + + PROGRAM=foo + +However, the program filename may end up being just C (typical +for Unix), or C (typical for Windows), or even C +(possible on VMS, depending on policy). + +These platform specific decorations are not the concern of +F files. The build file generators are responsible for +transforming these platform agnostic names to their platform specific +counterparts. + +=head3 Statements + +With the exception of variables and conditions, the general statement +syntax is one of: + +=over 4 + +=item B> B<=> I ... + +=item B[>IB<]> B<=> I ... + +=back + +Every B> represents some particular type of information. + +The first form (sometimes called "plain statement") is used to specify +information on what end products need to be built, for example: + + PROGRAMS=foo bar + LIBS=libpoly libcookie + MODULES=awesome-plugin + SCRIPTS=tool1 tool2 + SUBDIRS=dir1 dir2 + +This says that we want to build programs C and C, the +libraries C and C, an awesome plugin module +C, a couple of scripts C and C, and +finally that there are more F files in subdirectories +C and C. + +The second form (sometimes called "indexed statement") is used to +specify further details for existing items, for example: + + SOURCE[foo]=foo.c details.c + DEPEND[foo]=libcookie + +This says that the program C is built from the source files +F and F, and that it depends on the library +C (in other words, the library will be included when +linking that program together). + +For any indexed statement for which the item hasn't been specified +through any plain statement, or where the item exists but the indexed +statement does not apply, the value is simply ignored by the build +file generators. + +=head3 Statement attributes + +Some statements can have attributes added to them, to allow for +variations on how they are treated. + +=over 4 + +=item B{> I | IB<=>I [,...]B<}> +B<=> I ... + +=back + +Attributes are passed as they are to the build file generators, and +the exact interpretation of those attributes is entirely up to them +(see L below for details). + +A current example: + + LIBS{noinst,has_main}=libtestutil.a + +This says that the static library C should not be +installed (C), and that it includes an object file that has +the C
symbol (C). Most platforms don't need to know +the latter, but there are some where the program linker will not look +for C
in libraries unless it's explicitly told so, so this is +way to tell the build file generator to emit the necessary command +options to make that happen. + +Attributes are accumulated globally. This means that a library could +be given like this in different places: + + # Location 1 + LIBS=libwhatever + + # Location 2 + LIBS{noinst}=libwhatever + + # Location 3 + LIBS{has_main}=libwhatever + +The end result is that the library C will have the +attributes C and C attached to it. + +=head3 Quoting and tokens + +Statement values are normally split into a list of tokens, separated +by spaces. + +To avoid having a value split up into several tokens, they may be +quoted with double (C<">) or single (C<'>) quotes. + +For example: + + PROGRAMS=foo "space cadet" bar + +This says that we sant to build three programs, C, C +and C. + +=head3 Conditionals + +F files include a very simple condition system, involving +the following keywords: + +=over 4 + +=item B0|1B<]> + +=item B0|1B<]> + +=item B + +=item B + +=back + +This works like any condition system with similar syntax, and the +condition value in B and B can really be any literal value +that perl can interpret as true or false. + +Conditional statements are nesting. + +In itself, this is not very powerful, but together with L, +it can be. + +=head3 Variables + +F handles simple variables. They are defined by +assignment: + +=over 4 + +=item B<$>I B<=> I + +=back + +These variables can then be used as part of any statement value or +indexed statement item. This should be used with some care, as +I. + +I + +=head2 Scope + +Most of the statement values are accumulated globally from all the +F files that are digested. There are two exceptions, +F variables and B statement, for which the scope +is the F file they are in. + +=head2 Perl nuggets + +Whenever a F file is read, it is passed through the Perl +template processor L, which is a small extension of +L. + +Perl nuggets are anything between C<{-> and C<-}>, and whatever the +result from such a nugget is, that value will replace the nugget in +text form. This is useful to get dynamically generated F +statements, and is most often seen used together with the B and +B conditional statements. + +For example: + + IF[{- $disabled{something} -}] + # do whatever's needed when "something" is disabled + ELSIF[{- $somethingelse eq 'blah' -}] + # do whatever's needed to satisfy this condition + ELSE + # fallback + ENDIF + +Normal Perl scope applies, so it's possible to have an initial perl +nugget that sets diverse global variables that are used in later +nuggets. Each nugget is a Perl block of its own, so B definitions +are only in scope within the same nugget, while B definitions are +in scope within the whole F file. + +=head1 REFERENCE + +=head2 Conditionals + +=over 4 + +=item B0|1B<]> + +If the condition is true (represented as C<1> here), everything +between this B and the next corresponding B or B +applies, and the rest until the corresponding B is skipped +over. + +If the condition is false (represented as C<0> here), everything +from this B is skipped over until the next corresponding B +or B, at which point processing continues. + +=item B + +If F statements have been skipped over to this point since +the corresponding B or B, F processing starts +again following this line. + +=item B0|1B<]> + +This is B and B combined. + +=item B + +Marks the end of a conditional. + +=back + +=head2 Plain statements + +=over 4 + +=item B I ... + +This instructs the F reader to also read the F +file in every specified directory. All directories should be given +relative to the location of the current F file. + +=item B I ... + +Collects names of programs that should be built. + +B statements may have attributes, which apply to all the +programs given in such a statement. For example: + + PROGRAMS=foo + PROGRAMS{noinst}=bar + +With those two lines, the program C will not have the attribute +C, while the program C will. + +=item B I ... + +Collects names of libraries that should be built. + +The normal case is that libraries are built in both static and shared +form. However, if a name ends with C<.a>, only the static form will +be produced. + +Similarly, libraries may be referred in indexed statements as just the +plain name, or the name including the ending C<.a>. If given without +the ending C<.a>, any form available will be used, but if given with +the ending C<.a>, the static library form is used unconditionally. + +B statements may have attributes, which apply to all the +libraries given in such a statement. For example: + + LIBS=libfoo + LIBS{noinst}=libbar + +With those two lines, the library C will not have the +attribute C, while the library C will. + +=item B I + +Collects names of dynamically loadable modules that should be built. + +B statements may have attributes, which apply to all the +modules given in such a statement. For example: + + MODULES=foo + MODULES{noinst}=bar + +With those two lines, the module C will not have the attribute +C, while the module C will. + +=item B I + +Collects names of scripts that should be built, or that just exist. +That is how they differ from programs, as programs are always expected +to be compiled from multiple sources. + +B statements may have attributes, which apply to all the +scripts given in such a statement. For example: + + SCRIPTS=foo + SCRIPTS{noinst}=bar + +With those two lines, the script C will not have the attribute +C, while the script C will. + +=back + +=head2 Indexed statements + +=over 4 + +=item BIB<]> B<=> I ... + +Collects dependencies, where I depends on the given Is. + +As a special case, the I may be empty, for which the build file +generators should make the whole build depend on the given Is, +rather than some specific I. + +The I may be any program, library, module, script, or any +filename used as a value anywhere. + +=item BIB<]> B<=> I I ... + +This specifies that the I is generated using the I +with the Is as arguments, plus the name of the output +file as last argument. + +For Is where this is applicable, any B statement +for the same I will be given to the I as its +inclusion directories. + +The build file generators must be able to recognise the I. +Currently, they at least recognise files ending in C<.pl>, and will +execute them to generate the I, and files ending in C<.in>, +which will be used as input for L to generate +I (in other words, we use the exact same style of +L mechanism that is used to read F files). + +=item BIB<]> B<=> I ... + +Collects filenames that will be used as source files for I. + +The I must be a singular item, and may be any program, library, +module or script given with B, B, B and +B. + +=item BIB<]> B<=> I ... + +Collects filenames that will be used as source files for I. + +The I must be a singular item, and may be any library or module +given with B or B. For libraries, the given filenames +are only used for their shared form, so if the item is a library name +ending with C<.a>, the filenames will be ignored. + +=item BIB<]> B<=> I[B<=>I] ... + +Collects I / I pairs (or just I with no defined +value if no I is given) associated with I. + +The build file generators will decide what to do with them. For +example, these pairs should become C macro definitions whenever a +C<.c> file is built into an object file. + +=item BIB<]> B<=> I ... + +Collects inclusion directories that will be used when building the +I components (object files and whatever else). This is used at +the discretion of the build file generators. + +=back + +=head2 Known attributes + +Note: this will never be a complete list of attributes. + +=over 4 + +=item B + +This is used to specify that the end products this is set for should +not be installed, that they are only internal. This is applicable on +internal static libraries, or on test programs. + +=item B + +This is used with B, to specify that some scripts should be +installed in the "misc" directory rather than the normal program +directory. + +=item B + +This is used with B, to specify what modules are engines and +should be installed in the engines directory instead of the modules +directory. + +=back + +=head1 GLOSSARY + +=over 4 + +=item "build file" + +This is any platform specific file that describes the complete build, +with platform specific commands. On Unix, this is typically +F; on VMS, this is typically F. + +=item "build file generator" + +Perl code that generates build files, given configuration data and +data collected from F files. + +=item "plain statement" + +Any F statement of the form B>=I, with +the exception of conditional statements and variable assignments. + +=item "indexed statement" + +Any F statement of the form B[>IB<]=>I, +with the exception of conditional statements. + +=item "intermediate file" + +Any file that's an intermediate between a source file and an end +product. + +=item "end product" + +Any file that is mentioned in the B, B, B or +B. + +=back + +=head1 SEE ALSO + +For OpenSSL::Template documentation, +C + +L + +=head1 COPYRIGHT + +Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use this +file except in compliance with the License. You can obtain a copy in the file +LICENSE in the source distribution or at +L. + +=cut -- 2.25.1