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                            In its simplest form, the value is a string
 101                            with the name of the build scheme.
 102                            The value may also take the form of a list
 103                            of strings, if the build_scheme is to have
 104                            some options.  In this case, the first
 105                            string in the list is the name of the build
 106                            scheme.
 107                            Currently recognised build schemes are
 108                            "mk1mf" and "unixmake" and "unified".
 109                            For the "unified" build scheme, this item
 110                            *must* be an array with the first being the
 111                            word "unified" and the second being a word
 112                            to identify the platform family.
 113
 114         multilib        => On systems that support having multiple
 115                            implementations of a library (typically a
 116                            32-bit and a 64-bit variant), this is used
 117                            to have the different variants in different
 118                            directories.
 119
 120         bn_ops          => Building options (was just bignum options
 121                            in the earlier history of this option,
 122                            hence the name).  This a string of words
 123                            that describe properties on the designated
 124                            target platform, such as the type of
 125                            integers used to build up the bitnum,
 126                            different ways to implement certain ciphers
 127                            and so on.  To fully comprehend the
 128                            meaning, the best is to read the affected
 129                            source.
 130                            The valid words are:
 131
 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 unit of
 138                                         calculation an unsigned char.
 139                            SIXTY_FOUR_BIT       processor registers
 140                                                 are 64 bits, long is
 141                                                 32 bits, long long is
 142                                                 64 bits.
 143                            SIXTY_FOUR_BIT_LONG  processor registers
 144                                                 are 64 bits, long is
 145                                                 64 bits.
 146                            THIRTY_TWO_BIT       processor registers
 147                                                 are 32 bits.
 148                            EXPORT_VAR_AS_FN     for shared libraries,
 149                                                 export vars as
 150                                                 accessor functions.
 151
 152         cpuid_asm_src   => assembler implementation of cpuid code as
 153                            well as OPENSSL_cleanse().
 154                            Default to mem_clr.c
 155         bn_asm_src      => Assembler implementation of core bignum
 156                            functions.
 157                            Defaults to bn_asm.c
 158         ec_asm_src      => Assembler implementation of core EC
 159                            functions.
 160         des_asm_src     => Assembler implementation of core DES
 161                            encryption functions.
 162                            Defaults to 'des_enc.c fcrypt_b.c'
 163         aes_asm_src     => Assembler implementation of core AES
 164                            functions.
 165                            Defaults to 'aes_core.c aes_cbc.c'
 166         bf_asm_src      => Assembler implementation of core BlowFish
 167                            functions.
 168                            Defaults to 'bf_enc.c'
 169         md5_asm_src     => Assembler implementation of core MD5
 170                            functions.
 171         sha1_asm_src    => Assembler implementation of core SHA1,
 172                            functions, and also possibly SHA256 and
 173                            SHA512 ones.
 174         cast_asm_src    => Assembler implementation of core CAST
 175                            functions.
 176                            Defaults to 'c_enc.c'
 177         rc4_asm_src     => Assembler implementation of core RC4
 178                            functions.
 179                            Defaults to 'rc4_enc.c rc4_skey.c'
 180         rmd160_asm_src  => Assembler implementation of core RMD160
 181                            functions.
 182         rc5_asm_src     => Assembler implementation of core RC5
 183                            functions.
 184                            Defaults to 'rc5_enc.c'
 185         wp_asm_src      => Assembler implementation of core WHIRLPOOL
 186                            functions.
 187         cmll_asm_src    => Assembler implementation of core CAMELLIA
 188                            functions.
 189                            Defaults to 'camellia.c cmll_misc.c cmll_cbc.c'
 190         modes_asm_src   => Assembler implementation of cipher modes,
 191                            currently the functions gcm_gmult_4bit and
 192                            gcm_ghash_4bit.
 193         padlock_asm_src => Assembler implementation of core parts of
 194                            the padlock engine.  This is mandatory on
 195                            any platform where the padlock engine might
 196                            actually be built.
 197
 198
 199 [1] as part of the target configuration, one can have a key called
 200     'inherit_from' that indicate what other configurations to inherit
 201     data from.  These are resolved recursively.
 202
 203     Inheritance works as a set of default values that can be overriden
 204     by corresponding key values in the inheriting configuration.
 205
 206     Note 1: any configuration table can be used as a template.
 207     Note 2: pure templates have the attribute 'template => 1' and
 208             cannot be used as build targets.
 209
 210     If several configurations are given in the 'inherit_from' array,
 211     the values of same attribute are concatenated with space
 212     separation.  With this, it's possible to have several smaller
 213     templates for different configuration aspects that can be combined
 214     into a complete configuration.
 215
 216     instead of a scalar value or an array, a value can be a code block
 217     of the form 'sub { /* your code here */ }'.  This code block will
 218     be called with the list of inherited values for that key as
 219     arguments.  In fact, the concatenation of strings is really done
 220     by using 'sub { join(" ",@_) }' on the list of inherited values.
 221
 222     An example:
 223
 224         "foo" => {
 225                 template => 1,
 226                 haha => "ha ha",
 227                 hoho => "ho",
 228                 ignored => "This should not appear in the end result",
 229         },
 230         "bar" => {
 231                 template => 1,
 232                 haha => "ah",
 233                 hoho => "haho",
 234                 hehe => "hehe"
 235         },
 236         "laughter" => {
 237                 inherit_from => [ "foo", "bar" ],
 238                 hehe => sub { join(" ",(@_,"!!!")) },
 239                 ignored => "",
 240         }
 241
 242         The entry for "laughter" will become as follows after processing:
 243
 244         "laughter" => {
 245                 haha => "ha ha ah",
 246                 hoho => "ho haho",
 247                 hehe => "hehe !!!",
 248                 ignored => ""
 249         }
 250
 251 [2] OpenSSL is built with threading capabilities unless the user
 252     specifies 'no-threads'.  The value of the key 'thread_cflags' may
 253     be "(unknown)", in which case the user MUST give some compilation
 254     flags to Configure.
 255
 256
 257 Historically, the target configurations came in form of a string with
 258 values separated by colons.  This use is deprecated.  The string form
 259 looked like this:
 260
 261    "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}"
 262
 263
 264 Build info files
 265 ================
 266
 267 The build.info files that are spread over the source tree contain the
 268 minimum information needed to build and distribute OpenSSL.  It uses a
 269 simple and yet fairly powerful language to determine what needs to be
 270 built, from what sources, and other relationships between files.
 271
 272 For every build.info file, all file references are relative to the
 273 directory of the build.info file for source files, and the
 274 corresponding build directory for built files if the build tree
 275 differs from the source tree.
 276
 277 When processed, every line is processed with the perl module
 278 Text::Template, using the delimiters "{-" and "-}".  The hashes
 279 %config and %target are passed to the perl fragments, along with
 280 $sourcedir and $builddir, which are the locations of the source
 281 directory for the current build.info file and the corresponding build
 282 directory, all relative to the top of the build tree.
 283
 284 To begin with, things to be built are declared by setting specific
 285 variables:
 286
 287     PROGRAMS=foo bar
 288     LIBS=libsomething
 289     ENGINES=libeng
 290     SCRIPTS=myhack
 291     EXTRA=file1 file2
 292
 293 Note that the files mentioned for PROGRAMS, LIBS and ENGINES *must* be
 294 without extensions.  The build file templates will figure them out.
 295
 296 For each thing to be built, it is then possible to say what sources
 297 they are built from:
 298
 299     PROGRAMS=foo bar
 300     SOURCE[foo]=foo.c common.c
 301     SOURCE[bar]=bar.c extra.c common.c
 302
 303 It's also possible to tell some other dependencies:
 304
 305     DEPEND[foo]=libsomething
 306     DEPEND[libbar]=libsomethingelse
 307
 308 (it could be argued that 'libsomething' and 'libsomethingelse' are
 309 source as well.  However, the files given through SOURCE are expected
 310 to be located in the source tree while files given through DEPEND are
 311 expected to be located in the build tree)
 312
 313 For some libraries, we maintain files with public symbols and their
 314 slot in a transfer vector (important on some platforms).  It can be
 315 declared like this:
 316
 317     ORDINALS[libcrypto]=crypto
 318
 319 The value is not the name of the file in question, but rather the
 320 argument to util/mkdef.pl that indicates which file to use.
 321
 322 One some platforms, shared libraries come with a name that's different
 323 from their static counterpart.  That's declared as follows:
 324
 325     SHARED_NAME[libfoo]=cygfoo-{- $config{shlibver} -}
 326
 327 The example is from Cygwin, which has a required naming convention.
 328
 329 Sometimes, it makes sense to rename an output file, for example a
 330 library:
 331
 332     RENAME[libfoo]=libbar
 333
 334 That lines has "libfoo" get renamed to "libbar".  While it makes no
 335 sense at all to just have a rename like that (why not just use
 336 "libbar" everywhere?), it does make sense when it can be used
 337 conditionally.  See a little further below for an example.
 338
 339 For any file to be built, it's also possible to tell what extra
 340 include paths the build of their source files should use:
 341
 342     INCLUDE[foo]=include
 343
 344 It's possible to have raw build file lines, between BEGINRAW and
 345 ENDRAW lines as follows:
 346
 347     BEGINRAW[Makefile(unix)]
 348     haha.h: {- $builddir -}/Makefile
 349         echo "/* haha */" > haha.h
 350     ENDRAW[Makefile(unix)]
 351
 352 The word withing square brackets is the build_file configuration item
 353 or the build_file configuration item followed by the second word in the
 354 build_scheme configuration item for the configured target within
 355 parenthesis as shown above.  For example, with the following relevant
 356 configuration items:
 357
 358    build_file   => "build.ninja"
 359    build_scheme => [ "unified", "unix" ]
 360
 361 ... these lines will be considered:
 362
 363    BEGINRAW[build.ninja]
 364    build haha.h: echo "/* haha */" > haha.h
 365    ENDRAW[build.ninja]
 366
 367    BEGINRAW[build.ninja(unix)]
 368    build hoho.h: echo "/* hoho */" > hoho.h
 369    ENDRAW[build.ninja(unix)]
 370
 371 See the documentation further up for more information on configuration
 372 items.
 373
 374 Finally, you can have some simple conditional use of the build.info
 375 information, looking like this:
 376
 377     IF[1]
 378      something
 379     ELSIF[2]
 380      something other
 381     ELSE
 382      something else
 383     ENDIF
 384
 385 The expression in square brackets is interpreted as a string in perl,
 386 and will be seen as true if perl thinks it is, otherwise false.  For
 387 example, the above would have "something" used, since 1 is true.
 388
 389 Together with the use of Text::Template, this can be used as
 390 conditions based on something in the passed variables, for example:
 391
 392     IF[{- $config{no_shared} -}]
 393       LIBS=libcrypto
 394       SOURCE[libcrypto]=...
 395     ELSE
 396       LIBS=libfoo
 397       SOURCE[libfoo]=...
 398     ENDIF
 399
 400 or:
 401
 402     # VMS has a cultural standard where all libraries are prefixed.
 403     # For OpenSSL, the choice is 'ossl_'
 404     IF[{- $config{target} =~ /^vms/ -}]
 405      RENAME[libcrypto]=ossl_libcrypto
 406      RENAME[libssl]=ossl_libssl
 407     ENDIF