| 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 |
