]>
Commit | Line | Data |
---|---|---|
9e0724a1 | 1 | Configurations of OpenSSL target platforms |
ddf1847d | 2 | ========================================== |
9e0724a1 RL |
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. | |
bcb1977b RL |
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. | |
9e0724a1 RL |
31 | shared_cflag => Extra compilation flags used when |
32 | compiling for shared libraries, typically | |
33 | something like "-fPIC". | |
34 | ||
c86ddbe6 RL |
35 | (linking is a complex thing, see [3] below) |
36 | ld => Linker command, usually not defined | |
9e0724a1 RL |
37 | (meaning the compiler command is used |
38 | instead). | |
39 | (NOTE: this is here for future use, it's | |
40 | not implemented yet) | |
c86ddbe6 RL |
41 | lflags => Flags that are used when linking apps. |
42 | shared_ldflag => Flags that are used when linking shared | |
43 | or dynamic libraries. | |
44 | plib_lflags => Extra linking flags to appear just before | |
45 | the libraries on the command line. | |
46 | ex_libs => Extra libraries that are needed when | |
47 | linking. | |
9e0724a1 | 48 | |
9e0724a1 RL |
49 | ar => The library archive command, the default is |
50 | "ar". | |
51 | (NOTE: this is here for future use, it's | |
52 | not implemented yet) | |
53 | arflags => Flags to be used with the library archive | |
54 | command. | |
55 | ||
56 | ranlib => The library archive indexing command, the | |
57 | default is 'ranlib' it it exists. | |
58 | ||
59 | unistd => An alternative header to the typical | |
60 | '<unistd.h>'. This is very rarely needed. | |
61 | ||
62 | shared_extension => File name extension used for shared | |
63 | libraries. | |
64 | obj_extension => File name extension used for object files. | |
65 | On unix, this defaults to ".o" (NOTE: this | |
66 | is here for future use, it's not | |
67 | implemented yet) | |
68 | exe_extension => File name extension used for executable | |
69 | files. On unix, this defaults to "" (NOTE: | |
70 | this is here for future use, it's not | |
71 | implemented yet) | |
72 | ||
2ad9ef06 RL |
73 | thread_scheme => The type of threads is used on the |
74 | configured platform. Currently known | |
75 | values are "(unknown)", "pthreads", | |
76 | "uithreads" (a.k.a solaris threads) and | |
77 | "winthreads". Except for "(unknown)", the | |
78 | actual value is currently ignored but may | |
79 | be used in the future. See further notes | |
80 | below [2]. | |
9e0724a1 RL |
81 | dso_scheme => The type of dynamic shared objects to build |
82 | for. This mostly comes into play with | |
83 | engines, but can be used for other purposes | |
84 | as well. Valid values are "DLFCN" | |
85 | (dlopen() et al), "DLFCN_NO_H" (for systems | |
86 | that use dlopen() et al but do not have | |
87 | fcntl.h), "DL" (shl_load() et al), "WIN32" | |
88 | and "VMS". | |
89 | perlasm_scheme => The perlasm method used to created the | |
90 | assembler files used when compiling with | |
91 | assembler implementations. | |
92 | shared_target => The shared library building method used. | |
93 | This is a target found in Makefile.shared. | |
94 | build_scheme => The scheme used to build up a Makefile. | |
88087414 RL |
95 | In its simplest form, the value is a string |
96 | with the name of the build scheme. | |
97 | The value may also take the form of a list | |
98 | of strings, if the build_scheme is to have | |
99 | some options. In this case, the first | |
100 | string in the list is the name of the build | |
101 | scheme. | |
45c6e23c | 102 | Currently recognised build scheme is "unified". |
9fe2bb77 RL |
103 | For the "unified" build scheme, this item |
104 | *must* be an array with the first being the | |
105 | word "unified" and the second being a word | |
106 | to identify the platform family. | |
9e0724a1 RL |
107 | |
108 | multilib => On systems that support having multiple | |
109 | implementations of a library (typically a | |
110 | 32-bit and a 64-bit variant), this is used | |
111 | to have the different variants in different | |
112 | directories. | |
113 | ||
114 | bn_ops => Building options (was just bignum options | |
115 | in the earlier history of this option, | |
116 | hence the name). This a string of words | |
117 | that describe properties on the designated | |
118 | target platform, such as the type of | |
119 | integers used to build up the bitnum, | |
120 | different ways to implement certain ciphers | |
121 | and so on. To fully comprehend the | |
122 | meaning, the best is to read the affected | |
123 | source. | |
124 | The valid words are: | |
125 | ||
9e0724a1 RL |
126 | BN_LLONG use 'unsigned long long' in |
127 | some bignum calculations. | |
128 | This has no value when | |
129 | SIXTY_FOUR_BIT or | |
130 | SIXTY_FOUR_BIT_LONG is given. | |
3e9e810f | 131 | RC4_CHAR makes the basic RC4 unit of |
9e0724a1 | 132 | calculation an unsigned char. |
9e0724a1 RL |
133 | SIXTY_FOUR_BIT processor registers |
134 | are 64 bits, long is | |
135 | 32 bits, long long is | |
136 | 64 bits. | |
137 | SIXTY_FOUR_BIT_LONG processor registers | |
138 | are 64 bits, long is | |
139 | 64 bits. | |
140 | THIRTY_TWO_BIT processor registers | |
141 | are 32 bits. | |
142 | EXPORT_VAR_AS_FN for shared libraries, | |
143 | export vars as | |
144 | accessor functions. | |
145 | ||
e84193e4 RL |
146 | apps_extra_src => Extra source to build apps/openssl, as |
147 | needed by the target. | |
9fe2bb77 | 148 | cpuid_asm_src => assembler implementation of cpuid code as |
9e0724a1 | 149 | well as OPENSSL_cleanse(). |
9fe2bb77 RL |
150 | Default to mem_clr.c |
151 | bn_asm_src => Assembler implementation of core bignum | |
9e0724a1 | 152 | functions. |
9fe2bb77 RL |
153 | Defaults to bn_asm.c |
154 | ec_asm_src => Assembler implementation of core EC | |
9e0724a1 | 155 | functions. |
9fe2bb77 | 156 | des_asm_src => Assembler implementation of core DES |
9e0724a1 | 157 | encryption functions. |
9fe2bb77 RL |
158 | Defaults to 'des_enc.c fcrypt_b.c' |
159 | aes_asm_src => Assembler implementation of core AES | |
9e0724a1 | 160 | functions. |
9fe2bb77 RL |
161 | Defaults to 'aes_core.c aes_cbc.c' |
162 | bf_asm_src => Assembler implementation of core BlowFish | |
9e0724a1 | 163 | functions. |
9fe2bb77 RL |
164 | Defaults to 'bf_enc.c' |
165 | md5_asm_src => Assembler implementation of core MD5 | |
9e0724a1 | 166 | functions. |
9fe2bb77 | 167 | sha1_asm_src => Assembler implementation of core SHA1, |
9e0724a1 RL |
168 | functions, and also possibly SHA256 and |
169 | SHA512 ones. | |
9fe2bb77 | 170 | cast_asm_src => Assembler implementation of core CAST |
9e0724a1 | 171 | functions. |
9fe2bb77 RL |
172 | Defaults to 'c_enc.c' |
173 | rc4_asm_src => Assembler implementation of core RC4 | |
9e0724a1 | 174 | functions. |
9fe2bb77 RL |
175 | Defaults to 'rc4_enc.c rc4_skey.c' |
176 | rmd160_asm_src => Assembler implementation of core RMD160 | |
9e0724a1 | 177 | functions. |
9fe2bb77 | 178 | rc5_asm_src => Assembler implementation of core RC5 |
9e0724a1 | 179 | functions. |
9fe2bb77 RL |
180 | Defaults to 'rc5_enc.c' |
181 | wp_asm_src => Assembler implementation of core WHIRLPOOL | |
9e0724a1 | 182 | functions. |
9fe2bb77 | 183 | cmll_asm_src => Assembler implementation of core CAMELLIA |
9e0724a1 | 184 | functions. |
9fe2bb77 RL |
185 | Defaults to 'camellia.c cmll_misc.c cmll_cbc.c' |
186 | modes_asm_src => Assembler implementation of cipher modes, | |
187 | currently the functions gcm_gmult_4bit and | |
188 | gcm_ghash_4bit. | |
189 | padlock_asm_src => Assembler implementation of core parts of | |
9e0724a1 RL |
190 | the padlock engine. This is mandatory on |
191 | any platform where the padlock engine might | |
192 | actually be built. | |
193 | ||
194 | ||
195 | [1] as part of the target configuration, one can have a key called | |
196 | 'inherit_from' that indicate what other configurations to inherit | |
197 | data from. These are resolved recursively. | |
198 | ||
b6453a68 | 199 | Inheritance works as a set of default values that can be overridden |
9e0724a1 RL |
200 | by corresponding key values in the inheriting configuration. |
201 | ||
202 | Note 1: any configuration table can be used as a template. | |
203 | Note 2: pure templates have the attribute 'template => 1' and | |
204 | cannot be used as build targets. | |
205 | ||
206 | If several configurations are given in the 'inherit_from' array, | |
207 | the values of same attribute are concatenated with space | |
208 | separation. With this, it's possible to have several smaller | |
209 | templates for different configuration aspects that can be combined | |
210 | into a complete configuration. | |
211 | ||
212 | instead of a scalar value or an array, a value can be a code block | |
213 | of the form 'sub { /* your code here */ }'. This code block will | |
214 | be called with the list of inherited values for that key as | |
215 | arguments. In fact, the concatenation of strings is really done | |
216 | by using 'sub { join(" ",@_) }' on the list of inherited values. | |
217 | ||
218 | An example: | |
219 | ||
220 | "foo" => { | |
221 | template => 1, | |
222 | haha => "ha ha", | |
223 | hoho => "ho", | |
224 | ignored => "This should not appear in the end result", | |
225 | }, | |
226 | "bar" => { | |
227 | template => 1, | |
228 | haha => "ah", | |
229 | hoho => "haho", | |
230 | hehe => "hehe" | |
231 | }, | |
232 | "laughter" => { | |
233 | inherit_from => [ "foo", "bar" ], | |
234 | hehe => sub { join(" ",(@_,"!!!")) }, | |
235 | ignored => "", | |
236 | } | |
237 | ||
238 | The entry for "laughter" will become as follows after processing: | |
239 | ||
240 | "laughter" => { | |
241 | haha => "ha ha ah", | |
242 | hoho => "ho haho", | |
243 | hehe => "hehe !!!", | |
244 | ignored => "" | |
245 | } | |
246 | ||
247 | [2] OpenSSL is built with threading capabilities unless the user | |
2ad9ef06 | 248 | specifies 'no-threads'. The value of the key 'thread_scheme' may |
9e0724a1 RL |
249 | be "(unknown)", in which case the user MUST give some compilation |
250 | flags to Configure. | |
251 | ||
c86ddbe6 RL |
252 | [3] OpenSSL has three types of things to link from object files or |
253 | static libraries: | |
254 | ||
255 | - shared libraries; that would be libcrypto and libssl. | |
256 | - shared objects (sometimes called dynamic libraries); that would | |
257 | be the engines. | |
258 | - applications; those are apps/openssl and all the test apps. | |
259 | ||
260 | Very roughly speaking, linking is done like this (words in braces | |
261 | represent the configuration settings documented at the beginning | |
262 | of this file): | |
263 | ||
264 | shared libraries: | |
265 | {ld} $(CFLAGS) {shared_ldflag} -shared -o libfoo.so \ | |
266 | -Wl,--whole-archive libfoo.a -Wl,--no-whole-archive \ | |
267 | {plib_lflags} -lcrypto {ex_libs} | |
268 | ||
269 | shared objects: | |
270 | {ld} $(CFLAGS) {shared_ldflag} -shared -o libeng.so \ | |
271 | blah1.o blah2.o {plib_lflags} -lcrypto {ex_libs} | |
272 | ||
273 | applications: | |
274 | {ld} $(CFLAGS) {lflags} -o app \ | |
275 | app1.o utils.o {plib_lflags} -lssl -lcrypto {ex_libs} | |
276 | ||
9e0724a1 RL |
277 | |
278 | Historically, the target configurations came in form of a string with | |
df71f0b8 RL |
279 | values separated by colons. This use is deprecated. The string form |
280 | looked like this: | |
9e0724a1 | 281 | |
f0bd4686 | 282 | "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 |
283 | |
284 | ||
285 | Build info files | |
286 | ================ | |
287 | ||
288 | The build.info files that are spread over the source tree contain the | |
289 | minimum information needed to build and distribute OpenSSL. It uses a | |
290 | simple and yet fairly powerful language to determine what needs to be | |
291 | built, from what sources, and other relationships between files. | |
292 | ||
293 | For every build.info file, all file references are relative to the | |
294 | directory of the build.info file for source files, and the | |
295 | corresponding build directory for built files if the build tree | |
296 | differs from the source tree. | |
297 | ||
298 | When processed, every line is processed with the perl module | |
299 | Text::Template, using the delimiters "{-" and "-}". The hashes | |
300 | %config and %target are passed to the perl fragments, along with | |
301 | $sourcedir and $builddir, which are the locations of the source | |
302 | directory for the current build.info file and the corresponding build | |
303 | directory, all relative to the top of the build tree. | |
304 | ||
305 | To begin with, things to be built are declared by setting specific | |
306 | variables: | |
307 | ||
308 | PROGRAMS=foo bar | |
309 | LIBS=libsomething | |
310 | ENGINES=libeng | |
311 | SCRIPTS=myhack | |
312 | EXTRA=file1 file2 | |
313 | ||
314 | Note that the files mentioned for PROGRAMS, LIBS and ENGINES *must* be | |
315 | without extensions. The build file templates will figure them out. | |
316 | ||
317 | For each thing to be built, it is then possible to say what sources | |
318 | they are built from: | |
319 | ||
320 | PROGRAMS=foo bar | |
321 | SOURCE[foo]=foo.c common.c | |
322 | SOURCE[bar]=bar.c extra.c common.c | |
323 | ||
324 | It's also possible to tell some other dependencies: | |
325 | ||
326 | DEPEND[foo]=libsomething | |
327 | DEPEND[libbar]=libsomethingelse | |
328 | ||
329 | (it could be argued that 'libsomething' and 'libsomethingelse' are | |
330 | source as well. However, the files given through SOURCE are expected | |
331 | to be located in the source tree while files given through DEPEND are | |
332 | expected to be located in the build tree) | |
333 | ||
334 | For some libraries, we maintain files with public symbols and their | |
335 | slot in a transfer vector (important on some platforms). It can be | |
336 | declared like this: | |
337 | ||
338 | ORDINALS[libcrypto]=crypto | |
339 | ||
340 | The value is not the name of the file in question, but rather the | |
341 | argument to util/mkdef.pl that indicates which file to use. | |
342 | ||
343 | One some platforms, shared libraries come with a name that's different | |
344 | from their static counterpart. That's declared as follows: | |
345 | ||
346 | SHARED_NAME[libfoo]=cygfoo-{- $config{shlibver} -} | |
347 | ||
348 | The example is from Cygwin, which has a required naming convention. | |
349 | ||
350 | Sometimes, it makes sense to rename an output file, for example a | |
351 | library: | |
352 | ||
353 | RENAME[libfoo]=libbar | |
354 | ||
355 | That lines has "libfoo" get renamed to "libbar". While it makes no | |
356 | sense at all to just have a rename like that (why not just use | |
357 | "libbar" everywhere?), it does make sense when it can be used | |
358 | conditionally. See a little further below for an example. | |
359 | ||
2a08d1a0 RL |
360 | In some cases, it's desirable to include some source files in the |
361 | shared form of a library only: | |
362 | ||
363 | SHARED_SOURCE[libfoo]=dllmain.c | |
364 | ||
9fe2bb77 RL |
365 | For any file to be built, it's also possible to tell what extra |
366 | include paths the build of their source files should use: | |
367 | ||
368 | INCLUDE[foo]=include | |
369 | ||
ae4c7450 RL |
370 | In some cases, one might want to generate some source files from |
371 | others, that's done as follows: | |
372 | ||
373 | GENERATE[foo.s]=asm/something.pl $(CFLAGS) | |
374 | GENERATE[bar.s]=asm/bar.S | |
375 | ||
376 | The value of each GENERATE line is a command line or part of it. | |
377 | Configure places no rules on the command line, except the the first | |
378 | item muct be the generator file. It is, however, entirely up to the | |
379 | build file template to define exactly how those command lines should | |
380 | be handled, how the output is captured and so on. | |
381 | ||
2036fd50 RL |
382 | Sometimes, the generator file itself depends on other files, for |
383 | example if it is a perl script that depends on other perl modules. | |
384 | This can be expressed using DEPEND like this: | |
385 | ||
386 | DEPEND[asm/something.pl]=../perlasm/Foo.pm | |
387 | ||
388 | There may also be cases where the exact file isn't easily specified, | |
389 | but an inclusion directory still needs to be specified. INCLUDE can | |
390 | be used in that case: | |
391 | ||
392 | INCLUDE[asm/something.pl]=../perlasm | |
393 | ||
ae4c7450 RL |
394 | NOTE: GENERATE lines are limited to one command only per GENERATE. |
395 | ||
396 | As a last resort, it's possible to have raw build file lines, between | |
397 | BEGINRAW and ENDRAW lines as follows: | |
9fe2bb77 RL |
398 | |
399 | BEGINRAW[Makefile(unix)] | |
400 | haha.h: {- $builddir -}/Makefile | |
401 | echo "/* haha */" > haha.h | |
402 | ENDRAW[Makefile(unix)] | |
403 | ||
60250017 | 404 | The word within square brackets is the build_file configuration item |
9fe2bb77 RL |
405 | or the build_file configuration item followed by the second word in the |
406 | build_scheme configuration item for the configured target within | |
407 | parenthesis as shown above. For example, with the following relevant | |
408 | configuration items: | |
409 | ||
410 | build_file => "build.ninja" | |
411 | build_scheme => [ "unified", "unix" ] | |
412 | ||
413 | ... these lines will be considered: | |
414 | ||
415 | BEGINRAW[build.ninja] | |
416 | build haha.h: echo "/* haha */" > haha.h | |
417 | ENDRAW[build.ninja] | |
418 | ||
419 | BEGINRAW[build.ninja(unix)] | |
420 | build hoho.h: echo "/* hoho */" > hoho.h | |
421 | ENDRAW[build.ninja(unix)] | |
422 | ||
8a67946e RL |
423 | Should it be needed because the recipes within a RAW section might |
424 | clash with those generated by Configure, it's possible to tell it | |
425 | not to generate them with the use of OVERRIDES, for example: | |
426 | ||
427 | SOURCE[libfoo]=foo.c bar.c | |
428 | ||
429 | OVERRIDES=bar.o | |
430 | BEGINRAW[Makefile(unix)] | |
431 | bar.o: bar.c | |
432 | $(CC) $(CFLAGS) -DSPECIAL -c -o $@ $< | |
433 | ENDRAW[Makefile(unix)] | |
434 | ||
9fe2bb77 RL |
435 | See the documentation further up for more information on configuration |
436 | items. | |
437 | ||
438 | Finally, you can have some simple conditional use of the build.info | |
439 | information, looking like this: | |
440 | ||
441 | IF[1] | |
442 | something | |
443 | ELSIF[2] | |
444 | something other | |
445 | ELSE | |
446 | something else | |
447 | ENDIF | |
448 | ||
449 | The expression in square brackets is interpreted as a string in perl, | |
450 | and will be seen as true if perl thinks it is, otherwise false. For | |
451 | example, the above would have "something" used, since 1 is true. | |
452 | ||
453 | Together with the use of Text::Template, this can be used as | |
454 | conditions based on something in the passed variables, for example: | |
455 | ||
84af1bae | 456 | IF[{- $disabled{shared} -}] |
9fe2bb77 RL |
457 | LIBS=libcrypto |
458 | SOURCE[libcrypto]=... | |
459 | ELSE | |
460 | LIBS=libfoo | |
461 | SOURCE[libfoo]=... | |
462 | ENDIF | |
463 | ||
464 | or: | |
465 | ||
466 | # VMS has a cultural standard where all libraries are prefixed. | |
467 | # For OpenSSL, the choice is 'ossl_' | |
468 | IF[{- $config{target} =~ /^vms/ -}] | |
469 | RENAME[libcrypto]=ossl_libcrypto | |
470 | RENAME[libssl]=ossl_libssl | |
471 | ENDIF | |
ddf1847d RL |
472 | |
473 | ||
474 | Build-file programming with the "unified" build system | |
475 | ====================================================== | |
476 | ||
477 | "Build files" are called "Makefile" on Unix-like operating systems, | |
478 | "descrip.mms" for MMS on VMS, "makefile" for nmake on Windows, etc. | |
479 | ||
480 | To use the "unified" build system, the target configuration needs to | |
481 | set the three items 'build_scheme', 'build_file' and 'build_command'. | |
482 | In the rest of this section, we will assume that 'build_scheme' is set | |
483 | to "unified" (see the configurations documentation above for the | |
484 | details). | |
485 | ||
486 | For any name given by 'build_file', the "unified" system expects a | |
487 | template file in Configurations/ named like the build file, with | |
488 | ".tmpl" appended, or in case of possible ambiguity, a combination of | |
489 | the second 'build_scheme' list item and the 'build_file' name. For | |
490 | example, if 'build_file' is set to "Makefile", the template could be | |
491 | Configurations/Makefile.tmpl or Configurations/unix-Makefile.tmpl. | |
492 | In case both Configurations/unix-Makefile.tmpl and | |
493 | Configurations/Makefile.tmpl are present, the former takes | |
494 | precedence. | |
495 | ||
496 | The build-file template is processed with the perl module | |
497 | Text::Template, using "{-" and "-}" as delimiters that enclose the | |
498 | perl code fragments that generate configuration-dependent content. | |
499 | Those perl fragments have access to all the hash variables from | |
500 | configdata.pem. | |
501 | ||
502 | The build-file template is expected to define at least the following | |
503 | perl functions in a perl code fragment enclosed with "{-" and "-}". | |
504 | They are all expected to return a string with the lines they produce. | |
505 | ||
ae4c7450 RL |
506 | generatesrc - function that produces build file lines to generate |
507 | a source file from some input. | |
508 | ||
509 | It's called like this: | |
510 | ||
511 | generatesrc(src => "PATH/TO/tobegenerated", | |
512 | generator => [ "generatingfile", ... ] | |
2036fd50 RL |
513 | generator_incs => [ "INCL/PATH", ... ] |
514 | generator_deps => [ "dep1", ... ] | |
e38bd948 RL |
515 | generator => [ "generatingfile", ... ] |
516 | incs => [ "INCL/PATH", ... ], | |
ae4c7450 RL |
517 | deps => [ "dep1", ... ], |
518 | intent => one of "libs", "dso", "bin" ); | |
519 | ||
520 | 'src' has the name of the file to be generated. | |
521 | 'generator' is the command or part of command to | |
522 | generate the file, of which the first item is | |
523 | expected to be the file to generate from. | |
524 | generatesrc() is expected to analyse and figure out | |
525 | exactly how to apply that file and how to capture | |
2036fd50 RL |
526 | the result. 'generator_incs' and 'generator_deps' |
527 | are include directories and files that the generator | |
528 | file itself depends on. 'incs' and 'deps' are | |
529 | include directories and files that are used if $(CC) | |
530 | is used as an intermediary step when generating the | |
531 | end product (the file indicated by 'src'). 'intent' | |
532 | indicates what the generated file is going to be | |
533 | used for. | |
ae4c7450 | 534 | |
ddf1847d RL |
535 | src2obj - function that produces build file lines to build an |
536 | object file from source files and associated data. | |
537 | ||
538 | It's called like this: | |
539 | ||
540 | src2obj(obj => "PATH/TO/objectfile", | |
541 | srcs => [ "PATH/TO/sourcefile", ... ], | |
542 | deps => [ "dep1", ... ], | |
45502bfe RL |
543 | incs => [ "INCL/PATH", ... ] |
544 | intent => one of "lib", "dso", "bin" ); | |
ddf1847d RL |
545 | |
546 | 'obj' has the intended object file *without* | |
547 | extension, src2obj() is expected to add that. | |
548 | 'srcs' has the list of source files to build the | |
549 | object file, with the first item being the source | |
550 | file that directly corresponds to the object file. | |
50e83cdd | 551 | 'deps' is a list of explicit dependencies. 'incs' |
45502bfe RL |
552 | is a list of include file directories. Finally, |
553 | 'intent' indicates what this object file is going | |
554 | to be used for. | |
ddf1847d RL |
555 | |
556 | obj2lib - function that produces build file lines to build a | |
557 | static library file ("libfoo.a" in Unix terms) from | |
558 | object files. | |
559 | ||
560 | called like this: | |
561 | ||
562 | obj2lib(lib => "PATH/TO/libfile", | |
563 | objs => [ "PATH/TO/objectfile", ... ]); | |
564 | ||
565 | 'lib' has the intended library file name *without* | |
566 | extension, obj2lib is expected to add that. 'objs' | |
567 | has the list of object files (also *without* | |
568 | extension) to build this library. | |
569 | ||
570 | libobj2shlib - function that produces build file lines to build a | |
571 | shareable object library file ("libfoo.so" in Unix | |
572 | terms) from the corresponding static library file | |
573 | or object files. | |
574 | ||
575 | called like this: | |
576 | ||
577 | libobj2shlib(shlib => "PATH/TO/shlibfile", | |
578 | lib => "PATH/TO/libfile", | |
579 | objs => [ "PATH/TO/objectfile", ... ], | |
580 | deps => [ "PATH/TO/otherlibfile", ... ], | |
581 | ordinals => [ "word", "/PATH/TO/ordfile" ]); | |
582 | ||
583 | 'lib' has the intended library file name *without* | |
584 | extension, libobj2shlib is expected to add that. | |
b6453a68 | 585 | 'shlib' has the corresponding shared library name |
ddf1847d RL |
586 | *without* extension. 'deps' has the list of other |
587 | libraries (also *without* extension) this library | |
588 | needs to be linked with. 'objs' has the list of | |
589 | object files (also *without* extension) to build | |
590 | this library. 'ordinals' MAY be present, and when | |
591 | it is, its value is an array where the word is | |
592 | "crypto" or "ssl" and the file is one of the ordinal | |
593 | files util/libeay.num or util/ssleay.num in the | |
594 | source directory. | |
595 | ||
596 | This function has a choice; it can use the | |
597 | corresponding static library as input to make the | |
598 | shared library, or the list of object files. | |
599 | ||
5386287c RL |
600 | obj2dso - function that produces build file lines to build a |
601 | dynamic shared object file from object files. | |
ddf1847d RL |
602 | |
603 | called like this: | |
604 | ||
5386287c RL |
605 | obj2dso(lib => "PATH/TO/libfile", |
606 | objs => [ "PATH/TO/objectfile", ... ], | |
607 | deps => [ "PATH/TO/otherlibfile", | |
608 | ... ]); | |
ddf1847d RL |
609 | |
610 | This is almost the same as libobj2shlib, but the | |
611 | intent is to build a shareable library that can be | |
612 | loaded in runtime (a "plugin"...). The differences | |
613 | are subtle, one of the most visible ones is that the | |
614 | resulting shareable library is produced from object | |
615 | files only. | |
616 | ||
617 | obj2bin - function that produces build file lines to build an | |
618 | executable file from object files. | |
619 | ||
620 | called like this: | |
621 | ||
622 | obj2bin(bin => "PATH/TO/binfile", | |
623 | objs => [ "PATH/TO/objectfile", ... ], | |
624 | deps => [ "PATH/TO/libfile", ... ]); | |
625 | ||
626 | 'bin' has the intended executable file name | |
627 | *without* extension, obj2bin is expected to add | |
628 | that. 'objs' has the list of object files (also | |
629 | *without* extension) to build this library. 'deps' | |
630 | has the list of library files (also *without* | |
631 | extension) that the programs needs to be linked | |
632 | with. | |
633 | ||
634 | in2script - function that produces build file lines to build a | |
635 | script file from some input. | |
636 | ||
637 | called like this: | |
638 | ||
639 | in2script(script => "PATH/TO/scriptfile", | |
640 | sources => [ "PATH/TO/infile", ... ]); | |
641 | ||
642 | 'script' has the intended script file name. | |
643 | 'sources' has the list of source files to build the | |
644 | resulting script from. | |
645 | ||
646 | In all cases, file file paths are relative to the build tree top, and | |
647 | the build file actions run with the build tree top as current working | |
648 | directory. | |
649 | ||
650 | Make sure to end the section with these functions with a string that | |
b6453a68 | 651 | you thing is appropriate for the resulting build file. If nothing |
ddf1847d RL |
652 | else, end it like this: |
653 | ||
654 | ""; # Make sure no lingering values end up in the Makefile | |
655 | -} |