B<SCRIPTS=> I<name> ...
-B<DEPEND[>I<item>B<]=> I<otheritem> ...
+B<DEPEND[>I<items>B<]=> I<otheritem> ...
B<GENERATE[>I<item>B<]=> I<generator> I<generator-args> ...
B<SHARED_SOURCE[>I<item>B<]=> I<file> ...
-B<DEFINE[>I<item>B<]=> I<name>[B<=>I<value>] ...
+B<DEFINE[>I<items>B<]=> I<name>[B<=>I<value>] ...
-B<INCLUDE[>I<item>B<]=> I<dir> ...
+B<INCLUDE[>I<items>B<]=> I<dir> ...
B<$>I<VARIABLE>B<=>I<value>
(programs, libraries, modules or scripts) are to be produced, and from
what sources.
-Intermediate files, such as object files, are seldom refered to at
+Intermediate files, such as object files, are seldom referred 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.
=item B<I<KEYWORD>> B<=> I<value> ...
-=item B<I<KEYWORD>[>I<item>B<]> B<=> I<value> ...
+=item B<I<KEYWORD>[>I<items>B<]> B<=> I<value> ...
=back
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
+Multiple space separated items are allowed too:
+
+ SOURCE[foo]=foo.c
+ SOURCE[details]=details.c
+ DEPEND[foo details]=libcookie
+
+For any indexed statement for which the items haven't been specified
+through any plain statement, or where the items exists but the indexed
statement does not apply, the value is simply ignored by the build
file generators.
=over 4
-=item B<I<KEYWORD>{> I<attrib> | I<attrib>B<=>I<attrib-value> [,...]B<}>
+=item B<I<KEYWORD>{> I<attrib> | I<attrib>B<=>I<attrib-value> [,...]B<}>
B<=> I<value> ...
+=item B<I<KEYWORD>[>I<items>B<]{> 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
I<Variable assignment values are not tokenized.>
+Variable references can be one of:
+
+=over 4
+
+=item B<$>I<NAME> or B<${>I<NAME>B<}>
+
+Simple reference; the variable reference is replaced with its value,
+verbatim.
+
+=item B<${>I<NAME>B</>I<str>B</>I<subst>B<}>
+
+Substitution reference; the variable reference is replaced with its
+value, modified by replacing all occurrences of I<str> with I<subst>.
+
+=back
+
=head2 Scope
Most of the statement values are accumulated globally from all the
=over 4
-=item B<DEPEND[>I<item>B<]> B<=> I<file> ...
+=item B<DEPEND[>I<items>B<]> B<=> I<file> ...
-Collects dependencies, where I<item> depends on the given I<file>s.
+Collects dependencies, where I<items> depend on the given I<file>s.
-As a special case, the I<item> may be empty, for which the build file
+As a special case, the I<items> 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>.
+rather than the specific I<items>.
-The I<item> may be any program, library, module, script, or any
+The I<items> may be any program, library, module, script, or any
filename used as a value anywhere.
+The I<items> may also be literal build file targets. Those are
+recognised by being surrounded be vertical bars (also known as the
+"pipe" character), C<|>. For example:
+
+ DEPEND[|tests|]=fipsmodule.cnf
+
+B<DEPEND> statements may have attributes, which apply to each
+individual dependency in such a statement. For example:
+
+ DEPEND[libfoo.a]=libmandatory.a
+ DEPEND[libfoo.a]{weak}=libbar.a libcookie.a
+
+With those statements, the dependency between C<libfoo.a> and
+C<libmandatory.a> is strong, while the dependency between C<libfoo.a>
+and C<libbar.a> and C<libcookie.a> is weak. See the description of
+B<weak> in L</Known attributes> for more information.
+
+B<DEPEND> is a bit more involving when used with I<item>s that are
+generated with B<GENERATE>. This is described more in depth below.
+
=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>,
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).
+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.
+
+Likewise, For I<generator>s where this is applicable, any B<DEPEND>
+statement for the same I<item> will be given to the I<generator> as an
+extra file or module to load, where this is applicable.
+
+=over 4
+
+=item The B<DEPEND> statement may be problematic:
+
+Depending on what generator is used, a B<DEPEND> statement also acts
+as an B<INCLUDE> statement for the directory where the I<file> is
+located. In some cases, that's not quite feasible, because a module
+isn't meant to be loaded by filename only and may require a nondefault
+separation between the implied inclusion directory and the intended module
+name.
+
+=item ... but there is a solution:
+
+To enable that sort of separation, B<DEPEND> can use a slightly
+different I<file> syntax, that looks like this:
+
+B<DEPEND[>I<items>B<]> B<=> I<dir>|I<module>
+
+The I<module> must be specified in a way that makes sense for the generator.
+For example, when the generator implies perl (ends with C<.in>) and depends
+on the module F<OpenSSL::foo> - a.k.a. F<OpenSSL/foo.pm> - which lives in
+F<util/perl>, it feasible to have something like this:
+
+ GENERATE[something.c]=something.c.in
+ DEPEND[something.c]=util/perl|OpenSSL/foo.pm
+
+=back
+
=item B<SOURCE[>I<item>B<]> B<=> I<file> ...
Collects filenames that will be used as source files for I<item>.
module or script given with B<PROGRAMS>, B<LIBS>, B<MODULES> and
B<SCRIPTS>.
+Static libraries may be sources. In that case, its object files are
+used directly when building I<item> instead of relying on library
+dependency and symbol resolution (through B<DEPEND> statements).
+
+B<SOURCE> statements may have attributes, which apply to each
+individual dependency in such a statement. For example:
+
+ SOURCE[prog]=prog_a.c
+ SOURCE[prog]{check}=prog_b.c prog_c.c
+
+With those statements, the association between C<prog> and C<prog_a.c>
+comes with no extra attributes, while the association between C<prog>
+and C<prog_b.c> as well as C<prog_c.c> comes with the extra attribute
+C<check>.
+
=item B<SHARED_SOURCE[>I<item>B<]> B<=> I<file> ...
Collects filenames that will be used as source files for I<item>.
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>] ...
+B<SHARED_SOURCE> statements may have attributes, just as B<SOURCE>
+statements.
+
+=item B<DEFINE[>I<items>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>.
+value if no I<value> is given) associated with I<items>.
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> ...
+=item B<INCLUDE[>I<items>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
+I<items> components (object files and whatever else). This is used at
the discretion of the build file generators.
=back
should be installed in the engines directory instead of the modules
directory.
+=item B<weak>
+
+This is used with B<DEPEND> where libraries are involved, to specify
+that the dependency between two libraries is weak and is only there to
+infer order.
+
+Without this attribute, a dependency between two libraries, expressed
+like this, means that if C<libfoo.a> appears in a linking command
+line, so will C<libmandatory.a>:
+
+ DEPEND[libfoo.a]=libmandatory.a
+
+With this attribute, a dependency between two libraries, expressed
+like this, means that if I<both> C<libfoo.a> and C<libmandatory.a>
+appear in a linking command line (because of recursive dependencies
+through other libraries), they will be ordered in such a way that this
+dependency is maintained:
+
+ DEPEND[libfoo.a]{weak}=libfoo.a libcookie.a
+
+This is useful in complex dependency trees where two libraries can be
+used as alternatives for each other. In this example, C<lib1.a> and
+C<lib2.a> have alternative implementations of the same thing, and
+C<libmandatory.a> has unresolved references to that same thing, and is
+therefore depending on either of them, but not both at the same time:
+
+ DEPEND[program1]=libmandatory.a lib1.a
+ DEPEND[program2]=libmandatory.a lib2.a
+ DEPEND[libmandatory]{weak}=lib1.a lib2.a
+
=back
=head1 GLOSSARY
=item "indexed statement"
-Any F<build.info> statement of the form B<I<KEYWORD>[>I<item>B<]=>I<values>,
+Any F<build.info> statement of the form B<I<KEYWORD>[>I<items>B<]=>I<values>,
with the exception of conditional statements.
=item "intermediate file"
For OpenSSL::Template documentation,
C<perldoc -o man util/perl/OpenSSL/Template.pm>
-L<Text::Temlate|https://metacpan.org/pod/Text::Template>
+L<Text::Template|https://metacpan.org/pod/Text::Template>
=head1 COPYRIGHT
-Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2019-2023 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
projects / thirdparty / openssl.git / blobdiff