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 apps_extra_src => Extra source to build apps/openssl, as
167 needed by the target.
168 cpuid_asm_src => assembler implementation of cpuid code as
169 well as OPENSSL_cleanse().
171 bn_asm_src => Assembler implementation of core bignum
174 ec_asm_src => Assembler implementation of core EC
176 des_asm_src => Assembler implementation of core DES
177 encryption functions.
178 Defaults to 'des_enc.c fcrypt_b.c'
179 aes_asm_src => Assembler implementation of core AES
181 Defaults to 'aes_core.c aes_cbc.c'
182 bf_asm_src => Assembler implementation of core BlowFish
184 Defaults to 'bf_enc.c'
185 md5_asm_src => Assembler implementation of core MD5
187 sha1_asm_src => Assembler implementation of core SHA1,
188 functions, and also possibly SHA256 and
190 cast_asm_src => Assembler implementation of core CAST
192 Defaults to 'c_enc.c'
193 rc4_asm_src => Assembler implementation of core RC4
195 Defaults to 'rc4_enc.c rc4_skey.c'
196 rmd160_asm_src => Assembler implementation of core RMD160
198 rc5_asm_src => Assembler implementation of core RC5
200 Defaults to 'rc5_enc.c'
201 wp_asm_src => Assembler implementation of core WHIRLPOOL
203 cmll_asm_src => Assembler implementation of core CAMELLIA
205 Defaults to 'camellia.c cmll_misc.c cmll_cbc.c'
206 modes_asm_src => Assembler implementation of cipher modes,
207 currently the functions gcm_gmult_4bit and
209 padlock_asm_src => Assembler implementation of core parts of
210 the padlock engine. This is mandatory on
211 any platform where the padlock engine might
215 [1] as part of the target configuration, one can have a key called
216 'inherit_from' that indicate what other configurations to inherit
217 data from. These are resolved recursively.
219 Inheritance works as a set of default values that can be overriden
220 by corresponding key values in the inheriting configuration.
222 Note 1: any configuration table can be used as a template.
223 Note 2: pure templates have the attribute 'template => 1' and
224 cannot be used as build targets.
226 If several configurations are given in the 'inherit_from' array,
227 the values of same attribute are concatenated with space
228 separation. With this, it's possible to have several smaller
229 templates for different configuration aspects that can be combined
230 into a complete configuration.
232 instead of a scalar value or an array, a value can be a code block
233 of the form 'sub { /* your code here */ }'. This code block will
234 be called with the list of inherited values for that key as
235 arguments. In fact, the concatenation of strings is really done
236 by using 'sub { join(" ",@_) }' on the list of inherited values.
244 ignored => "This should not appear in the end result",
253 inherit_from => [ "foo", "bar" ],
254 hehe => sub { join(" ",(@_,"!!!")) },
258 The entry for "laughter" will become as follows after processing:
267 [2] OpenSSL is built with threading capabilities unless the user
268 specifies 'no-threads'. The value of the key 'thread_cflags' may
269 be "(unknown)", in which case the user MUST give some compilation
272 [3] OpenSSL has three types of things to link from object files or
275 - shared libraries; that would be libcrypto and libssl.
276 - shared objects (sometimes called dynamic libraries); that would
278 - applications; those are apps/openssl and all the test apps.
280 Very roughly speaking, linking is done like this (words in braces
281 represent the configuration settings documented at the beginning
285 {ld} $(CFLAGS) {shared_ldflag} -shared -o libfoo.so \
286 -Wl,--whole-archive libfoo.a -Wl,--no-whole-archive \
287 {plib_lflags} -lcrypto {ex_libs}
290 {ld} $(CFLAGS) {shared_ldflag} -shared -o libeng.so \
291 blah1.o blah2.o {plib_lflags} -lcrypto {ex_libs}
294 {ld} $(CFLAGS) {lflags} -o app \
295 app1.o utils.o {plib_lflags} -lssl -lcrypto {ex_libs}
298 Historically, the target configurations came in form of a string with
299 values separated by colons. This use is deprecated. The string form
302 "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}"
308 The build.info files that are spread over the source tree contain the
309 minimum information needed to build and distribute OpenSSL. It uses a
310 simple and yet fairly powerful language to determine what needs to be
311 built, from what sources, and other relationships between files.
313 For every build.info file, all file references are relative to the
314 directory of the build.info file for source files, and the
315 corresponding build directory for built files if the build tree
316 differs from the source tree.
318 When processed, every line is processed with the perl module
319 Text::Template, using the delimiters "{-" and "-}". The hashes
320 %config and %target are passed to the perl fragments, along with
321 $sourcedir and $builddir, which are the locations of the source
322 directory for the current build.info file and the corresponding build
323 directory, all relative to the top of the build tree.
325 To begin with, things to be built are declared by setting specific
334 Note that the files mentioned for PROGRAMS, LIBS and ENGINES *must* be
335 without extensions. The build file templates will figure them out.
337 For each thing to be built, it is then possible to say what sources
341 SOURCE[foo]=foo.c common.c
342 SOURCE[bar]=bar.c extra.c common.c
344 It's also possible to tell some other dependencies:
346 DEPEND[foo]=libsomething
347 DEPEND[libbar]=libsomethingelse
349 (it could be argued that 'libsomething' and 'libsomethingelse' are
350 source as well. However, the files given through SOURCE are expected
351 to be located in the source tree while files given through DEPEND are
352 expected to be located in the build tree)
354 For some libraries, we maintain files with public symbols and their
355 slot in a transfer vector (important on some platforms). It can be
358 ORDINALS[libcrypto]=crypto
360 The value is not the name of the file in question, but rather the
361 argument to util/mkdef.pl that indicates which file to use.
363 One some platforms, shared libraries come with a name that's different
364 from their static counterpart. That's declared as follows:
366 SHARED_NAME[libfoo]=cygfoo-{- $config{shlibver} -}
368 The example is from Cygwin, which has a required naming convention.
370 Sometimes, it makes sense to rename an output file, for example a
373 RENAME[libfoo]=libbar
375 That lines has "libfoo" get renamed to "libbar". While it makes no
376 sense at all to just have a rename like that (why not just use
377 "libbar" everywhere?), it does make sense when it can be used
378 conditionally. See a little further below for an example.
380 For any file to be built, it's also possible to tell what extra
381 include paths the build of their source files should use:
385 It's possible to have raw build file lines, between BEGINRAW and
386 ENDRAW lines as follows:
388 BEGINRAW[Makefile(unix)]
389 haha.h: {- $builddir -}/Makefile
390 echo "/* haha */" > haha.h
391 ENDRAW[Makefile(unix)]
393 The word withing square brackets is the build_file configuration item
394 or the build_file configuration item followed by the second word in the
395 build_scheme configuration item for the configured target within
396 parenthesis as shown above. For example, with the following relevant
399 build_file => "build.ninja"
400 build_scheme => [ "unified", "unix" ]
402 ... these lines will be considered:
404 BEGINRAW[build.ninja]
405 build haha.h: echo "/* haha */" > haha.h
408 BEGINRAW[build.ninja(unix)]
409 build hoho.h: echo "/* hoho */" > hoho.h
410 ENDRAW[build.ninja(unix)]
412 See the documentation further up for more information on configuration
415 Finally, you can have some simple conditional use of the build.info
416 information, looking like this:
426 The expression in square brackets is interpreted as a string in perl,
427 and will be seen as true if perl thinks it is, otherwise false. For
428 example, the above would have "something" used, since 1 is true.
430 Together with the use of Text::Template, this can be used as
431 conditions based on something in the passed variables, for example:
433 IF[{- $config{no_shared} -}]
435 SOURCE[libcrypto]=...
443 # VMS has a cultural standard where all libraries are prefixed.
444 # For OpenSSL, the choice is 'ossl_'
445 IF[{- $config{target} =~ /^vms/ -}]
446 RENAME[libcrypto]=ossl_libcrypto
447 RENAME[libssl]=ossl_libssl
451 Build-file programming with the "unified" build system
452 ======================================================
454 "Build files" are called "Makefile" on Unix-like operating systems,
455 "descrip.mms" for MMS on VMS, "makefile" for nmake on Windows, etc.
457 To use the "unified" build system, the target configuration needs to
458 set the three items 'build_scheme', 'build_file' and 'build_command'.
459 In the rest of this section, we will assume that 'build_scheme' is set
460 to "unified" (see the configurations documentation above for the
463 For any name given by 'build_file', the "unified" system expects a
464 template file in Configurations/ named like the build file, with
465 ".tmpl" appended, or in case of possible ambiguity, a combination of
466 the second 'build_scheme' list item and the 'build_file' name. For
467 example, if 'build_file' is set to "Makefile", the template could be
468 Configurations/Makefile.tmpl or Configurations/unix-Makefile.tmpl.
469 In case both Configurations/unix-Makefile.tmpl and
470 Configurations/Makefile.tmpl are present, the former takes
473 The build-file template is processed with the perl module
474 Text::Template, using "{-" and "-}" as delimiters that enclose the
475 perl code fragments that generate configuration-dependent content.
476 Those perl fragments have access to all the hash variables from
479 The build-file template is expected to define at least the following
480 perl functions in a perl code fragment enclosed with "{-" and "-}".
481 They are all expected to return a string with the lines they produce.
483 src2dep - function that produces build file lines to get the
484 dependencies for an object file into a dependency
487 It's called like this:
489 src2dep(obj => "PATH/TO/objectfile",
490 srcs => [ "PATH/TO/sourcefile", ... ],
491 deps => [ "dep1", ... ],
492 incs => [ "INCL/PATH", ... ]);
494 'obj' has the dependent object file as well as
495 object file the dependencies are for; it's *without*
496 extension, src2dep() is expected to add that.
497 'srcs' has the list of source files to build the
498 object file, with the first item being the source
499 file that directly corresponds to the object file.
500 'deps' is a list of explicit dependencies. 'incs'
501 is a list of include file directories.
503 src2obj - function that produces build file lines to build an
504 object file from source files and associated data.
506 It's called like this:
508 src2obj(obj => "PATH/TO/objectfile",
509 srcs => [ "PATH/TO/sourcefile", ... ],
510 deps => [ "dep1", ... ],
511 incs => [ "INCL/PATH", ... ]);
513 'obj' has the intended object file *without*
514 extension, src2obj() is expected to add that.
515 'srcs' has the list of source files to build the
516 object file, with the first item being the source
517 file that directly corresponds to the object file.
518 'deps' is a list of explicit dependencies. 'incs'
519 is a list of include file directories.
521 obj2lib - function that produces build file lines to build a
522 static library file ("libfoo.a" in Unix terms) from
527 obj2lib(lib => "PATH/TO/libfile",
528 objs => [ "PATH/TO/objectfile", ... ]);
530 'lib' has the intended library file name *without*
531 extension, obj2lib is expected to add that. 'objs'
532 has the list of object files (also *without*
533 extension) to build this library.
535 libobj2shlib - function that produces build file lines to build a
536 shareable object library file ("libfoo.so" in Unix
537 terms) from the corresponding static library file
542 libobj2shlib(shlib => "PATH/TO/shlibfile",
543 lib => "PATH/TO/libfile",
544 objs => [ "PATH/TO/objectfile", ... ],
545 deps => [ "PATH/TO/otherlibfile", ... ],
546 ordinals => [ "word", "/PATH/TO/ordfile" ]);
548 'lib' has the intended library file name *without*
549 extension, libobj2shlib is expected to add that.
550 'shlib' has the correcponding shared library name
551 *without* extension. 'deps' has the list of other
552 libraries (also *without* extension) this library
553 needs to be linked with. 'objs' has the list of
554 object files (also *without* extension) to build
555 this library. 'ordinals' MAY be present, and when
556 it is, its value is an array where the word is
557 "crypto" or "ssl" and the file is one of the ordinal
558 files util/libeay.num or util/ssleay.num in the
561 This function has a choice; it can use the
562 corresponding static library as input to make the
563 shared library, or the list of object files.
565 obj2dynlib - function that produces build file lines to build a
566 dynamically loadable library file ("libfoo.so" on
567 Unix) from object files.
571 obj2dynlib(lib => "PATH/TO/libfile",
572 objs => [ "PATH/TO/objectfile", ... ],
573 deps => [ "PATH/TO/otherlibfile",
576 This is almost the same as libobj2shlib, but the
577 intent is to build a shareable library that can be
578 loaded in runtime (a "plugin"...). The differences
579 are subtle, one of the most visible ones is that the
580 resulting shareable library is produced from object
583 obj2bin - function that produces build file lines to build an
584 executable file from object files.
588 obj2bin(bin => "PATH/TO/binfile",
589 objs => [ "PATH/TO/objectfile", ... ],
590 deps => [ "PATH/TO/libfile", ... ]);
592 'bin' has the intended executable file name
593 *without* extension, obj2bin is expected to add
594 that. 'objs' has the list of object files (also
595 *without* extension) to build this library. 'deps'
596 has the list of library files (also *without*
597 extension) that the programs needs to be linked
600 in2script - function that produces build file lines to build a
601 script file from some input.
605 in2script(script => "PATH/TO/scriptfile",
606 sources => [ "PATH/TO/infile", ... ]);
608 'script' has the intended script file name.
609 'sources' has the list of source files to build the
610 resulting script from.
612 In all cases, file file paths are relative to the build tree top, and
613 the build file actions run with the build tree top as current working
616 Make sure to end the section with these functions with a string that
617 you thing is apropriate for the resulting build file. If nothing
618 else, end it like this:
620 ""; # Make sure no lingering values end up in the Makefile