Configurations/README

   1 Configurations of OpenSSL target platforms
   2 ------------------------------------------
   3
   4 Target configurations are a collection of facts that we know about
   5 different platforms and their capabilities.  We organise them in a
   6 hash table, where each entry represent a specific target.
   7
   8 In each table entry, the following keys are significant:
   9
  10         inherit_from    => Other targets to inherit values from.
  11                            Explained further below. [1]
  12         template        => Set to 1 if this isn't really a platform
  13                            target.  Instead, this target is a template
  14                            upon which other targets can be built.
  15                            Explained further below.  [1]
  16
  17         sys_id          => System identity for systems where that
  18                            is difficult to determine automatically.
  19
  20         cc              => The compiler command, usually one of "cc",
  21                            "gcc" or "clang".  This command is normally
  22                            also used to link object files and
  23                            libraries into the final program.
  24         cflags          => Flags that are used at all times when
  25                            compiling.
  26         debug_cflags    => Extra compilation flags used when making a
  27                            debug build (when Configure receives the
  28                            --debug option).  Typically something like
  29                            "-g -O0".
  30         release_cflags  => Extra compilation flags used when making a
  31                            release build (when Configure receives the
  32                            --release option, or doesn't receive the
  33                            --debug option).  Typically something like
  34                            "-O" or "-O3".
  35         thread_cflags   => Extra compilation flags used when
  36                            compiling with threading enabled.
  37                            Explained further below.  [2]
  38         shared_cflag    => Extra compilation flags used when
  39                            compiling for shared libraries, typically
  40                            something like "-fPIC".
  41
  42         ld              => the linker command, usually not defined
  43                            (meaning the compiler command is used
  44                            instead).
  45                            (NOTE: this is here for future use, it's
  46                            not implemented yet)
  47         lflags          => the flags that are used at all times when
  48                            linking.  These can have a % sign in them
  49                            showing where the OpenSSL libraries should
  50                            appear, otherwise these flags will come
  51                            last.  So in a typical links situation,
  52                            this is a quick table of results:
  53
  54                            "-foo%-bar"  > -foo -lssl -lcrypto -bar
  55                            "-foo%"      > -foo -lssl -lcrypto
  56                            "-foo"       > -lssl -lcrypto -foo
  57
  58         debug_lflags    => Like debug_cflags, but used when linking.
  59         release_lflags  => Like release_cflags, but used when linking.
  60         shared_lflags   => Like shared_cflags, but used when linking.
  61
  62         ar              => The library archive command, the default is
  63                            "ar".
  64                            (NOTE: this is here for future use, it's
  65                            not implemented yet)
  66         arflags         => Flags to be used with the library archive
  67                            command.
  68
  69         ranlib          => The library archive indexing command, the
  70                            default is 'ranlib' it it exists.
  71
  72         unistd          => An alternative header to the typical
  73                            '<unistd.h>'.  This is very rarely needed.
  74
  75         shared_extension => File name extension used for shared
  76                             libraries.
  77         obj_extension   => File name extension used for object files.
  78                            On unix, this defaults to ".o" (NOTE: this
  79                            is here for future use, it's not
  80                            implemented yet)
  81         exe_extension   => File name extension used for executable
  82                            files.  On unix, this defaults to "" (NOTE:
  83                            this is here for future use, it's not
  84                            implemented yet)
  85
  86         dso_scheme      => The type of dynamic shared objects to build
  87                            for.  This mostly comes into play with
  88                            engines, but can be used for other purposes
  89                            as well.  Valid values are "DLFCN"
  90                            (dlopen() et al), "DLFCN_NO_H" (for systems
  91                            that use dlopen() et al but do not have
  92                            fcntl.h), "DL" (shl_load() et al), "WIN32"
  93                            and "VMS".
  94         perlasm_scheme  => The perlasm method used to created the
  95                            assembler files used when compiling with
  96                            assembler implementations.
  97         shared_target   => The shared library building method used.
  98                            This is a target found in Makefile.shared.
  99         build_scheme    => The scheme used to build up a Makefile.
 100                            (NOTE: this is here for future use, it's
 101                            not implemented yet)
 102
 103         multilib        => On systems that support having multiple
 104                            implementations of a library (typically a
 105                            32-bit and a 64-bit variant), this is used
 106                            to have the different variants in different
 107                            directories.
 108
 109         bn_ops          => Building options (was just bignum options
 110                            in the earlier history of this option,
 111                            hence the name).  This a string of words
 112                            that describe properties on the designated
 113                            target platform, such as the type of
 114                            integers used to build up the bitnum,
 115                            different ways to implement certain ciphers
 116                            and so on.  To fully comprehend the
 117                            meaning, the best is to read the affected
 118                            source.
 119                            The valid words are:
 120
 121                            DES_PTR      use a pointer to DES_SPtrans
 122                                         rather that DES_SPtrans
 123                                         directly in D_ENCRYPT.
 124                            DES_RISC1    Alternate implementations of
 125                            DES_RISC2    D_ENCRYPT for certain RISC
 126                                         processors.
 127                            DES_UNROLL   do not loop around calls to
 128                                         D_ENCRYPT.
 129                            DES_INT      have unsigned int as the
 130                                         integer type for DES rather
 131                                         than unsigned long.
 132                            BN_LLONG     use 'unsigned long long' in
 133                                         some bignum calculations.
 134                                         This has no value when
 135                                         SIXTY_FOUR_BIT or
 136                                         SIXTY_FOUR_BIT_LONG is given.
 137                            RC4_CHAR     makes the basic RC4 unif of
 138                                         calculation an unsigned char.
 139                            RC4_LONG     makes the basic RC4 unif of
 140                                         calculation an unsigned long.
 141                            RC4_INDEX    go through input and output
 142                                         data by indexing into them
 143                                         rather than incrementing the
 144                                         pointer.
 145                            RC4_CHUNK    sets the chunk type to
 146                                         unsigned long.
 147                            RC4_CHUNK_LL sets the chunk type to
 148                                         unsigned long long.
 149                                         both these chunk sizes are for
 150                                         handling data in chunks on
 151                                         processors that do not have
 152                                         byte load/store instructions.
 153                            MD2_CHAR     makes the basic MD2 unit of
 154                                         calculation an unsigned char.
 155                            MD2_LONG     makes the basic MD2 unit of
 156                                         calculation an unsigned long.
 157                            IDEA_SHORT   makes the basic IDEA unit of
 158                                         calculation an unsigned short.
 159                            IDEA_LONG    makes the basic IDEA unit of
 160                                         calculation an unsigned long.
 161                            RC2_SHORT    makes the basic RC2 unit of
 162                                         calculation an unsigned short.
 163                            RC2_LONG     makes the basic RC2 unit of
 164                                         calculation an unsigned long.
 165                            BF_PTR       use different pointer based
 166                            BF_PTR2      versions of BF_ENC.
 167                            SIXTY_FOUR_BIT       processor registers
 168                                                 are 64 bits, long is
 169                                                 32 bits, long long is
 170                                                 64 bits.
 171                            SIXTY_FOUR_BIT_LONG  processor registers
 172                                                 are 64 bits, long is
 173                                                 64 bits.
 174                            THIRTY_TWO_BIT       processor registers
 175                                                 are 32 bits.
 176                            EXPORT_VAR_AS_FN     for shared libraries,
 177                                                 export vars as
 178                                                 accessor functions.
 179
 180         cpuid_obj       => assembler implementation of cpuid code as
 181                            well as OPENSSL_cleanse().
 182                            Default to mem_clr.o
 183         bn_obj          => assembler implementation of core bignum
 184                            functions.
 185                            Defaults to bn_asm.o
 186         ec_obj          => assembler implementation of core EC
 187                            functions.
 188         des_obj         => assembler implementation of core DES
 189                            encryption functions.
 190                            Defaults to 'des_enc.o fcrypt_b.o'
 191         aes_obj         => assembler implementation of core AES
 192                            functions.
 193                            Defaults to 'aes_core.o aes_cbc.o'
 194         bf_obj          => assembler implementation of core BF
 195                            functions.
 196                            Defaults to 'bf_enc.o'
 197         md5_obj         => assembler implementation of core MD5
 198                            functions.
 199         sha1_obj        => assembler implementation of core SHA1,
 200                            functions, and also possibly SHA256 and
 201                            SHA512 ones.
 202         cast_obj        => assembler implementation of core BF
 203                            functions.
 204                            Defaults to 'c_enc.o'
 205         rc4_obj         => assembler implementation of core BF
 206                            functions.
 207                            Defaults to 'rc4_enc.o rc4_skey.o'
 208         rmd160_obj      => assembler implementation of core RMD160
 209                            functions.
 210         rc5_obj         => assembler implementation of core RC4
 211                            functions.
 212                            Defaults to 'rc5_enc.o'
 213         wp_obj          => assembler implementation of core WHIRLPOOL
 214                            functions.
 215         cmll_obj        => assembler implementation of core CAMELLIA
 216                            functions.
 217                            Defaults to 'camellia.o cmll_misc.o cmll_cbc.o'
 218         modes_obj       => assembler implementation of the
 219                            functions gcm_gmult_4bit and gcm_ghash_4bit.
 220         engines_obj     => assembler implementation of core parts of
 221                            the padlock engine.  This is mandatory on
 222                            any platform where the padlock engine might
 223                            actually be built.
 224
 225
 226 [1] as part of the target configuration, one can have a key called
 227     'inherit_from' that indicate what other configurations to inherit
 228     data from.  These are resolved recursively.
 229
 230     Inheritance works as a set of default values that can be overriden
 231     by corresponding key values in the inheriting configuration.
 232
 233     Note 1: any configuration table can be used as a template.
 234     Note 2: pure templates have the attribute 'template => 1' and
 235             cannot be used as build targets.
 236
 237     If several configurations are given in the 'inherit_from' array,
 238     the values of same attribute are concatenated with space
 239     separation.  With this, it's possible to have several smaller
 240     templates for different configuration aspects that can be combined
 241     into a complete configuration.
 242
 243     instead of a scalar value or an array, a value can be a code block
 244     of the form 'sub { /* your code here */ }'.  This code block will
 245     be called with the list of inherited values for that key as
 246     arguments.  In fact, the concatenation of strings is really done
 247     by using 'sub { join(" ",@_) }' on the list of inherited values.
 248
 249     An example:
 250
 251         "foo" => {
 252                 template => 1,
 253                 haha => "ha ha",
 254                 hoho => "ho",
 255                 ignored => "This should not appear in the end result",
 256         },
 257         "bar" => {
 258                 template => 1,
 259                 haha => "ah",
 260                 hoho => "haho",
 261                 hehe => "hehe"
 262         },
 263         "laughter" => {
 264                 inherit_from => [ "foo", "bar" ],
 265                 hehe => sub { join(" ",(@_,"!!!")) },
 266                 ignored => "",
 267         }
 268
 269         The entry for "laughter" will become as follows after processing:
 270
 271         "laughter" => {
 272                 haha => "ha ha ah",
 273                 hoho => "ho haho",
 274                 hehe => "hehe !!!",
 275                 ignored => ""
 276         }
 277
 278 [2] OpenSSL is built with threading capabilities unless the user
 279     specifies 'no-threads'.  The value of the key 'thread_cflags' may
 280     be "(unknown)", in which case the user MUST give some compilation
 281     flags to Configure.
 282
 283
 284 Historically, the target configurations came in form of a string with
 285 values separated by colons.  This use is deprecated, although
 286 currently somewhat supported.  The string form looks like this:
 287
 288    "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}:{engines_obj}:{perlasm_scheme}:{dso_scheme}:{shared_target}:{shared_cflag}:{shared_ldflag}:{shared_extension}:{ranlib}:{arflags}:{multilib}"