source: rtems-docs/user/rsb/configuration.rst @ bb47f89

Last change on this file since bb47f89 was bb47f89, checked in by Chris Johns <chrisj@…>, on Oct 13, 2019 at 8:51:25 AM

user/rsb: Update 3rd party package build and add packaging details.

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