1Intro 2===== 3 4This directory contains a few sets of files that are used for 5configuration in diverse ways: 6 7 *.conf Target platform configurations, please read 8 'Configurations of OpenSSL target platforms' for more 9 information. 10 *.tmpl Build file templates, please read 'Build-file 11 programming with the "unified" build system' as well 12 as 'Build info files' for more information. 13 *.pm Helper scripts / modules for the main `Configure` 14 script. See 'Configure helper scripts for more 15 information. 16 17Configurations of OpenSSL target platforms 18========================================== 19 20Configuration targets are a collection of facts that we know about 21different platforms and their capabilities. We organise them in a 22hash table, where each entry represent a specific target. 23 24Note that configuration target names must be unique across all config 25files. The Configure script does check that a config file doesn't 26have config targets that shadow config targets from other files. 27 28In each table entry, the following keys are significant: 29 30 inherit_from => Other targets to inherit values from. 31 Explained further below. [1] 32 template => Set to 1 if this isn't really a platform 33 target. Instead, this target is a template 34 upon which other targets can be built. 35 Explained further below. [1] 36 37 sys_id => System identity for systems where that 38 is difficult to determine automatically. 39 40 enable => Enable specific configuration features. 41 This MUST be an array of words. 42 disable => Disable specific configuration features. 43 This MUST be an array of words. 44 Note: if the same feature is both enabled 45 and disabled, disable wins. 46 47 as => The assembler command. This is not always 48 used (for example on Unix, where the C 49 compiler is used instead). 50 asflags => Default assembler command flags [4]. 51 cpp => The C preprocessor command, normally not 52 given, as the build file defaults are 53 usually good enough. 54 cppflags => Default C preprocessor flags [4]. 55 defines => As an alternative, macro definitions may be 56 given here instead of in 'cppflags' [4]. 57 If given here, they MUST be as an array of 58 the string such as "MACRO=value", or just 59 "MACRO" for definitions without value. 60 includes => As an alternative, inclusion directories 61 may be given here instead of in 'cppflags' 62 [4]. If given here, the MUST be an array 63 of strings, one directory specification 64 each. 65 cc => The C compiler command, usually one of "cc", 66 "gcc" or "clang". This command is normally 67 also used to link object files and 68 libraries into the final program. 69 cxx => The C++ compiler command, usually one of 70 "c++", "g++" or "clang++". This command is 71 also used when linking a program where at 72 least one of the object file is made from 73 C++ source. 74 cflags => Defaults C compiler flags [4]. 75 cxxflags => Default C++ compiler flags [4]. If unset, 76 it gets the same value as cflags. 77 78 (linking is a complex thing, see [3] below) 79 ld => Linker command, usually not defined 80 (meaning the compiler command is used 81 instead). 82 (NOTE: this is here for future use, it's 83 not implemented yet) 84 lflags => Default flags used when linking apps, 85 shared libraries or DSOs [4]. 86 ex_libs => Extra libraries that are needed when 87 linking shared libraries, DSOs or programs. 88 The value is also assigned to Libs.private 89 in $(libdir)/pkgconfig/libcrypto.pc. 90 91 shared_cppflags => Extra C preprocessor flags used when 92 processing C files for shared libraries. 93 shared_cflag => Extra C compiler flags used when compiling 94 for shared libraries, typically something 95 like "-fPIC". 96 shared_ldflag => Extra linking flags used when linking 97 shared libraries. 98 module_cppflags 99 module_cflags 100 module_ldflags => Has the same function as the corresponding 101 'shared_' attributes, but for building DSOs. 102 When unset, they get the same values as the 103 corresponding 'shared_' attributes. 104 105 ar => The library archive command, the default is 106 "ar". 107 (NOTE: this is here for future use, it's 108 not implemented yet) 109 arflags => Flags to be used with the library archive 110 command. On Unix, this includes the 111 command letter, 'r' by default. 112 113 ranlib => The library archive indexing command, the 114 default is 'ranlib' it it exists. 115 116 unistd => An alternative header to the typical 117 '<unistd.h>'. This is very rarely needed. 118 119 shared_extension => File name extension used for shared 120 libraries. 121 obj_extension => File name extension used for object files. 122 On unix, this defaults to ".o" (NOTE: this 123 is here for future use, it's not 124 implemented yet) 125 exe_extension => File name extension used for executable 126 files. On unix, this defaults to "" (NOTE: 127 this is here for future use, it's not 128 implemented yet) 129 shlib_variant => A "variant" identifier inserted between the base 130 shared library name and the extension. On "unixy" 131 platforms (BSD, Linux, Solaris, MacOS/X, ...) this 132 supports installation of custom OpenSSL libraries 133 that don't conflict with other builds of OpenSSL 134 installed on the system. The variant identifier 135 becomes part of the SONAME of the library and also 136 any symbol versions (symbol versions are not used or 137 needed with MacOS/X). For example, on a system 138 where a default build would normally create the SSL 139 shared library as 'libssl.so -> libssl.so.1.1' with 140 the value of the symlink as the SONAME, a target 141 definition that sets 'shlib_variant => "-abc"' will 142 create 'libssl.so -> libssl-abc.so.1.1', again with 143 an SONAME equal to the value of the symlink. The 144 symbol versions associated with the variant library 145 would then be 'OPENSSL_ABC_<version>' rather than 146 the default 'OPENSSL_<version>'. The string inserted 147 into symbol versions is obtained by mapping all 148 letters in the "variant" identifier to upper case 149 and all non-alphanumeric characters to '_'. 150 151 thread_scheme => The type of threads is used on the 152 configured platform. Currently known 153 values are "(unknown)", "pthreads", 154 "uithreads" (a.k.a solaris threads) and 155 "winthreads". Except for "(unknown)", the 156 actual value is currently ignored but may 157 be used in the future. See further notes 158 below [2]. 159 dso_scheme => The type of dynamic shared objects to build 160 for. This mostly comes into play with 161 modules, but can be used for other purposes 162 as well. Valid values are "DLFCN" 163 (dlopen() et al), "DLFCN_NO_H" (for systems 164 that use dlopen() et al but do not have 165 fcntl.h), "DL" (shl_load() et al), "WIN32" 166 and "VMS". 167 asm_arch => The architecture to be used for compiling assembly 168 source. This acts as a selector in build.info files. 169 uplink_arch => The architecture to be used for compiling uplink 170 source. This acts as a selector in build.info files. 171 This is separate from asm_arch because it's compiled 172 even when 'no-asm' is given, even though it contains 173 assembler source. 174 perlasm_scheme => The perlasm method used to create the 175 assembler files used when compiling with 176 assembler implementations. 177 shared_target => The shared library building method used. 178 This serves multiple purposes: 179 - as index for targets found in shared_info.pl. 180 - as linker script generation selector. 181 To serve both purposes, the index for shared_info.pl 182 should end with '-shared', and this suffix will be 183 removed for use as a linker script generation 184 selector. Note that the latter is only used if 185 'shared_defflag' is defined. 186 build_scheme => The scheme used to build up a Makefile. 187 In its simplest form, the value is a string 188 with the name of the build scheme. 189 The value may also take the form of a list 190 of strings, if the build_scheme is to have 191 some options. In this case, the first 192 string in the list is the name of the build 193 scheme. 194 Currently recognised build scheme is "unified". 195 For the "unified" build scheme, this item 196 *must* be an array with the first being the 197 word "unified" and the second being a word 198 to identify the platform family. 199 200 multilib => On systems that support having multiple 201 implementations of a library (typically a 202 32-bit and a 64-bit variant), this is used 203 to have the different variants in different 204 directories. 205 206 bn_ops => Building options (was just bignum options in 207 the earlier history of this option, hence the 208 name). This is a string of words that describe 209 algorithms' implementation parameters that 210 are optimal for the designated target platform, 211 such as the type of integers used to build up 212 the bignum, different ways to implement certain 213 ciphers and so on. To fully comprehend the 214 meaning, the best is to read the affected 215 source. 216 The valid words are: 217 218 THIRTY_TWO_BIT bignum limbs are 32 bits, 219 this is default if no 220 option is specified, it 221 works on any supported 222 system [unless "wider" 223 limb size is implied in 224 assembly code]; 225 BN_LLONG bignum limbs are 32 bits, 226 but 64-bit 'unsigned long 227 long' is used internally 228 in calculations; 229 SIXTY_FOUR_BIT_LONG bignum limbs are 64 bits 230 and sizeof(long) is 8; 231 SIXTY_FOUR_BIT bignums limbs are 64 bits, 232 but execution environment 233 is ILP32; 234 RC4_CHAR RC4 key schedule is made 235 up of 'unsigned char's; 236 RC4_INT RC4 key schedule is made 237 up of 'unsigned int's; 238 239[1] as part of the target configuration, one can have a key called 240 `inherit_from` that indicates what other configurations to inherit 241 data from. These are resolved recursively. 242 243 Inheritance works as a set of default values that can be overridden 244 by corresponding key values in the inheriting configuration. 245 246 Note 1: any configuration table can be used as a template. 247 Note 2: pure templates have the attribute `template => 1` and 248 cannot be used as build targets. 249 250 If several configurations are given in the `inherit_from` array, 251 the values of same attribute are concatenated with space 252 separation. With this, it's possible to have several smaller 253 templates for different configuration aspects that can be combined 254 into a complete configuration. 255 256 Instead of a scalar value or an array, a value can be a code block 257 of the form `sub { /* your code here */ }`. This code block will 258 be called with the list of inherited values for that key as 259 arguments. In fact, the concatenation of strings is really done 260 by using `sub { join(" ",@_) }` on the list of inherited values. 261 262 An example: 263 264 "foo" => { 265 template => 1, 266 haha => "ha ha", 267 hoho => "ho", 268 ignored => "This should not appear in the end result", 269 }, 270 "bar" => { 271 template => 1, 272 haha => "ah", 273 hoho => "haho", 274 hehe => "hehe" 275 }, 276 "laughter" => { 277 inherit_from => [ "foo", "bar" ], 278 hehe => sub { join(" ",(@_,"!!!")) }, 279 ignored => "", 280 } 281 282 The entry for "laughter" will become as follows after processing: 283 284 "laughter" => { 285 haha => "ha ha ah", 286 hoho => "ho haho", 287 hehe => "hehe !!!", 288 ignored => "" 289 } 290 291[2] OpenSSL is built with threading capabilities unless the user 292 specifies `no-threads`. The value of the key `thread_scheme` may 293 be `(unknown)`, in which case the user MUST give some compilation 294 flags to `Configure`. 295 296[3] OpenSSL has three types of things to link from object files or 297 static libraries: 298 299 - shared libraries; that would be libcrypto and libssl. 300 - shared objects (sometimes called dynamic libraries); that would 301 be the modules. 302 - applications; those are apps/openssl and all the test apps. 303 304 Very roughly speaking, linking is done like this (words in braces 305 represent the configuration settings documented at the beginning 306 of this file): 307 308 shared libraries: 309 {ld} $(CFLAGS) {lflags} {shared_ldflag} -o libfoo.so \ 310 foo/something.o foo/somethingelse.o {ex_libs} 311 312 shared objects: 313 {ld} $(CFLAGS) {lflags} {module_ldflags} -o libeng.so \ 314 blah1.o blah2.o -lcrypto {ex_libs} 315 316 applications: 317 {ld} $(CFLAGS) {lflags} -o app \ 318 app1.o utils.o -lssl -lcrypto {ex_libs} 319 320[4] There are variants of these attribute, prefixed with `lib_`, 321 `dso_` or `bin_`. Those variants replace the unprefixed attribute 322 when building library, DSO or program modules specifically. 323 324Historically, the target configurations came in form of a string with 325values separated by colons. This use is deprecated. The string form 326looked like this: 327 328 "target" => "{cc}:{cflags}:{unistd}:{thread_cflag}:{sys_id}:{lflags}: 329 {bn_ops}:{cpuid_obj}:{bn_obj}:{ec_obj}:{des_obj}:{aes_obj}: 330 {bf_obj}:{md5_obj}:{sha1_obj}:{cast_obj}:{rc4_obj}: 331 {rmd160_obj}:{rc5_obj}:{wp_obj}:{cmll_obj}:{modes_obj}: 332 {padlock_obj}:{perlasm_scheme}:{dso_scheme}:{shared_target}: 333 {shared_cflag}:{shared_ldflag}:{shared_extension}:{ranlib}: 334 {arflags}:{multilib}" 335 336Build info files 337================ 338 339The `build.info` files that are spread over the source tree contain the 340minimum information needed to build and distribute OpenSSL. It uses a 341simple and yet fairly powerful language to determine what needs to be 342built, from what sources, and other relationships between files. 343 344For every `build.info` file, all file references are relative to the 345directory of the `build.info` file for source files, and the 346corresponding build directory for built files if the build tree 347differs from the source tree. 348 349When processed, every line is processed with the perl module 350Text::Template, using the delimiters `{-` and `-}`. The hashes 351`%config` and `%target` are passed to the perl fragments, along with 352$sourcedir and $builddir, which are the locations of the source 353directory for the current `build.info` file and the corresponding build 354directory, all relative to the top of the build tree. 355 356`Configure` only knows inherently about the top `build.info` file. For 357any other directory that has one, further directories to look into 358must be indicated like this: 359 360 SUBDIRS=something someelse 361 362On to things to be built; they are declared by setting specific 363variables: 364 365 PROGRAMS=foo bar 366 LIBS=libsomething 367 MODULES=libeng 368 SCRIPTS=myhack 369 370Note that the files mentioned for PROGRAMS, LIBS and MODULES *must* be 371without extensions. The build file templates will figure them out. 372 373For each thing to be built, it is then possible to say what sources 374they are built from: 375 376 PROGRAMS=foo bar 377 SOURCE[foo]=foo.c common.c 378 SOURCE[bar]=bar.c extra.c common.c 379 380It's also possible to tell some other dependencies: 381 382 DEPEND[foo]=libsomething 383 DEPEND[libbar]=libsomethingelse 384 385(it could be argued that 'libsomething' and 'libsomethingelse' are 386source as well. However, the files given through SOURCE are expected 387to be located in the source tree while files given through DEPEND are 388expected to be located in the build tree) 389 390It's also possible to depend on static libraries explicitly: 391 392 DEPEND[foo]=libsomething.a 393 DEPEND[libbar]=libsomethingelse.a 394 395This should be rarely used, and care should be taken to make sure it's 396only used when supported. For example, native Windows build doesn't 397support building static libraries and DLLs at the same time, so using 398static libraries on Windows can only be done when configured 399`no-shared`. 400 401In some cases, it's desirable to include some source files in the 402shared form of a library only: 403 404 SHARED_SOURCE[libfoo]=dllmain.c 405 406For any file to be built, it's also possible to tell what extra 407include paths the build of their source files should use: 408 409 INCLUDE[foo]=include 410 411It's also possible to specify C macros that should be defined: 412 413 DEFINE[foo]=FOO BAR=1 414 415In some cases, one might want to generate some source files from 416others, that's done as follows: 417 418 GENERATE[foo.s]=asm/something.pl $(CFLAGS) 419 GENERATE[bar.s]=asm/bar.S 420 421The value of each GENERATE line is a command line or part of it. 422Configure places no rules on the command line, except that the first 423item must be the generator file. It is, however, entirely up to the 424build file template to define exactly how those command lines should 425be handled, how the output is captured and so on. 426 427Sometimes, the generator file itself depends on other files, for 428example if it is a perl script that depends on other perl modules. 429This can be expressed using DEPEND like this: 430 431 DEPEND[asm/something.pl]=../perlasm/Foo.pm 432 433There may also be cases where the exact file isn't easily specified, 434but an inclusion directory still needs to be specified. INCLUDE can 435be used in that case: 436 437 INCLUDE[asm/something.pl]=../perlasm 438 439NOTE: GENERATE lines are limited to one command only per GENERATE. 440 441Finally, you can have some simple conditional use of the `build.info` 442information, looking like this: 443 444 IF[1] 445 something 446 ELSIF[2] 447 something other 448 ELSE 449 something else 450 ENDIF 451 452The expression in square brackets is interpreted as a string in perl, 453and will be seen as true if perl thinks it is, otherwise false. For 454example, the above would have "something" used, since 1 is true. 455 456Together with the use of Text::Template, this can be used as 457conditions based on something in the passed variables, for example: 458 459 IF[{- $disabled{shared} -}] 460 LIBS=libcrypto 461 SOURCE[libcrypto]=... 462 ELSE 463 LIBS=libfoo 464 SOURCE[libfoo]=... 465 ENDIF 466 467Build-file programming with the "unified" build system 468====================================================== 469 470"Build files" are called `Makefile` on Unix-like operating systems, 471`descrip.mms` for MMS on VMS, `makefile` for `nmake` on Windows, etc. 472 473To use the "unified" build system, the target configuration needs to 474set the three items `build_scheme`, `build_file` and `build_command`. 475In the rest of this section, we will assume that `build_scheme` is set 476to "unified" (see the configurations documentation above for the 477details). 478 479For any name given by `build_file`, the "unified" system expects a 480template file in `Configurations/` named like the build file, with 481`.tmpl` appended, or in case of possible ambiguity, a combination of 482the second `build_scheme` list item and the `build_file` name. For 483example, if `build_file` is set to `Makefile`, the template could be 484`Configurations/Makefile.tmpl` or `Configurations/unix-Makefile.tmpl`. 485In case both `Configurations/unix-Makefile.tmpl` and 486`Configurations/Makefile.tmpl` are present, the former takes precedence. 487 488The build-file template is processed with the perl module 489Text::Template, using `{-` and `-}` as delimiters that enclose the 490perl code fragments that generate configuration-dependent content. 491Those perl fragments have access to all the hash variables from 492configdata.pem. 493 494The build-file template is expected to define at least the following 495perl functions in a perl code fragment enclosed with `{-` and `-}`. 496They are all expected to return a string with the lines they produce. 497 498 generatesrc - function that produces build file lines to generate 499 a source file from some input. 500 501 It's called like this: 502 503 generatesrc(src => "PATH/TO/tobegenerated", 504 generator => [ "generatingfile", ... ] 505 generator_incs => [ "INCL/PATH", ... ] 506 generator_deps => [ "dep1", ... ] 507 generator => [ "generatingfile", ... ] 508 incs => [ "INCL/PATH", ... ], 509 deps => [ "dep1", ... ], 510 intent => one of "libs", "dso", "bin" ); 511 512 'src' has the name of the file to be generated. 513 'generator' is the command or part of command to 514 generate the file, of which the first item is 515 expected to be the file to generate from. 516 generatesrc() is expected to analyse and figure out 517 exactly how to apply that file and how to capture 518 the result. 'generator_incs' and 'generator_deps' 519 are include directories and files that the generator 520 file itself depends on. 'incs' and 'deps' are 521 include directories and files that are used if $(CC) 522 is used as an intermediary step when generating the 523 end product (the file indicated by 'src'). 'intent' 524 indicates what the generated file is going to be 525 used for. 526 527 src2obj - function that produces build file lines to build an 528 object file from source files and associated data. 529 530 It's called like this: 531 532 src2obj(obj => "PATH/TO/objectfile", 533 srcs => [ "PATH/TO/sourcefile", ... ], 534 deps => [ "dep1", ... ], 535 incs => [ "INCL/PATH", ... ] 536 intent => one of "lib", "dso", "bin" ); 537 538 'obj' has the intended object file with '.o' 539 extension, src2obj() is expected to change it to 540 something more suitable for the platform. 541 'srcs' has the list of source files to build the 542 object file, with the first item being the source 543 file that directly corresponds to the object file. 544 'deps' is a list of explicit dependencies. 'incs' 545 is a list of include file directories. Finally, 546 'intent' indicates what this object file is going 547 to be used for. 548 549 obj2lib - function that produces build file lines to build a 550 static library file ("libfoo.a" in Unix terms) from 551 object files. 552 553 called like this: 554 555 obj2lib(lib => "PATH/TO/libfile", 556 objs => [ "PATH/TO/objectfile", ... ]); 557 558 'lib' has the intended library file name *without* 559 extension, obj2lib is expected to add that. 'objs' 560 has the list of object files to build this library. 561 562 libobj2shlib - backward compatibility function that's used the 563 same way as obj2shlib (described next), and was 564 expected to build the shared library from the 565 corresponding static library when that was suitable. 566 NOTE: building a shared library from a static 567 library is now DEPRECATED, as they no longer share 568 object files. Attempting to do this will fail. 569 570 obj2shlib - function that produces build file lines to build a 571 shareable object library file ("libfoo.so" in Unix 572 terms) from the corresponding object files. 573 574 called like this: 575 576 obj2shlib(shlib => "PATH/TO/shlibfile", 577 lib => "PATH/TO/libfile", 578 objs => [ "PATH/TO/objectfile", ... ], 579 deps => [ "PATH/TO/otherlibfile", ... ]); 580 581 'lib' has the base (static) library ffile name 582 *without* extension. This is useful in case 583 supporting files are needed (such as import 584 libraries on Windows). 585 'shlib' has the corresponding shared library name 586 *without* extension. 'deps' has the list of other 587 libraries (also *without* extension) this library 588 needs to be linked with. 'objs' has the list of 589 object files to build this library. 590 591 obj2dso - function that produces build file lines to build a 592 dynamic shared object file from object files. 593 594 called like this: 595 596 obj2dso(lib => "PATH/TO/libfile", 597 objs => [ "PATH/TO/objectfile", ... ], 598 deps => [ "PATH/TO/otherlibfile", 599 ... ]); 600 601 This is almost the same as obj2shlib, but the 602 intent is to build a shareable library that can be 603 loaded in runtime (a "plugin"...). 604 605 obj2bin - function that produces build file lines to build an 606 executable file from object files. 607 608 called like this: 609 610 obj2bin(bin => "PATH/TO/binfile", 611 objs => [ "PATH/TO/objectfile", ... ], 612 deps => [ "PATH/TO/libfile", ... ]); 613 614 'bin' has the intended executable file name 615 *without* extension, obj2bin is expected to add 616 that. 'objs' has the list of object files to build 617 this library. 'deps' has the list of library files 618 (also *without* extension) that the programs needs 619 to be linked with. 620 621 in2script - function that produces build file lines to build a 622 script file from some input. 623 624 called like this: 625 626 in2script(script => "PATH/TO/scriptfile", 627 sources => [ "PATH/TO/infile", ... ]); 628 629 'script' has the intended script file name. 630 'sources' has the list of source files to build the 631 resulting script from. 632 633In all cases, file file paths are relative to the build tree top, and 634the build file actions run with the build tree top as current working 635directory. 636 637Make sure to end the section with these functions with a string that 638you thing is appropriate for the resulting build file. If nothing 639else, end it like this: 640 641 ""; # Make sure no lingering values end up in the Makefile 642 -} 643 644Configure helper scripts 645======================== 646 647Configure uses helper scripts in this directory: 648 649Checker scripts 650--------------- 651 652These scripts are per platform family, to check the integrity of the 653tools used for configuration and building. The checker script used is 654either `{build_platform}-{build_file}-checker.pm` or 655`{build_platform}-checker.pm`, where `{build_platform}` is the second 656`build_scheme` list element from the configuration target data, and 657`{build_file}` is `build_file` from the same target data. 658 659If the check succeeds, the script is expected to end with a non-zero 660expression. If the check fails, the script can end with a zero, or 661with a `die`. 662
