1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org> |
---|
4 | |
---|
5 | .. _Configuration: |
---|
6 | |
---|
7 | Configuration |
---|
8 | ============= |
---|
9 | |
---|
10 | The RTEMS Source Builder has two types of configuration data: |
---|
11 | |
---|
12 | - Build Sets |
---|
13 | |
---|
14 | - Package Build Configurations |
---|
15 | |
---|
16 | By default these files can be located in two separate directories and |
---|
17 | searched. The first directory is ``config`` in your current working directory |
---|
18 | (``_topdir``) and the second is ``config`` located in the base directory of the |
---|
19 | RTEMS Source Builder command you run (``_sbdir``). The RTEMS directory |
---|
20 | ``rtems``` located at the top of the RTEMS Source Builder source code is an |
---|
21 | example of a specific build configuration directory. You can create custom or |
---|
22 | private build configurations and if you run the RTEMS Source Builder command |
---|
23 | from that directory your configurations will be used. |
---|
24 | |
---|
25 | The configuration search path is a macro variable and is reference as |
---|
26 | ``%{_configdir}``. It's default is defined as:: |
---|
27 | |
---|
28 | _configdir : dir optional<2> %{_topdir}/config:%{_sbdir}/config <1> |
---|
29 | |
---|
30 | .. topic:: Items: |
---|
31 | |
---|
32 | 1. The ``_topdir`` is the directory you run the command from and ``_sbdir`` |
---|
33 | is the location of the RTEMS Source Builder command. |
---|
34 | |
---|
35 | 2. A macro definition in a macro file has 4 fields, the label, type, |
---|
36 | constraint and the definition. |
---|
37 | |
---|
38 | Build set files have the file extension ``.bset`` and the package build |
---|
39 | configuration files have the file extension of ``.cfg``. The ``sb-set-builder`` |
---|
40 | command will search for *build sets* and the ``sb-builder`` commands works with |
---|
41 | package build configuration files. |
---|
42 | |
---|
43 | Both types of configuration files use the ``#`` character as a comment |
---|
44 | character. Anything after this character on the line is ignored. There is no |
---|
45 | block comment. |
---|
46 | |
---|
47 | Source and Patches |
---|
48 | ------------------ |
---|
49 | |
---|
50 | The RTEMS Source Builder provides a flexible way to manage source. Source and |
---|
51 | patches are declare in configurations file using the ``source`` and ``patch`` |
---|
52 | directives. These are a single line containing a Universal Resource Location or |
---|
53 | URL and can contain macros and shell expansions. The :ref:`prep` section |
---|
54 | details the *source* and *patch* directives |
---|
55 | |
---|
56 | The URL can reference remote and local source and patch resources. The |
---|
57 | following schemes are provided: |
---|
58 | |
---|
59 | ``http``: |
---|
60 | Remote access using the HTTP protocol. |
---|
61 | |
---|
62 | ``https``: |
---|
63 | Remote access using the Secure HTTP protocol. |
---|
64 | |
---|
65 | ``ftp``: |
---|
66 | Remote access using the FTP protocol. |
---|
67 | |
---|
68 | ``git``: |
---|
69 | Remote access to a GIT repository. |
---|
70 | |
---|
71 | ``pm``: |
---|
72 | Remote access to a patch management repository. |
---|
73 | |
---|
74 | ``file``: |
---|
75 | Local access to an existing source directory. |
---|
76 | |
---|
77 | HTTP, HTTPS, and FTP |
---|
78 | ~~~~~~~~~~~~~~~~~~~~ |
---|
79 | |
---|
80 | Remote access to TAR or ZIP files is provided using HTTP, HTTPS and FTP |
---|
81 | protocols. The full URL provided is used to access the remote file including |
---|
82 | any query components. The URL is parsed to extract the file component and the |
---|
83 | local source directory is checked for that file. If the file is located locally |
---|
84 | the remote file is not downloaded. Currently no other checks are made. If a |
---|
85 | download fails you need to manually remove the file from the source directory |
---|
86 | and start the build process again. |
---|
87 | |
---|
88 | The URL can contain macros. These are expanded before issuing the request to |
---|
89 | download the file. The standard GNU GCC compiler source URL is: |
---|
90 | |
---|
91 | .. code-block:: auto |
---|
92 | |
---|
93 | %source set<1> gcc<2> ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2 |
---|
94 | |
---|
95 | .. topic:: Items: |
---|
96 | |
---|
97 | 1. The ``%source`` command's set command sets the source. The first is set |
---|
98 | and following sets are ignored. |
---|
99 | |
---|
100 | 2. The source is part of the ``gcc`` group. |
---|
101 | |
---|
102 | The type of compression is automatically detected from the file extension. The |
---|
103 | supported compression formats are: |
---|
104 | |
---|
105 | ``gz``: |
---|
106 | GNU ZIP |
---|
107 | |
---|
108 | ``bzip2``: |
---|
109 | BZIP2 |
---|
110 | |
---|
111 | ``zip``: |
---|
112 | ZIP |
---|
113 | |
---|
114 | ``xy``: |
---|
115 | XY |
---|
116 | |
---|
117 | The output of the decompression tool is fed to the standard ``tar`` utility if |
---|
118 | not a ZIP file and unpacked into the build directory. ZIP files are unpacked by |
---|
119 | the decompression tool and all other files must be in the tar file format. |
---|
120 | |
---|
121 | The ``%source`` directive typically supports a single source file tar or zip |
---|
122 | file. The ``set`` command is used to set the URL for a specific source |
---|
123 | group. The first set command encountered is registered and any further set |
---|
124 | commands are ignored. This allows you to define a base standard source location |
---|
125 | and override it in build and architecture specific files. You can also add |
---|
126 | extra source files to a group. This is typically done when a collection of |
---|
127 | source is broken down in a number of smaller files and you require the full |
---|
128 | package. The source's ``setup`` command must reside in the ``%prep:`` section |
---|
129 | and it unpacks the source code ready to be built. |
---|
130 | |
---|
131 | If the source URL references the GitHub API server https://api.github.com/ a |
---|
132 | tarball of the specified version is download. For example the URL for the |
---|
133 | STLINK project on GitHub and version is: |
---|
134 | |
---|
135 | .. code-block:: auto |
---|
136 | |
---|
137 | %define stlink_version 3494c11 |
---|
138 | %source set stlink https://api.github.com/repos/texane/stlink/texane-stlink-%{stlink_version}.tar.gz |
---|
139 | |
---|
140 | GIT |
---|
141 | ~~~ |
---|
142 | |
---|
143 | A GIT repository can be cloned and used as source. The GIT repository resides |
---|
144 | in the 'source' directory under the ``git`` directory. You can edit, update and |
---|
145 | use the repository as you normally do and the results will used to build the |
---|
146 | tools. This allows you to prepare and test patches in the build environment the |
---|
147 | tools are built in. The GIT URL only supports the GIT protocol. You can control |
---|
148 | the repository via the URL by appending options and arguments to the GIT |
---|
149 | path. The options are delimited by ``?`` and option arguments are delimited |
---|
150 | from the options with ``=``. The options are: |
---|
151 | |
---|
152 | ``protocol``: |
---|
153 | Use a specific protocol. The supported values are ``ssh``, ``git``, ``http``, |
---|
154 | ``https``, ``ftp``, ``ftps``, ``rsync``, and ``none``. |
---|
155 | |
---|
156 | ``branch``: |
---|
157 | Checkout the specified branch. |
---|
158 | |
---|
159 | ``pull``: |
---|
160 | Perform a pull to update the repository. |
---|
161 | |
---|
162 | ``fetch``: |
---|
163 | Perform a fetch to get any remote updates. |
---|
164 | |
---|
165 | ``reset``: |
---|
166 | Reset the repository. Useful to remove any local changes. You can pass the |
---|
167 | ``hard`` argument to force a hard reset. |
---|
168 | |
---|
169 | An example is: |
---|
170 | |
---|
171 | .. code-block:: auto |
---|
172 | |
---|
173 | %source set gcc git://gcc.gnu.org/git/gcc.git?branch=gcc-4_7-branch?reset=hard |
---|
174 | |
---|
175 | This will clone the GCC git repository and checkout the 4.7-branch and perform |
---|
176 | a hard reset. You can select specific branches and apply patches. The |
---|
177 | repository is cleaned up before each build to avoid various version control |
---|
178 | errors that can arise. |
---|
179 | |
---|
180 | The protocol option lets you set a specific protocol. The ``git://`` prefix |
---|
181 | used by the RSB to select a git repository can be removed using *none* or |
---|
182 | replaced with one of the standard git protcols. |
---|
183 | |
---|
184 | CVS |
---|
185 | ~~~ |
---|
186 | |
---|
187 | A CVS repository can be checked out. CVS is more complex than GIT to handle |
---|
188 | because of the modules support. This can effect the paths the source ends up |
---|
189 | in. The CVS URL only supports the CVS protocol. You can control the repository |
---|
190 | via the URL by appending options and arguments to the CVS path. The options are |
---|
191 | delimited by ``?`` and option arguments are delimited from the options with |
---|
192 | ``=``. The options are: |
---|
193 | |
---|
194 | ``module``: |
---|
195 | The module to checkout. |
---|
196 | |
---|
197 | ``src-prefix``: |
---|
198 | The path into the source where the module starts. |
---|
199 | |
---|
200 | ``tag``: |
---|
201 | The CVS tag to checkout. |
---|
202 | |
---|
203 | ``date``: |
---|
204 | The CVS date to checkout. |
---|
205 | |
---|
206 | The following is an example of checking out from a CVS repository: |
---|
207 | |
---|
208 | .. code-block:: auto |
---|
209 | |
---|
210 | %source set newlib cvs://pserver:anoncvs@sourceware.org/cvs/src?module=newlib?src-prefix=src |
---|
211 | |
---|
212 | Macros and Defaults |
---|
213 | ------------------- |
---|
214 | |
---|
215 | The RTEMS Source Builder uses tables of *macros* read in when the tool |
---|
216 | runs. The initial global set of macros is called the *defaults*. These values |
---|
217 | are read from a file called ``defaults.mc`` and modified to suite your |
---|
218 | host. This host specific adaption lets the Source Builder handle differences in |
---|
219 | the build hosts. |
---|
220 | |
---|
221 | Build set and configuration files can define new values updating and extending |
---|
222 | the global macro table. For example builds are given a release number. This is |
---|
223 | typically a single number at the end of the package name. For example:: |
---|
224 | |
---|
225 | %define release 1 |
---|
226 | |
---|
227 | Once defined if can be accessed in a build set or package configuration file |
---|
228 | with:: |
---|
229 | |
---|
230 | %{release} |
---|
231 | |
---|
232 | The ``sb-defaults`` command lists the defaults for your host. I will not include |
---|
233 | the output of this command because of its size:: |
---|
234 | |
---|
235 | $ ../source-builder/sb-defaults |
---|
236 | |
---|
237 | A nested build set is given a separate copy of the global macro maps. Changes |
---|
238 | in one change set are not seen in other build sets. That same happens with |
---|
239 | configuration files unless inline includes are used. Inline includes are seen |
---|
240 | as part of the same build set and configuration and changes are global to that |
---|
241 | build set and configuration. |
---|
242 | |
---|
243 | Macro Maps and Files |
---|
244 | ~~~~~~~~~~~~~~~~~~~~ |
---|
245 | |
---|
246 | Macros are read in from files when the tool starts. The default settings are |
---|
247 | read from the defaults macro file called ``defaults.mc`` located in the top |
---|
248 | level RTEMS Source Builder command directory. User macros can be read in at |
---|
249 | start up by using the ``--macros`` command line option. |
---|
250 | |
---|
251 | The format for a macro in macro files is:: |
---|
252 | |
---|
253 | Name Type Attribute String |
---|
254 | |
---|
255 | where ``Name`` is a case insensitive macro name, the ``Type`` field is: |
---|
256 | |
---|
257 | ``none``: |
---|
258 | Nothing, ignore. |
---|
259 | |
---|
260 | ``dir``: |
---|
261 | A directory path. |
---|
262 | |
---|
263 | ``exe``: |
---|
264 | An executable path. |
---|
265 | |
---|
266 | ``triplet``: |
---|
267 | A GNU style architecture, platform, operating system string. |
---|
268 | |
---|
269 | the ``Attribute`` field is: |
---|
270 | |
---|
271 | ``none``: |
---|
272 | Nothing, ignore |
---|
273 | |
---|
274 | ``required``: |
---|
275 | The host check must find the executable or path. |
---|
276 | |
---|
277 | ``optional``: |
---|
278 | The host check generates a warning if not found. |
---|
279 | |
---|
280 | ``override``: |
---|
281 | Only valid outside of the ``global`` map to indicate this macro overrides the |
---|
282 | same one in the ``global`` map when the map containing it is selected. |
---|
283 | |
---|
284 | ``undefine``: |
---|
285 | Only valid outside of the ``global`` map to undefine the macro if it exists |
---|
286 | in the ``global`` map when the map containing it is selected. The ``global`` |
---|
287 | map's macro is not visible but still exists. |
---|
288 | |
---|
289 | and the ``String`` field is a single or tripled multiline quoted string. The |
---|
290 | 'String' can contain references to other macros. Macro that loop are not |
---|
291 | currently detected and will cause the tool to lock up. |
---|
292 | |
---|
293 | Maps are declared anywhere in the map using the map directive:: |
---|
294 | |
---|
295 | # Comments |
---|
296 | [my-special-map] <1> |
---|
297 | _host: none, override, 'abc-xyz' |
---|
298 | multiline: none, override, '''First line, |
---|
299 | second line, |
---|
300 | and finally the last line''' |
---|
301 | |
---|
302 | .. topic:: Items: |
---|
303 | |
---|
304 | 1. The map is set to ``my-special-map``. |
---|
305 | |
---|
306 | Any macro defintions following a map declaration are placed in that map and the |
---|
307 | default map is ``global`` when loading a file. Maps are selected in |
---|
308 | configuration files by using the ``%select`` directive:: |
---|
309 | |
---|
310 | %select my-special-map |
---|
311 | |
---|
312 | Selecting a map means all requests for a macro first check the selected map and |
---|
313 | if present return that value else the ``global`` map is used. Any new macros or |
---|
314 | changes update only the ``global`` map. This may change in future releases so |
---|
315 | please make sure you use the ``override`` attribute. |
---|
316 | |
---|
317 | The macro files specificed on the command line are looked for in the |
---|
318 | ``_configdir`` paths. See <<X1,``_configdir``>> variable for details. Included |
---|
319 | files need to add the ``%{_configdir}`` macro to the start of the file. |
---|
320 | |
---|
321 | Macro map files can include other macro map files using the ``%include`` |
---|
322 | directive. The macro map to build *binutils*, *gcc*, *newlib*, *gdb* and |
---|
323 | RTEMS from version control heads is:: |
---|
324 | |
---|
325 | # <1> |
---|
326 | # Build all tool parts from version control head. |
---|
327 | # |
---|
328 | %include %{_configdir}/snapshots/binutils-head.mc |
---|
329 | %include %{_configdir}/snapshots/gcc-head.mc |
---|
330 | %include %{_configdir}/snapshots/newlib-head.mc |
---|
331 | %include %{_configdir}/snapshots/gdb-head.mc |
---|
332 | |
---|
333 | .. topic:: Items: |
---|
334 | |
---|
335 | 1. The file is ``config/snapshots/binutils-gcc-newlib-gdb-head.mc``. |
---|
336 | |
---|
337 | The macro map defaults to ``global`` at the start of each included file and the |
---|
338 | map setting of the macro file including the other macro files does not change. |
---|
339 | |
---|
340 | Personal Macros |
---|
341 | ~~~~~~~~~~~~~~~ |
---|
342 | |
---|
343 | When the tools start to run they will load personal macros. Personal macros are |
---|
344 | in the standard format for macros in a file. There are two places personal |
---|
345 | macros can be configured. The first is the environment variable |
---|
346 | ``RSB_MACROS``. If present the macros from the file the environment variable |
---|
347 | points to are loaded. The second is a file called ``.rsb_macros`` in your home |
---|
348 | directory. You need to have the environment variable ``HOME`` defined for this |
---|
349 | work. |
---|
350 | |
---|
351 | Report Mailing |
---|
352 | -------------- |
---|
353 | |
---|
354 | The build reports can be mailed to a specific email address to logging and |
---|
355 | monitoring. Mailing requires a number of parameters to function. These are: |
---|
356 | |
---|
357 | - To mail address |
---|
358 | |
---|
359 | - From mail address |
---|
360 | |
---|
361 | - SMTP host |
---|
362 | |
---|
363 | .. _To Mail Address: |
---|
364 | |
---|
365 | The ``to`` mail address is taken from the macro ``%{_mail_tools_to}`` and the |
---|
366 | default is *rtems-tooltestresults at rtems.org*. You can override the default |
---|
367 | with a personal or user macro file or via the command line option |
---|
368 | ``--mail-to``. |
---|
369 | |
---|
370 | .. _From Mail Address: |
---|
371 | |
---|
372 | The ``from`` mail address is taken from: |
---|
373 | |
---|
374 | - GIT configuration |
---|
375 | |
---|
376 | - User ``.mailrc`` file |
---|
377 | |
---|
378 | - Command line |
---|
379 | |
---|
380 | If you have configured an email and name in git it will be used used. If you do |
---|
381 | not a check is made for a ``.mailrc`` file. The environment variable ``MAILRC`` |
---|
382 | is used if present else your home directory is check. If found the file is |
---|
383 | scanned for the ``from`` setting:: |
---|
384 | |
---|
385 | set from="Foo Bar <foo@bar>" |
---|
386 | |
---|
387 | You can also support a from address on the command line with the ``--mail-from`` |
---|
388 | option. |
---|
389 | |
---|
390 | The SMTP host is taken from the macro ``%{_mail_smtp_host}`` and the |
---|
391 | default is ``localhost``. You can override the default with a personal |
---|
392 | or user macro file or via the command line option ``--smtp-host``. |
---|
393 | |
---|
394 | Build Set Files |
---|
395 | --------------- |
---|
396 | |
---|
397 | Build set files lets you list the packages in the build set you are defining |
---|
398 | and have a file extension of ``.bset``. Build sets can define macro variables, |
---|
399 | inline include other files and reference other build set or package |
---|
400 | configuration files. |
---|
401 | |
---|
402 | Defining macros is performed with the ``%define`` macro:: |
---|
403 | |
---|
404 | %define _target m32r-rtems4.11 |
---|
405 | |
---|
406 | Inline including another file with the ``%include`` macro continues processing |
---|
407 | with the specified file returning to carry on from just after the include |
---|
408 | point:: |
---|
409 | |
---|
410 | %include rtems-4.11-base.bset |
---|
411 | |
---|
412 | This includes the RTEMS 4.11 base set of defines and checks. The configuration |
---|
413 | paths as defined by ``_configdir`` are scanned. The file extension is optional. |
---|
414 | |
---|
415 | You reference build set or package configuration files by placing the file name |
---|
416 | on a single line:: |
---|
417 | |
---|
418 | tools/rtems-binutils-2.22-1 |
---|
419 | |
---|
420 | The ``_configdir`` path is scanned for ``tools/rtems-binutils-2.22-1.bset`` or |
---|
421 | ``tools/rtems-binutils-2.22-1.cfg``. Build set files take precedent over |
---|
422 | package configuration files. If ``tools/rtems-binutils-2.22-1`` is a build set |
---|
423 | a new instance of the build set processor is created and if the file is a |
---|
424 | package configuration the package is built with the package builder. This all |
---|
425 | happens once the build set file has finished being scanned. |
---|
426 | |
---|
427 | Configuration Control |
---|
428 | --------------------- |
---|
429 | |
---|
430 | The RTEMS Souce Builder is designed to fit within most verification and |
---|
431 | validation processes. All of the RTEMS Source Builder is source code. The |
---|
432 | Python code is source and comes with a commercial friendly license. All |
---|
433 | configuration data is text and can be read or parsed with standard text based |
---|
434 | tools. |
---|
435 | |
---|
436 | File naming provides configuration management. A specific version of a package |
---|
437 | is captured in a specific set of configuration files. The top level |
---|
438 | configuration file referenced in a *build set* or passed to the ``sb-builder`` |
---|
439 | command relates to a specific configuration of the package being built. For |
---|
440 | example the RTEMS configuration file ``rtems-gcc-4.7.2-newlib-2.0.0-1.cfg`` |
---|
441 | creates an RTEMS GCC and Newlib package where the GCC version is 4.7.2, the |
---|
442 | Newlib version is 2.0.0, plus any RTEMS specific patches that related to this |
---|
443 | version. The configuration defines the version numbers of the various parts |
---|
444 | that make up this package:: |
---|
445 | |
---|
446 | %define gcc_version 4.7.2 |
---|
447 | %define newlib_version 2.0.0 |
---|
448 | %define mpfr_version 3.0.1 |
---|
449 | %define mpc_version 0.8.2 |
---|
450 | %define gmp_version 5.0.5 |
---|
451 | |
---|
452 | The package build options, if there are any are also defined:: |
---|
453 | |
---|
454 | %define with_threads 1 |
---|
455 | %define with_plugin 0 |
---|
456 | %define with_iconv 1 |
---|
457 | |
---|
458 | The generic configuration may provide defaults in case options are not |
---|
459 | specified. The patches this specific version of the package requires can be |
---|
460 | included:: |
---|
461 | |
---|
462 | Patch0: gcc-4.7.2-rtems4.11-20121026.diff |
---|
463 | |
---|
464 | Finally including the GCC 4.7 configuration script:: |
---|
465 | |
---|
466 | %include %{_configdir}/gcc-4.7-1.cfg |
---|
467 | |
---|
468 | The ``gcc-4.7-1.cfg`` file is a generic script to build a GCC 4.7 compiler with |
---|
469 | Newlib. It is not specific to RTEMS. A bare no operating system tool set can be |
---|
470 | built with this file. |
---|
471 | |
---|
472 | The ``-1`` part of the file names is a revision. The GCC 4.7 script maybe |
---|
473 | revised to fix a problem and if this fix effects an existing script the file is |
---|
474 | copied and given a ``-2`` revision number. Any dependent scripts referencing |
---|
475 | the earlier revision number will not be effected by the change. This locks down |
---|
476 | a specific configuration over time. |
---|
477 | |
---|
478 | Personal Configurations |
---|
479 | ----------------------- |
---|
480 | |
---|
481 | The RSB supports personal configurations. You can view the RTEMS support in the |
---|
482 | ``rtems`` directory as a private configuration tree that resides within the RSB |
---|
483 | source. There is also the ``bare`` set of configurations. You can create your |
---|
484 | own configurations away from the RSB source tree yet use all that the RSB |
---|
485 | provides. |
---|
486 | |
---|
487 | To create a private configuration change to a suitable directory:: |
---|
488 | |
---|
489 | $ cd ~/work |
---|
490 | $ mkdir test |
---|
491 | $ cd test |
---|
492 | $ mkdir config |
---|
493 | |
---|
494 | and create a ``config`` directory. Here you can add a new configuration or |
---|
495 | build set file. The section 'Adding New Configurations' details how to add a |
---|
496 | new confguration. |
---|
497 | |
---|
498 | New Configurations |
---|
499 | ------------------ |
---|
500 | |
---|
501 | This section describes how to add a new configuration to the RSB. We will add a |
---|
502 | configuration to build the Device Tree Compiler. The Device Tree Compiler or |
---|
503 | DTC is part of the Flattened Device Tree project and compiles Device Tree |
---|
504 | Source (DTS) files into Device Tree Blobs (DTB). DTB files can be loaded by |
---|
505 | operating systems and used to locate the various resources such as base |
---|
506 | addresses of devices or interrupt numbers allocated to devices. The Device Tree |
---|
507 | Compiler source code can be downloaded from http://www.jdl.com/software. The |
---|
508 | DTC is supported in the RSB and you can find the configuration files under the |
---|
509 | ``bare/config`` tree. I suggest you have a brief look over these files. |
---|
510 | |
---|
511 | Layering by Including |
---|
512 | ~~~~~~~~~~~~~~~~~~~~~ |
---|
513 | |
---|
514 | Configurations can be layered using the ``%include`` directive. The user |
---|
515 | invokes the outer layers which include inner layers until all the required |
---|
516 | configuration is present and the package can be built. The outer layers can |
---|
517 | provide high level details such as the version and the release and the inner |
---|
518 | layers provide generic configuration details that do not change from one |
---|
519 | release to another. Macro variables are used to provide the specific |
---|
520 | configuration details. |
---|
521 | |
---|
522 | Configuration File Numbering |
---|
523 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
524 | |
---|
525 | Configuration files have a number at the end. This is a release number for that |
---|
526 | configuration and it gives us the ability to track a specific configuration for |
---|
527 | a specific version. For example lets say the developers of the DTC package |
---|
528 | change the build system from a single makefile to autoconf and automake between |
---|
529 | version 1.3.0 and version 1.4.0. The configuration file used to build the |
---|
530 | package would change have to change. If we did not number the configuration |
---|
531 | files the ability to build 1.1.0, 1.2.0 or 1.3.0 would be lost if we update a |
---|
532 | common configuration file to build an autoconf and automake version. For |
---|
533 | version 1.2.0 the same build script can be used so we can share the same |
---|
534 | configuration file between version 1.1.0 and version 1.2.0. An update to any |
---|
535 | previous release lets us still build the package. |
---|
536 | |
---|
537 | Common Configuration Scripts |
---|
538 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
539 | |
---|
540 | Common configuration scripts that are independent of version, platform and |
---|
541 | architecture are useful to everyone. These live in the Source Builder's |
---|
542 | configuration directory. Currently there are scripts to build binutils, expat, |
---|
543 | DTC, GCC, GDB and libusb. These files contain the recipes to build these |
---|
544 | package without the specific details of the versions or patches being |
---|
545 | built. They expect to be wrapped by a configuration file that ties the package |
---|
546 | to a specific version and optionally specific patches. |
---|
547 | |
---|
548 | DTC Example |
---|
549 | ~~~~~~~~~~~ |
---|
550 | |
---|
551 | We will be building the DTC for your host rather than a package for RTEMS. We |
---|
552 | will create a file called ``source-builder/config/dtc-1-1.cfg``. This is a |
---|
553 | common script that can be used to build a specific version using a general |
---|
554 | recipe. The file name is ``dtc-1-1.cfg`` where the ``cfg`` extension indicates |
---|
555 | this is a configuration file. The first ``1`` says this is for the major |
---|
556 | release 1 of the package and the last ``1`` is the build configuration version. |
---|
557 | |
---|
558 | The file starts with some comments that detail the configuration. If there is |
---|
559 | anything unusual about the configuration it is a good idea to add something in |
---|
560 | the comments here. The comments are followed by a check for the release. In |
---|
561 | this case if a release is not provided a default of 1 is used:: |
---|
562 | |
---|
563 | # |
---|
564 | # DTC 1.x.x Version 1. |
---|
565 | # |
---|
566 | # This configuration file configure's, make's and install's DTC. |
---|
567 | # |
---|
568 | |
---|
569 | %if %{release} == %{nil} |
---|
570 | %define release 1 |
---|
571 | %endif |
---|
572 | |
---|
573 | The next section defines some information about the package. It does not effect |
---|
574 | the build and is used to annotate the reports. It is recommended this |
---|
575 | information is kept updated and accurate:: |
---|
576 | |
---|
577 | Name: dtc-%{dtc_version}-%{_host}-%{release} |
---|
578 | Summary: Device Tree Compiler v%{dtc_version} for target %{_target} on host %{_host} |
---|
579 | Version: %{dtc_version} |
---|
580 | Release: %{release} |
---|
581 | URL: http://www.jdl.com/software/ |
---|
582 | BuildRoot: %{_tmppath}/%{name}-root-%(%{__id_u} -n) |
---|
583 | |
---|
584 | The next section defines the source and any patches. In this case there is a |
---|
585 | single source package and it can be downloaded using the HTTP protocol. The RSB |
---|
586 | knows this is GZip'ped tar file. If more than one package is needed, add |
---|
587 | them increasing the index. The ``gcc-4.8-1.cfg`` configuration contains |
---|
588 | examples of more than one source package as well as conditionally including |
---|
589 | source packages based on the outer configuration options:: |
---|
590 | |
---|
591 | # |
---|
592 | # Source |
---|
593 | # |
---|
594 | %source set dtc http://www.jdl.com/software/dtc-v%{dtc_version}.tgz |
---|
595 | |
---|
596 | The remainder of the script is broken in to the various phases of a build. They |
---|
597 | are: |
---|
598 | |
---|
599 | . Preperation |
---|
600 | . Bulding |
---|
601 | . Installing, and |
---|
602 | . Cleaning |
---|
603 | |
---|
604 | Preparation is the unpacking of the source, applying any patches as well as any |
---|
605 | package specific set ups. This part of the script is a standard Unix shell |
---|
606 | script. Be careful with the use of ``%`` and ``$``. The RSB uses ``%`` while |
---|
607 | the shell scripts use ``$``. |
---|
608 | |
---|
609 | A standard pattern you will observe is the saving of the build's top |
---|
610 | directory. This is used instead of changing into a subdirectory and then |
---|
611 | changing to the parent when finished. Some hosts will change in a subdirectory |
---|
612 | that is a link however changing to the parent does not change back to the |
---|
613 | parent of the link rather it changes to the parent of the target of the link |
---|
614 | and that is something the RSB nor you can track easily. The RSB configuration |
---|
615 | script's are a collection of various subtle issues so please ask if you are |
---|
616 | unsure why something is being done a particular way. |
---|
617 | |
---|
618 | The preparation phase will often include source and patch setup commands. Outer |
---|
619 | layers can set the source package and add patches as needed while being able to |
---|
620 | use a common recipe for the build. Users can override the standard build and |
---|
621 | supply a custom patch for testing using the user macro command line interface:: |
---|
622 | |
---|
623 | # |
---|
624 | # Prepare the source code. |
---|
625 | # |
---|
626 | %prep |
---|
627 | build_top=$(pwd) |
---|
628 | |
---|
629 | %source setup dtc -q -n dtc-v%{dtc_version} |
---|
630 | %patch setup dtc -p1 |
---|
631 | |
---|
632 | cd ${build_top} |
---|
633 | |
---|
634 | The configuration file ``gcc-common-1.cfg`` is a complex example of source |
---|
635 | preparation. It contains a number of source packages and patches and it |
---|
636 | combines these into a single source tree for building. It uses links to map |
---|
637 | source into the GCC source tree so GCC can be built using the *single source |
---|
638 | tree* method. It also shows how to fetch source code from version |
---|
639 | control. Newlib is taken directly from its CVS repository. |
---|
640 | |
---|
641 | Next is the building phase and for the DTC example this is simply a matter of |
---|
642 | running ``make``. Note the use of the RSB macros for commands. In the case of |
---|
643 | ``%{__make}`` it maps to the correct make for your host. In the case of BSD |
---|
644 | systems we need to use the BSD make and not the GNU make. |
---|
645 | |
---|
646 | If your package requires a configuration stage you need to run this before the |
---|
647 | make stage. Again the GCC common configuration file provides a detailed example:: |
---|
648 | |
---|
649 | %build |
---|
650 | build_top=$(pwd) |
---|
651 | |
---|
652 | cd dtc-v%{dtc_version} |
---|
653 | |
---|
654 | %{build_build_flags} |
---|
655 | |
---|
656 | %{__make} PREFIX=%{_prefix} |
---|
657 | |
---|
658 | cd ${build_top} |
---|
659 | |
---|
660 | You can invoke make with the macro ``%{?_smp_flags}`` as a command line |
---|
661 | argument. This macro is controlled by the ``--jobs`` command line option and |
---|
662 | the host CPU detection support in the RSB. If you are on a multicore host you |
---|
663 | can increase the build speed using this macro. It also lets you disabled |
---|
664 | building on multicores to aid debugging when testing. |
---|
665 | |
---|
666 | Next is the install phase. This phase is a little more complex because you may |
---|
667 | be building a tar file and the end result of the build is never actually |
---|
668 | installed into the prefix on the build host and you may not even have |
---|
669 | permissions to perform a real install. Most packages install to the ``prefix`` |
---|
670 | and the prefix is typically supplied via the command to the RSB or the |
---|
671 | package's default is used. The default can vary depending on the host's |
---|
672 | operating system. To install to a path that is not the prefix the ``DESTDIR`` |
---|
673 | make variable is used. Most packages should honour the ``DISTDIR`` make |
---|
674 | variables and you can typically specify it on the command line to make when |
---|
675 | invoking the install target. This results in the package being installed to a |
---|
676 | location that is not the prefix but one you can control. The RSB provides a |
---|
677 | shell variable called ``SB_BUILD_ROOT`` you can use. In a build set where you |
---|
678 | are building a number of packages you can collect all the built packages in a |
---|
679 | single tree that is captured in the tar file. |
---|
680 | |
---|
681 | Also note the use of the macro ``%{__rmdir}``. The use of these macros allow |
---|
682 | the RSB to vary specific commands based on the host. This can help on hosts |
---|
683 | like Windows where bugs can effect the standard commands such as ``rm``. There |
---|
684 | are many many macros to help you. You can find these listed in the |
---|
685 | ``defaults.mc`` file and in the trace output. If you are new to creating and |
---|
686 | editing configurations learning these can take a little time:: |
---|
687 | |
---|
688 | %install |
---|
689 | build_top=$(pwd) |
---|
690 | |
---|
691 | %{__rmdir} -rf $SB_BUILD_ROOT |
---|
692 | |
---|
693 | cd dtc-v%{dtc_version} |
---|
694 | %{__make} DESTDIR=$SB_BUILD_ROOT PREFIX=%{_prefix} install |
---|
695 | |
---|
696 | cd ${build_top} |
---|
697 | |
---|
698 | Finally there is an optional clean section. The RSB will run this section if |
---|
699 | ``--no-clean`` has not been provided on the command line. The RSB does clean up |
---|
700 | for you. |
---|
701 | |
---|
702 | Once we have the configuration files we can execute the build using the |
---|
703 | ``sb-builder`` command. The command will perform the build and create a tar file |
---|
704 | in the ``tar`` directory:: |
---|
705 | |
---|
706 | $ ../source-builder/sb-builder --prefix=/usr/local \ |
---|
707 | --log=log_dtc devel/dtc-1.2.0 |
---|
708 | RTEMS Source Builder, Package Builder v0.2.0 |
---|
709 | config: devel/dtc-1.2.0 |
---|
710 | package: dtc-1.2.0-x86_64-freebsd9.1-1 |
---|
711 | download: http://www.jdl.com/software/dtc-v1.2.0.tgz -> sources/dtc-v1.2.0.tgz |
---|
712 | building: dtc-1.2.0-x86_64-freebsd9.1-1 |
---|
713 | $ ls tar |
---|
714 | dtc-1.2.0-x86_64-freebsd9.1-1.tar.bz2 |
---|
715 | |
---|
716 | If you want to have the package installed automatically you need to create a |
---|
717 | build set. A build set can build one or more packages from their configurations |
---|
718 | at once to create a single package. For example the GNU tools is typically seen |
---|
719 | as binutils, GCC and GDB and a build set will build each of these packages and |
---|
720 | create a single build set tar file or install the tools on the host into the |
---|
721 | prefix path. |
---|
722 | |
---|
723 | The DTC build set file is called ``dtc.bset`` and contains:: |
---|
724 | |
---|
725 | # |
---|
726 | # Build the DTC. |
---|
727 | # |
---|
728 | |
---|
729 | %define release 1 |
---|
730 | |
---|
731 | devel/dtc-1.2.0.cfg |
---|
732 | |
---|
733 | To build this you can use something similar to:: |
---|
734 | |
---|
735 | $ ../source-builder/sb-set-builder --prefix=/usr/local --log=log_dtc \ |
---|
736 | --trace --bset-tar-file --no-install dtc |
---|
737 | RTEMS Source Builder - Set Builder, v0.2.0 |
---|
738 | Build Set: dtc |
---|
739 | config: devel/dtc-1.2.0.cfg |
---|
740 | package: dtc-1.2.0-x86_64-freebsd9.1-1 |
---|
741 | building: dtc-1.2.0-x86_64-freebsd9.1-1 |
---|
742 | tarball: tar/x86_64-freebsd9.1-dtc-set.tar.bz2 |
---|
743 | cleaning: dtc-1.2.0-x86_64-freebsd9.1-1 |
---|
744 | Build Set: Time 0:00:02.865758 |
---|
745 | $ ls tar |
---|
746 | dtc-1.2.0-x86_64-freebsd9.1-1.tar.bz2 x86_64-freebsd9.1-dtc-set.tar.bz2 |
---|
747 | |
---|
748 | The build is for a FreeBSD host and the prefix is for user installed |
---|
749 | packages. In this example I cannot let the source builder perform the install |
---|
750 | because I never run the RSB with root priviledges so a build set or bset tar |
---|
751 | file is created. This can then be installed using root priviledges. |
---|
752 | |
---|
753 | The command also supplies the ``--trace`` option. The output in the log file |
---|
754 | will contain all the macros. |
---|
755 | |
---|
756 | Debugging |
---|
757 | ~~~~~~~~~ |
---|
758 | |
---|
759 | New configuration files require debugging. There are two types of |
---|
760 | debugging. The first is debugging RSB script bugs. The ``--dry-run`` option is |
---|
761 | used here. Suppling this option will result in most of the RSB processing to be |
---|
762 | performed and suitable output placed in the log file. This with the ``--trace`` |
---|
763 | option should help you resolve any issues. |
---|
764 | |
---|
765 | The second type of bug to fix are related to the execution of one of |
---|
766 | phases. These are usually a mix of shell script bugs or package set up or |
---|
767 | configuration bugs. Here you can use any normal shell script type debug |
---|
768 | technique such as ``set +x`` to output the commands or ``echo`` |
---|
769 | statements. Debugging package related issues may require you start a build with |
---|
770 | the RSB and supply ``--no-clean`` option and then locate the build directories |
---|
771 | and change directory into them and manually run commands until to figure what |
---|
772 | the package requires. |
---|
773 | |
---|
774 | Scripting |
---|
775 | --------- |
---|
776 | |
---|
777 | Configuration files specify how to build a package. Configuration files are |
---|
778 | scripts and have a ``.cfg`` file extension. The script format is based loosely |
---|
779 | on the RPM spec file format however the use and purpose in this tool does not |
---|
780 | compare with the functionality and therefore the important features of the spec |
---|
781 | format RPM needs and uses. |
---|
782 | |
---|
783 | The script language is implemented in terms of macros. The built-in list is: |
---|
784 | |
---|
785 | ``%{}``: |
---|
786 | Macro expansion with conditional logic. |
---|
787 | |
---|
788 | ``%()``: |
---|
789 | Shell expansion. |
---|
790 | |
---|
791 | ``%prep``: |
---|
792 | The source preparation shell commands. |
---|
793 | |
---|
794 | ``%build``: |
---|
795 | The build shell commands. |
---|
796 | |
---|
797 | ``%install``: |
---|
798 | The package install shell commands. |
---|
799 | |
---|
800 | ``%clean``: |
---|
801 | The package clean shell commands. |
---|
802 | |
---|
803 | ``%include``: |
---|
804 | Inline include another configuration file. |
---|
805 | |
---|
806 | ``%name``: |
---|
807 | The name of the package. |
---|
808 | |
---|
809 | ``%summary``: |
---|
810 | A brief package description. Useful when reporting about a build. |
---|
811 | |
---|
812 | ``%release``: |
---|
813 | The package release. A number that is the release as built by this tool. |
---|
814 | |
---|
815 | ``%version``: |
---|
816 | The package's version string. |
---|
817 | |
---|
818 | ``%buildarch``: |
---|
819 | The build architecture. |
---|
820 | |
---|
821 | ``%source``: |
---|
822 | Define a source code package. This macro has a number appended. |
---|
823 | |
---|
824 | ``%patch``: |
---|
825 | Define a patch. This macro has a number appended. |
---|
826 | |
---|
827 | ``%hash``: |
---|
828 | Define a checksum for a source or patch file. |
---|
829 | |
---|
830 | ``%echo``: |
---|
831 | Print the following string as a message. |
---|
832 | |
---|
833 | ``%warning``: |
---|
834 | Print the following string as a warning and continue. |
---|
835 | |
---|
836 | ``%error``: |
---|
837 | Print the following string as an error and exit. |
---|
838 | |
---|
839 | ``%select``: |
---|
840 | Select the macro map. If there is no map nothing is reported. |
---|
841 | |
---|
842 | ``%define``: |
---|
843 | Define a macro. Macros cannot be redefined, you must first undefine it. |
---|
844 | |
---|
845 | ``%undefine``: |
---|
846 | Undefine a macro. |
---|
847 | |
---|
848 | ``%if``: |
---|
849 | Start a conditional logic block that ends with a ``%endif``. |
---|
850 | |
---|
851 | ``%ifn``: |
---|
852 | Inverted start of a conditional logic block. |
---|
853 | |
---|
854 | ``%ifarch``: |
---|
855 | Test the architecture against the following string. |
---|
856 | |
---|
857 | ``%ifnarch``: |
---|
858 | Inverted test of the architecture |
---|
859 | |
---|
860 | ``%ifos``: |
---|
861 | Test the host operating system. |
---|
862 | |
---|
863 | ``%else``: |
---|
864 | Start the *else* conditional logic block. |
---|
865 | |
---|
866 | ``%endfi``: |
---|
867 | End the conditional logic block. |
---|
868 | |
---|
869 | ``%bconf_with``: |
---|
870 | Test the build condition *with* setting. This is the ``--with-*`` command |
---|
871 | line option. |
---|
872 | |
---|
873 | ``%bconf_without``: |
---|
874 | Test the build condition *without* setting. This is the ``--without-*`` |
---|
875 | command line option. |
---|
876 | |
---|
877 | Expanding |
---|
878 | ~~~~~~~~~ |
---|
879 | |
---|
880 | A macro can be ``%{string}`` or the equivalent of ``%string``. The following macro |
---|
881 | expansions supported are: |
---|
882 | |
---|
883 | ``%{string}``: |
---|
884 | Expand the 'string' replacing the entire macro text with the text in the |
---|
885 | table for the entry 'string . For example if 'var' is 'foo' then ``${var}`` |
---|
886 | would become ``foo``. |
---|
887 | |
---|
888 | ``%{expand: string}``: |
---|
889 | Expand the 'string' and then use it as a ``string`` to the macro expanding |
---|
890 | the macro. For example if ``foo`` is set to ``bar`` and ``bar`` is set to |
---|
891 | ``foobar`` then ``%{expand:foo}`` would result in ``foobar``. Shell expansion |
---|
892 | can also be used. |
---|
893 | |
---|
894 | ``%{with string}``: |
---|
895 | Expand the macro to ``1`` if the macro ``with_string`` is defined else expand |
---|
896 | to ``0``. Macros with the name ``with_string`` can be define with command |
---|
897 | line arguments to the RTEMS Source Builder commands. |
---|
898 | |
---|
899 | ``%{defined string}``: |
---|
900 | Expand the macro to ``1`` if a macro of name ``string`` is defined else |
---|
901 | expand to '0'. |
---|
902 | |
---|
903 | ``%{?string: expression}``: |
---|
904 | Expand the macro to ``expression`` if a macro of name ``string`` is defined |
---|
905 | else expand to ``%{nil}``. |
---|
906 | |
---|
907 | ``%{!?string: expression}``: |
---|
908 | Expand the macro to ``expression`` if a macro of name ``string`` is not |
---|
909 | defined. If the macro is define expand to ``%{nil}``. |
---|
910 | |
---|
911 | ``%(expression)``: |
---|
912 | Expand the macro to the result of running the ``expression`` in a host |
---|
913 | shell. It is assumed this is a Unix type shell. For example ``%(whoami)`` |
---|
914 | will return your user name and ``%(date)`` will return the current date |
---|
915 | string. |
---|
916 | |
---|
917 | .. _prep: |
---|
918 | |
---|
919 | %prep |
---|
920 | ~~~~~ |
---|
921 | |
---|
922 | The +%prep+ macro starts a block that continues until the next block macro. The |
---|
923 | *prep* or preparation block defines the setup of the package's source and is a |
---|
924 | mix of RTEMS Source Builder macros and shell scripting. The sequence is |
---|
925 | typically +%source+ macros for source, +%patch+ macros to patch the source |
---|
926 | mixed with some shell commands to correct any source issues:: |
---|
927 | |
---|
928 | <1> <2> <3> |
---|
929 | %source setup gcc -q -c -T -n %{name}-%{version} |
---|
930 | |
---|
931 | .. topic:: Items: |
---|
932 | |
---|
933 | 1. The source group to set up. |
---|
934 | |
---|
935 | 2. The source's name. |
---|
936 | |
---|
937 | 3. The version of the source. |
---|
938 | |
---|
939 | The source set up are declared with the source ``set`` and ``add`` commands. For |
---|
940 | example: |
---|
941 | |
---|
942 | .. code-block:: auto |
---|
943 | |
---|
944 | %source set gdb http://ftp.gnu.org/gnu/gdb/gdb-%{gdb_version}.tar.bz2 |
---|
945 | |
---|
946 | This URL is the primary location of the GNU GDB source code and the RTEMS |
---|
947 | Source Builder can download the file from this location and by inspecting the |
---|
948 | file extension use ``bzip2`` decompression with +tar+. When the ``%prep`` |
---|
949 | section is processed a check of the local ``source`` directory is made to see |
---|
950 | if the file has already been downloaded. If not found in the source cache |
---|
951 | directory the package is downloaded from the URL. You can append other base |
---|
952 | URLs via the command line option ``--url``. This option accepts a comma |
---|
953 | delimited list of sites to try. |
---|
954 | |
---|
955 | You could optionally have a few source files that make up the package. For |
---|
956 | example GNU's GCC was a few tar files for a while and it is now a single tar |
---|
957 | file. Support for multiple source files can be conditionally implemented with |
---|
958 | the following scripting: |
---|
959 | |
---|
960 | .. code-block:: auto |
---|
961 | |
---|
962 | %source set gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-code-%{gcc_version}.tar.bz2 |
---|
963 | %source add gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-g++-%{gcc_version}.tar.bz2 |
---|
964 | %source setup gcc -q -T -D -n gcc-%{gcc_version} |
---|
965 | |
---|
966 | Separate modules use separate source groups. The GNU GCC compiler for RTEMS |
---|
967 | uses Newlib, MPFR, MPC, and GMP source packages. You define the source with: |
---|
968 | |
---|
969 | .. code-block:: auto |
---|
970 | |
---|
971 | %source set gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2 |
---|
972 | %source set newlib ftp://sourceware.org/pub/newlib/newlib-%{newlib_version}.tar.gz |
---|
973 | %source set mpfr http://www.mpfr.org/mpfr-%{mpfr_version}/mpfr-%{mpfr_version}.tar.bz2 |
---|
974 | %source set mpc http://www.multiprecision.org/mpc/download/mpc-%{mpc_version}.tar.gz |
---|
975 | %source set gmp ftp://ftp.gnu.org/gnu/gmp/gmp-%{gmp_version}.tar.bz2 |
---|
976 | |
---|
977 | and set up with: |
---|
978 | |
---|
979 | .. code-block:: auto |
---|
980 | |
---|
981 | %source setup gcc -q -n gcc-%{gcc_version} |
---|
982 | %source setup newlib -q -D -n newlib-%{newlib_version} |
---|
983 | %source setup mpfr -q -D -n mpfr-%{mpfr_version} |
---|
984 | %source setup mpc -q -D -n mpc-%{mpc_version} |
---|
985 | %source setup gmp -q -D -n gmp-%{gmp_version} |
---|
986 | |
---|
987 | Patching also occurs during the preparation stage. Patches are handled in a |
---|
988 | similar way to the source packages except you only ``add`` patches. Patches are |
---|
989 | applied using the +setup+ command. The +setup+ command takes the default patch |
---|
990 | option. You can provide options with each patch by adding them as arguments |
---|
991 | before the patch URL. Patches with no options uses the +setup+ default. |
---|
992 | |
---|
993 | .. code-block:: auto |
---|
994 | |
---|
995 | %patch add gdb %{rtems_gdb_patches}/gdb-sim-arange-inline.diff |
---|
996 | %patch add gdb -p0 <1> %{rtems_gdb_patches}/gdb-sim-cgen-inline.diff |
---|
997 | |
---|
998 | .. topic:: Items: |
---|
999 | |
---|
1000 | 1. This patch has a custom option. |
---|
1001 | |
---|
1002 | To apply these patches:: |
---|
1003 | |
---|
1004 | %patch setup gdb -p1 <1> |
---|
1005 | |
---|
1006 | .. topic:: Items: |
---|
1007 | |
---|
1008 | 1. The default options. |
---|
1009 | |
---|
1010 | .. _build: |
---|
1011 | |
---|
1012 | %build |
---|
1013 | ~~~~~~ |
---|
1014 | |
---|
1015 | The ``%build`` macro starts a block that continues until the next block |
---|
1016 | macro. The build block is a series of shell commands that execute to build the |
---|
1017 | package. It assumes all source code has been unpacked, patch and adjusted so |
---|
1018 | the build will succeed. |
---|
1019 | |
---|
1020 | The following is an example take from the GitHub STLink project. The STLink is |
---|
1021 | a JTAG debugging device for the ST ARM family of processors:: |
---|
1022 | |
---|
1023 | %build |
---|
1024 | export PATH="%{_bindir}:${PATH}" <1> |
---|
1025 | |
---|
1026 | cd texane-stlink-%{stlink_version} <2> |
---|
1027 | |
---|
1028 | ./autogen.sh <3> |
---|
1029 | |
---|
1030 | %if "%{_build}" != "%{_host}" |
---|
1031 | CFLAGS_FOR_BUILD="-g -O2 -Wall" \ <4> |
---|
1032 | %endif |
---|
1033 | CPPFLAGS="-I $SB_TMPPREFIX/include/libusb-1.0" \ <5> |
---|
1034 | CFLAGS="$SB_OPT_FLAGS" \ |
---|
1035 | LDFLAGS="-L $SB_TMPPREFIX/lib" \ |
---|
1036 | ./configure \ <6> |
---|
1037 | --build=%{_build} --host=%{_host} \ |
---|
1038 | --verbose \ |
---|
1039 | --prefix=%{_prefix} --bindir=%{_bindir} \ |
---|
1040 | --exec-prefix=%{_exec_prefix} \ |
---|
1041 | --includedir=%{_includedir} --libdir=%{_libdir} \ |
---|
1042 | --mandir=%{_mandir} --infodir=%{_infodir} |
---|
1043 | |
---|
1044 | %{__make} %{?_smp_mflags} all <7> |
---|
1045 | |
---|
1046 | cd .. |
---|
1047 | |
---|
1048 | .. topic:: Items: |
---|
1049 | |
---|
1050 | 1. Setup the PATH environment variable. This is not always needed. |
---|
1051 | |
---|
1052 | 2. This package builds in the source tree so enter it. |
---|
1053 | |
---|
1054 | 3. The package is actually checked directly out from the github project and |
---|
1055 | so it needs its autoconf and automake files generated. |
---|
1056 | |
---|
1057 | 4. Flags for a cross-compiled build. |
---|
1058 | |
---|
1059 | 5. Various settings passed to configure to customise the build. In this |
---|
1060 | example an include path is being set to the install point of |
---|
1061 | ``libusb``. This package requires ``libusb`` is built before it. |
---|
1062 | |
---|
1063 | 6. The ``configure`` command. The RTEMS Source Builder provides all the |
---|
1064 | needed paths as macro variables. You just need to provide them to |
---|
1065 | ``configure``. |
---|
1066 | |
---|
1067 | 7. Running make. Do not use ``make`` directly, use the RTEMS Source Builder's |
---|
1068 | defined value. This value is specific to the host. A large number of |
---|
1069 | packages need GNU make and on BSD systems this is ``gmake``. You can |
---|
1070 | optionally add the SMP flags if the packages build system can handle |
---|
1071 | parallel building with multiple jobs. The ``_smp_mflags`` value is |
---|
1072 | automatically setup for SMP hosts to match the number of cores the host |
---|
1073 | has. |
---|
1074 | |
---|
1075 | %install |
---|
1076 | ~~~~~~~~ |
---|
1077 | |
---|
1078 | The ``%install`` macro starts a block that continues until the next block |
---|
1079 | macro. The install block is a series of shell commands that execute to install |
---|
1080 | the package. You can assume the package has built correctly when this block |
---|
1081 | starts executing. |
---|
1082 | |
---|
1083 | Never install the package to the actual *prefix* the package was built |
---|
1084 | with. Always install to the RTEMS Source Builder's temporary path defined in |
---|
1085 | the macro variable ``__tmpdir``. The RTEMS Source Builder sets up a shell |
---|
1086 | environment variable called ``SB_BUILD_ROOT`` as the standard install point. Most |
---|
1087 | packages support adding ``DESTDIR=`` to the ``make install`` command. |
---|
1088 | |
---|
1089 | Looking at the same example as in :ref:`build`:: |
---|
1090 | |
---|
1091 | %install |
---|
1092 | export PATH="%{_bindir}:${PATH}" <1> |
---|
1093 | rm -rf $SB_BUILD_ROOT <2> |
---|
1094 | |
---|
1095 | cd texane-stlink-%{stlink_version} <3> |
---|
1096 | %{__make} DESTDIR=$SB_BUILD_ROOT install <4> |
---|
1097 | |
---|
1098 | cd .. |
---|
1099 | |
---|
1100 | .. topic:: Items: |
---|
1101 | |
---|
1102 | 1. Setup the PATH environment variable. This is not always needed. |
---|
1103 | |
---|
1104 | 2. Clean any installed files. This makes sure the install is just what the |
---|
1105 | package installs and not any left over files from a broken build or |
---|
1106 | install. |
---|
1107 | |
---|
1108 | 3. Enter the build directory. In this example it just happens to be the |
---|
1109 | source directory. |
---|
1110 | |
---|
1111 | 4. Run ``make install`` to install the package overriding the ``DESTDIR`` |
---|
1112 | make variable. |
---|
1113 | |
---|
1114 | %clean |
---|
1115 | ~~~~~~ |
---|
1116 | |
---|
1117 | The ``%clean`` macro starts a block that continues until the next block |
---|
1118 | macro. The clean block is a series of shell commands that execute to clean up |
---|
1119 | after a package has been built and install. This macro is currenly not been |
---|
1120 | used because the RTEMS Source Builder automatically cleans up. |
---|
1121 | |
---|
1122 | %include |
---|
1123 | ~~~~~~~~ |
---|
1124 | |
---|
1125 | The ``%include`` macro inline includes the specific file. The ``__confdir`` |
---|
1126 | path is searched. Any relative path component of the include file is appended |
---|
1127 | to each part of the ``__configdir``. Adding an extension is optional as files |
---|
1128 | with ``.bset`` and ``.cfg`` are automatically searched for. |
---|
1129 | |
---|
1130 | Inline including means the file is processed as part of the configuration at |
---|
1131 | the point it is included. Parsing continues from the next line in the |
---|
1132 | configuration file that contains the ``%include`` macro. |
---|
1133 | |
---|
1134 | Including files allow a kind of configuration file reuse. The outer |
---|
1135 | configuration files provide specific information such as package version |
---|
1136 | numbers and patches and then include a generic configuration script which |
---|
1137 | builds the package:: |
---|
1138 | |
---|
1139 | %include %{_configdir}/gcc-4.7-1.cfg |
---|
1140 | |
---|
1141 | %name |
---|
1142 | ~~~~~ |
---|
1143 | |
---|
1144 | The name of the package being built. The name typically contains the components |
---|
1145 | of the package and their version number plus a revision number. For the GCC |
---|
1146 | with Newlib configuration the name is typically:: |
---|
1147 | |
---|
1148 | Name: %{_target}-gcc-%{gcc_version}-newlib-%{newlib_version}-%{release} |
---|
1149 | |
---|
1150 | %summary |
---|
1151 | ~~~~~~~~ |
---|
1152 | |
---|
1153 | The ``%summary`` is a brief description of the package. It is useful when |
---|
1154 | reporting. This information is not capture in the package anywhere. For the GCC |
---|
1155 | with Newlib configuration the summary is typically:: |
---|
1156 | |
---|
1157 | Summary: GCC v%{gcc_version} and Newlib v%{newlib_version} for target %{_target} on host %{_host} |
---|
1158 | |
---|
1159 | %release |
---|
1160 | ~~~~~~~~ |
---|
1161 | |
---|
1162 | The ``%release`` is a packaging number that allows revisions of a package to |
---|
1163 | happen where no package versions change. This value typically increases when |
---|
1164 | the configuration building the package changes:: |
---|
1165 | |
---|
1166 | %define release 1 |
---|
1167 | |
---|
1168 | %version |
---|
1169 | ~~~~~~~~ |
---|
1170 | |
---|
1171 | The ``%version`` macro sets the version the package. If the package is a single |
---|
1172 | component it tracks that component's version number. For example in the |
---|
1173 | ``libusb`` configuration the ``%version`` is the same as ``%libusb_version``, |
---|
1174 | however in a GCC with Newlib configuration there is no single version |
---|
1175 | number. In this case the GCC version is used:: |
---|
1176 | |
---|
1177 | Version: %{gcc_version} |
---|
1178 | |
---|
1179 | %buildarch |
---|
1180 | ~~~~~~~~~~ |
---|
1181 | |
---|
1182 | The ``%buildarch`` macro is set to the architecture the package contains. This |
---|
1183 | is currently not used in the RTEMS Source Builder and may go away. This macro |
---|
1184 | is more important in a real packaging system where the package could end up on |
---|
1185 | the wrong architecture. |
---|
1186 | |
---|
1187 | %source |
---|
1188 | ~~~~~~~ |
---|
1189 | |
---|
1190 | The ``%source`` macro has 3 commands that controls what it does. You can |
---|
1191 | ``set`` the source files, ``add`` source files to a source group, and ``setup`` |
---|
1192 | the source file group getting it ready to be used. |
---|
1193 | |
---|
1194 | Source files are source code files in tar or zip files that are unpacked, |
---|
1195 | copied or symbolically linked into the package's build tree. Building a package |
---|
1196 | requires one or more dependent packages. These are typically the packages |
---|
1197 | source code plus dependent libraries or modules. You can create any number of |
---|
1198 | these source groups and set each of them up with a separate source group for |
---|
1199 | each needed library or module. Each source group normally has a single tar, zip |
---|
1200 | or repository and the ``set`` defines this. Some projects split the source code |
---|
1201 | into separate tar or zip files and you install them by using the ``add`` |
---|
1202 | command. |
---|
1203 | |
---|
1204 | The first instance of a ``set`` command creates the source group and sets the |
---|
1205 | source files to be set up. Subsequent ``set`` commands for the same source |
---|
1206 | group are ignored. this lets you define the standard source files and override |
---|
1207 | them for specific releases or snapshots. To set a source file group: |
---|
1208 | |
---|
1209 | .. code-block:: auto |
---|
1210 | |
---|
1211 | %source set gcc <1> ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2 |
---|
1212 | |
---|
1213 | .. topic:: Items: |
---|
1214 | |
---|
1215 | 1. The source group is ``gcc``. |
---|
1216 | |
---|
1217 | To add another source package to be installed into the same source tree you use |
---|
1218 | the ``add`` command: |
---|
1219 | |
---|
1220 | .. code-block:: auto |
---|
1221 | |
---|
1222 | %source add gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/g++-%{gcc_version}.tar.bz2 |
---|
1223 | |
---|
1224 | The source ``setup`` command can only be issued in the ``%prep:`` section. The |
---|
1225 | setup is:: |
---|
1226 | |
---|
1227 | %source gcc setup -q -T -D -n %{name}-%{version} |
---|
1228 | |
---|
1229 | Accepted options are: |
---|
1230 | |
---|
1231 | ``-n``: |
---|
1232 | The ``-n`` option is used to set the name of the software's build |
---|
1233 | directory. This is necessary only when the source archive unpacks into a |
---|
1234 | directory named other than ``<name>-<version>``. |
---|
1235 | |
---|
1236 | ``-c``: |
---|
1237 | The ``-c`` option is used to direct ``%setup`` to create the top-level build |
---|
1238 | directory before unpacking the sources. |
---|
1239 | |
---|
1240 | ``-D``: |
---|
1241 | The ``-D`` option is used to direct ``%setup`` to not delete the build |
---|
1242 | directory prior to unpacking the sources. This option is used when more than |
---|
1243 | one source archive is to be unpacked into the build directory, normally with |
---|
1244 | the ``-b`` or ``-a`` options. |
---|
1245 | |
---|
1246 | ``-T``: |
---|
1247 | The ``-T`` option is used to direct %setup to not perform the default |
---|
1248 | unpacking of the source archive specified by the first ``Source:`` macro. It |
---|
1249 | is used with the ``-a`` or ``-b`` options. |
---|
1250 | |
---|
1251 | ``-b <n>``: |
---|
1252 | The ``-b`` option is used to direct ``%setup`` to unpack the source archive |
---|
1253 | specified on the nth ``Source:`` macro line before changing directory into |
---|
1254 | the build directory. |
---|
1255 | |
---|
1256 | %patch |
---|
1257 | ~~~~~~ |
---|
1258 | |
---|
1259 | The ``%patch`` macro has the same 3 command as the ``%source`` command however |
---|
1260 | the ``set`` commands is not really that useful with the ``%patch`` command. You |
---|
1261 | add patches with the ``add`` command and ``setup`` applies the patches. Patch |
---|
1262 | options can be added to each patch by placing them before the patch URL. If no |
---|
1263 | patch option is provided the default options passed to the ``setup`` command |
---|
1264 | are used. An option starts with a ``-``. The ``setup`` command must reside |
---|
1265 | inside the ``%prep`` section. |
---|
1266 | |
---|
1267 | Patches are grouped in a similar way to the ``%source`` macro so you can |
---|
1268 | control applying a group of patches to a specific source tree. |
---|
1269 | |
---|
1270 | The ``__patchdir`` path is searched. |
---|
1271 | |
---|
1272 | To add a patch:: |
---|
1273 | |
---|
1274 | %patch add gcc <1> gcc-4.7.2-rtems4.11-20121026.diff |
---|
1275 | %patch add gcc -p0 <2> gcc-4.7.2-rtems4.11-20121101.diff |
---|
1276 | |
---|
1277 | .. topic:: Items: |
---|
1278 | |
---|
1279 | 1. The patch group is ``gcc``. |
---|
1280 | |
---|
1281 | 2. Option for this specific patch. |
---|
1282 | |
---|
1283 | Placing ``%patch setup`` in the ``%prep`` section will apply the groups |
---|
1284 | patches:: |
---|
1285 | |
---|
1286 | %patch setup gcc <1> -p1 <2> |
---|
1287 | |
---|
1288 | 1. The patch group. |
---|
1289 | |
---|
1290 | 2. The default option used to apply the patch. |
---|
1291 | |
---|
1292 | %hash |
---|
1293 | ~~~~~ |
---|
1294 | |
---|
1295 | The ``%hash`` macro requires 3 arguments and defines a checksum for a specific |
---|
1296 | file. The checksum is not applied until the file is checked before downloading |
---|
1297 | and once downloaded. A patch or source file that does not have a hash defined |
---|
1298 | generates a warning. |
---|
1299 | |
---|
1300 | A file to be checksummed must be unique in the source and patch directories. |
---|
1301 | The basename of the file is used as the key for the hash. |
---|
1302 | |
---|
1303 | The hash algorthim can be ``md5``, ``sha1``, ``sha224``, ``sha256``, |
---|
1304 | ``sha384``, and ``sha512`` and we typically use ``md5``. |
---|
1305 | |
---|
1306 | To add a hash:: |
---|
1307 | |
---|
1308 | %hash md5 <1> net-snmp-%{net_snmp_version}.tar.gz <2> 7db683faba037249837b226f64d566d4 <3> |
---|
1309 | |
---|
1310 | .. topic:: Items: |
---|
1311 | |
---|
1312 | 1. The type of checksum. |
---|
1313 | |
---|
1314 | 2. The file to checksum. It can contain macros that are expanded for you. |
---|
1315 | |
---|
1316 | 3. The MD5 hash for the Net-SNMP file ``net-snmp-5.7.2.1.tar.gz``. |
---|
1317 | |
---|
1318 | Do not include a path with the file name. Only the basename is required. Files |
---|
1319 | can be searched for from a number of places and having a path conponent would |
---|
1320 | create confusion. This does mean files with hashes must be unique. |
---|
1321 | |
---|
1322 | Downloading off repositories such as git and cvs cannot be checksummed. It is |
---|
1323 | assumed those protocols and tools manage the state of the files. |
---|
1324 | |
---|
1325 | %echo |
---|
1326 | ~~~~~ |
---|
1327 | |
---|
1328 | The ``%echo`` macro outputs the following string to stdout. This can also be used |
---|
1329 | as ``%{echo: message}``. |
---|
1330 | |
---|
1331 | %warning |
---|
1332 | ~~~~~~~~ |
---|
1333 | |
---|
1334 | The ``%warning`` macro outputs the following string as a warning. This can also |
---|
1335 | be used as ``%{warning: message}``. |
---|
1336 | |
---|
1337 | %error |
---|
1338 | ~~~~~~ |
---|
1339 | |
---|
1340 | The ``%error`` macro outputs the follow string as an error and exits the RTEMS |
---|
1341 | Source Builder. This can also be used as ``%{error: message}``. |
---|
1342 | |
---|
1343 | %select |
---|
1344 | ~~~~~~~ |
---|
1345 | |
---|
1346 | The ``%select`` macro selects the map specified. If there is no map no error or |
---|
1347 | warning is generated. Macro maps provide a simple way for a user to override |
---|
1348 | the settings in a configuration file without having to edit it. The changes are |
---|
1349 | recorded in the build report so they can be traced. |
---|
1350 | |
---|
1351 | Configurations use different maps so macro overrides can target a specific |
---|
1352 | package. |
---|
1353 | |
---|
1354 | The default map is ``global``:: |
---|
1355 | |
---|
1356 | %select gcc-4.8-snapshot <1> |
---|
1357 | %define one_plus_one 2 <2> |
---|
1358 | |
---|
1359 | .. topic:: Items: |
---|
1360 | |
---|
1361 | 1. The map switches to ``gcc-4.8-snapshot``. Any overrides in this map will |
---|
1362 | be used. |
---|
1363 | |
---|
1364 | 2. Defining macros only updates the ``global`` map and not the selected map. |
---|
1365 | |
---|
1366 | %define |
---|
1367 | ~~~~~~~ |
---|
1368 | |
---|
1369 | The ``%define`` macro defines a new macro or updates an existing one. If no |
---|
1370 | value is given it is assumed to be ``1``:: |
---|
1371 | |
---|
1372 | %define foo bar |
---|
1373 | %define one_plus_one 2 |
---|
1374 | %define one <1> |
---|
1375 | |
---|
1376 | .. topic:: Items: |
---|
1377 | |
---|
1378 | 1. The macro _one_ is set to 1. |
---|
1379 | |
---|
1380 | %undefine |
---|
1381 | ~~~~~~~~~ |
---|
1382 | |
---|
1383 | The ``%undefine`` macro removes a macro if it exists. Any further references to |
---|
1384 | it will result in an undefine macro error. |
---|
1385 | |
---|
1386 | %if |
---|
1387 | ~~~ |
---|
1388 | |
---|
1389 | The ``%if`` macro starts a conditional logic block that can optionally have a |
---|
1390 | *else* section. A test follows this macro and can have the following operators: |
---|
1391 | |
---|
1392 | .. list-table:: |
---|
1393 | |
---|
1394 | * - **%{}** |
---|
1395 | - Check the macro is set or *true*, ie non-zero:: |
---|
1396 | |
---|
1397 | %if ${foo} |
---|
1398 | %warning The test passes, must not be empty or is non-zero |
---|
1399 | %else |
---|
1400 | %error The test fails, must be empty or zero |
---|
1401 | %endif |
---|
1402 | |
---|
1403 | * - **\!** |
---|
1404 | - The *not* operator inverts the test of the macro:: |
---|
1405 | |
---|
1406 | %if ! ${foo} |
---|
1407 | %warning The test passes, must be empty or zero |
---|
1408 | %else |
---|
1409 | %error The test fails, must not be empty or is non-zero |
---|
1410 | %endif |
---|
1411 | |
---|
1412 | * - **==** |
---|
1413 | - The left hand size must equal the right hand side. For example:: |
---|
1414 | |
---|
1415 | %define one 1 |
---|
1416 | %if ${one} == 1 |
---|
1417 | %warning The test passes |
---|
1418 | %else |
---|
1419 | %error The test fails |
---|
1420 | %endif |
---|
1421 | You can also check to see if a macro is empty:: |
---|
1422 | |
---|
1423 | %if ${nothing} == %{nil} |
---|
1424 | %warning The test passes |
---|
1425 | %else |
---|
1426 | %error The test fails |
---|
1427 | |
---|
1428 | * - **!=** |
---|
1429 | - The left hand size does not equal the right hand side. For example:: |
---|
1430 | |
---|
1431 | # |
---|
1432 | # Check a value not being equal. |
---|
1433 | # |
---|
1434 | %define one 1 |
---|
1435 | %if ${one} != 2 |
---|
1436 | %warning The test passes |
---|
1437 | %else |
---|
1438 | %error The test fails |
---|
1439 | %endif |
---|
1440 | # |
---|
1441 | # Check if a macro is set. |
---|
1442 | # |
---|
1443 | %if ${something} != %{nil} |
---|
1444 | %warning The test passes |
---|
1445 | %else |
---|
1446 | %error The test fails |
---|
1447 | %endif |
---|
1448 | |
---|
1449 | * - **>** |
---|
1450 | - The left hand side is numerically greater than the right hand side. |
---|
1451 | |
---|
1452 | * - **>** |
---|
1453 | - The left hand side is numerically greater than or equal to the |
---|
1454 | right hand side. |
---|
1455 | |
---|
1456 | * - **<** |
---|
1457 | - The left hand side is numerically less than the right hand side. |
---|
1458 | |
---|
1459 | * - **<=** |
---|
1460 | - The left hand side is numerically less than or equal to the |
---|
1461 | right hand side. |
---|
1462 | |
---|
1463 | %ifn |
---|
1464 | ~~~~ |
---|
1465 | |
---|
1466 | The ``%ifn`` macro inverts the normal ``%if`` logic. It avoids needing to provide |
---|
1467 | empty *if* blocks followed by *else* blocks. It is useful when checking if a |
---|
1468 | macro is defined:: |
---|
1469 | |
---|
1470 | %ifn %{defined foo} |
---|
1471 | %define foo bar |
---|
1472 | %endif |
---|
1473 | |
---|
1474 | %ifarch |
---|
1475 | ~~~~~~~ |
---|
1476 | |
---|
1477 | The ``%ifarch`` is a short cut for ``%if %{_arch} == i386``. Currently not used. |
---|
1478 | |
---|
1479 | %ifnarch |
---|
1480 | ~~~~~~~~ |
---|
1481 | |
---|
1482 | The ``%ifnarch`` is a short cut for ``%if %{_arch} != i386``. Currently not |
---|
1483 | used. |
---|
1484 | |
---|
1485 | %ifos |
---|
1486 | ~~~~~ |
---|
1487 | |
---|
1488 | The ``%ifos`` is a short cut for ``%if %{_os} != mingw32``. It allows |
---|
1489 | conditional support for various operating system differences when building |
---|
1490 | packages. |
---|
1491 | |
---|
1492 | %else |
---|
1493 | ~~~~~ |
---|
1494 | |
---|
1495 | The ``%else`` macro starts the conditional *else* block. |
---|
1496 | |
---|
1497 | %endfi |
---|
1498 | ~~~~~~ |
---|
1499 | |
---|
1500 | The ``%endif`` macro ends a conditional logic block. |
---|
1501 | |
---|
1502 | %bconf_with |
---|
1503 | ~~~~~~~~~~~ |
---|
1504 | |
---|
1505 | The ``%bconf_with`` macro provides a way to test if the user has passed a |
---|
1506 | specific option on the command line with the ``--with-<label>`` option. This |
---|
1507 | option is only available with the ``sb-builder`` command. |
---|
1508 | |
---|
1509 | %bconf_without |
---|
1510 | ~~~~~~~~~~~~~~ |
---|
1511 | |
---|
1512 | The ``%bconf_without`` macro provides a way to test if the user has passed a |
---|
1513 | specific option on the command line with the ``--without-<label>`` option. This |
---|
1514 | option is only available with the ``sb-builder`` command. |
---|