]>
Commit | Line | Data |
---|---|---|
44eb65ce RL |
1 | Intro |
2 | ===== | |
3 | ||
4 | This directory contains a few sets of files that are used for | |
5 | configuration in diverse ways: | |
6 | ||
7 | *.conf Target platform configurations, please read | |
8 | 'Configurations of OpenSSL target platforms' for more | |
9 | information. | |
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 | |
15 | information. | |
16 | ||
17 | ||
9e0724a1 | 18 | Configurations of OpenSSL target platforms |
ddf1847d | 19 | ========================================== |
9e0724a1 | 20 | |
225f980d | 21 | Configuration targets are a collection of facts that we know about |
9e0724a1 RL |
22 | different platforms and their capabilities. We organise them in a |
23 | hash table, where each entry represent a specific target. | |
24 | ||
225f980d RL |
25 | Note that configuration target names must be unique across all config |
26 | files. The Configure script does check that a config file doesn't | |
27 | have config targets that shadow config targets from other files. | |
28 | ||
9e0724a1 RL |
29 | In each table entry, the following keys are significant: |
30 | ||
31 | inherit_from => Other targets to inherit values from. | |
32 | Explained further below. [1] | |
33 | template => Set to 1 if this isn't really a platform | |
34 | target. Instead, this target is a template | |
35 | upon which other targets can be built. | |
36 | Explained further below. [1] | |
37 | ||
38 | sys_id => System identity for systems where that | |
39 | is difficult to determine automatically. | |
40 | ||
906eb3d0 RL |
41 | enable => Enable specific configuration features. |
42 | This MUST be an array of words. | |
43 | disable => Disable specific configuration features. | |
44 | This MUST be an array of words. | |
45 | Note: if the same feature is both enabled | |
46 | and disabled, disable wins. | |
47 | ||
310f28df RL |
48 | as => The assembler command. This is not always |
49 | used (for example on Unix, where the C | |
50 | compiler is used instead). | |
51 | asflags => Default assembler command flags [4]. | |
8c3bc594 RL |
52 | cpp => The C preprocessor command, normally not |
53 | given, as the build file defaults are | |
54 | usually good enough. | |
310f28df | 55 | cppflags => Default C preprocessor flags [4]. |
8c3bc594 | 56 | defines => As an alternative, macro definitions may be |
310f28df RL |
57 | given here instead of in `cppflags' [4]. |
58 | If given here, they MUST be as an array of | |
59 | the string such as "MACRO=value", or just | |
8c3bc594 RL |
60 | "MACRO" for definitions without value. |
61 | includes => As an alternative, inclusion directories | |
310f28df RL |
62 | may be given here instead of in `cppflags' |
63 | [4]. If given here, the MUST be an array | |
64 | of strings, one directory specification | |
65 | each. | |
ea241958 | 66 | cc => The C compiler command, usually one of "cc", |
9e0724a1 RL |
67 | "gcc" or "clang". This command is normally |
68 | also used to link object files and | |
69 | libraries into the final program. | |
ea241958 RL |
70 | cxx => The C++ compiler command, usually one of |
71 | "c++", "g++" or "clang++". This command is | |
72 | also used when linking a program where at | |
73 | least one of the object file is made from | |
74 | C++ source. | |
310f28df RL |
75 | cflags => Defaults C compiler flags [4]. |
76 | cxxflags => Default C++ compiler flags [4]. If unset, | |
77 | it gets the same value as cflags. | |
9e0724a1 | 78 | |
c86ddbe6 RL |
79 | (linking is a complex thing, see [3] below) |
80 | ld => Linker command, usually not defined | |
9e0724a1 RL |
81 | (meaning the compiler command is used |
82 | instead). | |
83 | (NOTE: this is here for future use, it's | |
84 | not implemented yet) | |
310f28df RL |
85 | lflags => Default flags used when linking apps, |
86 | shared libraries or DSOs [4]. | |
c86ddbe6 | 87 | ex_libs => Extra libraries that are needed when |
310f28df | 88 | linking shared libraries, DSOs or programs. |
edc79fc9 AP |
89 | The value is also assigned to Libs.private |
90 | in $(libdir)/pkgconfig/libcrypto.pc. | |
310f28df RL |
91 | |
92 | shared_cppflags => Extra C preprocessor flags used when | |
93 | processing C files for shared libraries. | |
94 | shared_cflag => Extra C compiler flags used when compiling | |
95 | for shared libraries, typically something | |
96 | like "-fPIC". | |
97 | shared_ldflag => Extra linking flags used when linking | |
98 | shared libraries. | |
99 | module_cppflags | |
100 | module_cflags | |
101 | module_ldflags => Has the same function as the corresponding | |
102 | `shared_' attributes, but for building DSOs. | |
103 | When unset, they get the same values as the | |
104 | corresponding `shared_' attributes. | |
9e0724a1 | 105 | |
9e0724a1 RL |
106 | ar => The library archive command, the default is |
107 | "ar". | |
108 | (NOTE: this is here for future use, it's | |
109 | not implemented yet) | |
110 | arflags => Flags to be used with the library archive | |
6475b649 RL |
111 | command. On Unix, this includes the |
112 | command letter, 'r' by default. | |
9e0724a1 RL |
113 | |
114 | ranlib => The library archive indexing command, the | |
115 | default is 'ranlib' it it exists. | |
116 | ||
117 | unistd => An alternative header to the typical | |
118 | '<unistd.h>'. This is very rarely needed. | |
119 | ||
120 | shared_extension => File name extension used for shared | |
121 | libraries. | |
122 | obj_extension => File name extension used for object files. | |
123 | On unix, this defaults to ".o" (NOTE: this | |
124 | is here for future use, it's not | |
125 | implemented yet) | |
126 | exe_extension => File name extension used for executable | |
127 | files. On unix, this defaults to "" (NOTE: | |
128 | this is here for future use, it's not | |
129 | implemented yet) | |
822b5e26 VD |
130 | shlib_variant => A "variant" identifier inserted between the base |
131 | shared library name and the extension. On "unixy" | |
132 | platforms (BSD, Linux, Solaris, MacOS/X, ...) this | |
133 | supports installation of custom OpenSSL libraries | |
134 | that don't conflict with other builds of OpenSSL | |
135 | installed on the system. The variant identifier | |
136 | becomes part of the SONAME of the library and also | |
137 | any symbol versions (symbol versions are not used or | |
138 | needed with MacOS/X). For example, on a system | |
139 | where a default build would normally create the SSL | |
140 | shared library as 'libssl.so -> libssl.so.1.1' with | |
141 | the value of the symlink as the SONAME, a target | |
142 | definition that sets 'shlib_variant => "-abc"' will | |
143 | create 'libssl.so -> libssl-abc.so.1.1', again with | |
144 | an SONAME equal to the value of the symlink. The | |
145 | symbol versions associated with the variant library | |
146 | would then be 'OPENSSL_ABC_<version>' rather than | |
147 | the default 'OPENSSL_<version>'. The string inserted | |
148 | into symbol versions is obtained by mapping all | |
149 | letters in the "variant" identifier to upper case | |
150 | and all non-alphanumeric characters to '_'. | |
9e0724a1 | 151 | |
2ad9ef06 RL |
152 | thread_scheme => The type of threads is used on the |
153 | configured platform. Currently known | |
154 | values are "(unknown)", "pthreads", | |
155 | "uithreads" (a.k.a solaris threads) and | |
156 | "winthreads". Except for "(unknown)", the | |
157 | actual value is currently ignored but may | |
158 | be used in the future. See further notes | |
159 | below [2]. | |
9e0724a1 RL |
160 | dso_scheme => The type of dynamic shared objects to build |
161 | for. This mostly comes into play with | |
162 | engines, but can be used for other purposes | |
163 | as well. Valid values are "DLFCN" | |
164 | (dlopen() et al), "DLFCN_NO_H" (for systems | |
165 | that use dlopen() et al but do not have | |
166 | fcntl.h), "DL" (shl_load() et al), "WIN32" | |
167 | and "VMS". | |
a8b2b52f | 168 | perlasm_scheme => The perlasm method used to create the |
9e0724a1 RL |
169 | assembler files used when compiling with |
170 | assembler implementations. | |
171 | shared_target => The shared library building method used. | |
ef2dfc99 RL |
172 | This serves multiple purposes: |
173 | - as index for targets found in shared_info.pl. | |
174 | - as linker script generation selector. | |
175 | To serve both purposes, the index for shared_info.pl | |
176 | should end with '-shared', and this suffix will be | |
177 | removed for use as a linker script generation | |
178 | selector. Note that the latter is only used if | |
179 | 'shared_defflag' is defined. | |
9e0724a1 | 180 | build_scheme => The scheme used to build up a Makefile. |
88087414 RL |
181 | In its simplest form, the value is a string |
182 | with the name of the build scheme. | |
183 | The value may also take the form of a list | |
184 | of strings, if the build_scheme is to have | |
185 | some options. In this case, the first | |
186 | string in the list is the name of the build | |
187 | scheme. | |
45c6e23c | 188 | Currently recognised build scheme is "unified". |
9fe2bb77 RL |
189 | For the "unified" build scheme, this item |
190 | *must* be an array with the first being the | |
191 | word "unified" and the second being a word | |
192 | to identify the platform family. | |
9e0724a1 RL |
193 | |
194 | multilib => On systems that support having multiple | |
195 | implementations of a library (typically a | |
196 | 32-bit and a 64-bit variant), this is used | |
197 | to have the different variants in different | |
198 | directories. | |
199 | ||
1bc563ca AP |
200 | bn_ops => Building options (was just bignum options in |
201 | the earlier history of this option, hence the | |
202 | name). This is a string of words that describe | |
203 | algorithms' implementation parameters that | |
204 | are optimal for the designated target platform, | |
205 | such as the type of integers used to build up | |
206 | the bignum, different ways to implement certain | |
207 | ciphers and so on. To fully comprehend the | |
9e0724a1 RL |
208 | meaning, the best is to read the affected |
209 | source. | |
210 | The valid words are: | |
211 | ||
1bc563ca AP |
212 | THIRTY_TWO_BIT bignum limbs are 32 bits, |
213 | this is default if no | |
214 | option is specified, it | |
215 | works on any supported | |
216 | system [unless "wider" | |
217 | limb size is implied in | |
218 | assembly code]; | |
219 | BN_LLONG bignum limbs are 32 bits, | |
220 | but 64-bit 'unsigned long | |
221 | long' is used internally | |
222 | in calculations; | |
223 | SIXTY_FOUR_BIT_LONG bignum limbs are 64 bits | |
224 | and sizeof(long) is 8; | |
225 | SIXTY_FOUR_BIT bignums limbs are 64 bits, | |
226 | but execution environment | |
227 | is ILP32; | |
228 | RC4_CHAR RC4 key schedule is made | |
229 | up of 'unsigned char's; | |
230 | RC4_INT RC4 key schedule is made | |
231 | up of 'unsigned int's; | |
9e0724a1 RL |
232 | EXPORT_VAR_AS_FN for shared libraries, |
233 | export vars as | |
234 | accessor functions. | |
235 | ||
d6baf09f RL |
236 | apps_aux_src => Extra source to build apps/openssl and other |
237 | apps, as needed by the target and that can be | |
238 | collected in a library. | |
239 | apps_init_src => Init source to build apps/openssl and other | |
240 | apps, as needed by the target. This code | |
241 | cannot be placed in a library, as the rest | |
242 | of the code isn't expected to link to it | |
46d08509 | 243 | explicitly. |
9fe2bb77 | 244 | cpuid_asm_src => assembler implementation of cpuid code as |
9e0724a1 | 245 | well as OPENSSL_cleanse(). |
9fe2bb77 RL |
246 | Default to mem_clr.c |
247 | bn_asm_src => Assembler implementation of core bignum | |
9e0724a1 | 248 | functions. |
9fe2bb77 RL |
249 | Defaults to bn_asm.c |
250 | ec_asm_src => Assembler implementation of core EC | |
9e0724a1 | 251 | functions. |
9fe2bb77 | 252 | des_asm_src => Assembler implementation of core DES |
9e0724a1 | 253 | encryption functions. |
9fe2bb77 RL |
254 | Defaults to 'des_enc.c fcrypt_b.c' |
255 | aes_asm_src => Assembler implementation of core AES | |
9e0724a1 | 256 | functions. |
9fe2bb77 RL |
257 | Defaults to 'aes_core.c aes_cbc.c' |
258 | bf_asm_src => Assembler implementation of core BlowFish | |
9e0724a1 | 259 | functions. |
9fe2bb77 RL |
260 | Defaults to 'bf_enc.c' |
261 | md5_asm_src => Assembler implementation of core MD5 | |
9e0724a1 | 262 | functions. |
9fe2bb77 | 263 | sha1_asm_src => Assembler implementation of core SHA1, |
9e0724a1 RL |
264 | functions, and also possibly SHA256 and |
265 | SHA512 ones. | |
9fe2bb77 | 266 | cast_asm_src => Assembler implementation of core CAST |
9e0724a1 | 267 | functions. |
9fe2bb77 RL |
268 | Defaults to 'c_enc.c' |
269 | rc4_asm_src => Assembler implementation of core RC4 | |
9e0724a1 | 270 | functions. |
9fe2bb77 RL |
271 | Defaults to 'rc4_enc.c rc4_skey.c' |
272 | rmd160_asm_src => Assembler implementation of core RMD160 | |
9e0724a1 | 273 | functions. |
9fe2bb77 | 274 | rc5_asm_src => Assembler implementation of core RC5 |
9e0724a1 | 275 | functions. |
9fe2bb77 RL |
276 | Defaults to 'rc5_enc.c' |
277 | wp_asm_src => Assembler implementation of core WHIRLPOOL | |
9e0724a1 | 278 | functions. |
9fe2bb77 | 279 | cmll_asm_src => Assembler implementation of core CAMELLIA |
9e0724a1 | 280 | functions. |
9fe2bb77 RL |
281 | Defaults to 'camellia.c cmll_misc.c cmll_cbc.c' |
282 | modes_asm_src => Assembler implementation of cipher modes, | |
283 | currently the functions gcm_gmult_4bit and | |
284 | gcm_ghash_4bit. | |
285 | padlock_asm_src => Assembler implementation of core parts of | |
9e0724a1 RL |
286 | the padlock engine. This is mandatory on |
287 | any platform where the padlock engine might | |
288 | actually be built. | |
289 | ||
290 | ||
291 | [1] as part of the target configuration, one can have a key called | |
292 | 'inherit_from' that indicate what other configurations to inherit | |
293 | data from. These are resolved recursively. | |
294 | ||
b6453a68 | 295 | Inheritance works as a set of default values that can be overridden |
9e0724a1 RL |
296 | by corresponding key values in the inheriting configuration. |
297 | ||
298 | Note 1: any configuration table can be used as a template. | |
299 | Note 2: pure templates have the attribute 'template => 1' and | |
300 | cannot be used as build targets. | |
301 | ||
302 | If several configurations are given in the 'inherit_from' array, | |
303 | the values of same attribute are concatenated with space | |
304 | separation. With this, it's possible to have several smaller | |
305 | templates for different configuration aspects that can be combined | |
306 | into a complete configuration. | |
307 | ||
308 | instead of a scalar value or an array, a value can be a code block | |
309 | of the form 'sub { /* your code here */ }'. This code block will | |
310 | be called with the list of inherited values for that key as | |
311 | arguments. In fact, the concatenation of strings is really done | |
312 | by using 'sub { join(" ",@_) }' on the list of inherited values. | |
313 | ||
314 | An example: | |
315 | ||
316 | "foo" => { | |
317 | template => 1, | |
318 | haha => "ha ha", | |
319 | hoho => "ho", | |
320 | ignored => "This should not appear in the end result", | |
321 | }, | |
322 | "bar" => { | |
323 | template => 1, | |
324 | haha => "ah", | |
325 | hoho => "haho", | |
326 | hehe => "hehe" | |
327 | }, | |
328 | "laughter" => { | |
329 | inherit_from => [ "foo", "bar" ], | |
330 | hehe => sub { join(" ",(@_,"!!!")) }, | |
331 | ignored => "", | |
332 | } | |
333 | ||
334 | The entry for "laughter" will become as follows after processing: | |
335 | ||
336 | "laughter" => { | |
337 | haha => "ha ha ah", | |
338 | hoho => "ho haho", | |
339 | hehe => "hehe !!!", | |
340 | ignored => "" | |
341 | } | |
342 | ||
343 | [2] OpenSSL is built with threading capabilities unless the user | |
2ad9ef06 | 344 | specifies 'no-threads'. The value of the key 'thread_scheme' may |
9e0724a1 RL |
345 | be "(unknown)", in which case the user MUST give some compilation |
346 | flags to Configure. | |
347 | ||
c86ddbe6 RL |
348 | [3] OpenSSL has three types of things to link from object files or |
349 | static libraries: | |
350 | ||
351 | - shared libraries; that would be libcrypto and libssl. | |
352 | - shared objects (sometimes called dynamic libraries); that would | |
353 | be the engines. | |
354 | - applications; those are apps/openssl and all the test apps. | |
355 | ||
356 | Very roughly speaking, linking is done like this (words in braces | |
357 | represent the configuration settings documented at the beginning | |
358 | of this file): | |
359 | ||
360 | shared libraries: | |
310f28df RL |
361 | {ld} $(CFLAGS) {lflags} {shared_ldflag} -o libfoo.so \ |
362 | foo/something.o foo/somethingelse.o {ex_libs} | |
c86ddbe6 RL |
363 | |
364 | shared objects: | |
310f28df | 365 | {ld} $(CFLAGS) {lflags} {module_ldflags} -o libeng.so \ |
150624bc | 366 | blah1.o blah2.o -lcrypto {ex_libs} |
c86ddbe6 RL |
367 | |
368 | applications: | |
369 | {ld} $(CFLAGS) {lflags} -o app \ | |
150624bc | 370 | app1.o utils.o -lssl -lcrypto {ex_libs} |
c86ddbe6 | 371 | |
310f28df RL |
372 | [4] There are variants of these attribute, prefixed with `lib_', |
373 | `dso_' or `bin_'. Those variants replace the unprefixed attribute | |
374 | when building library, DSO or program modules specifically. | |
9e0724a1 RL |
375 | |
376 | Historically, the target configurations came in form of a string with | |
df71f0b8 RL |
377 | values separated by colons. This use is deprecated. The string form |
378 | looked like this: | |
9e0724a1 | 379 | |
f0bd4686 | 380 | "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}" |
9fe2bb77 RL |
381 | |
382 | ||
383 | Build info files | |
384 | ================ | |
385 | ||
386 | The build.info files that are spread over the source tree contain the | |
387 | minimum information needed to build and distribute OpenSSL. It uses a | |
388 | simple and yet fairly powerful language to determine what needs to be | |
389 | built, from what sources, and other relationships between files. | |
390 | ||
391 | For every build.info file, all file references are relative to the | |
392 | directory of the build.info file for source files, and the | |
393 | corresponding build directory for built files if the build tree | |
394 | differs from the source tree. | |
395 | ||
396 | When processed, every line is processed with the perl module | |
397 | Text::Template, using the delimiters "{-" and "-}". The hashes | |
398 | %config and %target are passed to the perl fragments, along with | |
399 | $sourcedir and $builddir, which are the locations of the source | |
400 | directory for the current build.info file and the corresponding build | |
401 | directory, all relative to the top of the build tree. | |
402 | ||
7f73eafe RL |
403 | 'Configure' only knows inherently about the top build.info file. For |
404 | any other directory that has one, further directories to look into | |
405 | must be indicated like this: | |
406 | ||
407 | SUBDIRS=something someelse | |
408 | ||
409 | On to things to be built; they are declared by setting specific | |
9fe2bb77 RL |
410 | variables: |
411 | ||
412 | PROGRAMS=foo bar | |
413 | LIBS=libsomething | |
414 | ENGINES=libeng | |
415 | SCRIPTS=myhack | |
416 | EXTRA=file1 file2 | |
417 | ||
418 | Note that the files mentioned for PROGRAMS, LIBS and ENGINES *must* be | |
419 | without extensions. The build file templates will figure them out. | |
420 | ||
421 | For each thing to be built, it is then possible to say what sources | |
422 | they are built from: | |
423 | ||
424 | PROGRAMS=foo bar | |
425 | SOURCE[foo]=foo.c common.c | |
426 | SOURCE[bar]=bar.c extra.c common.c | |
427 | ||
428 | It's also possible to tell some other dependencies: | |
429 | ||
430 | DEPEND[foo]=libsomething | |
431 | DEPEND[libbar]=libsomethingelse | |
432 | ||
433 | (it could be argued that 'libsomething' and 'libsomethingelse' are | |
434 | source as well. However, the files given through SOURCE are expected | |
435 | to be located in the source tree while files given through DEPEND are | |
436 | expected to be located in the build tree) | |
437 | ||
46f4e1be | 438 | It's also possible to depend on static libraries explicitly: |
473a9547 RL |
439 | |
440 | DEPEND[foo]=libsomething.a | |
441 | DEPEND[libbar]=libsomethingelse.a | |
442 | ||
443 | This should be rarely used, and care should be taken to make sure it's | |
444 | only used when supported. For example, native Windows build doesn't | |
a8b2b52f | 445 | support building static libraries and DLLs at the same time, so using |
473a9547 RL |
446 | static libraries on Windows can only be done when configured |
447 | 'no-shared'. | |
448 | ||
9fe2bb77 RL |
449 | One some platforms, shared libraries come with a name that's different |
450 | from their static counterpart. That's declared as follows: | |
451 | ||
452 | SHARED_NAME[libfoo]=cygfoo-{- $config{shlibver} -} | |
453 | ||
454 | The example is from Cygwin, which has a required naming convention. | |
455 | ||
456 | Sometimes, it makes sense to rename an output file, for example a | |
457 | library: | |
458 | ||
459 | RENAME[libfoo]=libbar | |
460 | ||
a8b2b52f | 461 | That line has "libfoo" renamed to "libbar". While it makes no |
9fe2bb77 RL |
462 | sense at all to just have a rename like that (why not just use |
463 | "libbar" everywhere?), it does make sense when it can be used | |
464 | conditionally. See a little further below for an example. | |
465 | ||
2a08d1a0 RL |
466 | In some cases, it's desirable to include some source files in the |
467 | shared form of a library only: | |
468 | ||
469 | SHARED_SOURCE[libfoo]=dllmain.c | |
470 | ||
9fe2bb77 RL |
471 | For any file to be built, it's also possible to tell what extra |
472 | include paths the build of their source files should use: | |
473 | ||
474 | INCLUDE[foo]=include | |
475 | ||
b96ab5e6 RL |
476 | It's also possible to specify C macros that should be defined: |
477 | ||
478 | DEFINE[foo]=FOO BAR=1 | |
479 | ||
ae4c7450 RL |
480 | In some cases, one might want to generate some source files from |
481 | others, that's done as follows: | |
482 | ||
483 | GENERATE[foo.s]=asm/something.pl $(CFLAGS) | |
484 | GENERATE[bar.s]=asm/bar.S | |
485 | ||
486 | The value of each GENERATE line is a command line or part of it. | |
436ad81f DB |
487 | Configure places no rules on the command line, except that the first |
488 | item must be the generator file. It is, however, entirely up to the | |
ae4c7450 RL |
489 | build file template to define exactly how those command lines should |
490 | be handled, how the output is captured and so on. | |
491 | ||
2036fd50 RL |
492 | Sometimes, the generator file itself depends on other files, for |
493 | example if it is a perl script that depends on other perl modules. | |
494 | This can be expressed using DEPEND like this: | |
495 | ||
496 | DEPEND[asm/something.pl]=../perlasm/Foo.pm | |
497 | ||
498 | There may also be cases where the exact file isn't easily specified, | |
499 | but an inclusion directory still needs to be specified. INCLUDE can | |
500 | be used in that case: | |
501 | ||
502 | INCLUDE[asm/something.pl]=../perlasm | |
503 | ||
ae4c7450 RL |
504 | NOTE: GENERATE lines are limited to one command only per GENERATE. |
505 | ||
506 | As a last resort, it's possible to have raw build file lines, between | |
507 | BEGINRAW and ENDRAW lines as follows: | |
9fe2bb77 RL |
508 | |
509 | BEGINRAW[Makefile(unix)] | |
510 | haha.h: {- $builddir -}/Makefile | |
511 | echo "/* haha */" > haha.h | |
512 | ENDRAW[Makefile(unix)] | |
513 | ||
60250017 | 514 | The word within square brackets is the build_file configuration item |
9fe2bb77 RL |
515 | or the build_file configuration item followed by the second word in the |
516 | build_scheme configuration item for the configured target within | |
517 | parenthesis as shown above. For example, with the following relevant | |
518 | configuration items: | |
519 | ||
520 | build_file => "build.ninja" | |
521 | build_scheme => [ "unified", "unix" ] | |
522 | ||
523 | ... these lines will be considered: | |
524 | ||
525 | BEGINRAW[build.ninja] | |
526 | build haha.h: echo "/* haha */" > haha.h | |
527 | ENDRAW[build.ninja] | |
528 | ||
529 | BEGINRAW[build.ninja(unix)] | |
530 | build hoho.h: echo "/* hoho */" > hoho.h | |
531 | ENDRAW[build.ninja(unix)] | |
532 | ||
8a67946e RL |
533 | Should it be needed because the recipes within a RAW section might |
534 | clash with those generated by Configure, it's possible to tell it | |
535 | not to generate them with the use of OVERRIDES, for example: | |
536 | ||
537 | SOURCE[libfoo]=foo.c bar.c | |
538 | ||
539 | OVERRIDES=bar.o | |
540 | BEGINRAW[Makefile(unix)] | |
541 | bar.o: bar.c | |
542 | $(CC) $(CFLAGS) -DSPECIAL -c -o $@ $< | |
543 | ENDRAW[Makefile(unix)] | |
544 | ||
9fe2bb77 RL |
545 | See the documentation further up for more information on configuration |
546 | items. | |
547 | ||
548 | Finally, you can have some simple conditional use of the build.info | |
549 | information, looking like this: | |
550 | ||
551 | IF[1] | |
552 | something | |
553 | ELSIF[2] | |
554 | something other | |
555 | ELSE | |
556 | something else | |
557 | ENDIF | |
558 | ||
559 | The expression in square brackets is interpreted as a string in perl, | |
560 | and will be seen as true if perl thinks it is, otherwise false. For | |
561 | example, the above would have "something" used, since 1 is true. | |
562 | ||
563 | Together with the use of Text::Template, this can be used as | |
564 | conditions based on something in the passed variables, for example: | |
565 | ||
84af1bae | 566 | IF[{- $disabled{shared} -}] |
9fe2bb77 RL |
567 | LIBS=libcrypto |
568 | SOURCE[libcrypto]=... | |
569 | ELSE | |
570 | LIBS=libfoo | |
571 | SOURCE[libfoo]=... | |
572 | ENDIF | |
573 | ||
574 | or: | |
575 | ||
576 | # VMS has a cultural standard where all libraries are prefixed. | |
577 | # For OpenSSL, the choice is 'ossl_' | |
578 | IF[{- $config{target} =~ /^vms/ -}] | |
579 | RENAME[libcrypto]=ossl_libcrypto | |
580 | RENAME[libssl]=ossl_libssl | |
581 | ENDIF | |
ddf1847d RL |
582 | |
583 | ||
584 | Build-file programming with the "unified" build system | |
585 | ====================================================== | |
586 | ||
587 | "Build files" are called "Makefile" on Unix-like operating systems, | |
588 | "descrip.mms" for MMS on VMS, "makefile" for nmake on Windows, etc. | |
589 | ||
590 | To use the "unified" build system, the target configuration needs to | |
591 | set the three items 'build_scheme', 'build_file' and 'build_command'. | |
592 | In the rest of this section, we will assume that 'build_scheme' is set | |
593 | to "unified" (see the configurations documentation above for the | |
594 | details). | |
595 | ||
596 | For any name given by 'build_file', the "unified" system expects a | |
597 | template file in Configurations/ named like the build file, with | |
598 | ".tmpl" appended, or in case of possible ambiguity, a combination of | |
599 | the second 'build_scheme' list item and the 'build_file' name. For | |
600 | example, if 'build_file' is set to "Makefile", the template could be | |
601 | Configurations/Makefile.tmpl or Configurations/unix-Makefile.tmpl. | |
602 | In case both Configurations/unix-Makefile.tmpl and | |
603 | Configurations/Makefile.tmpl are present, the former takes | |
604 | precedence. | |
605 | ||
606 | The build-file template is processed with the perl module | |
607 | Text::Template, using "{-" and "-}" as delimiters that enclose the | |
608 | perl code fragments that generate configuration-dependent content. | |
609 | Those perl fragments have access to all the hash variables from | |
610 | configdata.pem. | |
611 | ||
612 | The build-file template is expected to define at least the following | |
613 | perl functions in a perl code fragment enclosed with "{-" and "-}". | |
614 | They are all expected to return a string with the lines they produce. | |
615 | ||
ae4c7450 RL |
616 | generatesrc - function that produces build file lines to generate |
617 | a source file from some input. | |
618 | ||
619 | It's called like this: | |
620 | ||
621 | generatesrc(src => "PATH/TO/tobegenerated", | |
622 | generator => [ "generatingfile", ... ] | |
2036fd50 RL |
623 | generator_incs => [ "INCL/PATH", ... ] |
624 | generator_deps => [ "dep1", ... ] | |
e38bd948 RL |
625 | generator => [ "generatingfile", ... ] |
626 | incs => [ "INCL/PATH", ... ], | |
ae4c7450 RL |
627 | deps => [ "dep1", ... ], |
628 | intent => one of "libs", "dso", "bin" ); | |
629 | ||
630 | 'src' has the name of the file to be generated. | |
631 | 'generator' is the command or part of command to | |
632 | generate the file, of which the first item is | |
633 | expected to be the file to generate from. | |
634 | generatesrc() is expected to analyse and figure out | |
635 | exactly how to apply that file and how to capture | |
2036fd50 RL |
636 | the result. 'generator_incs' and 'generator_deps' |
637 | are include directories and files that the generator | |
638 | file itself depends on. 'incs' and 'deps' are | |
639 | include directories and files that are used if $(CC) | |
640 | is used as an intermediary step when generating the | |
641 | end product (the file indicated by 'src'). 'intent' | |
642 | indicates what the generated file is going to be | |
643 | used for. | |
ae4c7450 | 644 | |
ddf1847d RL |
645 | src2obj - function that produces build file lines to build an |
646 | object file from source files and associated data. | |
647 | ||
648 | It's called like this: | |
649 | ||
650 | src2obj(obj => "PATH/TO/objectfile", | |
651 | srcs => [ "PATH/TO/sourcefile", ... ], | |
652 | deps => [ "dep1", ... ], | |
45502bfe RL |
653 | incs => [ "INCL/PATH", ... ] |
654 | intent => one of "lib", "dso", "bin" ); | |
ddf1847d | 655 | |
aa343982 RL |
656 | 'obj' has the intended object file with '.o' |
657 | extension, src2obj() is expected to change it to | |
658 | something more suitable for the platform. | |
ddf1847d RL |
659 | 'srcs' has the list of source files to build the |
660 | object file, with the first item being the source | |
661 | file that directly corresponds to the object file. | |
50e83cdd | 662 | 'deps' is a list of explicit dependencies. 'incs' |
45502bfe RL |
663 | is a list of include file directories. Finally, |
664 | 'intent' indicates what this object file is going | |
665 | to be used for. | |
ddf1847d RL |
666 | |
667 | obj2lib - function that produces build file lines to build a | |
668 | static library file ("libfoo.a" in Unix terms) from | |
669 | object files. | |
670 | ||
671 | called like this: | |
672 | ||
673 | obj2lib(lib => "PATH/TO/libfile", | |
674 | objs => [ "PATH/TO/objectfile", ... ]); | |
675 | ||
676 | 'lib' has the intended library file name *without* | |
677 | extension, obj2lib is expected to add that. 'objs' | |
aa343982 | 678 | has the list of object files to build this library. |
ddf1847d | 679 | |
aa343982 RL |
680 | libobj2shlib - backward compatibility function that's used the |
681 | same way as obj2shlib (described next), and was | |
682 | expected to build the shared library from the | |
683 | corresponding static library when that was suitable. | |
684 | NOTE: building a shared library from a static | |
685 | library is now DEPRECATED, as they no longer share | |
686 | object files. Attempting to do this will fail. | |
687 | ||
688 | obj2shlib - function that produces build file lines to build a | |
ddf1847d | 689 | shareable object library file ("libfoo.so" in Unix |
aa343982 | 690 | terms) from the corresponding object files. |
ddf1847d RL |
691 | |
692 | called like this: | |
693 | ||
aa343982 RL |
694 | obj2shlib(shlib => "PATH/TO/shlibfile", |
695 | lib => "PATH/TO/libfile", | |
696 | objs => [ "PATH/TO/objectfile", ... ], | |
697 | deps => [ "PATH/TO/otherlibfile", ... ]); | |
ddf1847d | 698 | |
aa343982 RL |
699 | 'lib' has the base (static) library ffile name |
700 | *without* extension. This is useful in case | |
701 | supporting files are needed (such as import | |
702 | libraries on Windows). | |
b6453a68 | 703 | 'shlib' has the corresponding shared library name |
ddf1847d RL |
704 | *without* extension. 'deps' has the list of other |
705 | libraries (also *without* extension) this library | |
706 | needs to be linked with. 'objs' has the list of | |
aa343982 | 707 | object files to build this library. |
ddf1847d | 708 | |
5386287c RL |
709 | obj2dso - function that produces build file lines to build a |
710 | dynamic shared object file from object files. | |
ddf1847d RL |
711 | |
712 | called like this: | |
713 | ||
5386287c RL |
714 | obj2dso(lib => "PATH/TO/libfile", |
715 | objs => [ "PATH/TO/objectfile", ... ], | |
716 | deps => [ "PATH/TO/otherlibfile", | |
717 | ... ]); | |
ddf1847d | 718 | |
aa343982 | 719 | This is almost the same as obj2shlib, but the |
ddf1847d | 720 | intent is to build a shareable library that can be |
aa343982 | 721 | loaded in runtime (a "plugin"...). |
ddf1847d RL |
722 | |
723 | obj2bin - function that produces build file lines to build an | |
724 | executable file from object files. | |
725 | ||
726 | called like this: | |
727 | ||
728 | obj2bin(bin => "PATH/TO/binfile", | |
729 | objs => [ "PATH/TO/objectfile", ... ], | |
730 | deps => [ "PATH/TO/libfile", ... ]); | |
731 | ||
732 | 'bin' has the intended executable file name | |
733 | *without* extension, obj2bin is expected to add | |
aa343982 RL |
734 | that. 'objs' has the list of object files to build |
735 | this library. 'deps' has the list of library files | |
736 | (also *without* extension) that the programs needs | |
737 | to be linked with. | |
ddf1847d RL |
738 | |
739 | in2script - function that produces build file lines to build a | |
740 | script file from some input. | |
741 | ||
742 | called like this: | |
743 | ||
744 | in2script(script => "PATH/TO/scriptfile", | |
745 | sources => [ "PATH/TO/infile", ... ]); | |
746 | ||
747 | 'script' has the intended script file name. | |
748 | 'sources' has the list of source files to build the | |
749 | resulting script from. | |
750 | ||
751 | In all cases, file file paths are relative to the build tree top, and | |
752 | the build file actions run with the build tree top as current working | |
753 | directory. | |
754 | ||
755 | Make sure to end the section with these functions with a string that | |
b6453a68 | 756 | you thing is appropriate for the resulting build file. If nothing |
ddf1847d RL |
757 | else, end it like this: |
758 | ||
759 | ""; # Make sure no lingering values end up in the Makefile | |
760 | -} | |
44eb65ce RL |
761 | |
762 | ||
763 | Configure helper scripts | |
764 | ======================== | |
765 | ||
766 | Configure uses helper scripts in this directory: | |
767 | ||
768 | Checker scripts | |
769 | --------------- | |
770 | ||
771 | These scripts are per platform family, to check the integrity of the | |
772 | tools used for configuration and building. The checker script used is | |
773 | either {build_platform}-{build_file}-checker.pm or | |
774 | {build_platform}-checker.pm, where {build_platform} is the second | |
775 | 'build_scheme' list element from the configuration target data, and | |
776 | {build_file} is 'build_file' from the same target data. | |
777 | ||
778 | If the check succeeds, the script is expected to end with a non-zero | |
779 | expression. If the check fails, the script can end with a zero, or | |
780 | with a `die`. |