3b09585bd6
Trim trailing whitespace. It doesn't match OpenSSL coding standards, AFAICT, and it can cause problems with git tooling. Trailing whitespace remains in test data and external source. Backport-of: https://github.com/openssl/openssl/pull/8092 Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/8134)
763 lines
35 KiB
Text
763 lines
35 KiB
Text
Intro
|
|
=====
|
|
|
|
This directory contains a few sets of files that are used for
|
|
configuration in diverse ways:
|
|
|
|
*.conf Target platform configurations, please read
|
|
'Configurations of OpenSSL target platforms' for more
|
|
information.
|
|
*.tmpl Build file templates, please read 'Build-file
|
|
programming with the "unified" build system' as well
|
|
as 'Build info files' for more information.
|
|
*.pm Helper scripts / modules for the main `Configure`
|
|
script. See 'Configure helper scripts for more
|
|
information.
|
|
|
|
|
|
Configurations of OpenSSL target platforms
|
|
==========================================
|
|
|
|
Configuration targets are a collection of facts that we know about
|
|
different platforms and their capabilities. We organise them in a
|
|
hash table, where each entry represent a specific target.
|
|
|
|
Note that configuration target names must be unique across all config
|
|
files. The Configure script does check that a config file doesn't
|
|
have config targets that shadow config targets from other files.
|
|
|
|
In each table entry, the following keys are significant:
|
|
|
|
inherit_from => Other targets to inherit values from.
|
|
Explained further below. [1]
|
|
template => Set to 1 if this isn't really a platform
|
|
target. Instead, this target is a template
|
|
upon which other targets can be built.
|
|
Explained further below. [1]
|
|
|
|
sys_id => System identity for systems where that
|
|
is difficult to determine automatically.
|
|
|
|
enable => Enable specific configuration features.
|
|
This MUST be an array of words.
|
|
disable => Disable specific configuration features.
|
|
This MUST be an array of words.
|
|
Note: if the same feature is both enabled
|
|
and disabled, disable wins.
|
|
|
|
as => The assembler command. This is not always
|
|
used (for example on Unix, where the C
|
|
compiler is used instead).
|
|
asflags => Default assembler command flags [4].
|
|
cpp => The C preprocessor command, normally not
|
|
given, as the build file defaults are
|
|
usually good enough.
|
|
cppflags => Default C preprocessor flags [4].
|
|
defines => As an alternative, macro definitions may be
|
|
given here instead of in `cppflags' [4].
|
|
If given here, they MUST be as an array of
|
|
the string such as "MACRO=value", or just
|
|
"MACRO" for definitions without value.
|
|
includes => As an alternative, inclusion directories
|
|
may be given here instead of in `cppflags'
|
|
[4]. If given here, the MUST be an array
|
|
of strings, one directory specification
|
|
each.
|
|
cc => The C compiler command, usually one of "cc",
|
|
"gcc" or "clang". This command is normally
|
|
also used to link object files and
|
|
libraries into the final program.
|
|
cxx => The C++ compiler command, usually one of
|
|
"c++", "g++" or "clang++". This command is
|
|
also used when linking a program where at
|
|
least one of the object file is made from
|
|
C++ source.
|
|
cflags => Defaults C compiler flags [4].
|
|
cxxflags => Default C++ compiler flags [4]. If unset,
|
|
it gets the same value as cflags.
|
|
|
|
(linking is a complex thing, see [3] below)
|
|
ld => Linker command, usually not defined
|
|
(meaning the compiler command is used
|
|
instead).
|
|
(NOTE: this is here for future use, it's
|
|
not implemented yet)
|
|
lflags => Default flags used when linking apps,
|
|
shared libraries or DSOs [4].
|
|
ex_libs => Extra libraries that are needed when
|
|
linking shared libraries, DSOs or programs.
|
|
The value is also assigned to Libs.private
|
|
in $(libdir)/pkgconfig/libcrypto.pc.
|
|
|
|
shared_cppflags => Extra C preprocessor flags used when
|
|
processing C files for shared libraries.
|
|
shared_cflag => Extra C compiler flags used when compiling
|
|
for shared libraries, typically something
|
|
like "-fPIC".
|
|
shared_ldflag => Extra linking flags used when linking
|
|
shared libraries.
|
|
module_cppflags
|
|
module_cflags
|
|
module_ldflags => Has the same function as the corresponding
|
|
`shared_' attributes, but for building DSOs.
|
|
When unset, they get the same values as the
|
|
corresponding `shared_' attributes.
|
|
|
|
ar => The library archive command, the default is
|
|
"ar".
|
|
(NOTE: this is here for future use, it's
|
|
not implemented yet)
|
|
arflags => Flags to be used with the library archive
|
|
command. On Unix, this includes the
|
|
command letter, 'r' by default.
|
|
|
|
ranlib => The library archive indexing command, the
|
|
default is 'ranlib' it it exists.
|
|
|
|
unistd => An alternative header to the typical
|
|
'<unistd.h>'. This is very rarely needed.
|
|
|
|
shared_extension => File name extension used for shared
|
|
libraries.
|
|
obj_extension => File name extension used for object files.
|
|
On unix, this defaults to ".o" (NOTE: this
|
|
is here for future use, it's not
|
|
implemented yet)
|
|
exe_extension => File name extension used for executable
|
|
files. On unix, this defaults to "" (NOTE:
|
|
this is here for future use, it's not
|
|
implemented yet)
|
|
shlib_variant => A "variant" identifier inserted between the base
|
|
shared library name and the extension. On "unixy"
|
|
platforms (BSD, Linux, Solaris, MacOS/X, ...) this
|
|
supports installation of custom OpenSSL libraries
|
|
that don't conflict with other builds of OpenSSL
|
|
installed on the system. The variant identifier
|
|
becomes part of the SONAME of the library and also
|
|
any symbol versions (symbol versions are not used or
|
|
needed with MacOS/X). For example, on a system
|
|
where a default build would normally create the SSL
|
|
shared library as 'libssl.so -> libssl.so.1.1' with
|
|
the value of the symlink as the SONAME, a target
|
|
definition that sets 'shlib_variant => "-abc"' will
|
|
create 'libssl.so -> libssl-abc.so.1.1', again with
|
|
an SONAME equal to the value of the symlink. The
|
|
symbol versions associated with the variant library
|
|
would then be 'OPENSSL_ABC_<version>' rather than
|
|
the default 'OPENSSL_<version>'. The string inserted
|
|
into symbol versions is obtained by mapping all
|
|
letters in the "variant" identifier to upper case
|
|
and all non-alphanumeric characters to '_'.
|
|
|
|
thread_scheme => The type of threads is used on the
|
|
configured platform. Currently known
|
|
values are "(unknown)", "pthreads",
|
|
"uithreads" (a.k.a solaris threads) and
|
|
"winthreads". Except for "(unknown)", the
|
|
actual value is currently ignored but may
|
|
be used in the future. See further notes
|
|
below [2].
|
|
dso_scheme => The type of dynamic shared objects to build
|
|
for. This mostly comes into play with
|
|
engines, but can be used for other purposes
|
|
as well. Valid values are "DLFCN"
|
|
(dlopen() et al), "DLFCN_NO_H" (for systems
|
|
that use dlopen() et al but do not have
|
|
fcntl.h), "DL" (shl_load() et al), "WIN32"
|
|
and "VMS".
|
|
perlasm_scheme => The perlasm method used to create the
|
|
assembler files used when compiling with
|
|
assembler implementations.
|
|
shared_target => The shared library building method used.
|
|
This is a target found in Makefile.shared.
|
|
build_scheme => The scheme used to build up a Makefile.
|
|
In its simplest form, the value is a string
|
|
with the name of the build scheme.
|
|
The value may also take the form of a list
|
|
of strings, if the build_scheme is to have
|
|
some options. In this case, the first
|
|
string in the list is the name of the build
|
|
scheme.
|
|
Currently recognised build scheme is "unified".
|
|
For the "unified" build scheme, this item
|
|
*must* be an array with the first being the
|
|
word "unified" and the second being a word
|
|
to identify the platform family.
|
|
|
|
multilib => On systems that support having multiple
|
|
implementations of a library (typically a
|
|
32-bit and a 64-bit variant), this is used
|
|
to have the different variants in different
|
|
directories.
|
|
|
|
bn_ops => Building options (was just bignum options in
|
|
the earlier history of this option, hence the
|
|
name). This is a string of words that describe
|
|
algorithms' implementation parameters that
|
|
are optimal for the designated target platform,
|
|
such as the type of integers used to build up
|
|
the bignum, different ways to implement certain
|
|
ciphers and so on. To fully comprehend the
|
|
meaning, the best is to read the affected
|
|
source.
|
|
The valid words are:
|
|
|
|
THIRTY_TWO_BIT bignum limbs are 32 bits,
|
|
this is default if no
|
|
option is specified, it
|
|
works on any supported
|
|
system [unless "wider"
|
|
limb size is implied in
|
|
assembly code];
|
|
BN_LLONG bignum limbs are 32 bits,
|
|
but 64-bit 'unsigned long
|
|
long' is used internally
|
|
in calculations;
|
|
SIXTY_FOUR_BIT_LONG bignum limbs are 64 bits
|
|
and sizeof(long) is 8;
|
|
SIXTY_FOUR_BIT bignums limbs are 64 bits,
|
|
but execution environment
|
|
is ILP32;
|
|
RC4_CHAR RC4 key schedule is made
|
|
up of 'unsigned char's;
|
|
RC4_INT RC4 key schedule is made
|
|
up of 'unsigned int's;
|
|
EXPORT_VAR_AS_FN for shared libraries,
|
|
export vars as
|
|
accessor functions.
|
|
|
|
apps_aux_src => Extra source to build apps/openssl and other
|
|
apps, as needed by the target and that can be
|
|
collected in a library.
|
|
apps_init_src => Init source to build apps/openssl and other
|
|
apps, as needed by the target. This code
|
|
cannot be placed in a library, as the rest
|
|
of the code isn't expected to link to it
|
|
explicitly.
|
|
cpuid_asm_src => assembler implementation of cpuid code as
|
|
well as OPENSSL_cleanse().
|
|
Default to mem_clr.c
|
|
bn_asm_src => Assembler implementation of core bignum
|
|
functions.
|
|
Defaults to bn_asm.c
|
|
ec_asm_src => Assembler implementation of core EC
|
|
functions.
|
|
des_asm_src => Assembler implementation of core DES
|
|
encryption functions.
|
|
Defaults to 'des_enc.c fcrypt_b.c'
|
|
aes_asm_src => Assembler implementation of core AES
|
|
functions.
|
|
Defaults to 'aes_core.c aes_cbc.c'
|
|
bf_asm_src => Assembler implementation of core BlowFish
|
|
functions.
|
|
Defaults to 'bf_enc.c'
|
|
md5_asm_src => Assembler implementation of core MD5
|
|
functions.
|
|
sha1_asm_src => Assembler implementation of core SHA1,
|
|
functions, and also possibly SHA256 and
|
|
SHA512 ones.
|
|
cast_asm_src => Assembler implementation of core CAST
|
|
functions.
|
|
Defaults to 'c_enc.c'
|
|
rc4_asm_src => Assembler implementation of core RC4
|
|
functions.
|
|
Defaults to 'rc4_enc.c rc4_skey.c'
|
|
rmd160_asm_src => Assembler implementation of core RMD160
|
|
functions.
|
|
rc5_asm_src => Assembler implementation of core RC5
|
|
functions.
|
|
Defaults to 'rc5_enc.c'
|
|
wp_asm_src => Assembler implementation of core WHIRLPOOL
|
|
functions.
|
|
cmll_asm_src => Assembler implementation of core CAMELLIA
|
|
functions.
|
|
Defaults to 'camellia.c cmll_misc.c cmll_cbc.c'
|
|
modes_asm_src => Assembler implementation of cipher modes,
|
|
currently the functions gcm_gmult_4bit and
|
|
gcm_ghash_4bit.
|
|
padlock_asm_src => Assembler implementation of core parts of
|
|
the padlock engine. This is mandatory on
|
|
any platform where the padlock engine might
|
|
actually be built.
|
|
|
|
|
|
[1] as part of the target configuration, one can have a key called
|
|
'inherit_from' that indicate what other configurations to inherit
|
|
data from. These are resolved recursively.
|
|
|
|
Inheritance works as a set of default values that can be overridden
|
|
by corresponding key values in the inheriting configuration.
|
|
|
|
Note 1: any configuration table can be used as a template.
|
|
Note 2: pure templates have the attribute 'template => 1' and
|
|
cannot be used as build targets.
|
|
|
|
If several configurations are given in the 'inherit_from' array,
|
|
the values of same attribute are concatenated with space
|
|
separation. With this, it's possible to have several smaller
|
|
templates for different configuration aspects that can be combined
|
|
into a complete configuration.
|
|
|
|
instead of a scalar value or an array, a value can be a code block
|
|
of the form 'sub { /* your code here */ }'. This code block will
|
|
be called with the list of inherited values for that key as
|
|
arguments. In fact, the concatenation of strings is really done
|
|
by using 'sub { join(" ",@_) }' on the list of inherited values.
|
|
|
|
An example:
|
|
|
|
"foo" => {
|
|
template => 1,
|
|
haha => "ha ha",
|
|
hoho => "ho",
|
|
ignored => "This should not appear in the end result",
|
|
},
|
|
"bar" => {
|
|
template => 1,
|
|
haha => "ah",
|
|
hoho => "haho",
|
|
hehe => "hehe"
|
|
},
|
|
"laughter" => {
|
|
inherit_from => [ "foo", "bar" ],
|
|
hehe => sub { join(" ",(@_,"!!!")) },
|
|
ignored => "",
|
|
}
|
|
|
|
The entry for "laughter" will become as follows after processing:
|
|
|
|
"laughter" => {
|
|
haha => "ha ha ah",
|
|
hoho => "ho haho",
|
|
hehe => "hehe !!!",
|
|
ignored => ""
|
|
}
|
|
|
|
[2] OpenSSL is built with threading capabilities unless the user
|
|
specifies 'no-threads'. The value of the key 'thread_scheme' may
|
|
be "(unknown)", in which case the user MUST give some compilation
|
|
flags to Configure.
|
|
|
|
[3] OpenSSL has three types of things to link from object files or
|
|
static libraries:
|
|
|
|
- shared libraries; that would be libcrypto and libssl.
|
|
- shared objects (sometimes called dynamic libraries); that would
|
|
be the engines.
|
|
- applications; those are apps/openssl and all the test apps.
|
|
|
|
Very roughly speaking, linking is done like this (words in braces
|
|
represent the configuration settings documented at the beginning
|
|
of this file):
|
|
|
|
shared libraries:
|
|
{ld} $(CFLAGS) {lflags} {shared_ldflag} -o libfoo.so \
|
|
foo/something.o foo/somethingelse.o {ex_libs}
|
|
|
|
shared objects:
|
|
{ld} $(CFLAGS) {lflags} {module_ldflags} -o libeng.so \
|
|
blah1.o blah2.o -lcrypto {ex_libs}
|
|
|
|
applications:
|
|
{ld} $(CFLAGS) {lflags} -o app \
|
|
app1.o utils.o -lssl -lcrypto {ex_libs}
|
|
|
|
[4] There are variants of these attribute, prefixed with `lib_',
|
|
`dso_' or `bin_'. Those variants replace the unprefixed attribute
|
|
when building library, DSO or program modules specifically.
|
|
|
|
Historically, the target configurations came in form of a string with
|
|
values separated by colons. This use is deprecated. The string form
|
|
looked like this:
|
|
|
|
"target" => "{cc}:{cflags}:{unistd}:{thread_cflag}:{sys_id}:{lflags}:{bn_ops}:{cpuid_obj}:{bn_obj}:{ec_obj}:{des_obj}:{aes_obj}:{bf_obj}:{md5_obj}:{sha1_obj}:{cast_obj}:{rc4_obj}:{rmd160_obj}:{rc5_obj}:{wp_obj}:{cmll_obj}:{modes_obj}:{padlock_obj}:{perlasm_scheme}:{dso_scheme}:{shared_target}:{shared_cflag}:{shared_ldflag}:{shared_extension}:{ranlib}:{arflags}:{multilib}"
|
|
|
|
|
|
Build info files
|
|
================
|
|
|
|
The build.info files that are spread over the source tree contain the
|
|
minimum information needed to build and distribute OpenSSL. It uses a
|
|
simple and yet fairly powerful language to determine what needs to be
|
|
built, from what sources, and other relationships between files.
|
|
|
|
For every build.info file, all file references are relative to the
|
|
directory of the build.info file for source files, and the
|
|
corresponding build directory for built files if the build tree
|
|
differs from the source tree.
|
|
|
|
When processed, every line is processed with the perl module
|
|
Text::Template, using the delimiters "{-" and "-}". The hashes
|
|
%config and %target are passed to the perl fragments, along with
|
|
$sourcedir and $builddir, which are the locations of the source
|
|
directory for the current build.info file and the corresponding build
|
|
directory, all relative to the top of the build tree.
|
|
|
|
To begin with, things to be built are declared by setting specific
|
|
variables:
|
|
|
|
PROGRAMS=foo bar
|
|
LIBS=libsomething
|
|
ENGINES=libeng
|
|
SCRIPTS=myhack
|
|
EXTRA=file1 file2
|
|
|
|
Note that the files mentioned for PROGRAMS, LIBS and ENGINES *must* be
|
|
without extensions. The build file templates will figure them out.
|
|
|
|
For each thing to be built, it is then possible to say what sources
|
|
they are built from:
|
|
|
|
PROGRAMS=foo bar
|
|
SOURCE[foo]=foo.c common.c
|
|
SOURCE[bar]=bar.c extra.c common.c
|
|
|
|
It's also possible to tell some other dependencies:
|
|
|
|
DEPEND[foo]=libsomething
|
|
DEPEND[libbar]=libsomethingelse
|
|
|
|
(it could be argued that 'libsomething' and 'libsomethingelse' are
|
|
source as well. However, the files given through SOURCE are expected
|
|
to be located in the source tree while files given through DEPEND are
|
|
expected to be located in the build tree)
|
|
|
|
It's also possible to depend on static libraries explicitly:
|
|
|
|
DEPEND[foo]=libsomething.a
|
|
DEPEND[libbar]=libsomethingelse.a
|
|
|
|
This should be rarely used, and care should be taken to make sure it's
|
|
only used when supported. For example, native Windows build doesn't
|
|
support building static libraries and DLLs at the same time, so using
|
|
static libraries on Windows can only be done when configured
|
|
'no-shared'.
|
|
|
|
One some platforms, shared libraries come with a name that's different
|
|
from their static counterpart. That's declared as follows:
|
|
|
|
SHARED_NAME[libfoo]=cygfoo-{- $config{shlibver} -}
|
|
|
|
The example is from Cygwin, which has a required naming convention.
|
|
|
|
Sometimes, it makes sense to rename an output file, for example a
|
|
library:
|
|
|
|
RENAME[libfoo]=libbar
|
|
|
|
That line has "libfoo" renamed to "libbar". While it makes no
|
|
sense at all to just have a rename like that (why not just use
|
|
"libbar" everywhere?), it does make sense when it can be used
|
|
conditionally. See a little further below for an example.
|
|
|
|
In some cases, it's desirable to include some source files in the
|
|
shared form of a library only:
|
|
|
|
SHARED_SOURCE[libfoo]=dllmain.c
|
|
|
|
For any file to be built, it's also possible to tell what extra
|
|
include paths the build of their source files should use:
|
|
|
|
INCLUDE[foo]=include
|
|
|
|
In some cases, one might want to generate some source files from
|
|
others, that's done as follows:
|
|
|
|
GENERATE[foo.s]=asm/something.pl $(CFLAGS)
|
|
GENERATE[bar.s]=asm/bar.S
|
|
|
|
The value of each GENERATE line is a command line or part of it.
|
|
Configure places no rules on the command line, except that the first
|
|
item must be the generator file. It is, however, entirely up to the
|
|
build file template to define exactly how those command lines should
|
|
be handled, how the output is captured and so on.
|
|
|
|
Sometimes, the generator file itself depends on other files, for
|
|
example if it is a perl script that depends on other perl modules.
|
|
This can be expressed using DEPEND like this:
|
|
|
|
DEPEND[asm/something.pl]=../perlasm/Foo.pm
|
|
|
|
There may also be cases where the exact file isn't easily specified,
|
|
but an inclusion directory still needs to be specified. INCLUDE can
|
|
be used in that case:
|
|
|
|
INCLUDE[asm/something.pl]=../perlasm
|
|
|
|
NOTE: GENERATE lines are limited to one command only per GENERATE.
|
|
|
|
As a last resort, it's possible to have raw build file lines, between
|
|
BEGINRAW and ENDRAW lines as follows:
|
|
|
|
BEGINRAW[Makefile(unix)]
|
|
haha.h: {- $builddir -}/Makefile
|
|
echo "/* haha */" > haha.h
|
|
ENDRAW[Makefile(unix)]
|
|
|
|
The word within square brackets is the build_file configuration item
|
|
or the build_file configuration item followed by the second word in the
|
|
build_scheme configuration item for the configured target within
|
|
parenthesis as shown above. For example, with the following relevant
|
|
configuration items:
|
|
|
|
build_file => "build.ninja"
|
|
build_scheme => [ "unified", "unix" ]
|
|
|
|
... these lines will be considered:
|
|
|
|
BEGINRAW[build.ninja]
|
|
build haha.h: echo "/* haha */" > haha.h
|
|
ENDRAW[build.ninja]
|
|
|
|
BEGINRAW[build.ninja(unix)]
|
|
build hoho.h: echo "/* hoho */" > hoho.h
|
|
ENDRAW[build.ninja(unix)]
|
|
|
|
Should it be needed because the recipes within a RAW section might
|
|
clash with those generated by Configure, it's possible to tell it
|
|
not to generate them with the use of OVERRIDES, for example:
|
|
|
|
SOURCE[libfoo]=foo.c bar.c
|
|
|
|
OVERRIDES=bar.o
|
|
BEGINRAW[Makefile(unix)]
|
|
bar.o: bar.c
|
|
$(CC) $(CFLAGS) -DSPECIAL -c -o $@ $<
|
|
ENDRAW[Makefile(unix)]
|
|
|
|
See the documentation further up for more information on configuration
|
|
items.
|
|
|
|
Finally, you can have some simple conditional use of the build.info
|
|
information, looking like this:
|
|
|
|
IF[1]
|
|
something
|
|
ELSIF[2]
|
|
something other
|
|
ELSE
|
|
something else
|
|
ENDIF
|
|
|
|
The expression in square brackets is interpreted as a string in perl,
|
|
and will be seen as true if perl thinks it is, otherwise false. For
|
|
example, the above would have "something" used, since 1 is true.
|
|
|
|
Together with the use of Text::Template, this can be used as
|
|
conditions based on something in the passed variables, for example:
|
|
|
|
IF[{- $disabled{shared} -}]
|
|
LIBS=libcrypto
|
|
SOURCE[libcrypto]=...
|
|
ELSE
|
|
LIBS=libfoo
|
|
SOURCE[libfoo]=...
|
|
ENDIF
|
|
|
|
or:
|
|
|
|
# VMS has a cultural standard where all libraries are prefixed.
|
|
# For OpenSSL, the choice is 'ossl_'
|
|
IF[{- $config{target} =~ /^vms/ -}]
|
|
RENAME[libcrypto]=ossl_libcrypto
|
|
RENAME[libssl]=ossl_libssl
|
|
ENDIF
|
|
|
|
|
|
Build-file programming with the "unified" build system
|
|
======================================================
|
|
|
|
"Build files" are called "Makefile" on Unix-like operating systems,
|
|
"descrip.mms" for MMS on VMS, "makefile" for nmake on Windows, etc.
|
|
|
|
To use the "unified" build system, the target configuration needs to
|
|
set the three items 'build_scheme', 'build_file' and 'build_command'.
|
|
In the rest of this section, we will assume that 'build_scheme' is set
|
|
to "unified" (see the configurations documentation above for the
|
|
details).
|
|
|
|
For any name given by 'build_file', the "unified" system expects a
|
|
template file in Configurations/ named like the build file, with
|
|
".tmpl" appended, or in case of possible ambiguity, a combination of
|
|
the second 'build_scheme' list item and the 'build_file' name. For
|
|
example, if 'build_file' is set to "Makefile", the template could be
|
|
Configurations/Makefile.tmpl or Configurations/unix-Makefile.tmpl.
|
|
In case both Configurations/unix-Makefile.tmpl and
|
|
Configurations/Makefile.tmpl are present, the former takes
|
|
precedence.
|
|
|
|
The build-file template is processed with the perl module
|
|
Text::Template, using "{-" and "-}" as delimiters that enclose the
|
|
perl code fragments that generate configuration-dependent content.
|
|
Those perl fragments have access to all the hash variables from
|
|
configdata.pem.
|
|
|
|
The build-file template is expected to define at least the following
|
|
perl functions in a perl code fragment enclosed with "{-" and "-}".
|
|
They are all expected to return a string with the lines they produce.
|
|
|
|
generatesrc - function that produces build file lines to generate
|
|
a source file from some input.
|
|
|
|
It's called like this:
|
|
|
|
generatesrc(src => "PATH/TO/tobegenerated",
|
|
generator => [ "generatingfile", ... ]
|
|
generator_incs => [ "INCL/PATH", ... ]
|
|
generator_deps => [ "dep1", ... ]
|
|
generator => [ "generatingfile", ... ]
|
|
incs => [ "INCL/PATH", ... ],
|
|
deps => [ "dep1", ... ],
|
|
intent => one of "libs", "dso", "bin" );
|
|
|
|
'src' has the name of the file to be generated.
|
|
'generator' is the command or part of command to
|
|
generate the file, of which the first item is
|
|
expected to be the file to generate from.
|
|
generatesrc() is expected to analyse and figure out
|
|
exactly how to apply that file and how to capture
|
|
the result. 'generator_incs' and 'generator_deps'
|
|
are include directories and files that the generator
|
|
file itself depends on. 'incs' and 'deps' are
|
|
include directories and files that are used if $(CC)
|
|
is used as an intermediary step when generating the
|
|
end product (the file indicated by 'src'). 'intent'
|
|
indicates what the generated file is going to be
|
|
used for.
|
|
|
|
src2obj - function that produces build file lines to build an
|
|
object file from source files and associated data.
|
|
|
|
It's called like this:
|
|
|
|
src2obj(obj => "PATH/TO/objectfile",
|
|
srcs => [ "PATH/TO/sourcefile", ... ],
|
|
deps => [ "dep1", ... ],
|
|
incs => [ "INCL/PATH", ... ]
|
|
intent => one of "lib", "dso", "bin" );
|
|
|
|
'obj' has the intended object file *without*
|
|
extension, src2obj() is expected to add that.
|
|
'srcs' has the list of source files to build the
|
|
object file, with the first item being the source
|
|
file that directly corresponds to the object file.
|
|
'deps' is a list of explicit dependencies. 'incs'
|
|
is a list of include file directories. Finally,
|
|
'intent' indicates what this object file is going
|
|
to be used for.
|
|
|
|
obj2lib - function that produces build file lines to build a
|
|
static library file ("libfoo.a" in Unix terms) from
|
|
object files.
|
|
|
|
called like this:
|
|
|
|
obj2lib(lib => "PATH/TO/libfile",
|
|
objs => [ "PATH/TO/objectfile", ... ]);
|
|
|
|
'lib' has the intended library file name *without*
|
|
extension, obj2lib is expected to add that. 'objs'
|
|
has the list of object files (also *without*
|
|
extension) to build this library.
|
|
|
|
libobj2shlib - function that produces build file lines to build a
|
|
shareable object library file ("libfoo.so" in Unix
|
|
terms) from the corresponding static library file
|
|
or object files.
|
|
|
|
called like this:
|
|
|
|
libobj2shlib(shlib => "PATH/TO/shlibfile",
|
|
lib => "PATH/TO/libfile",
|
|
objs => [ "PATH/TO/objectfile", ... ],
|
|
deps => [ "PATH/TO/otherlibfile", ... ]);
|
|
|
|
'lib' has the intended library file name *without*
|
|
extension, libobj2shlib is expected to add that.
|
|
'shlib' has the corresponding shared library name
|
|
*without* extension. 'deps' has the list of other
|
|
libraries (also *without* extension) this library
|
|
needs to be linked with. 'objs' has the list of
|
|
object files (also *without* extension) to build
|
|
this library.
|
|
|
|
This function has a choice; it can use the
|
|
corresponding static library as input to make the
|
|
shared library, or the list of object files.
|
|
|
|
obj2dso - function that produces build file lines to build a
|
|
dynamic shared object file from object files.
|
|
|
|
called like this:
|
|
|
|
obj2dso(lib => "PATH/TO/libfile",
|
|
objs => [ "PATH/TO/objectfile", ... ],
|
|
deps => [ "PATH/TO/otherlibfile",
|
|
... ]);
|
|
|
|
This is almost the same as libobj2shlib, but the
|
|
intent is to build a shareable library that can be
|
|
loaded in runtime (a "plugin"...). The differences
|
|
are subtle, one of the most visible ones is that the
|
|
resulting shareable library is produced from object
|
|
files only.
|
|
|
|
obj2bin - function that produces build file lines to build an
|
|
executable file from object files.
|
|
|
|
called like this:
|
|
|
|
obj2bin(bin => "PATH/TO/binfile",
|
|
objs => [ "PATH/TO/objectfile", ... ],
|
|
deps => [ "PATH/TO/libfile", ... ]);
|
|
|
|
'bin' has the intended executable file name
|
|
*without* extension, obj2bin is expected to add
|
|
that. 'objs' has the list of object files (also
|
|
*without* extension) to build this library. 'deps'
|
|
has the list of library files (also *without*
|
|
extension) that the programs needs to be linked
|
|
with.
|
|
|
|
in2script - function that produces build file lines to build a
|
|
script file from some input.
|
|
|
|
called like this:
|
|
|
|
in2script(script => "PATH/TO/scriptfile",
|
|
sources => [ "PATH/TO/infile", ... ]);
|
|
|
|
'script' has the intended script file name.
|
|
'sources' has the list of source files to build the
|
|
resulting script from.
|
|
|
|
In all cases, file file paths are relative to the build tree top, and
|
|
the build file actions run with the build tree top as current working
|
|
directory.
|
|
|
|
Make sure to end the section with these functions with a string that
|
|
you thing is appropriate for the resulting build file. If nothing
|
|
else, end it like this:
|
|
|
|
""; # Make sure no lingering values end up in the Makefile
|
|
-}
|
|
|
|
|
|
Configure helper scripts
|
|
========================
|
|
|
|
Configure uses helper scripts in this directory:
|
|
|
|
Checker scripts
|
|
---------------
|
|
|
|
These scripts are per platform family, to check the integrity of the
|
|
tools used for configuration and building. The checker script used is
|
|
either {build_platform}-{build_file}-checker.pm or
|
|
{build_platform}-checker.pm, where {build_platform} is the second
|
|
'build_scheme' list element from the configuration target data, and
|
|
{build_file} is 'build_file' from the same target data.
|
|
|
|
If the check succeeds, the script is expected to end with a non-zero
|
|
expression. If the check fails, the script can end with a zero, or
|
|
with a `die`.
|