4 This directory contains a few sets of files that are used for
5 configuration in diverse ways:
7 *.conf Target platform configurations, please read
8 'Configurations of OpenSSL target platforms' for more
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
17 Configurations of OpenSSL target platforms
18 ==========================================
20 Configuration targets are a collection of facts that we know about
21 different platforms and their capabilities. We organise them in a
22 hash table, where each entry represent a specific target.
24 Note that configuration target names must be unique across all config
25 files. The Configure script does check that a config file doesn't
26 have config targets that shadow config targets from other files.
28 In each table entry, the following keys are significant:
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]
37 sys_id => System identity for systems where that
38 is difficult to determine automatically.
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.
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
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
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
74 cflags => Defaults C compiler flags [4].
75 cxxflags => Default C++ compiler flags [4]. If unset,
76 it gets the same value as cflags.
78 (linking is a complex thing, see [3] below)
79 ld => Linker command, usually not defined
80 (meaning the compiler command is used
82 (NOTE: this is here for future use, it's
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.
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
96 shared_ldflag => Extra linking flags used when linking
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.
105 ar => The library archive command, the default is
107 (NOTE: this is here for future use, it's
109 arflags => Flags to be used with the library archive
110 command. On Unix, this includes the
111 command letter, 'r' by default.
113 ranlib => The library archive indexing command, the
114 default is 'ranlib' it it exists.
116 unistd => An alternative header to the typical
117 '<unistd.h>'. This is very rarely needed.
119 shared_extension => File name extension used for shared
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
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
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 uppercase
149 and all non-alphanumeric characters to '_'.
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
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"
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
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
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.
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
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
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
225 BN_LLONG bignum limbs are 32 bits,
226 but 64-bit 'unsigned long
227 long' is used internally
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
234 RC4_CHAR RC4 key schedule is made
235 up of 'unsigned char's;
236 Note: should not be used
237 for new configuration
239 RC4_INT RC4 key schedule is made
240 up of 'unsigned int's;
241 Note: should not be used
242 for new configuration
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.
249 Inheritance works as a set of default values that can be overridden
250 by corresponding key values in the inheriting configuration.
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.
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.
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.
274 ignored => "This should not appear in the end result",
283 inherit_from => [ "foo", "bar" ],
284 hehe => sub { join(" ",(@_,"!!!")) },
288 The entry for "laughter" will become as follows after processing:
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`.
302 [3] OpenSSL has three types of things to link from object files or
305 - shared libraries; that would be libcrypto and libssl.
306 - shared objects (sometimes called dynamic libraries); that would
308 - applications; those are apps/openssl and all the test apps.
310 Very roughly speaking, linking is done like this (words in braces
311 represent the configuration settings documented at the beginning
315 {ld} $(CFLAGS) {lflags} {shared_ldflag} -o libfoo.so \
316 foo/something.o foo/somethingelse.o {ex_libs}
319 {ld} $(CFLAGS) {lflags} {module_ldflags} -o libeng.so \
320 blah1.o blah2.o -lcrypto {ex_libs}
323 {ld} $(CFLAGS) {lflags} -o app \
324 app1.o utils.o -lssl -lcrypto {ex_libs}
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.
330 Historically, the target configurations came in form of a string with
331 values separated by colons. This use is deprecated. The string form
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}"
345 The `build.info` files that are spread over the source tree contain the
346 minimum information needed to build and distribute OpenSSL. It uses a
347 simple and yet fairly powerful language to determine what needs to be
348 built, from what sources, and other relationships between files.
350 For every `build.info` file, all file references are relative to the
351 directory of the `build.info` file for source files, and the
352 corresponding build directory for built files if the build tree
353 differs from the source tree.
355 When processed, every line is processed with the perl module
356 Text::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
359 directory for the current `build.info` file and the corresponding build
360 directory, all relative to the top of the build tree.
362 `Configure` only knows inherently about the top `build.info` file. For
363 any other directory that has one, further directories to look into
364 must be indicated like this:
366 SUBDIRS=something someelse
368 On to things to be built; they are declared by setting specific
376 Note that the files mentioned for PROGRAMS, LIBS and MODULES *must* be
377 without extensions. The build file templates will figure them out.
379 For each thing to be built, it is then possible to say what sources
383 SOURCE[foo]=foo.c common.c
384 SOURCE[bar]=bar.c extra.c common.c
386 It's also possible to tell some other dependencies:
388 DEPEND[foo]=libsomething
389 DEPEND[libbar]=libsomethingelse
391 (it could be argued that 'libsomething' and 'libsomethingelse' are
392 source as well. However, the files given through SOURCE are expected
393 to be located in the source tree while files given through DEPEND are
394 expected to be located in the build tree)
396 It's also possible to depend on static libraries explicitly:
398 DEPEND[foo]=libsomething.a
399 DEPEND[libbar]=libsomethingelse.a
401 This should be rarely used, and care should be taken to make sure it's
402 only used when supported. For example, native Windows build doesn't
403 support building static libraries and DLLs at the same time, so using
404 static libraries on Windows can only be done when configured
407 In some cases, it's desirable to include some source files in the
408 shared form of a library only:
410 SHARED_SOURCE[libfoo]=dllmain.c
412 For any file to be built, it's also possible to tell what extra
413 include paths the build of their source files should use:
417 It's also possible to specify C macros that should be defined:
419 DEFINE[foo]=FOO BAR=1
421 In some cases, one might want to generate some source files from
422 others, that's done as follows:
424 GENERATE[foo.s]=asm/something.pl $(CFLAGS)
425 GENERATE[bar.s]=asm/bar.S
427 The value of each GENERATE line is a command line or part of it.
428 Configure places no rules on the command line, except that the first
429 item must be the generator file. It is, however, entirely up to the
430 build file template to define exactly how those command lines should
431 be handled, how the output is captured and so on.
433 Sometimes, the generator file itself depends on other files, for
434 example if it is a perl script that depends on other perl modules.
435 This can be expressed using DEPEND like this:
437 DEPEND[asm/something.pl]=../perlasm/Foo.pm
439 There may also be cases where the exact file isn't easily specified,
440 but an inclusion directory still needs to be specified. INCLUDE can
441 be used in that case:
443 INCLUDE[asm/something.pl]=../perlasm
445 NOTE: GENERATE lines are limited to one command only per GENERATE.
447 Finally, you can have some simple conditional use of the `build.info`
448 information, looking like this:
458 The expression in square brackets is interpreted as a string in perl,
459 and will be seen as true if perl thinks it is, otherwise false. For
460 example, the above would have "something" used, since 1 is true.
462 Together with the use of Text::Template, this can be used as
463 conditions based on something in the passed variables, for example:
465 IF[{- $disabled{shared} -}]
467 SOURCE[libcrypto]=...
473 Build-file programming with the "unified" build system
474 ======================================================
476 "Build files" are called `Makefile` on Unix-like operating systems,
477 `descrip.mms` for MMS on VMS, `makefile` for `nmake` on Windows, etc.
479 To use the "unified" build system, the target configuration needs to
480 set the three items `build_scheme`, `build_file` and `build_command`.
481 In the rest of this section, we will assume that `build_scheme` is set
482 to "unified" (see the configurations documentation above for the
485 For any name given by `build_file`, the "unified" system expects a
486 template file in `Configurations/` named like the build file, with
487 `.tmpl` appended, or in case of possible ambiguity, a combination of
488 the second `build_scheme` list item and the `build_file` name. For
489 example, if `build_file` is set to `Makefile`, the template could be
490 `Configurations/Makefile.tmpl` or `Configurations/unix-Makefile.tmpl`.
491 In case both `Configurations/unix-Makefile.tmpl` and
492 `Configurations/Makefile.tmpl` are present, the former takes precedence.
494 The build-file template is processed with the perl module
495 Text::Template, using `{-` and `-}` as delimiters that enclose the
496 perl code fragments that generate configuration-dependent content.
497 Those perl fragments have access to all the hash variables from
500 The build-file template is expected to define at least the following
501 perl functions in a perl code fragment enclosed with `{-` and `-}`.
502 They are all expected to return a string with the lines they produce.
504 generatesrc - function that produces build file lines to generate
505 a source file from some input.
507 It's called like this:
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" );
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
533 src2obj - function that produces build file lines to build an
534 object file from source files and associated data.
536 It's called like this:
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" );
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
555 obj2lib - function that produces build file lines to build a
556 static library file ("libfoo.a" in Unix terms) from
561 obj2lib(lib => "PATH/TO/libfile",
562 objs => [ "PATH/TO/objectfile", ... ]);
564 'lib' has the intended library filename *without*
565 extension, obj2lib is expected to add that. 'objs'
566 has the list of object files to build this library.
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.
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.
582 obj2shlib(shlib => "PATH/TO/shlibfile",
583 lib => "PATH/TO/libfile",
584 objs => [ "PATH/TO/objectfile", ... ],
585 deps => [ "PATH/TO/otherlibfile", ... ]);
587 'lib' has the base (static) library filename
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.
597 obj2dso - function that produces build file lines to build a
598 dynamic shared object file from object files.
602 obj2dso(lib => "PATH/TO/libfile",
603 objs => [ "PATH/TO/objectfile", ... ],
604 deps => [ "PATH/TO/otherlibfile",
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"...).
611 obj2bin - function that produces build file lines to build an
612 executable file from object files.
616 obj2bin(bin => "PATH/TO/binfile",
617 objs => [ "PATH/TO/objectfile", ... ],
618 deps => [ "PATH/TO/libfile", ... ]);
620 'bin' has the intended executable filename
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
627 in2script - function that produces build file lines to build a
628 script file from some input.
632 in2script(script => "PATH/TO/scriptfile",
633 sources => [ "PATH/TO/infile", ... ]);
635 'script' has the intended script filename.
636 'sources' has the list of source files to build the
637 resulting script from.
639 In all cases, file file paths are relative to the build tree top, and
640 the build file actions run with the build tree top as current working
643 Make sure to end the section with these functions with a string that
644 you thing is appropriate for the resulting build file. If nothing
645 else, end it like this:
647 ""; # Make sure no lingering values end up in the Makefile
650 Configure helper scripts
651 ========================
653 Configure uses helper scripts in this directory:
658 These scripts are per platform family, to check the integrity of the
659 tools used for configuration and building. The checker script used is
660 either `{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.
665 If the check succeeds, the script is expected to end with a non-zero
666 expression. If the check fails, the script can end with a zero, or