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