[e52906b] | 1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
[8b64335] | 2 | |
---|
[4886d60] | 3 | .. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org> |
---|
[8b64335] | 4 | |
---|
| 5 | .. _Configuration: |
---|
| 6 | |
---|
| 7 | Configuration |
---|
[9742e45] | 8 | ============= |
---|
[8b64335] | 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 |
---|
[9742e45] | 48 | ------------------ |
---|
[8b64335] | 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 |
---|
[9742e45] | 78 | ~~~~~~~~~~~~~~~~~~~~ |
---|
[8b64335] | 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 | |
---|
[c41810b] | 117 | The output of the decompression tool is fed to the standard ``tar`` utility if |
---|
[8b64335] | 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 |
---|
[c41810b] | 123 | group. The first set command encountered is registered and any further set |
---|
[8b64335] | 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 |
---|
[c41810b] | 128 | package. The source's ``setup`` command must reside in the ``%prep:`` section |
---|
[8b64335] | 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 |
---|
[9742e45] | 141 | ~~~ |
---|
[8b64335] | 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 |
---|
[9742e45] | 185 | ~~~ |
---|
[8b64335] | 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 |
---|
[9742e45] | 213 | ------------------- |
---|
[8b64335] | 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 |
---|
[9742e45] | 244 | ~~~~~~~~~~~~~~~~~~~~ |
---|
[8b64335] | 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 |
---|
[9742e45] | 341 | ~~~~~~~~~~~~~~~ |
---|
[8b64335] | 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 |
---|
[9742e45] | 352 | -------------- |
---|
[8b64335] | 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 |
---|
[9742e45] | 395 | --------------- |
---|
[8b64335] | 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 |
---|
[9742e45] | 428 | --------------------- |
---|
[8b64335] | 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 |
---|
[9742e45] | 479 | ----------------------- |
---|
[8b64335] | 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 |
---|
[9742e45] | 499 | ------------------ |
---|
[8b64335] | 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 |
---|
[9742e45] | 512 | ~~~~~~~~~~~~~~~~~~~~~ |
---|
[8b64335] | 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 |
---|
[9742e45] | 523 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
[8b64335] | 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 |
---|
[9742e45] | 538 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
[8b64335] | 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 |
---|
[9742e45] | 549 | ~~~~~~~~~~~ |
---|
[8b64335] | 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 |
---|
[c41810b] | 586 | knows this is GZip'ped tar file. If more than one package is needed, add |
---|
[8b64335] | 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 |
---|
[c41810b] | 644 | systems we need to use the BSD make and not the GNU make. |
---|
[8b64335] | 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 |
---|
[c41810b] | 751 | file is created. This can then be installed using root priviledges. |
---|
[8b64335] | 752 | |
---|
| 753 | The command also supplies the ``--trace`` option. The output in the log file |
---|
[c41810b] | 754 | will contain all the macros. |
---|
[8b64335] | 755 | |
---|
| 756 | Debugging |
---|
[9742e45] | 757 | ~~~~~~~~~ |
---|
[8b64335] | 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 |
---|
[c41810b] | 770 | the RSB and supply ``--no-clean`` option and then locate the build directories |
---|
[8b64335] | 771 | and change directory into them and manually run commands until to figure what |
---|
| 772 | the package requires. |
---|
| 773 | |
---|
| 774 | Scripting |
---|
[9742e45] | 775 | --------- |
---|
[8b64335] | 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``: |
---|
[c41810b] | 825 | Define a patch. This macro has a number appended. |
---|
[8b64335] | 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 |
---|
[9742e45] | 878 | ~~~~~~~~~ |
---|
[8b64335] | 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 |
---|
[9742e45] | 920 | ~~~~~ |
---|
[8b64335] | 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 |
---|
[9742e45] | 1013 | ~~~~~~ |
---|
[8b64335] | 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 | |
---|
[c41810b] | 1020 | The following is an example take from the GitHub STLink project. The STLink is |
---|
[8b64335] | 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 |
---|
[9742e45] | 1076 | ~~~~~~~~ |
---|
[8b64335] | 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 |
---|
[c41810b] | 1080 | the package. You can assume the package has built correctly when this block |
---|
[8b64335] | 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 | |
---|
[c41810b] | 1104 | 2. Clean any installed files. This makes sure the install is just what the |
---|
[8b64335] | 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 |
---|
[9742e45] | 1115 | ~~~~~~ |
---|
[8b64335] | 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 |
---|
[9742e45] | 1123 | ~~~~~~~~ |
---|
[8b64335] | 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 |
---|
[9742e45] | 1142 | ~~~~~ |
---|
[8b64335] | 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 |
---|
[9742e45] | 1151 | ~~~~~~~~ |
---|
[8b64335] | 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 |
---|
[9742e45] | 1160 | ~~~~~~~~ |
---|
[8b64335] | 1161 | |
---|
[c41810b] | 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 |
---|
[8b64335] | 1164 | the configuration building the package changes:: |
---|
| 1165 | |
---|
| 1166 | %define release 1 |
---|
| 1167 | |
---|
| 1168 | %version |
---|
[9742e45] | 1169 | ~~~~~~~~ |
---|
[8b64335] | 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 |
---|
[9742e45] | 1180 | ~~~~~~~~~~ |
---|
[8b64335] | 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 |
---|
[9742e45] | 1188 | ~~~~~~~ |
---|
[8b64335] | 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 |
---|
[c41810b] | 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 |
---|
[8b64335] | 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 |
---|
[c41810b] | 1205 | source files to be set up. Subsequent ``set`` commands for the same source |
---|
[8b64335] | 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 |
---|
[9742e45] | 1257 | ~~~~~~ |
---|
[8b64335] | 1258 | |
---|
| 1259 | The ``%patch`` macro has the same 3 command as the ``%source`` command however |
---|
[c41810b] | 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 |
---|
[8b64335] | 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 | |
---|
[c41810b] | 1270 | The ``__patchdir`` path is searched. |
---|
[8b64335] | 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 |
---|
[9742e45] | 1293 | ~~~~~ |
---|
[8b64335] | 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 |
---|
[c41810b] | 1297 | and once downloaded. A patch or source file that does not have a hash defined |
---|
[8b64335] | 1298 | generates a warning. |
---|
| 1299 | |
---|
[c41810b] | 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. |
---|
[8b64335] | 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 | |
---|
[c41810b] | 1322 | Downloading off repositories such as git and cvs cannot be checksummed. It is |
---|
[8b64335] | 1323 | assumed those protocols and tools manage the state of the files. |
---|
| 1324 | |
---|
| 1325 | %echo |
---|
[9742e45] | 1326 | ~~~~~ |
---|
[8b64335] | 1327 | |
---|
| 1328 | The ``%echo`` macro outputs the following string to stdout. This can also be used |
---|
| 1329 | as ``%{echo: message}``. |
---|
| 1330 | |
---|
| 1331 | %warning |
---|
[9742e45] | 1332 | ~~~~~~~~ |
---|
[8b64335] | 1333 | |
---|
| 1334 | The ``%warning`` macro outputs the following string as a warning. This can also |
---|
| 1335 | be used as ``%{warning: message}``. |
---|
| 1336 | |
---|
| 1337 | %error |
---|
[9742e45] | 1338 | ~~~~~~ |
---|
[8b64335] | 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 |
---|
[9742e45] | 1344 | ~~~~~~~ |
---|
[8b64335] | 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 |
---|
[c41810b] | 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. |
---|
[8b64335] | 1350 | |
---|
[c41810b] | 1351 | Configurations use different maps so macro overrides can target a specific |
---|
[8b64335] | 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 |
---|
[9742e45] | 1367 | ~~~~~~~ |
---|
[8b64335] | 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 |
---|
[9742e45] | 1381 | ~~~~~~~~~ |
---|
[8b64335] | 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 |
---|
[9742e45] | 1387 | ~~~ |
---|
[8b64335] | 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 |
---|
[9742e45] | 1464 | ~~~~ |
---|
[8b64335] | 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 |
---|
[9742e45] | 1475 | ~~~~~~~ |
---|
[8b64335] | 1476 | |
---|
| 1477 | The ``%ifarch`` is a short cut for ``%if %{_arch} == i386``. Currently not used. |
---|
| 1478 | |
---|
| 1479 | %ifnarch |
---|
[9742e45] | 1480 | ~~~~~~~~ |
---|
[8b64335] | 1481 | |
---|
| 1482 | The ``%ifnarch`` is a short cut for ``%if %{_arch} != i386``. Currently not |
---|
| 1483 | used. |
---|
| 1484 | |
---|
| 1485 | %ifos |
---|
[9742e45] | 1486 | ~~~~~ |
---|
[8b64335] | 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 |
---|
[9742e45] | 1493 | ~~~~~ |
---|
[8b64335] | 1494 | |
---|
| 1495 | The ``%else`` macro starts the conditional *else* block. |
---|
| 1496 | |
---|
| 1497 | %endfi |
---|
[9742e45] | 1498 | ~~~~~~ |
---|
[8b64335] | 1499 | |
---|
| 1500 | The ``%endif`` macro ends a conditional logic block. |
---|
| 1501 | |
---|
| 1502 | %bconf_with |
---|
[9742e45] | 1503 | ~~~~~~~~~~~ |
---|
[8b64335] | 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 |
---|
[9742e45] | 1510 | ~~~~~~~~~~~~~~ |
---|
[8b64335] | 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. |
---|