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 Note: should not be used 237 for new configuration 238 targets 239 RC4_INT RC4 key schedule is made 240 up of 'unsigned int's; 241 Note: should not be used 242 for new configuration 243 targets 244 245[1] as part of the target configuration, one can have a key called 246 `inherit_from` that indicates what other configurations to inherit 247 data from. These are resolved recursively. 248 249 Inheritance works as a set of default values that can be overridden 250 by corresponding key values in the inheriting configuration. 251 252 Note 1: any configuration table can be used as a template. 253 Note 2: pure templates have the attribute `template => 1` and 254 cannot be used as build targets. 255 256 If several configurations are given in the `inherit_from` array, 257 the values of same attribute are concatenated with space 258 separation. With this, it's possible to have several smaller 259 templates for different configuration aspects that can be combined 260 into a complete configuration. 261 262 Instead of a scalar value or an array, a value can be a code block 263 of the form `sub { /* your code here */ }`. This code block will 264 be called with the list of inherited values for that key as 265 arguments. In fact, the concatenation of strings is really done 266 by using `sub { join(" ",@_) }` on the list of inherited values. 267 268 An example: 269 270 "foo" => { 271 template => 1, 272 haha => "ha ha", 273 hoho => "ho", 274 ignored => "This should not appear in the end result", 275 }, 276 "bar" => { 277 template => 1, 278 haha => "ah", 279 hoho => "haho", 280 hehe => "hehe" 281 }, 282 "laughter" => { 283 inherit_from => [ "foo", "bar" ], 284 hehe => sub { join(" ",(@_,"!!!")) }, 285 ignored => "", 286 } 287 288 The entry for "laughter" will become as follows after processing: 289 290 "laughter" => { 291 haha => "ha ha ah", 292 hoho => "ho haho", 293 hehe => "hehe !!!", 294 ignored => "" 295 } 296 297[2] OpenSSL is built with threading capabilities unless the user 298 specifies `no-threads`. The value of the key `thread_scheme` may 299 be `(unknown)`, in which case the user MUST give some compilation 300 flags to `Configure`. 301 302[3] OpenSSL has three types of things to link from object files or 303 static libraries: 304 305 - shared libraries; that would be libcrypto and libssl. 306 - shared objects (sometimes called dynamic libraries); that would 307 be the modules. 308 - applications; those are apps/openssl and all the test apps. 309 310 Very roughly speaking, linking is done like this (words in braces 311 represent the configuration settings documented at the beginning 312 of this file): 313 314 shared libraries: 315 {ld} $(CFLAGS) {lflags} {shared_ldflag} -o libfoo.so \ 316 foo/something.o foo/somethingelse.o {ex_libs} 317 318 shared objects: 319 {ld} $(CFLAGS) {lflags} {module_ldflags} -o libeng.so \ 320 blah1.o blah2.o -lcrypto {ex_libs} 321 322 applications: 323 {ld} $(CFLAGS) {lflags} -o app \ 324 app1.o utils.o -lssl -lcrypto {ex_libs} 325 326[4] There are variants of these attribute, prefixed with `lib_`, 327 `dso_` or `bin_`. Those variants replace the unprefixed attribute 328 when building library, DSO or program modules specifically. 329 330Historically, the target configurations came in form of a string with 331values separated by colons. This use is deprecated. The string form 332looked like this: 333 334 "target" => "{cc}:{cflags}:{unistd}:{thread_cflag}:{sys_id}:{lflags}: 335 {bn_ops}:{cpuid_obj}:{bn_obj}:{ec_obj}:{des_obj}:{aes_obj}: 336 {bf_obj}:{md5_obj}:{sha1_obj}:{cast_obj}:{rc4_obj}: 337 {rmd160_obj}:{rc5_obj}:{wp_obj}:{cmll_obj}:{modes_obj}: 338 {padlock_obj}:{perlasm_scheme}:{dso_scheme}:{shared_target}: 339 {shared_cflag}:{shared_ldflag}:{shared_extension}:{ranlib}: 340 {arflags}:{multilib}" 341 342Build info files 343================ 344 345The `build.info` files that are spread over the source tree contain the 346minimum information needed to build and distribute OpenSSL. It uses a 347simple and yet fairly powerful language to determine what needs to be 348built, from what sources, and other relationships between files. 349 350For every `build.info` file, all file references are relative to the 351directory of the `build.info` file for source files, and the 352corresponding build directory for built files if the build tree 353differs from the source tree. 354 355When processed, every line is processed with the perl module 356Text::Template, using the delimiters `{-` and `-}`. The hashes 357`%config` and `%target` are passed to the perl fragments, along with 358$sourcedir and $builddir, which are the locations of the source 359directory for the current `build.info` file and the corresponding build 360directory, all relative to the top of the build tree. 361 362`Configure` only knows inherently about the top `build.info` file. For 363any other directory that has one, further directories to look into 364must be indicated like this: 365 366 SUBDIRS=something someelse 367 368On to things to be built; they are declared by setting specific 369variables: 370 371 PROGRAMS=foo bar 372 LIBS=libsomething 373 MODULES=libeng 374 SCRIPTS=myhack 375 376Note that the files mentioned for PROGRAMS, LIBS and MODULES *must* be 377without extensions. The build file templates will figure them out. 378 379For each thing to be built, it is then possible to say what sources 380they are built from: 381 382 PROGRAMS=foo bar 383 SOURCE[foo]=foo.c common.c 384 SOURCE[bar]=bar.c extra.c common.c 385 386It's also possible to tell some other dependencies: 387 388 DEPEND[foo]=libsomething 389 DEPEND[libbar]=libsomethingelse 390 391(it could be argued that 'libsomething' and 'libsomethingelse' are 392source as well. However, the files given through SOURCE are expected 393to be located in the source tree while files given through DEPEND are 394expected to be located in the build tree) 395 396It's also possible to depend on static libraries explicitly: 397 398 DEPEND[foo]=libsomething.a 399 DEPEND[libbar]=libsomethingelse.a 400 401This should be rarely used, and care should be taken to make sure it's 402only used when supported. For example, native Windows build doesn't 403support building static libraries and DLLs at the same time, so using 404static libraries on Windows can only be done when configured 405`no-shared`. 406 407In some cases, it's desirable to include some source files in the 408shared form of a library only: 409 410 SHARED_SOURCE[libfoo]=dllmain.c 411 412For any file to be built, it's also possible to tell what extra 413include paths the build of their source files should use: 414 415 INCLUDE[foo]=include 416 417It's also possible to specify C macros that should be defined: 418 419 DEFINE[foo]=FOO BAR=1 420 421In some cases, one might want to generate some source files from 422others, that's done as follows: 423 424 GENERATE[foo.s]=asm/something.pl $(CFLAGS) 425 GENERATE[bar.s]=asm/bar.S 426 427The value of each GENERATE line is a command line or part of it. 428Configure places no rules on the command line, except that the first 429item must be the generator file. It is, however, entirely up to the 430build file template to define exactly how those command lines should 431be handled, how the output is captured and so on. 432 433Sometimes, the generator file itself depends on other files, for 434example if it is a perl script that depends on other perl modules. 435This can be expressed using DEPEND like this: 436 437 DEPEND[asm/something.pl]=../perlasm/Foo.pm 438 439There may also be cases where the exact file isn't easily specified, 440but an inclusion directory still needs to be specified. INCLUDE can 441be used in that case: 442 443 INCLUDE[asm/something.pl]=../perlasm 444 445NOTE: GENERATE lines are limited to one command only per GENERATE. 446 447Finally, you can have some simple conditional use of the `build.info` 448information, looking like this: 449 450 IF[1] 451 something 452 ELSIF[2] 453 something other 454 ELSE 455 something else 456 ENDIF 457 458The expression in square brackets is interpreted as a string in perl, 459and will be seen as true if perl thinks it is, otherwise false. For 460example, the above would have "something" used, since 1 is true. 461 462Together with the use of Text::Template, this can be used as 463conditions based on something in the passed variables, for example: 464 465 IF[{- $disabled{shared} -}] 466 LIBS=libcrypto 467 SOURCE[libcrypto]=... 468 ELSE 469 LIBS=libfoo 470 SOURCE[libfoo]=... 471 ENDIF 472 473Build-file programming with the "unified" build system 474====================================================== 475 476"Build files" are called `Makefile` on Unix-like operating systems, 477`descrip.mms` for MMS on VMS, `makefile` for `nmake` on Windows, etc. 478 479To use the "unified" build system, the target configuration needs to 480set the three items `build_scheme`, `build_file` and `build_command`. 481In the rest of this section, we will assume that `build_scheme` is set 482to "unified" (see the configurations documentation above for the 483details). 484 485For any name given by `build_file`, the "unified" system expects a 486template file in `Configurations/` named like the build file, with 487`.tmpl` appended, or in case of possible ambiguity, a combination of 488the second `build_scheme` list item and the `build_file` name. For 489example, if `build_file` is set to `Makefile`, the template could be 490`Configurations/Makefile.tmpl` or `Configurations/unix-Makefile.tmpl`. 491In case both `Configurations/unix-Makefile.tmpl` and 492`Configurations/Makefile.tmpl` are present, the former takes precedence. 493 494The build-file template is processed with the perl module 495Text::Template, using `{-` and `-}` as delimiters that enclose the 496perl code fragments that generate configuration-dependent content. 497Those perl fragments have access to all the hash variables from 498configdata.pem. 499 500The build-file template is expected to define at least the following 501perl functions in a perl code fragment enclosed with `{-` and `-}`. 502They are all expected to return a string with the lines they produce. 503 504 generatesrc - function that produces build file lines to generate 505 a source file from some input. 506 507 It's called like this: 508 509 generatesrc(src => "PATH/TO/tobegenerated", 510 generator => [ "generatingfile", ... ] 511 generator_incs => [ "INCL/PATH", ... ] 512 generator_deps => [ "dep1", ... ] 513 generator => [ "generatingfile", ... ] 514 incs => [ "INCL/PATH", ... ], 515 deps => [ "dep1", ... ], 516 intent => one of "libs", "dso", "bin" ); 517 518 'src' has the name of the file to be generated. 519 'generator' is the command or part of command to 520 generate the file, of which the first item is 521 expected to be the file to generate from. 522 generatesrc() is expected to analyse and figure out 523 exactly how to apply that file and how to capture 524 the result. 'generator_incs' and 'generator_deps' 525 are include directories and files that the generator 526 file itself depends on. 'incs' and 'deps' are 527 include directories and files that are used if $(CC) 528 is used as an intermediary step when generating the 529 end product (the file indicated by 'src'). 'intent' 530 indicates what the generated file is going to be 531 used for. 532 533 src2obj - function that produces build file lines to build an 534 object file from source files and associated data. 535 536 It's called like this: 537 538 src2obj(obj => "PATH/TO/objectfile", 539 srcs => [ "PATH/TO/sourcefile", ... ], 540 deps => [ "dep1", ... ], 541 incs => [ "INCL/PATH", ... ] 542 intent => one of "lib", "dso", "bin" ); 543 544 'obj' has the intended object file with '.o' 545 extension, src2obj() is expected to change it to 546 something more suitable for the platform. 547 'srcs' has the list of source files to build the 548 object file, with the first item being the source 549 file that directly corresponds to the object file. 550 'deps' is a list of explicit dependencies. 'incs' 551 is a list of include file directories. Finally, 552 'intent' indicates what this object file is going 553 to be used for. 554 555 obj2lib - function that produces build file lines to build a 556 static library file ("libfoo.a" in Unix terms) from 557 object files. 558 559 called like this: 560 561 obj2lib(lib => "PATH/TO/libfile", 562 objs => [ "PATH/TO/objectfile", ... ]); 563 564 'lib' has the intended library file name *without* 565 extension, obj2lib is expected to add that. 'objs' 566 has the list of object files to build this library. 567 568 libobj2shlib - backward compatibility function that's used the 569 same way as obj2shlib (described next), and was 570 expected to build the shared library from the 571 corresponding static library when that was suitable. 572 NOTE: building a shared library from a static 573 library is now DEPRECATED, as they no longer share 574 object files. Attempting to do this will fail. 575 576 obj2shlib - function that produces build file lines to build a 577 shareable object library file ("libfoo.so" in Unix 578 terms) from the corresponding object files. 579 580 called like this: 581 582 obj2shlib(shlib => "PATH/TO/shlibfile", 583 lib => "PATH/TO/libfile", 584 objs => [ "PATH/TO/objectfile", ... ], 585 deps => [ "PATH/TO/otherlibfile", ... ]); 586 587 'lib' has the base (static) library ffile name 588 *without* extension. This is useful in case 589 supporting files are needed (such as import 590 libraries on Windows). 591 'shlib' has the corresponding shared library name 592 *without* extension. 'deps' has the list of other 593 libraries (also *without* extension) this library 594 needs to be linked with. 'objs' has the list of 595 object files to build this library. 596 597 obj2dso - function that produces build file lines to build a 598 dynamic shared object file from object files. 599 600 called like this: 601 602 obj2dso(lib => "PATH/TO/libfile", 603 objs => [ "PATH/TO/objectfile", ... ], 604 deps => [ "PATH/TO/otherlibfile", 605 ... ]); 606 607 This is almost the same as obj2shlib, but the 608 intent is to build a shareable library that can be 609 loaded in runtime (a "plugin"...). 610 611 obj2bin - function that produces build file lines to build an 612 executable file from object files. 613 614 called like this: 615 616 obj2bin(bin => "PATH/TO/binfile", 617 objs => [ "PATH/TO/objectfile", ... ], 618 deps => [ "PATH/TO/libfile", ... ]); 619 620 'bin' has the intended executable file name 621 *without* extension, obj2bin is expected to add 622 that. 'objs' has the list of object files to build 623 this library. 'deps' has the list of library files 624 (also *without* extension) that the programs needs 625 to be linked with. 626 627 in2script - function that produces build file lines to build a 628 script file from some input. 629 630 called like this: 631 632 in2script(script => "PATH/TO/scriptfile", 633 sources => [ "PATH/TO/infile", ... ]); 634 635 'script' has the intended script file name. 636 'sources' has the list of source files to build the 637 resulting script from. 638 639In all cases, file file paths are relative to the build tree top, and 640the build file actions run with the build tree top as current working 641directory. 642 643Make sure to end the section with these functions with a string that 644you thing is appropriate for the resulting build file. If nothing 645else, end it like this: 646 647 ""; # Make sure no lingering values end up in the Makefile 648 -} 649 650Configure helper scripts 651======================== 652 653Configure uses helper scripts in this directory: 654 655Checker scripts 656--------------- 657 658These scripts are per platform family, to check the integrity of the 659tools used for configuration and building. The checker script used is 660either `{build_platform}-{build_file}-checker.pm` or 661`{build_platform}-checker.pm`, where `{build_platform}` is the second 662`build_scheme` list element from the configuration target data, and 663`{build_file}` is `build_file` from the same target data. 664 665If the check succeeds, the script is expected to end with a non-zero 666expression. If the check fails, the script can end with a zero, or 667with a `die`. 668