2
0

build.info.pod 20 KB

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