Don't treat .d (depend) files separately from object files
[openssl.git] / Configurations / README
1 Configurations of OpenSSL target platforms
2 ==========================================
3
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.
7
8 In each table entry, the following keys are significant:
9
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]
16
17         sys_id          => System identity for systems where that
18                            is difficult to determine automatically.
19
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
25                            compiling.
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
34                            "-g -O0".
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
43                            "-O" or "-O3".
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".
58
59         (linking is a complex thing, see [3] below)
60         ld              => Linker command, usually not defined
61                            (meaning the compiler command is used
62                            instead).
63                            (NOTE: this is here for future use, it's
64                            not implemented yet)
65         lflags          => Flags that are used when linking apps.
66         shared_ldflag   => Flags that are used when linking shared
67                            or dynamic libraries.
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
71                            linking.
72
73         debug_lflags    => Like debug_cflags, but used when linking.
74         release_lflags  => Like release_cflags, but used when linking.
75
76         ar              => The library archive command, the default is
77                            "ar".
78                            (NOTE: this is here for future use, it's
79                            not implemented yet)
80         arflags         => Flags to be used with the library archive
81                            command.
82
83         ranlib          => The library archive indexing command, the
84                            default is 'ranlib' it it exists.
85
86         unistd          => An alternative header to the typical
87                            '<unistd.h>'.  This is very rarely needed.
88
89         shared_extension => File name extension used for shared
90                             libraries. 
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
94                            implemented yet)
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
98                            implemented yet)
99
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"
107                            and "VMS".
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
120                            scheme.
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.
127
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
132                            directories.
133
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
143                            source.
144                            The valid words are:
145
146                            BN_LLONG     use 'unsigned long long' in
147                                         some bignum calculations.
148                                         This has no value when
149                                         SIXTY_FOUR_BIT or
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
154                                                 are 64 bits, long is
155                                                 32 bits, long long is
156                                                 64 bits.
157                            SIXTY_FOUR_BIT_LONG  processor registers
158                                                 are 64 bits, long is
159                                                 64 bits.
160                            THIRTY_TWO_BIT       processor registers
161                                                 are 32 bits.
162                            EXPORT_VAR_AS_FN     for shared libraries,
163                                                 export vars as
164                                                 accessor functions.
165
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().
170                            Default to mem_clr.c
171         bn_asm_src      => Assembler implementation of core bignum
172                            functions.
173                            Defaults to bn_asm.c
174         ec_asm_src      => Assembler implementation of core EC
175                            functions.
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
180                            functions.
181                            Defaults to 'aes_core.c aes_cbc.c'
182         bf_asm_src      => Assembler implementation of core BlowFish
183                            functions.
184                            Defaults to 'bf_enc.c'
185         md5_asm_src     => Assembler implementation of core MD5
186                            functions.
187         sha1_asm_src    => Assembler implementation of core SHA1,
188                            functions, and also possibly SHA256 and
189                            SHA512 ones.
190         cast_asm_src    => Assembler implementation of core CAST
191                            functions.
192                            Defaults to 'c_enc.c'
193         rc4_asm_src     => Assembler implementation of core RC4
194                            functions.
195                            Defaults to 'rc4_enc.c rc4_skey.c'
196         rmd160_asm_src  => Assembler implementation of core RMD160
197                            functions.
198         rc5_asm_src     => Assembler implementation of core RC5
199                            functions.
200                            Defaults to 'rc5_enc.c'
201         wp_asm_src      => Assembler implementation of core WHIRLPOOL
202                            functions.
203         cmll_asm_src    => Assembler implementation of core CAMELLIA
204                            functions.
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
208                            gcm_ghash_4bit.
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
212                            actually be built.
213
214
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.
218
219     Inheritance works as a set of default values that can be overriden
220     by corresponding key values in the inheriting configuration.
221
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.
225
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.
231
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.
237
238     An example:
239
240         "foo" => {
241                 template => 1,
242                 haha => "ha ha",
243                 hoho => "ho",
244                 ignored => "This should not appear in the end result",
245         },
246         "bar" => {
247                 template => 1,
248                 haha => "ah",
249                 hoho => "haho",
250                 hehe => "hehe"
251         },
252         "laughter" => {
253                 inherit_from => [ "foo", "bar" ],
254                 hehe => sub { join(" ",(@_,"!!!")) },
255                 ignored => "",
256         }
257
258         The entry for "laughter" will become as follows after processing:
259
260         "laughter" => {
261                 haha => "ha ha ah",
262                 hoho => "ho haho",
263                 hehe => "hehe !!!",
264                 ignored => ""
265         }
266
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
270     flags to Configure.
271
272 [3] OpenSSL has three types of things to link from object files or
273     static libraries:
274
275     - shared libraries; that would be libcrypto and libssl.
276     - shared objects (sometimes called dynamic libraries);  that would
277       be the engines.
278     - applications; those are apps/openssl and all the test apps.
279
280     Very roughly speaking, linking is done like this (words in braces
281     represent the configuration settings documented at the beginning
282     of this file):
283
284     shared libraries:
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}
288
289     shared objects:
290         {ld} $(CFLAGS) {shared_ldflag} -shared -o libeng.so \
291             blah1.o blah2.o {plib_lflags} -lcrypto {ex_libs}
292
293     applications:
294         {ld} $(CFLAGS) {lflags} -o app \
295             app1.o utils.o {plib_lflags} -lssl -lcrypto {ex_libs}
296
297
298 Historically, the target configurations came in form of a string with
299 values separated by colons.  This use is deprecated.  The string form
300 looked like this:
301
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}"
303
304
305 Build info files
306 ================
307
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.
312
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.
317
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.
324
325 To begin with, things to be built are declared by setting specific
326 variables:
327
328     PROGRAMS=foo bar
329     LIBS=libsomething
330     ENGINES=libeng
331     SCRIPTS=myhack
332     EXTRA=file1 file2
333
334 Note that the files mentioned for PROGRAMS, LIBS and ENGINES *must* be
335 without extensions.  The build file templates will figure them out.
336
337 For each thing to be built, it is then possible to say what sources
338 they are built from:
339
340     PROGRAMS=foo bar
341     SOURCE[foo]=foo.c common.c
342     SOURCE[bar]=bar.c extra.c common.c
343
344 It's also possible to tell some other dependencies:
345
346     DEPEND[foo]=libsomething
347     DEPEND[libbar]=libsomethingelse
348
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)
353
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
356 declared like this:
357
358     ORDINALS[libcrypto]=crypto
359
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.
362
363 One some platforms, shared libraries come with a name that's different
364 from their static counterpart.  That's declared as follows:
365
366     SHARED_NAME[libfoo]=cygfoo-{- $config{shlibver} -}
367
368 The example is from Cygwin, which has a required naming convention.
369
370 Sometimes, it makes sense to rename an output file, for example a
371 library:
372
373     RENAME[libfoo]=libbar
374
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.
379
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:
382
383     INCLUDE[foo]=include
384
385 It's possible to have raw build file lines, between BEGINRAW and
386 ENDRAW lines as follows:
387
388     BEGINRAW[Makefile(unix)]
389     haha.h: {- $builddir -}/Makefile
390         echo "/* haha */" > haha.h
391     ENDRAW[Makefile(unix)]
392
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
397 configuration items:
398
399    build_file   => "build.ninja"
400    build_scheme => [ "unified", "unix" ]
401
402 ... these lines will be considered:
403
404    BEGINRAW[build.ninja]
405    build haha.h: echo "/* haha */" > haha.h
406    ENDRAW[build.ninja]
407
408    BEGINRAW[build.ninja(unix)]
409    build hoho.h: echo "/* hoho */" > hoho.h
410    ENDRAW[build.ninja(unix)]
411
412 See the documentation further up for more information on configuration
413 items.
414
415 Finally, you can have some simple conditional use of the build.info
416 information, looking like this:
417
418     IF[1]
419      something
420     ELSIF[2]
421      something other
422     ELSE
423      something else
424     ENDIF
425
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.
429
430 Together with the use of Text::Template, this can be used as
431 conditions based on something in the passed variables, for example:
432
433     IF[{- $config{no_shared} -}]
434       LIBS=libcrypto
435       SOURCE[libcrypto]=...
436     ELSE
437       LIBS=libfoo
438       SOURCE[libfoo]=...
439     ENDIF
440
441 or:
442
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
448     ENDIF
449
450
451 Build-file programming with the "unified" build system
452 ======================================================
453
454 "Build files" are called "Makefile" on Unix-like operating systems,
455 "descrip.mms" for MMS on VMS, "makefile" for nmake on Windows, etc.
456
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
461 details).
462
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
471 precedence.
472
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
477 configdata.pem.
478
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.
482
483     src2obj     - function that produces build file lines to build an
484                   object file from source files and associated data.
485
486                   It's called like this:
487
488                         src2obj(obj => "PATH/TO/objectfile",
489                                 srcs => [ "PATH/TO/sourcefile", ... ],
490                                 deps => [ "dep1", ... ],
491                                 incs => [ "INCL/PATH", ... ]);
492
493                   'obj' has the intended object file *without*
494                   extension, src2obj() is expected to add that.
495                   'srcs' has the list of source files to build the
496                   object file, with the first item being the source
497                   file that directly corresponds to the object file.
498                   'deps' is a list of explicit dependencies.  'incs'
499                   is a list of include file directories.
500
501     obj2lib     - function that produces build file lines to build a
502                   static library file ("libfoo.a" in Unix terms) from
503                   object files.
504
505                   called like this:
506
507                         obj2lib(lib => "PATH/TO/libfile",
508                                 objs => [ "PATH/TO/objectfile", ... ]);
509
510                   'lib' has the intended library file name *without*
511                   extension, obj2lib is expected to add that.  'objs'
512                   has the list of object files (also *without*
513                   extension) to build this library.
514
515     libobj2shlib - function that produces build file lines to build a
516                   shareable object library file ("libfoo.so" in Unix
517                   terms) from the corresponding static library file
518                   or object files.
519
520                   called like this:
521
522                         libobj2shlib(shlib => "PATH/TO/shlibfile",
523                                      lib => "PATH/TO/libfile",
524                                      objs => [ "PATH/TO/objectfile", ... ],
525                                      deps => [ "PATH/TO/otherlibfile", ... ],
526                                      ordinals => [ "word", "/PATH/TO/ordfile" ]);
527
528                   'lib' has the intended library file name *without*
529                   extension, libobj2shlib is expected to add that.
530                   'shlib' has the correcponding shared library name
531                   *without* extension.  'deps' has the list of other
532                   libraries (also *without* extension) this library
533                   needs to be linked with.  'objs' has the list of
534                   object files (also *without* extension) to build
535                   this library.  'ordinals' MAY be present, and when
536                   it is, its value is an array where the word is
537                   "crypto" or "ssl" and the file is one of the ordinal
538                   files util/libeay.num or util/ssleay.num in the
539                   source directory.
540
541                   This function has a choice; it can use the
542                   corresponding static library as input to make the
543                   shared library, or the list of object files.
544
545     obj2dynlib  - function that produces build file lines to build a
546                   dynamically loadable library file ("libfoo.so" on
547                   Unix) from object files.
548
549                   called like this:
550
551                         obj2dynlib(lib => "PATH/TO/libfile",
552                                    objs => [ "PATH/TO/objectfile", ... ],
553                                    deps => [ "PATH/TO/otherlibfile",
554                                    ... ]);
555
556                   This is almost the same as libobj2shlib, but the
557                   intent is to build a shareable library that can be
558                   loaded in runtime (a "plugin"...).  The differences
559                   are subtle, one of the most visible ones is that the
560                   resulting shareable library is produced from object
561                   files only.
562
563     obj2bin     - function that produces build file lines to build an
564                   executable file from object files.
565
566                   called like this:
567
568                         obj2bin(bin => "PATH/TO/binfile",
569                                 objs => [ "PATH/TO/objectfile", ... ],
570                                 deps => [ "PATH/TO/libfile", ... ]);
571
572                   'bin' has the intended executable file name
573                   *without* extension, obj2bin is expected to add
574                   that.  'objs' has the list of object files (also
575                   *without* extension) to build this library.  'deps'
576                   has the list of library files (also *without*
577                   extension) that the programs needs to be linked
578                   with.
579
580     in2script   - function that produces build file lines to build a
581                   script file from some input.
582
583                   called like this:
584
585                         in2script(script => "PATH/TO/scriptfile",
586                                   sources => [ "PATH/TO/infile", ... ]);
587
588                   'script' has the intended script file name.
589                   'sources' has the list of source files to build the
590                   resulting script from.
591
592 In all cases, file file paths are relative to the build tree top, and
593 the build file actions run with the build tree top as current working
594 directory.
595
596 Make sure to end the section with these functions with a string that
597 you thing is apropriate for the resulting build file.  If nothing
598 else, end it like this:
599
600       "";       # Make sure no lingering values end up in the Makefile
601     -}