diff options
author | Richard Levitte <levitte@openssl.org> | 2019-10-08 10:30:21 +0200 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2019-10-09 18:19:12 +0200 |
commit | e20ba0a51571ce48043e129546deb15be30f287d (patch) | |
tree | f255afd023591978314c2e3066009c1e07fd67c2 /doc | |
parent | 120cc034271e9ab52f92840a16784228e50564f9 (diff) |
Document build.info syntax internally
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10121)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/internal/man7/build.info.pod | 552 |
1 files changed, 552 insertions, 0 deletions
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 + +B<IF[>0|1B<]> + +B<ELSIF[>0|1B<]> + +B<ELSE> + +B<ENDIF> + +B<SUBDIRS=> I<dir> ... + +B<PROGRAMS=> I<name> ... + +B<LIBS=> I<name> ... + +B<MODULES=> I<name> ... + +B<SCRIPTS=> I<name> ... + +B<DEPEND[>I<item>B<]=> I<otheritem> ... + +B<GENERATE[>I<item>B<]=> I<generator> I<generator-args> ... + +B<SOURCE[>I<item>B<]=> I<file> ... + +B<SHARED_SOURCE[>I<item>B<]=> I<file> ... + +B<DEFINE[>I<item>B<]=> I<name>[B<=>I<value>] ... + +B<INCLUDE[>I<item>B<]=> I<dir> ... + +B<$>I<VARIABLE>B<=>I<value> + +=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</GLOSSARY> at +the end. + +=head2 F<build.info> files + +F<build.info> 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<build.info> 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<foo>, it +would look like this: + + PROGRAM=foo + +However, the program filename may end up being just C<foo> (typical +for Unix), or C<foo.exe> (typical for Windows), or even C<BLAH$FOO.EXE> +(possible on VMS, depending on policy). + +These platform specific decorations are not the concern of +F<build.info> 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<I<KEYWORD>> B<=> I<value> ... + +=item B<I<KEYWORD>[>I<item>B<]> B<=> I<value> ... + +=back + +Every B<I<KEYWORD>> 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<foo> and C<bar>, the +libraries C<libpoly> and C<libcookie>, an awesome plugin module +C<awesome-plugin>, a couple of scripts C<tool1> and C<tool2>, and +finally that there are more F<build.info> files in subdirectories +C<dir1> and C<dir2>. + +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<foo> is built from the source files +F<foo.c> and F<details.c>, and that it depends on the library +C<libcookie> (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<KEYWORD>{> I<attrib> | I<attrib>B<=>I<attrib-value> [,...]B<}> +B<=> I<value> ... + +=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</Known attributes> below for details). + +A current example: + + LIBS{noinst,has_main}=libtestutil.a + +This says that the static library C<libtestutil.a> should not be +installed (C<noinst>), and that it includes an object file that has +the C<main> symbol (C<has_main>). Most platforms don't need to know +the latter, but there are some where the program linker will not look +for C<main> 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<libwhatever> will have the +attributes C<noinst> and C<has_main> 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<foo>, C<space cadet> +and C<bar>. + +=head3 Conditionals + +F<build.info> files include a very simple condition system, involving +the following keywords: + +=over 4 + +=item B<IF[>0|1B<]> + +=item B<ELSIF[>0|1B<]> + +=item B<ELSE> + +=item B<ENDIF> + +=back + +This works like any condition system with similar syntax, and the +condition value in B<IF> and B<ELSIF> 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</Perl nuggets>, +it can be. + +=head3 Variables + +F<build.info> handles simple variables. They are defined by +assignment: + +=over 4 + +=item B<$>I<NAME> B<=> I<value> + +=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<variables are expanded into their values before the value they are +part of is tokenized>. + +I<Variable assignment values are not tokenized.> + +=head2 Scope + +Most of the statement values are accumulated globally from all the +F<build.info> files that are digested. There are two exceptions, +F<build.info> variables and B<SUBDIRS> statement, for which the scope +is the F<build.info> file they are in. + +=head2 Perl nuggets + +Whenever a F<build.info> file is read, it is passed through the Perl +template processor L<OpenSSL::Template>, which is a small extension of +L<Text::Template>. + +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<build.info> +statements, and is most often seen used together with the B<IF> and +B<ELSIF> 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<my> definitions +are only in scope within the same nugget, while B<our> definitions are +in scope within the whole F<build.info> file. + +=head1 REFERENCE + +=head2 Conditionals + +=over 4 + +=item B<IF[>0|1B<]> + +If the condition is true (represented as C<1> here), everything +between this B<IF> and the next corresponding B<ELSIF> or B<ELSE> +applies, and the rest until the corresponding B<ENDIF> is skipped +over. + +If the condition is false (represented as C<0> here), everything +from this B<IF> is skipped over until the next corresponding B<ELSIF> +or B<ELSE>, at which point processing continues. + +=item B<ELSE> + +If F<build.info> statements have been skipped over to this point since +the corresponding B<IF> or B<ELSIF>, F<build.info> processing starts +again following this line. + +=item B<ELSIF[>0|1B<]> + +This is B<ELSE> and B<IF> combined. + +=item B<ENDIF> + +Marks the end of a conditional. + +=back + +=head2 Plain statements + +=over 4 + +=item B<SUBDIRS=> I<dir> ... + +This instructs the F<build.info> reader to also read the F<build.info> +file in every specified directory. All directories should be given +relative to the location of the current F<build.info> file. + +=item B<PROGRAMS=> I<name> ... + +Collects names of programs that should be built. + +B<PROGRAMS> 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<foo> will not have the attribute +C<noinst>, while the program C<bar> will. + +=item B<LIBS=> I<name> ... + +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<LIBS> 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<libfoo> will not have the +attribute C<noinst>, while the library C<libbar> will. + +=item B<MODULES=> I<name> + +Collects names of dynamically loadable modules that should be built. + +B<MODULES> 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<foo> will not have the attribute +C<noinst>, while the module C<bar> will. + +=item B<SCRIPTS=> I<name> + +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<SCRIPTS> 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<foo> will not have the attribute +C<noinst>, while the script C<bar> will. + +=back + +=head2 Indexed statements + +=over 4 + +=item B<DEPEND[>I<item>B<]> B<=> I<file> ... + +Collects dependencies, where I<item> depends on the given I<file>s. + +As a special case, the I<item> may be empty, for which the build file +generators should make the whole build depend on the given I<file>s, +rather than some specific I<item>. + +The I<item> may be any program, library, module, script, or any +filename used as a value anywhere. + +=item B<GENERATE[>I<item>B<]> B<=> I<generator> I<generator-arg> ... + +This specifies that the I<item> is generated using the I<generator> +with the I<generator-arg>s as arguments, plus the name of the output +file as last argument. + +For I<generator>s where this is applicable, any B<INCLUDE> statement +for the same I<item> will be given to the I<generator> as its +inclusion directories. + +The build file generators must be able to recognise the I<generator>. +Currently, they at least recognise files ending in C<.pl>, and will +execute them to generate the I<item>, and files ending in C<.in>, +which will be used as input for L<OpenSSL::Template> to generate +I<item> (in other words, we use the exact same style of +L</Perl nuggets> mechanism that is used to read F<build.info> files). + +=item B<SOURCE[>I<item>B<]> B<=> I<file> ... + +Collects filenames that will be used as source files for I<item>. + +The I<item> must be a singular item, and may be any program, library, +module or script given with B<PROGRAMS>, B<LIBS>, B<MODULES> and +B<SCRIPTS>. + +=item B<SHARED_SOURCE[>I<item>B<]> B<=> I<file> ... + +Collects filenames that will be used as source files for I<item>. + +The I<item> must be a singular item, and may be any library or module +given with B<LIBS> or B<MODULES>. 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 B<DEFINE[>I<item>B<]> B<=> I<name>[B<=>I<value>] ... + +Collects I<name> / I<value> pairs (or just I<name> with no defined +value if no I<value> is given) associated with I<item>. + +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 B<INCLUDE[>I<item>B<]> B<=> I<dir> ... + +Collects inclusion directories that will be used when building the +I<item> 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<noinst> + +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<misc> + +This is used with B<SCRIPTS>, to specify that some scripts should be +installed in the "misc" directory rather than the normal program +directory. + +=item B<engine> + +This is used with B<MODULES>, 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<Makefile>; on VMS, this is typically F<descrip.mms>. + +=item "build file generator" + +Perl code that generates build files, given configuration data and +data collected from F<build.info> files. + +=item "plain statement" + +Any F<build.info> statement of the form B<I<KEYWORD>>=I<values>, with +the exception of conditional statements and variable assignments. + +=item "indexed statement" + +Any F<build.info> statement of the form B<I<KEYWORD>[>I<item>B<]=>I<values>, +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<PROGRAMS>, B<LIBS>, B<MODULES> or +B<SCRIPTS>. + +=back + +=head1 SEE ALSO + +For OpenSSL::Template documentation, +C<perldoc -o man util/perl/OpenSSL/Template.pm> + +L<Text::Temlate|https://metacpan.org/pod/Text::Template> + +=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<https://www.openssl.org/source/license.html>. + +=cut |