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 C 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 cxx => The C++ compiler command, usually one of
25 "c++", "g++" or "clang++". This command is
26 also used when linking a program where at
27 least one of the object file is made from
29 cflags => Flags that are used at all times when
30 compiling C object files.
31 cxxflags => Flags that are used at all times when
32 compiling C++ object files. If unset, it
33 gets the same value as cflags.
34 defines => As an alternative, macro definitions may be
35 present here instead of in `cflags'. If
36 given here, they MUST be as an array of the
37 string such as "MACRO=value", or just
38 "MACRO" for definitions without value.
39 shared_cflag => Extra compilation flags used when
40 compiling for shared libraries, typically
41 something like "-fPIC".
43 (linking is a complex thing, see [3] below)
44 ld => Linker command, usually not defined
45 (meaning the compiler command is used
47 (NOTE: this is here for future use, it's
49 lflags => Flags that are used when linking apps.
50 shared_ldflag => Flags that are used when linking shared
52 plib_lflags => Extra linking flags to appear just before
53 the libraries on the command line.
54 ex_libs => Extra libraries that are needed when
57 ar => The library archive command, the default is
59 (NOTE: this is here for future use, it's
61 arflags => Flags to be used with the library archive
64 ranlib => The library archive indexing command, the
65 default is 'ranlib' it it exists.
67 unistd => An alternative header to the typical
68 '<unistd.h>'. This is very rarely needed.
70 shared_extension => File name extension used for shared
72 obj_extension => File name extension used for object files.
73 On unix, this defaults to ".o" (NOTE: this
74 is here for future use, it's not
76 exe_extension => File name extension used for executable
77 files. On unix, this defaults to "" (NOTE:
78 this is here for future use, it's not
81 thread_scheme => The type of threads is used on the
82 configured platform. Currently known
83 values are "(unknown)", "pthreads",
84 "uithreads" (a.k.a solaris threads) and
85 "winthreads". Except for "(unknown)", the
86 actual value is currently ignored but may
87 be used in the future. See further notes
89 dso_scheme => The type of dynamic shared objects to build
90 for. This mostly comes into play with
91 engines, but can be used for other purposes
92 as well. Valid values are "DLFCN"
93 (dlopen() et al), "DLFCN_NO_H" (for systems
94 that use dlopen() et al but do not have
95 fcntl.h), "DL" (shl_load() et al), "WIN32"
97 perlasm_scheme => The perlasm method used to created the
98 assembler files used when compiling with
99 assembler implementations.
100 shared_target => The shared library building method used.
101 This is a target found in Makefile.shared.
102 build_scheme => The scheme used to build up a Makefile.
103 In its simplest form, the value is a string
104 with the name of the build scheme.
105 The value may also take the form of a list
106 of strings, if the build_scheme is to have
107 some options. In this case, the first
108 string in the list is the name of the build
110 Currently recognised build scheme is "unified".
111 For the "unified" build scheme, this item
112 *must* be an array with the first being the
113 word "unified" and the second being a word
114 to identify the platform family.
116 multilib => On systems that support having multiple
117 implementations of a library (typically a
118 32-bit and a 64-bit variant), this is used
119 to have the different variants in different
122 bn_ops => Building options (was just bignum options
123 in the earlier history of this option,
124 hence the name). This a string of words
125 that describe properties on the designated
126 target platform, such as the type of
127 integers used to build up the bitnum,
128 different ways to implement certain ciphers
129 and so on. To fully comprehend the
130 meaning, the best is to read the affected
134 BN_LLONG use 'unsigned long long' in
135 some bignum calculations.
136 This has no value when
138 SIXTY_FOUR_BIT_LONG is given.
139 RC4_CHAR makes the basic RC4 unit of
140 calculation an unsigned char.
141 SIXTY_FOUR_BIT processor registers
143 32 bits, long long is
145 SIXTY_FOUR_BIT_LONG processor registers
148 THIRTY_TWO_BIT processor registers
150 EXPORT_VAR_AS_FN for shared libraries,
154 apps_extra_src => Extra source to build apps/openssl, as
155 needed by the target.
156 cpuid_asm_src => assembler implementation of cpuid code as
157 well as OPENSSL_cleanse().
159 bn_asm_src => Assembler implementation of core bignum
162 ec_asm_src => Assembler implementation of core EC
164 des_asm_src => Assembler implementation of core DES
165 encryption functions.
166 Defaults to 'des_enc.c fcrypt_b.c'
167 aes_asm_src => Assembler implementation of core AES
169 Defaults to 'aes_core.c aes_cbc.c'
170 bf_asm_src => Assembler implementation of core BlowFish
172 Defaults to 'bf_enc.c'
173 md5_asm_src => Assembler implementation of core MD5
175 sha1_asm_src => Assembler implementation of core SHA1,
176 functions, and also possibly SHA256 and
178 cast_asm_src => Assembler implementation of core CAST
180 Defaults to 'c_enc.c'
181 rc4_asm_src => Assembler implementation of core RC4
183 Defaults to 'rc4_enc.c rc4_skey.c'
184 rmd160_asm_src => Assembler implementation of core RMD160
186 rc5_asm_src => Assembler implementation of core RC5
188 Defaults to 'rc5_enc.c'
189 wp_asm_src => Assembler implementation of core WHIRLPOOL
191 cmll_asm_src => Assembler implementation of core CAMELLIA
193 Defaults to 'camellia.c cmll_misc.c cmll_cbc.c'
194 modes_asm_src => Assembler implementation of cipher modes,
195 currently the functions gcm_gmult_4bit and
197 padlock_asm_src => Assembler implementation of core parts of
198 the padlock engine. This is mandatory on
199 any platform where the padlock engine might
203 [1] as part of the target configuration, one can have a key called
204 'inherit_from' that indicate what other configurations to inherit
205 data from. These are resolved recursively.
207 Inheritance works as a set of default values that can be overridden
208 by corresponding key values in the inheriting configuration.
210 Note 1: any configuration table can be used as a template.
211 Note 2: pure templates have the attribute 'template => 1' and
212 cannot be used as build targets.
214 If several configurations are given in the 'inherit_from' array,
215 the values of same attribute are concatenated with space
216 separation. With this, it's possible to have several smaller
217 templates for different configuration aspects that can be combined
218 into a complete configuration.
220 instead of a scalar value or an array, a value can be a code block
221 of the form 'sub { /* your code here */ }'. This code block will
222 be called with the list of inherited values for that key as
223 arguments. In fact, the concatenation of strings is really done
224 by using 'sub { join(" ",@_) }' on the list of inherited values.
232 ignored => "This should not appear in the end result",
241 inherit_from => [ "foo", "bar" ],
242 hehe => sub { join(" ",(@_,"!!!")) },
246 The entry for "laughter" will become as follows after processing:
255 [2] OpenSSL is built with threading capabilities unless the user
256 specifies 'no-threads'. The value of the key 'thread_scheme' may
257 be "(unknown)", in which case the user MUST give some compilation
260 [3] OpenSSL has three types of things to link from object files or
263 - shared libraries; that would be libcrypto and libssl.
264 - shared objects (sometimes called dynamic libraries); that would
266 - applications; those are apps/openssl and all the test apps.
268 Very roughly speaking, linking is done like this (words in braces
269 represent the configuration settings documented at the beginning
273 {ld} $(CFLAGS) {shared_ldflag} -shared -o libfoo.so \
274 -Wl,--whole-archive libfoo.a -Wl,--no-whole-archive \
275 {plib_lflags} -lcrypto {ex_libs}
278 {ld} $(CFLAGS) {shared_ldflag} -shared -o libeng.so \
279 blah1.o blah2.o {plib_lflags} -lcrypto {ex_libs}
282 {ld} $(CFLAGS) {lflags} -o app \
283 app1.o utils.o {plib_lflags} -lssl -lcrypto {ex_libs}
286 Historically, the target configurations came in form of a string with
287 values separated by colons. This use is deprecated. The string form
290 "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}"
296 The build.info files that are spread over the source tree contain the
297 minimum information needed to build and distribute OpenSSL. It uses a
298 simple and yet fairly powerful language to determine what needs to be
299 built, from what sources, and other relationships between files.
301 For every build.info file, all file references are relative to the
302 directory of the build.info file for source files, and the
303 corresponding build directory for built files if the build tree
304 differs from the source tree.
306 When processed, every line is processed with the perl module
307 Text::Template, using the delimiters "{-" and "-}". The hashes
308 %config and %target are passed to the perl fragments, along with
309 $sourcedir and $builddir, which are the locations of the source
310 directory for the current build.info file and the corresponding build
311 directory, all relative to the top of the build tree.
313 To begin with, things to be built are declared by setting specific
322 Note that the files mentioned for PROGRAMS, LIBS and ENGINES *must* be
323 without extensions. The build file templates will figure them out.
325 For each thing to be built, it is then possible to say what sources
329 SOURCE[foo]=foo.c common.c
330 SOURCE[bar]=bar.c extra.c common.c
332 It's also possible to tell some other dependencies:
334 DEPEND[foo]=libsomething
335 DEPEND[libbar]=libsomethingelse
337 (it could be argued that 'libsomething' and 'libsomethingelse' are
338 source as well. However, the files given through SOURCE are expected
339 to be located in the source tree while files given through DEPEND are
340 expected to be located in the build tree)
342 For some libraries, we maintain files with public symbols and their
343 slot in a transfer vector (important on some platforms). It can be
346 ORDINALS[libcrypto]=crypto
348 The value is not the name of the file in question, but rather the
349 argument to util/mkdef.pl that indicates which file to use.
351 One some platforms, shared libraries come with a name that's different
352 from their static counterpart. That's declared as follows:
354 SHARED_NAME[libfoo]=cygfoo-{- $config{shlibver} -}
356 The example is from Cygwin, which has a required naming convention.
358 Sometimes, it makes sense to rename an output file, for example a
361 RENAME[libfoo]=libbar
363 That lines has "libfoo" get renamed to "libbar". While it makes no
364 sense at all to just have a rename like that (why not just use
365 "libbar" everywhere?), it does make sense when it can be used
366 conditionally. See a little further below for an example.
368 In some cases, it's desirable to include some source files in the
369 shared form of a library only:
371 SHARED_SOURCE[libfoo]=dllmain.c
373 For any file to be built, it's also possible to tell what extra
374 include paths the build of their source files should use:
378 In some cases, one might want to generate some source files from
379 others, that's done as follows:
381 GENERATE[foo.s]=asm/something.pl $(CFLAGS)
382 GENERATE[bar.s]=asm/bar.S
384 The value of each GENERATE line is a command line or part of it.
385 Configure places no rules on the command line, except the the first
386 item muct be the generator file. It is, however, entirely up to the
387 build file template to define exactly how those command lines should
388 be handled, how the output is captured and so on.
390 Sometimes, the generator file itself depends on other files, for
391 example if it is a perl script that depends on other perl modules.
392 This can be expressed using DEPEND like this:
394 DEPEND[asm/something.pl]=../perlasm/Foo.pm
396 There may also be cases where the exact file isn't easily specified,
397 but an inclusion directory still needs to be specified. INCLUDE can
398 be used in that case:
400 INCLUDE[asm/something.pl]=../perlasm
402 NOTE: GENERATE lines are limited to one command only per GENERATE.
404 As a last resort, it's possible to have raw build file lines, between
405 BEGINRAW and ENDRAW lines as follows:
407 BEGINRAW[Makefile(unix)]
408 haha.h: {- $builddir -}/Makefile
409 echo "/* haha */" > haha.h
410 ENDRAW[Makefile(unix)]
412 The word within square brackets is the build_file configuration item
413 or the build_file configuration item followed by the second word in the
414 build_scheme configuration item for the configured target within
415 parenthesis as shown above. For example, with the following relevant
418 build_file => "build.ninja"
419 build_scheme => [ "unified", "unix" ]
421 ... these lines will be considered:
423 BEGINRAW[build.ninja]
424 build haha.h: echo "/* haha */" > haha.h
427 BEGINRAW[build.ninja(unix)]
428 build hoho.h: echo "/* hoho */" > hoho.h
429 ENDRAW[build.ninja(unix)]
431 Should it be needed because the recipes within a RAW section might
432 clash with those generated by Configure, it's possible to tell it
433 not to generate them with the use of OVERRIDES, for example:
435 SOURCE[libfoo]=foo.c bar.c
438 BEGINRAW[Makefile(unix)]
440 $(CC) $(CFLAGS) -DSPECIAL -c -o $@ $<
441 ENDRAW[Makefile(unix)]
443 See the documentation further up for more information on configuration
446 Finally, you can have some simple conditional use of the build.info
447 information, looking like this:
457 The expression in square brackets is interpreted as a string in perl,
458 and will be seen as true if perl thinks it is, otherwise false. For
459 example, the above would have "something" used, since 1 is true.
461 Together with the use of Text::Template, this can be used as
462 conditions based on something in the passed variables, for example:
464 IF[{- $disabled{shared} -}]
466 SOURCE[libcrypto]=...
474 # VMS has a cultural standard where all libraries are prefixed.
475 # For OpenSSL, the choice is 'ossl_'
476 IF[{- $config{target} =~ /^vms/ -}]
477 RENAME[libcrypto]=ossl_libcrypto
478 RENAME[libssl]=ossl_libssl
482 Build-file programming with the "unified" build system
483 ======================================================
485 "Build files" are called "Makefile" on Unix-like operating systems,
486 "descrip.mms" for MMS on VMS, "makefile" for nmake on Windows, etc.
488 To use the "unified" build system, the target configuration needs to
489 set the three items 'build_scheme', 'build_file' and 'build_command'.
490 In the rest of this section, we will assume that 'build_scheme' is set
491 to "unified" (see the configurations documentation above for the
494 For any name given by 'build_file', the "unified" system expects a
495 template file in Configurations/ named like the build file, with
496 ".tmpl" appended, or in case of possible ambiguity, a combination of
497 the second 'build_scheme' list item and the 'build_file' name. For
498 example, if 'build_file' is set to "Makefile", the template could be
499 Configurations/Makefile.tmpl or Configurations/unix-Makefile.tmpl.
500 In case both Configurations/unix-Makefile.tmpl and
501 Configurations/Makefile.tmpl are present, the former takes
504 The build-file template is processed with the perl module
505 Text::Template, using "{-" and "-}" as delimiters that enclose the
506 perl code fragments that generate configuration-dependent content.
507 Those perl fragments have access to all the hash variables from
510 The build-file template is expected to define at least the following
511 perl functions in a perl code fragment enclosed with "{-" and "-}".
512 They are all expected to return a string with the lines they produce.
514 generatesrc - function that produces build file lines to generate
515 a source file from some input.
517 It's called like this:
519 generatesrc(src => "PATH/TO/tobegenerated",
520 generator => [ "generatingfile", ... ]
521 generator_incs => [ "INCL/PATH", ... ]
522 generator_deps => [ "dep1", ... ]
523 generator => [ "generatingfile", ... ]
524 incs => [ "INCL/PATH", ... ],
525 deps => [ "dep1", ... ],
526 intent => one of "libs", "dso", "bin" );
528 'src' has the name of the file to be generated.
529 'generator' is the command or part of command to
530 generate the file, of which the first item is
531 expected to be the file to generate from.
532 generatesrc() is expected to analyse and figure out
533 exactly how to apply that file and how to capture
534 the result. 'generator_incs' and 'generator_deps'
535 are include directories and files that the generator
536 file itself depends on. 'incs' and 'deps' are
537 include directories and files that are used if $(CC)
538 is used as an intermediary step when generating the
539 end product (the file indicated by 'src'). 'intent'
540 indicates what the generated file is going to be
543 src2obj - function that produces build file lines to build an
544 object file from source files and associated data.
546 It's called like this:
548 src2obj(obj => "PATH/TO/objectfile",
549 srcs => [ "PATH/TO/sourcefile", ... ],
550 deps => [ "dep1", ... ],
551 incs => [ "INCL/PATH", ... ]
552 intent => one of "lib", "dso", "bin" );
554 'obj' has the intended object file *without*
555 extension, src2obj() is expected to add that.
556 'srcs' has the list of source files to build the
557 object file, with the first item being the source
558 file that directly corresponds to the object file.
559 'deps' is a list of explicit dependencies. 'incs'
560 is a list of include file directories. Finally,
561 'intent' indicates what this object file is going
564 obj2lib - function that produces build file lines to build a
565 static library file ("libfoo.a" in Unix terms) from
570 obj2lib(lib => "PATH/TO/libfile",
571 objs => [ "PATH/TO/objectfile", ... ]);
573 'lib' has the intended library file name *without*
574 extension, obj2lib is expected to add that. 'objs'
575 has the list of object files (also *without*
576 extension) to build this library.
578 libobj2shlib - function that produces build file lines to build a
579 shareable object library file ("libfoo.so" in Unix
580 terms) from the corresponding static library file
585 libobj2shlib(shlib => "PATH/TO/shlibfile",
586 lib => "PATH/TO/libfile",
587 objs => [ "PATH/TO/objectfile", ... ],
588 deps => [ "PATH/TO/otherlibfile", ... ],
589 ordinals => [ "word", "/PATH/TO/ordfile" ]);
591 'lib' has the intended library file name *without*
592 extension, libobj2shlib is expected to add that.
593 'shlib' has the corresponding shared library name
594 *without* extension. 'deps' has the list of other
595 libraries (also *without* extension) this library
596 needs to be linked with. 'objs' has the list of
597 object files (also *without* extension) to build
598 this library. 'ordinals' MAY be present, and when
599 it is, its value is an array where the word is
600 "crypto" or "ssl" and the file is one of the ordinal
601 files util/libeay.num or util/ssleay.num in the
604 This function has a choice; it can use the
605 corresponding static library as input to make the
606 shared library, or the list of object files.
608 obj2dso - function that produces build file lines to build a
609 dynamic shared object file from object files.
613 obj2dso(lib => "PATH/TO/libfile",
614 objs => [ "PATH/TO/objectfile", ... ],
615 deps => [ "PATH/TO/otherlibfile",
618 This is almost the same as libobj2shlib, but the
619 intent is to build a shareable library that can be
620 loaded in runtime (a "plugin"...). The differences
621 are subtle, one of the most visible ones is that the
622 resulting shareable library is produced from object
625 obj2bin - function that produces build file lines to build an
626 executable file from object files.
630 obj2bin(bin => "PATH/TO/binfile",
631 objs => [ "PATH/TO/objectfile", ... ],
632 deps => [ "PATH/TO/libfile", ... ]);
634 'bin' has the intended executable file name
635 *without* extension, obj2bin is expected to add
636 that. 'objs' has the list of object files (also
637 *without* extension) to build this library. 'deps'
638 has the list of library files (also *without*
639 extension) that the programs needs to be linked
642 in2script - function that produces build file lines to build a
643 script file from some input.
647 in2script(script => "PATH/TO/scriptfile",
648 sources => [ "PATH/TO/infile", ... ]);
650 'script' has the intended script file name.
651 'sources' has the list of source files to build the
652 resulting script from.
654 In all cases, file file paths are relative to the build tree top, and
655 the build file actions run with the build tree top as current working
658 Make sure to end the section with these functions with a string that
659 you thing is appropriate for the resulting build file. If nothing
660 else, end it like this:
662 ""; # Make sure no lingering values end up in the Makefile