+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
==========================================
sys_id => System identity for systems where that
is difficult to determine automatically.
- cc => The compiler command, usually one of "cc",
+ 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.
+
+ 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 => Flags that are used at all times when
- compiling.
+ compiling C object files.
+ cxxflags => Flags that are used at all times when
+ compiling C++ object files. If unset, it
+ gets the same value as cflags.
defines => As an alternative, macro definitions may be
present here instead of in `cflags'. If
given here, they MUST be as an array of the
some options. In this case, the first
string in the list is the name of the build
scheme.
- Currently recognised build schemes are
- "unixmake" and "unified".
+ 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 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 a string of words
- that describe properties on the designated
- target platform, such as the type of
- integers used to build up the bitnum,
- different ways to implement certain ciphers
- and so on. To fully comprehend the
+ 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:
- BN_LLONG use 'unsigned long long' in
- some bignum calculations.
- This has no value when
- SIXTY_FOUR_BIT or
- SIXTY_FOUR_BIT_LONG is given.
- RC4_CHAR makes the basic RC4 unit of
- calculation an unsigned char.
- SIXTY_FOUR_BIT processor registers
- are 64 bits, long is
- 32 bits, long long is
- 64 bits.
- SIXTY_FOUR_BIT_LONG processor registers
- are 64 bits, long is
- 64 bits.
- THIRTY_TWO_BIT processor registers
- are 32 bits.
+ 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.
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 explicitely:
+
+ 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 build static libraries and DLLs at the same time, so using
+static libraries on Windows can only be done when configured
+'no-shared'.
+
For some libraries, we maintain files with public symbols and their
slot in a transfer vector (important on some platforms). It can be
declared like this:
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
echo "/* haha */" > haha.h
ENDRAW[Makefile(unix)]
-The word withing square brackets is the build_file configuration item
+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
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" );
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. 'deps' is a list of explicit
- dependencies. 'intent' indicates what the generated
- file is going to be used for.
+ 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.
""; # 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`.
projects / openssl.git / blobdiff