]>
Commit | Line | Data |
---|---|---|
e20ba0a5 RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | build.info - Building information files | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | B<IF[>0|1B<]> | |
10 | ||
11 | B<ELSIF[>0|1B<]> | |
12 | ||
13 | B<ELSE> | |
14 | ||
15 | B<ENDIF> | |
16 | ||
17 | B<SUBDIRS=> I<dir> ... | |
18 | ||
19 | B<PROGRAMS=> I<name> ... | |
20 | ||
21 | B<LIBS=> I<name> ... | |
22 | ||
23 | B<MODULES=> I<name> ... | |
24 | ||
25 | B<SCRIPTS=> I<name> ... | |
26 | ||
27 | B<DEPEND[>I<item>B<]=> I<otheritem> ... | |
28 | ||
29 | B<GENERATE[>I<item>B<]=> I<generator> I<generator-args> ... | |
30 | ||
31 | B<SOURCE[>I<item>B<]=> I<file> ... | |
32 | ||
33 | B<SHARED_SOURCE[>I<item>B<]=> I<file> ... | |
34 | ||
35 | B<DEFINE[>I<item>B<]=> I<name>[B<=>I<value>] ... | |
36 | ||
37 | B<INCLUDE[>I<item>B<]=> I<dir> ... | |
38 | ||
39 | B<$>I<VARIABLE>B<=>I<value> | |
40 | ||
41 | =head1 DESCRIPTION | |
42 | ||
43 | OpenSSL's build system revolves around three questions: | |
44 | ||
45 | =over 4 | |
46 | ||
47 | =item What to build for? | |
48 | ||
49 | This is about choice of platform (combination of hardware, operating | |
50 | system, and toolchain). | |
51 | ||
52 | =item What to build? | |
53 | ||
54 | This is about having all the information on what needs to be built and | |
55 | from what. | |
56 | ||
57 | =item How to build it? | |
58 | ||
59 | This is about build file generation. | |
60 | ||
61 | =back | |
62 | ||
63 | This document is all about the second item, "What to build?", and most | |
64 | of all, how to specify that information. | |
65 | ||
66 | For some terms used in this document, please see the L</GLOSSARY> at | |
67 | the end. | |
68 | ||
69 | =head2 F<build.info> files | |
70 | ||
71 | F<build.info> files are meta data files for OpenSSL's built file | |
72 | generators, and are used to specify exactly what end product files | |
73 | (programs, libraries, modules or scripts) are to be produced, and from | |
74 | what sources. | |
75 | ||
79c44b4e | 76 | Intermediate files, such as object files, are seldom referred to at |
e20ba0a5 RL |
77 | all. They sometimes can be, if there's a need, but this should happen |
78 | very rarely, and support for that sort of thing is added on as-needed | |
79 | basis. | |
80 | ||
81 | Any time a directory or file is expected in a statement value, Unix | |
82 | syntax must be used, which means that the slash C</> must be used as | |
83 | the directory separator. | |
84 | ||
85 | =head2 General syntax | |
86 | ||
87 | =head3 Comments | |
88 | ||
89 | Comments are any line that start with a hash sign (C<#>). The hash | |
90 | sign may be preceded by any number of horizontal spaces. | |
91 | ||
92 | =head3 Filenames | |
93 | ||
94 | F<build.info> files are platform agnostic. This means that there is | |
95 | some information in them that is representative rather than specific. | |
96 | ||
97 | This is particularly visible with end product names, they work more | |
98 | like a tag than as the actual filename that's going to be produced. | |
99 | This is because different platforms have different decorations on | |
100 | different types of files. | |
101 | ||
102 | For example, if we say that we want to produce a program C<foo>, it | |
103 | would look like this: | |
104 | ||
105 | PROGRAM=foo | |
106 | ||
107 | However, the program filename may end up being just C<foo> (typical | |
108 | for Unix), or C<foo.exe> (typical for Windows), or even C<BLAH$FOO.EXE> | |
109 | (possible on VMS, depending on policy). | |
110 | ||
111 | These platform specific decorations are not the concern of | |
112 | F<build.info> files. The build file generators are responsible for | |
113 | transforming these platform agnostic names to their platform specific | |
114 | counterparts. | |
115 | ||
116 | =head3 Statements | |
117 | ||
118 | With the exception of variables and conditions, the general statement | |
119 | syntax is one of: | |
120 | ||
121 | =over 4 | |
122 | ||
123 | =item B<I<KEYWORD>> B<=> I<value> ... | |
124 | ||
125 | =item B<I<KEYWORD>[>I<item>B<]> B<=> I<value> ... | |
126 | ||
127 | =back | |
128 | ||
129 | Every B<I<KEYWORD>> represents some particular type of information. | |
130 | ||
131 | The first form (sometimes called "plain statement") is used to specify | |
132 | information on what end products need to be built, for example: | |
133 | ||
134 | PROGRAMS=foo bar | |
135 | LIBS=libpoly libcookie | |
136 | MODULES=awesome-plugin | |
137 | SCRIPTS=tool1 tool2 | |
138 | SUBDIRS=dir1 dir2 | |
139 | ||
140 | This says that we want to build programs C<foo> and C<bar>, the | |
141 | libraries C<libpoly> and C<libcookie>, an awesome plugin module | |
142 | C<awesome-plugin>, a couple of scripts C<tool1> and C<tool2>, and | |
143 | finally that there are more F<build.info> files in subdirectories | |
144 | C<dir1> and C<dir2>. | |
145 | ||
146 | The second form (sometimes called "indexed statement") is used to | |
147 | specify further details for existing items, for example: | |
148 | ||
149 | SOURCE[foo]=foo.c details.c | |
150 | DEPEND[foo]=libcookie | |
151 | ||
152 | This says that the program C<foo> is built from the source files | |
153 | F<foo.c> and F<details.c>, and that it depends on the library | |
154 | C<libcookie> (in other words, the library will be included when | |
155 | linking that program together). | |
156 | ||
157 | For any indexed statement for which the item hasn't been specified | |
158 | through any plain statement, or where the item exists but the indexed | |
159 | statement does not apply, the value is simply ignored by the build | |
160 | file generators. | |
161 | ||
162 | =head3 Statement attributes | |
163 | ||
164 | Some statements can have attributes added to them, to allow for | |
165 | variations on how they are treated. | |
166 | ||
167 | =over 4 | |
168 | ||
7c3ccd7f | 169 | =item B<I<KEYWORD>{> I<attrib> | I<attrib>B<=>I<attrib-value> [,...]B<}> |
e20ba0a5 RL |
170 | B<=> I<value> ... |
171 | ||
7c3ccd7f RL |
172 | =item B<I<KEYWORD>[>I<item>B<]{> I<attrib> | I<attrib>B<=>I<attrib-value> |
173 | [,...]B<}> B<=> I<value> ... | |
174 | ||
e20ba0a5 RL |
175 | =back |
176 | ||
177 | Attributes are passed as they are to the build file generators, and | |
178 | the exact interpretation of those attributes is entirely up to them | |
179 | (see L</Known attributes> below for details). | |
180 | ||
181 | A current example: | |
182 | ||
183 | LIBS{noinst,has_main}=libtestutil.a | |
184 | ||
185 | This says that the static library C<libtestutil.a> should not be | |
186 | installed (C<noinst>), and that it includes an object file that has | |
187 | the C<main> symbol (C<has_main>). Most platforms don't need to know | |
188 | the latter, but there are some where the program linker will not look | |
189 | for C<main> in libraries unless it's explicitly told so, so this is | |
190 | way to tell the build file generator to emit the necessary command | |
191 | options to make that happen. | |
192 | ||
193 | Attributes are accumulated globally. This means that a library could | |
194 | be given like this in different places: | |
195 | ||
196 | # Location 1 | |
197 | LIBS=libwhatever | |
198 | ||
199 | # Location 2 | |
200 | LIBS{noinst}=libwhatever | |
201 | ||
202 | # Location 3 | |
203 | LIBS{has_main}=libwhatever | |
204 | ||
205 | The end result is that the library C<libwhatever> will have the | |
206 | attributes C<noinst> and C<has_main> attached to it. | |
207 | ||
208 | =head3 Quoting and tokens | |
209 | ||
210 | Statement values are normally split into a list of tokens, separated | |
211 | by spaces. | |
212 | ||
213 | To avoid having a value split up into several tokens, they may be | |
214 | quoted with double (C<">) or single (C<'>) quotes. | |
215 | ||
216 | For example: | |
217 | ||
218 | PROGRAMS=foo "space cadet" bar | |
219 | ||
220 | This says that we sant to build three programs, C<foo>, C<space cadet> | |
221 | and C<bar>. | |
222 | ||
223 | =head3 Conditionals | |
224 | ||
225 | F<build.info> files include a very simple condition system, involving | |
226 | the following keywords: | |
227 | ||
228 | =over 4 | |
229 | ||
230 | =item B<IF[>0|1B<]> | |
231 | ||
232 | =item B<ELSIF[>0|1B<]> | |
233 | ||
234 | =item B<ELSE> | |
235 | ||
236 | =item B<ENDIF> | |
237 | ||
238 | =back | |
239 | ||
240 | This works like any condition system with similar syntax, and the | |
241 | condition value in B<IF> and B<ELSIF> can really be any literal value | |
242 | that perl can interpret as true or false. | |
243 | ||
244 | Conditional statements are nesting. | |
245 | ||
246 | In itself, this is not very powerful, but together with L</Perl nuggets>, | |
247 | it can be. | |
248 | ||
249 | =head3 Variables | |
250 | ||
251 | F<build.info> handles simple variables. They are defined by | |
252 | assignment: | |
253 | ||
254 | =over 4 | |
255 | ||
256 | =item B<$>I<NAME> B<=> I<value> | |
257 | ||
258 | =back | |
259 | ||
260 | These variables can then be used as part of any statement value or | |
261 | indexed statement item. This should be used with some care, as | |
262 | I<variables are expanded into their values before the value they are | |
263 | part of is tokenized>. | |
264 | ||
265 | I<Variable assignment values are not tokenized.> | |
266 | ||
267 | =head2 Scope | |
268 | ||
269 | Most of the statement values are accumulated globally from all the | |
270 | F<build.info> files that are digested. There are two exceptions, | |
271 | F<build.info> variables and B<SUBDIRS> statement, for which the scope | |
272 | is the F<build.info> file they are in. | |
273 | ||
274 | =head2 Perl nuggets | |
275 | ||
276 | Whenever a F<build.info> file is read, it is passed through the Perl | |
277 | template processor L<OpenSSL::Template>, which is a small extension of | |
278 | L<Text::Template>. | |
279 | ||
280 | Perl nuggets are anything between C<{-> and C<-}>, and whatever the | |
281 | result from such a nugget is, that value will replace the nugget in | |
282 | text form. This is useful to get dynamically generated F<build.info> | |
283 | statements, and is most often seen used together with the B<IF> and | |
284 | B<ELSIF> conditional statements. | |
285 | ||
286 | For example: | |
287 | ||
288 | IF[{- $disabled{something} -}] | |
289 | # do whatever's needed when "something" is disabled | |
290 | ELSIF[{- $somethingelse eq 'blah' -}] | |
291 | # do whatever's needed to satisfy this condition | |
292 | ELSE | |
293 | # fallback | |
294 | ENDIF | |
295 | ||
296 | Normal Perl scope applies, so it's possible to have an initial perl | |
297 | nugget that sets diverse global variables that are used in later | |
298 | nuggets. Each nugget is a Perl block of its own, so B<my> definitions | |
299 | are only in scope within the same nugget, while B<our> definitions are | |
300 | in scope within the whole F<build.info> file. | |
301 | ||
302 | =head1 REFERENCE | |
303 | ||
304 | =head2 Conditionals | |
305 | ||
306 | =over 4 | |
307 | ||
308 | =item B<IF[>0|1B<]> | |
309 | ||
310 | If the condition is true (represented as C<1> here), everything | |
311 | between this B<IF> and the next corresponding B<ELSIF> or B<ELSE> | |
312 | applies, and the rest until the corresponding B<ENDIF> is skipped | |
313 | over. | |
314 | ||
315 | If the condition is false (represented as C<0> here), everything | |
316 | from this B<IF> is skipped over until the next corresponding B<ELSIF> | |
317 | or B<ELSE>, at which point processing continues. | |
318 | ||
319 | =item B<ELSE> | |
320 | ||
321 | If F<build.info> statements have been skipped over to this point since | |
322 | the corresponding B<IF> or B<ELSIF>, F<build.info> processing starts | |
323 | again following this line. | |
324 | ||
325 | =item B<ELSIF[>0|1B<]> | |
326 | ||
327 | This is B<ELSE> and B<IF> combined. | |
328 | ||
329 | =item B<ENDIF> | |
330 | ||
331 | Marks the end of a conditional. | |
332 | ||
333 | =back | |
334 | ||
335 | =head2 Plain statements | |
336 | ||
337 | =over 4 | |
338 | ||
339 | =item B<SUBDIRS=> I<dir> ... | |
340 | ||
341 | This instructs the F<build.info> reader to also read the F<build.info> | |
342 | file in every specified directory. All directories should be given | |
343 | relative to the location of the current F<build.info> file. | |
344 | ||
345 | =item B<PROGRAMS=> I<name> ... | |
346 | ||
347 | Collects names of programs that should be built. | |
348 | ||
349 | B<PROGRAMS> statements may have attributes, which apply to all the | |
350 | programs given in such a statement. For example: | |
351 | ||
352 | PROGRAMS=foo | |
353 | PROGRAMS{noinst}=bar | |
354 | ||
355 | With those two lines, the program C<foo> will not have the attribute | |
356 | C<noinst>, while the program C<bar> will. | |
357 | ||
358 | =item B<LIBS=> I<name> ... | |
359 | ||
360 | Collects names of libraries that should be built. | |
361 | ||
362 | The normal case is that libraries are built in both static and shared | |
363 | form. However, if a name ends with C<.a>, only the static form will | |
364 | be produced. | |
365 | ||
366 | Similarly, libraries may be referred in indexed statements as just the | |
367 | plain name, or the name including the ending C<.a>. If given without | |
368 | the ending C<.a>, any form available will be used, but if given with | |
369 | the ending C<.a>, the static library form is used unconditionally. | |
370 | ||
371 | B<LIBS> statements may have attributes, which apply to all the | |
372 | libraries given in such a statement. For example: | |
373 | ||
374 | LIBS=libfoo | |
375 | LIBS{noinst}=libbar | |
376 | ||
377 | With those two lines, the library C<libfoo> will not have the | |
378 | attribute C<noinst>, while the library C<libbar> will. | |
379 | ||
380 | =item B<MODULES=> I<name> | |
381 | ||
382 | Collects names of dynamically loadable modules that should be built. | |
383 | ||
384 | B<MODULES> statements may have attributes, which apply to all the | |
385 | modules given in such a statement. For example: | |
386 | ||
387 | MODULES=foo | |
388 | MODULES{noinst}=bar | |
389 | ||
390 | With those two lines, the module C<foo> will not have the attribute | |
391 | C<noinst>, while the module C<bar> will. | |
392 | ||
393 | =item B<SCRIPTS=> I<name> | |
394 | ||
395 | Collects names of scripts that should be built, or that just exist. | |
396 | That is how they differ from programs, as programs are always expected | |
397 | to be compiled from multiple sources. | |
398 | ||
399 | B<SCRIPTS> statements may have attributes, which apply to all the | |
400 | scripts given in such a statement. For example: | |
401 | ||
402 | SCRIPTS=foo | |
403 | SCRIPTS{noinst}=bar | |
404 | ||
405 | With those two lines, the script C<foo> will not have the attribute | |
406 | C<noinst>, while the script C<bar> will. | |
407 | ||
408 | =back | |
409 | ||
410 | =head2 Indexed statements | |
411 | ||
412 | =over 4 | |
413 | ||
414 | =item B<DEPEND[>I<item>B<]> B<=> I<file> ... | |
415 | ||
416 | Collects dependencies, where I<item> depends on the given I<file>s. | |
417 | ||
418 | As a special case, the I<item> may be empty, for which the build file | |
419 | generators should make the whole build depend on the given I<file>s, | |
420 | rather than some specific I<item>. | |
421 | ||
422 | The I<item> may be any program, library, module, script, or any | |
423 | filename used as a value anywhere. | |
424 | ||
7c3ccd7f RL |
425 | B<DEPEND> statements may have attributes, which apply to each |
426 | individual dependency in such a statement. For example: | |
427 | ||
428 | DEPEND[libfoo.a]=libmandatory.a | |
429 | DEPEND[libfoo.a]{weak}=libbar.a libcookie.a | |
430 | ||
431 | With those statements, the dependency between C<libfoo.a> and | |
432 | C<libmandatory.a> is strong, while the dependency between C<libfoo.a> | |
433 | and C<libbar.a> and C<libcookie.a> is weak. See the description of | |
434 | B<weak> in L</Known attributes> for more information. | |
435 | ||
e20ba0a5 RL |
436 | =item B<GENERATE[>I<item>B<]> B<=> I<generator> I<generator-arg> ... |
437 | ||
438 | This specifies that the I<item> is generated using the I<generator> | |
439 | with the I<generator-arg>s as arguments, plus the name of the output | |
440 | file as last argument. | |
441 | ||
442 | For I<generator>s where this is applicable, any B<INCLUDE> statement | |
443 | for the same I<item> will be given to the I<generator> as its | |
70d96753 RL |
444 | inclusion directories. Likewise, any B<DEPEND> statement for the same |
445 | I<item> will be given to the I<generator> as an extra file or module | |
446 | to load, where this is applicable. | |
e20ba0a5 RL |
447 | |
448 | The build file generators must be able to recognise the I<generator>. | |
449 | Currently, they at least recognise files ending in C<.pl>, and will | |
450 | execute them to generate the I<item>, and files ending in C<.in>, | |
451 | which will be used as input for L<OpenSSL::Template> to generate | |
452 | I<item> (in other words, we use the exact same style of | |
453 | L</Perl nuggets> mechanism that is used to read F<build.info> files). | |
454 | ||
455 | =item B<SOURCE[>I<item>B<]> B<=> I<file> ... | |
456 | ||
457 | Collects filenames that will be used as source files for I<item>. | |
458 | ||
459 | The I<item> must be a singular item, and may be any program, library, | |
460 | module or script given with B<PROGRAMS>, B<LIBS>, B<MODULES> and | |
461 | B<SCRIPTS>. | |
462 | ||
7c3ccd7f RL |
463 | Static libraries may be sources. In that case, its object files are |
464 | used directly when building I<item> instead of relying on library | |
465 | dependency and symbol resolution (through B<DEPEND> statements). | |
466 | ||
e20ba0a5 RL |
467 | =item B<SHARED_SOURCE[>I<item>B<]> B<=> I<file> ... |
468 | ||
469 | Collects filenames that will be used as source files for I<item>. | |
470 | ||
471 | The I<item> must be a singular item, and may be any library or module | |
472 | given with B<LIBS> or B<MODULES>. For libraries, the given filenames | |
473 | are only used for their shared form, so if the item is a library name | |
474 | ending with C<.a>, the filenames will be ignored. | |
475 | ||
476 | =item B<DEFINE[>I<item>B<]> B<=> I<name>[B<=>I<value>] ... | |
477 | ||
478 | Collects I<name> / I<value> pairs (or just I<name> with no defined | |
479 | value if no I<value> is given) associated with I<item>. | |
480 | ||
481 | The build file generators will decide what to do with them. For | |
482 | example, these pairs should become C macro definitions whenever a | |
483 | C<.c> file is built into an object file. | |
484 | ||
485 | =item B<INCLUDE[>I<item>B<]> B<=> I<dir> ... | |
486 | ||
487 | Collects inclusion directories that will be used when building the | |
488 | I<item> components (object files and whatever else). This is used at | |
489 | the discretion of the build file generators. | |
490 | ||
491 | =back | |
492 | ||
493 | =head2 Known attributes | |
494 | ||
495 | Note: this will never be a complete list of attributes. | |
496 | ||
497 | =over 4 | |
498 | ||
499 | =item B<noinst> | |
500 | ||
501 | This is used to specify that the end products this is set for should | |
502 | not be installed, that they are only internal. This is applicable on | |
503 | internal static libraries, or on test programs. | |
504 | ||
505 | =item B<misc> | |
506 | ||
507 | This is used with B<SCRIPTS>, to specify that some scripts should be | |
508 | installed in the "misc" directory rather than the normal program | |
509 | directory. | |
510 | ||
511 | =item B<engine> | |
512 | ||
513 | This is used with B<MODULES>, to specify what modules are engines and | |
514 | should be installed in the engines directory instead of the modules | |
515 | directory. | |
516 | ||
7c3ccd7f RL |
517 | =item B<weak> |
518 | ||
519 | This is used with B<DEPEND> where libraries are involved, to specify | |
520 | that the dependency between two libraries is weak and is only there to | |
521 | infer order. | |
522 | ||
523 | Without this attribute, a dependency between two libraries, expressed | |
524 | like this, means that if C<libfoo.a> appears in a linking command | |
525 | line, so will C<libmandatory.a>: | |
526 | ||
527 | DEPEND[libfoo.a]=libmandatory.a | |
528 | ||
529 | With this attribute, a dependency between two libraries, expressed | |
530 | like this, means that if I<both> C<libfoo.a> and C<libmandatory.a> | |
531 | appear in a linking command line (because of recursive dependencies | |
532 | through other libraries), they will be ordered in such a way that this | |
533 | dependency is maintained: | |
534 | ||
535 | DEPEND[libfoo.a]{weak}=libfoo.a libcookie.a | |
536 | ||
79c44b4e | 537 | This is useful in complex dependency trees where two libraries can be |
7c3ccd7f RL |
538 | used as alternatives for each other. In this example, C<lib1.a> and |
539 | C<lib2.a> have alternative implementations of the same thing, and | |
540 | C<libmandatory.a> has unresolved references to that same thing, and is | |
541 | therefore depending on either of them, but not both at the same time: | |
542 | ||
543 | DEPEND[program1]=libmandatory.a lib1.a | |
544 | DEPEND[program2]=libmandatory.a lib2.a | |
545 | DEPEND[libmandatory]{weak}=lib1.a lib2.a | |
546 | ||
e20ba0a5 RL |
547 | =back |
548 | ||
549 | =head1 GLOSSARY | |
550 | ||
551 | =over 4 | |
552 | ||
553 | =item "build file" | |
554 | ||
555 | This is any platform specific file that describes the complete build, | |
556 | with platform specific commands. On Unix, this is typically | |
557 | F<Makefile>; on VMS, this is typically F<descrip.mms>. | |
558 | ||
559 | =item "build file generator" | |
560 | ||
561 | Perl code that generates build files, given configuration data and | |
562 | data collected from F<build.info> files. | |
563 | ||
564 | =item "plain statement" | |
565 | ||
566 | Any F<build.info> statement of the form B<I<KEYWORD>>=I<values>, with | |
567 | the exception of conditional statements and variable assignments. | |
568 | ||
569 | =item "indexed statement" | |
570 | ||
571 | Any F<build.info> statement of the form B<I<KEYWORD>[>I<item>B<]=>I<values>, | |
572 | with the exception of conditional statements. | |
573 | ||
574 | =item "intermediate file" | |
575 | ||
576 | Any file that's an intermediate between a source file and an end | |
577 | product. | |
578 | ||
579 | =item "end product" | |
580 | ||
581 | Any file that is mentioned in the B<PROGRAMS>, B<LIBS>, B<MODULES> or | |
582 | B<SCRIPTS>. | |
583 | ||
584 | =back | |
585 | ||
586 | =head1 SEE ALSO | |
587 | ||
588 | For OpenSSL::Template documentation, | |
589 | C<perldoc -o man util/perl/OpenSSL/Template.pm> | |
590 | ||
591 | L<Text::Temlate|https://metacpan.org/pod/Text::Template> | |
592 | ||
593 | =head1 COPYRIGHT | |
594 | ||
595 | Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. | |
596 | ||
597 | Licensed under the Apache License 2.0 (the "License"). You may not use this | |
598 | file except in compliance with the License. You can obtain a copy in the file | |
599 | LICENSE in the source distribution or at | |
600 | L<https://www.openssl.org/source/license.html>. | |
601 | ||
602 | =cut |