| 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 |
| modules, 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". |
| asm_arch => The architecture to be used for compiling assembly |
| source. This acts as a selector in build.info files. |
| uplink_arch => The architecture to be used for compiling uplink |
| source. This acts as a selector in build.info files. |
| This is separate from asm_arch because it's compiled |
| even when 'no-asm' is given, even though it contains |
| assembler source. |
| 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 serves multiple purposes: |
| - as index for targets found in shared_info.pl. |
| - as linker script generation selector. |
| To serve both purposes, the index for shared_info.pl |
| should end with '-shared', and this suffix will be |
| removed for use as a linker script generation |
| selector. Note that the latter is only used if |
| 'shared_defflag' is defined. |
| 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; |
| |
| [1] as part of the target configuration, one can have a key called |
| `inherit_from` that indicates 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 modules. |
| - 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. |
| |
| `Configure` only knows inherently about the top `build.info` file. For |
| any other directory that has one, further directories to look into |
| must be indicated like this: |
| |
| SUBDIRS=something someelse |
| |
| On to things to be built; they are declared by setting specific |
| variables: |
| |
| PROGRAMS=foo bar |
| LIBS=libsomething |
| MODULES=libeng |
| SCRIPTS=myhack |
| |
| Note that the files mentioned for PROGRAMS, LIBS and MODULES *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`. |
| |
| 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 |
| |
| It's also possible to specify C macros that should be defined: |
| |
| DEFINE[foo]=FOO BAR=1 |
| |
| 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. |
| |
| 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 |
| |
| 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 with '.o' |
| extension, src2obj() is expected to change it to |
| something more suitable for the platform. |
| '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 to build this library. |
| |
| libobj2shlib - backward compatibility function that's used the |
| same way as obj2shlib (described next), and was |
| expected to build the shared library from the |
| corresponding static library when that was suitable. |
| NOTE: building a shared library from a static |
| library is now DEPRECATED, as they no longer share |
| object files. Attempting to do this will fail. |
| |
| obj2shlib - function that produces build file lines to build a |
| shareable object library file ("libfoo.so" in Unix |
| terms) from the corresponding object files. |
| |
| called like this: |
| |
| obj2shlib(shlib => "PATH/TO/shlibfile", |
| lib => "PATH/TO/libfile", |
| objs => [ "PATH/TO/objectfile", ... ], |
| deps => [ "PATH/TO/otherlibfile", ... ]); |
| |
| 'lib' has the base (static) library ffile name |
| *without* extension. This is useful in case |
| supporting files are needed (such as import |
| libraries on Windows). |
| '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 to build this library. |
| |
| 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 obj2shlib, but the |
| intent is to build a shareable library that can be |
| loaded in runtime (a "plugin"...). |
| |
| 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 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`. |
