mirror of https://github.com/openssl/openssl
408 lines
18 KiB
Plaintext
408 lines
18 KiB
Plaintext
Configurations of OpenSSL target platforms
|
|
------------------------------------------
|
|
|
|
Target configurations 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.
|
|
|
|
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.
|
|
|
|
cc => The 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.
|
|
cflags => Flags that are used at all times when
|
|
compiling.
|
|
debug_cflags => Extra compilation flags used when making a
|
|
debug build (when Configure receives the
|
|
--debug option). Typically something like
|
|
"-g -O0".
|
|
release_cflags => Extra compilation flags used when making a
|
|
release build (when Configure receives the
|
|
--release option, or doesn't receive the
|
|
--debug option). Typically something like
|
|
"-O" or "-O3".
|
|
thread_cflags => Extra compilation flags used when
|
|
compiling with threading enabled.
|
|
Explained further below. [2]
|
|
shared_cflag => Extra compilation flags used when
|
|
compiling for shared libraries, typically
|
|
something like "-fPIC".
|
|
|
|
ld => the 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 => the flags that are used at all times when
|
|
linking. These can have a % sign in them
|
|
showing where the OpenSSL libraries should
|
|
appear, otherwise these flags will come
|
|
last. So in a typical links situation,
|
|
this is a quick table of results:
|
|
|
|
"-foo%-bar" > -foo -lssl -lcrypto -bar
|
|
"-foo%" > -foo -lssl -lcrypto
|
|
"-foo" > -lssl -lcrypto -foo
|
|
|
|
debug_lflags => Like debug_cflags, but used when linking.
|
|
release_lflags => Like release_cflags, but used when linking.
|
|
shared_lflags => Like shared_cflags, but used when linking.
|
|
|
|
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.
|
|
|
|
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)
|
|
|
|
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 created 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 schemes are
|
|
"mk1mf" and "unixmake" and "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 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
|
|
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.
|
|
EXPORT_VAR_AS_FN for shared libraries,
|
|
export vars as
|
|
accessor functions.
|
|
|
|
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 overriden
|
|
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_cflags' may
|
|
be "(unknown)", in which case the user MUST give some compilation
|
|
flags to Configure.
|
|
|
|
|
|
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)
|
|
|
|
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:
|
|
|
|
ORDINALS[libcrypto]=crypto
|
|
|
|
The value is not the name of the file in question, but rather the
|
|
argument to util/mkdef.pl that indicates which file to use.
|
|
|
|
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 lines has "libfoo" get 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.
|
|
|
|
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
|
|
|
|
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 withing 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)]
|
|
|
|
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[{- $config{no_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
|