1 Configurations of OpenSSL target platforms
2 ==========================================
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.
8 In each table entry, the following keys are significant:
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]
17 sys_id => System identity for systems where that
18 is difficult to determine automatically.
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
26 defines => As an alternative, macro definitions may be
27 present here instead of in `cflags'. If
28 given here, they MUST be as an array of the
29 string such as "MACRO=value", or just
30 "MACRO" for definitions without value.
31 debug_cflags => Extra compilation flags used when making a
32 debug build (when Configure receives the
33 --debug option). Typically something like
35 debug_defines => Similarly to `debug_cflags', this gets
36 combined with `defines' during a debug
37 build. The value here MUST also be an
38 array of the same form as for `defines'.
39 release_cflags => Extra compilation flags used when making a
40 release build (when Configure receives the
41 --release option, or doesn't receive the
42 --debug option). Typically something like
44 release_defines => Similarly to `release_cflags', this gets
45 combined with `defines' during a release
46 build. The value here MUST also be an
47 array of the same form as for `defines'.
48 thread_cflags => Extra compilation flags used when
49 compiling with threading enabled.
50 Explained further below. [2]
51 thread_defines => Similarly to `thread_cflags', this gets
52 combined with `defines' when threading is
53 enabled. The value here MUST also be an
54 array of the same form as for `defines'.
55 shared_cflag => Extra compilation flags used when
56 compiling for shared libraries, typically
57 something like "-fPIC".
59 (linking is a complex thing, see [3] below)
60 ld => Linker command, usually not defined
61 (meaning the compiler command is used
63 (NOTE: this is here for future use, it's
65 lflags => Flags that are used when linking apps.
66 shared_ldflag => Flags that are used when linking shared
68 plib_lflags => Extra linking flags to appear just before
69 the libraries on the command line.
70 ex_libs => Extra libraries that are needed when
73 debug_lflags => Like debug_cflags, but used when linking.
74 release_lflags => Like release_cflags, but used when linking.
76 ar => The library archive command, the default is
78 (NOTE: this is here for future use, it's
80 arflags => Flags to be used with the library archive
83 ranlib => The library archive indexing command, the
84 default is 'ranlib' it it exists.
86 unistd => An alternative header to the typical
87 '<unistd.h>'. This is very rarely needed.
89 shared_extension => File name extension used for shared
91 obj_extension => File name extension used for object files.
92 On unix, this defaults to ".o" (NOTE: this
93 is here for future use, it's not
95 exe_extension => File name extension used for executable
96 files. On unix, this defaults to "" (NOTE:
97 this is here for future use, it's not
100 dso_scheme => The type of dynamic shared objects to build
101 for. This mostly comes into play with
102 engines, but can be used for other purposes
103 as well. Valid values are "DLFCN"
104 (dlopen() et al), "DLFCN_NO_H" (for systems
105 that use dlopen() et al but do not have
106 fcntl.h), "DL" (shl_load() et al), "WIN32"
108 perlasm_scheme => The perlasm method used to created the
109 assembler files used when compiling with
110 assembler implementations.
111 shared_target => The shared library building method used.
112 This is a target found in Makefile.shared.
113 build_scheme => The scheme used to build up a Makefile.
114 In its simplest form, the value is a string
115 with the name of the build scheme.
116 The value may also take the form of a list
117 of strings, if the build_scheme is to have
118 some options. In this case, the first
119 string in the list is the name of the build
121 Currently recognised build schemes are
122 "mk1mf" and "unixmake" and "unified".
123 For the "unified" build scheme, this item
124 *must* be an array with the first being the
125 word "unified" and the second being a word
126 to identify the platform family.
128 multilib => On systems that support having multiple
129 implementations of a library (typically a
130 32-bit and a 64-bit variant), this is used
131 to have the different variants in different
134 bn_ops => Building options (was just bignum options
135 in the earlier history of this option,
136 hence the name). This a string of words
137 that describe properties on the designated
138 target platform, such as the type of
139 integers used to build up the bitnum,
140 different ways to implement certain ciphers
141 and so on. To fully comprehend the
142 meaning, the best is to read the affected
146 BN_LLONG use 'unsigned long long' in
147 some bignum calculations.
148 This has no value when
150 SIXTY_FOUR_BIT_LONG is given.
151 RC4_CHAR makes the basic RC4 unit of
152 calculation an unsigned char.
153 SIXTY_FOUR_BIT processor registers
155 32 bits, long long is
157 SIXTY_FOUR_BIT_LONG processor registers
160 THIRTY_TWO_BIT processor registers
162 EXPORT_VAR_AS_FN for shared libraries,
166 cpuid_asm_src => assembler implementation of cpuid code as
167 well as OPENSSL_cleanse().
169 bn_asm_src => Assembler implementation of core bignum
172 ec_asm_src => Assembler implementation of core EC
174 des_asm_src => Assembler implementation of core DES
175 encryption functions.
176 Defaults to 'des_enc.c fcrypt_b.c'
177 aes_asm_src => Assembler implementation of core AES
179 Defaults to 'aes_core.c aes_cbc.c'
180 bf_asm_src => Assembler implementation of core BlowFish
182 Defaults to 'bf_enc.c'
183 md5_asm_src => Assembler implementation of core MD5
185 sha1_asm_src => Assembler implementation of core SHA1,
186 functions, and also possibly SHA256 and
188 cast_asm_src => Assembler implementation of core CAST
190 Defaults to 'c_enc.c'
191 rc4_asm_src => Assembler implementation of core RC4
193 Defaults to 'rc4_enc.c rc4_skey.c'
194 rmd160_asm_src => Assembler implementation of core RMD160
196 rc5_asm_src => Assembler implementation of core RC5
198 Defaults to 'rc5_enc.c'
199 wp_asm_src => Assembler implementation of core WHIRLPOOL
201 cmll_asm_src => Assembler implementation of core CAMELLIA
203 Defaults to 'camellia.c cmll_misc.c cmll_cbc.c'
204 modes_asm_src => Assembler implementation of cipher modes,
205 currently the functions gcm_gmult_4bit and
207 padlock_asm_src => Assembler implementation of core parts of
208 the padlock engine. This is mandatory on
209 any platform where the padlock engine might
213 [1] as part of the target configuration, one can have a key called
214 'inherit_from' that indicate what other configurations to inherit
215 data from. These are resolved recursively.
217 Inheritance works as a set of default values that can be overriden
218 by corresponding key values in the inheriting configuration.
220 Note 1: any configuration table can be used as a template.
221 Note 2: pure templates have the attribute 'template => 1' and
222 cannot be used as build targets.
224 If several configurations are given in the 'inherit_from' array,
225 the values of same attribute are concatenated with space
226 separation. With this, it's possible to have several smaller
227 templates for different configuration aspects that can be combined
228 into a complete configuration.
230 instead of a scalar value or an array, a value can be a code block
231 of the form 'sub { /* your code here */ }'. This code block will
232 be called with the list of inherited values for that key as
233 arguments. In fact, the concatenation of strings is really done
234 by using 'sub { join(" ",@_) }' on the list of inherited values.
242 ignored => "This should not appear in the end result",
251 inherit_from => [ "foo", "bar" ],
252 hehe => sub { join(" ",(@_,"!!!")) },
256 The entry for "laughter" will become as follows after processing:
265 [2] OpenSSL is built with threading capabilities unless the user
266 specifies 'no-threads'. The value of the key 'thread_cflags' may
267 be "(unknown)", in which case the user MUST give some compilation
270 [3] OpenSSL has three types of things to link from object files or
273 - shared libraries; that would be libcrypto and libssl.
274 - shared objects (sometimes called dynamic libraries); that would
276 - applications; those are apps/openssl and all the test apps.
278 Very roughly speaking, linking is done like this (words in braces
279 represent the configuration settings documented at the beginning
283 {ld} $(CFLAGS) {shared_ldflag} -shared -o libfoo.so \
284 -Wl,--whole-archive libfoo.a -Wl,--no-whole-archive \
285 {plib_lflags} -lcrypto {ex_libs}
288 {ld} $(CFLAGS) {shared_ldflag} -shared -o libeng.so \
289 blah1.o blah2.o {plib_lflags} -lcrypto {ex_libs}
292 {ld} $(CFLAGS) {lflags} -o app \
293 app1.o utils.o {plib_lflags} -lssl -lcrypto {ex_libs}
296 Historically, the target configurations came in form of a string with
297 values separated by colons. This use is deprecated. The string form
300 "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}"
306 The build.info files that are spread over the source tree contain the
307 minimum information needed to build and distribute OpenSSL. It uses a
308 simple and yet fairly powerful language to determine what needs to be
309 built, from what sources, and other relationships between files.
311 For every build.info file, all file references are relative to the
312 directory of the build.info file for source files, and the
313 corresponding build directory for built files if the build tree
314 differs from the source tree.
316 When processed, every line is processed with the perl module
317 Text::Template, using the delimiters "{-" and "-}". The hashes
318 %config and %target are passed to the perl fragments, along with
319 $sourcedir and $builddir, which are the locations of the source
320 directory for the current build.info file and the corresponding build
321 directory, all relative to the top of the build tree.
323 To begin with, things to be built are declared by setting specific
332 Note that the files mentioned for PROGRAMS, LIBS and ENGINES *must* be
333 without extensions. The build file templates will figure them out.
335 For each thing to be built, it is then possible to say what sources
339 SOURCE[foo]=foo.c common.c
340 SOURCE[bar]=bar.c extra.c common.c
342 It's also possible to tell some other dependencies:
344 DEPEND[foo]=libsomething
345 DEPEND[libbar]=libsomethingelse
347 (it could be argued that 'libsomething' and 'libsomethingelse' are
348 source as well. However, the files given through SOURCE are expected
349 to be located in the source tree while files given through DEPEND are
350 expected to be located in the build tree)
352 For some libraries, we maintain files with public symbols and their
353 slot in a transfer vector (important on some platforms). It can be
356 ORDINALS[libcrypto]=crypto
358 The value is not the name of the file in question, but rather the
359 argument to util/mkdef.pl that indicates which file to use.
361 One some platforms, shared libraries come with a name that's different
362 from their static counterpart. That's declared as follows:
364 SHARED_NAME[libfoo]=cygfoo-{- $config{shlibver} -}
366 The example is from Cygwin, which has a required naming convention.
368 Sometimes, it makes sense to rename an output file, for example a
371 RENAME[libfoo]=libbar
373 That lines has "libfoo" get renamed to "libbar". While it makes no
374 sense at all to just have a rename like that (why not just use
375 "libbar" everywhere?), it does make sense when it can be used
376 conditionally. See a little further below for an example.
378 For any file to be built, it's also possible to tell what extra
379 include paths the build of their source files should use:
383 It's possible to have raw build file lines, between BEGINRAW and
384 ENDRAW lines as follows:
386 BEGINRAW[Makefile(unix)]
387 haha.h: {- $builddir -}/Makefile
388 echo "/* haha */" > haha.h
389 ENDRAW[Makefile(unix)]
391 The word withing square brackets is the build_file configuration item
392 or the build_file configuration item followed by the second word in the
393 build_scheme configuration item for the configured target within
394 parenthesis as shown above. For example, with the following relevant
397 build_file => "build.ninja"
398 build_scheme => [ "unified", "unix" ]
400 ... these lines will be considered:
402 BEGINRAW[build.ninja]
403 build haha.h: echo "/* haha */" > haha.h
406 BEGINRAW[build.ninja(unix)]
407 build hoho.h: echo "/* hoho */" > hoho.h
408 ENDRAW[build.ninja(unix)]
410 See the documentation further up for more information on configuration
413 Finally, you can have some simple conditional use of the build.info
414 information, looking like this:
424 The expression in square brackets is interpreted as a string in perl,
425 and will be seen as true if perl thinks it is, otherwise false. For
426 example, the above would have "something" used, since 1 is true.
428 Together with the use of Text::Template, this can be used as
429 conditions based on something in the passed variables, for example:
431 IF[{- $config{no_shared} -}]
433 SOURCE[libcrypto]=...
441 # VMS has a cultural standard where all libraries are prefixed.
442 # For OpenSSL, the choice is 'ossl_'
443 IF[{- $config{target} =~ /^vms/ -}]
444 RENAME[libcrypto]=ossl_libcrypto
445 RENAME[libssl]=ossl_libssl
449 Build-file programming with the "unified" build system
450 ======================================================
452 "Build files" are called "Makefile" on Unix-like operating systems,
453 "descrip.mms" for MMS on VMS, "makefile" for nmake on Windows, etc.
455 To use the "unified" build system, the target configuration needs to
456 set the three items 'build_scheme', 'build_file' and 'build_command'.
457 In the rest of this section, we will assume that 'build_scheme' is set
458 to "unified" (see the configurations documentation above for the
461 For any name given by 'build_file', the "unified" system expects a
462 template file in Configurations/ named like the build file, with
463 ".tmpl" appended, or in case of possible ambiguity, a combination of
464 the second 'build_scheme' list item and the 'build_file' name. For
465 example, if 'build_file' is set to "Makefile", the template could be
466 Configurations/Makefile.tmpl or Configurations/unix-Makefile.tmpl.
467 In case both Configurations/unix-Makefile.tmpl and
468 Configurations/Makefile.tmpl are present, the former takes
471 The build-file template is processed with the perl module
472 Text::Template, using "{-" and "-}" as delimiters that enclose the
473 perl code fragments that generate configuration-dependent content.
474 Those perl fragments have access to all the hash variables from
477 The build-file template is expected to define at least the following
478 perl functions in a perl code fragment enclosed with "{-" and "-}".
479 They are all expected to return a string with the lines they produce.
481 src2dep - function that produces build file lines to get the
482 dependencies for an object file into a dependency
485 It's called like this:
487 src2dep(obj => "PATH/TO/objectfile",
488 srcs => [ "PATH/TO/sourcefile", ... ],
489 incs => [ "INCL/PATH", ... ]);
491 'obj' has the dependent object file as well as
492 object file the dependencies are for; it's *without*
493 extension, src2dep() is expected to add that.
494 'srcs' has the list of source files to build the
495 object file, with the first item being the source
496 file that directly corresponds to the object file.
497 'incs' is a list of include file directories.
499 src2obj - function that produces build file lines to build an
500 object file from source files and associated data.
502 It's called like this:
504 src2obj(obj => "PATH/TO/objectfile",
505 srcs => [ "PATH/TO/sourcefile", ... ],
506 deps => [ "dep1", ... ],
507 incs => [ "INCL/PATH", ... ]);
509 'obj' has the intended object file *without*
510 extension, src2obj() is expected to add that.
511 'srcs' has the list of source files to build the
512 object file, with the first item being the source
513 file that directly corresponds to the object file.
514 'deps' is a list of dependencies. 'incs' is a list
515 of include file directories.
517 obj2lib - function that produces build file lines to build a
518 static library file ("libfoo.a" in Unix terms) from
523 obj2lib(lib => "PATH/TO/libfile",
524 objs => [ "PATH/TO/objectfile", ... ]);
526 'lib' has the intended library file name *without*
527 extension, obj2lib is expected to add that. 'objs'
528 has the list of object files (also *without*
529 extension) to build this library.
531 libobj2shlib - function that produces build file lines to build a
532 shareable object library file ("libfoo.so" in Unix
533 terms) from the corresponding static library file
538 libobj2shlib(shlib => "PATH/TO/shlibfile",
539 lib => "PATH/TO/libfile",
540 objs => [ "PATH/TO/objectfile", ... ],
541 deps => [ "PATH/TO/otherlibfile", ... ],
542 ordinals => [ "word", "/PATH/TO/ordfile" ]);
544 'lib' has the intended library file name *without*
545 extension, libobj2shlib is expected to add that.
546 'shlib' has the correcponding shared library name
547 *without* extension. 'deps' has the list of other
548 libraries (also *without* extension) this library
549 needs to be linked with. 'objs' has the list of
550 object files (also *without* extension) to build
551 this library. 'ordinals' MAY be present, and when
552 it is, its value is an array where the word is
553 "crypto" or "ssl" and the file is one of the ordinal
554 files util/libeay.num or util/ssleay.num in the
557 This function has a choice; it can use the
558 corresponding static library as input to make the
559 shared library, or the list of object files.
561 obj2dynlib - function that produces build file lines to build a
562 dynamically loadable library file ("libfoo.so" on
563 Unix) from object files.
567 obj2dynlib(lib => "PATH/TO/libfile",
568 objs => [ "PATH/TO/objectfile", ... ],
569 deps => [ "PATH/TO/otherlibfile",
572 This is almost the same as libobj2shlib, but the
573 intent is to build a shareable library that can be
574 loaded in runtime (a "plugin"...). The differences
575 are subtle, one of the most visible ones is that the
576 resulting shareable library is produced from object
579 obj2bin - function that produces build file lines to build an
580 executable file from object files.
584 obj2bin(bin => "PATH/TO/binfile",
585 objs => [ "PATH/TO/objectfile", ... ],
586 deps => [ "PATH/TO/libfile", ... ]);
588 'bin' has the intended executable file name
589 *without* extension, obj2bin is expected to add
590 that. 'objs' has the list of object files (also
591 *without* extension) to build this library. 'deps'
592 has the list of library files (also *without*
593 extension) that the programs needs to be linked
596 in2script - function that produces build file lines to build a
597 script file from some input.
601 in2script(script => "PATH/TO/scriptfile",
602 sources => [ "PATH/TO/infile", ... ]);
604 'script' has the intended script file name.
605 'sources' has the list of source files to build the
606 resulting script from.
608 In all cases, file file paths are relative to the build tree top, and
609 the build file actions run with the build tree top as current working
612 Make sure to end the section with these functions with a string that
613 you thing is apropriate for the resulting build file. If nothing
614 else, end it like this:
616 ""; # Make sure no lingering values end up in the Makefile