Changeset 8b64335 in rtems-docs for rsb/source-builder.rst

Nov 2, 2016, 1:09:54 AM (4 years ago)
Chris Johns <chrisj@…>
4.11, 5, am, master

RSB: Finish reformatting after moving from asciidocs.

1 edited


  • rsb/source-builder.rst

    r75e787d r8b64335  
    44.. comment Chris Johns <>
    6 RTEMS Tools From Source
    7 #######################
     6RTEMS Source Builder
    9 The RTEMS Source Builder is a tool to aid building packages from source used by
    10 the RTEMS project. It helps consolidate the details you need to build a package
    11 from source in a controlled and verifiable way. The tool is aimed at developers
    12 of software who use tool sets for embedded type development and is not limited
    13 to building just for RTEMS. Embedded development typically uses cross-compiling
    14 tool chains, debuggers, and debugging aids. Together we call these a 'tool
    15 set'. The RTEMS Source Builder is not limited to this role but designed to fit
    16 with-in this specific niche. It can be used outside of the RTEMS project and we
    17 welcome this happening in other open source or commercial projects.
     9The RTEMS Source Builder or RSB is a tool to build packages from source. It is
     10used by the RTEMS project to build it's compilers and OS. The RSB helps
     11consolidate the details you need to build a package from source in a controlled
     12and verifiable way. The tool is aimed at developers of software who use tool
     13sets for embedded development. The RSB is not limited to building tools just
     14for RTEMS, you can build bare metal development environments.
    19 The RTEMS Source Builder is typically used to build a set of tools or a 'build
    20 set'. A 'build set' is a collection of packages and a package is a specific
    21 tool, for example gcc or gdb. The RTEMS Source Builder attempts to support any
    22 host environment that runs Python and you can build the package on. It is not
    23 some sort of magic that can take any piece of source code and make it
    24 build. Someone at some point in time has figured out how to build that package
    25 from source and taught this tool. The RTEMS Source Builder has been tested on:
     16Embedded development typically uses cross-compiling tool chains, debuggers, and
     17debugging aids. Together we call these a **tool set**. The RTEMS Source Builder
     18is designed to fit this specific niche but is not limited to it. The RSB can be
     19used outside of the RTEMS project and we welcome this.
    27 .. _platform_links:
     21The RTEMS Source Builder is typically used to build a set of tools or a **build
     22set**. A **build set** is a collection of packages and a package is a specific
     23tool, for example gcc or gdb, or library. The RTEMS Source Builder attempts to
     24support any host environment that runs Python and you can build the package
     25on. The RSB is not some sort of magic that can take any piece of source code
     26and make it build. Someone at some point in time has figured out how to build
     27that package from source and taught this tool.
    29 - :ref:`ArchLinux`
     29The RTEMS Source Builder has been tested on:
    31 - :ref:`CentOS`
     31- ArchLinux
     32- CentOS
     33- Fedora
     34- Raspbian
     35- Ubuntu (includes XUbuntu)
     36- Linux Mint
     37- openSUSE
     38- FreeBSD
     39- NetBSD
     40- MacOS
     41- Windows
    33 - :ref:`Fedora`
     43.. topic:: Setting up your Host
    35 - :ref:`Raspbian`
    37 - :ref:`Ubuntu` (includes XUbuntu)
    39 - :ref:`Linux Mint`
    41 - :ref:`openSUSE`
    43 - :ref:`FreeBSD`
    45 - :ref:`NetBSD`
    47 - :ref:`MacOS`
    49 - :ref:`Windows`
     45   :ref:`Hosts` details setting up hosts.
    5147The RTEMS Source Builder has two types of configuration data. The first is the
    5753is built. Configuration files are scripts loosely based on the RPM spec file
    5854format and they detail the steps needed to build a package. The steps are
    59 'preparation', 'building', and 'installing'. Scripts support macros, shell
     55*preparation*, *building*, and *installing*. Scripts support macros, shell
    6056expansion, logic, includes plus many more features useful when build packages.
    6460build or packages and software your host system you may have installed. We
    6561assume the build sets and configuration files you are using have been created
    66 by developers who do. Support is provided for package config or pkgconfg type
    67 files so you can check and use standard libraries if present. If you have a
    68 problem please ask on the RTEMS Users mailing list.
     62by developers who do. Support is provided for package config or ``pkgconfg``
     63type files so you can check and use standard libraries if present. If you have
     64a problem please ask on our :r:list:`devel`.
    7066.. comment: TBD: The section "Installing and Tar Files" does not exist.
    7773configuration can read the remaining sections.
    79 .. sidebar: Bug Reporting:
    80   IMPORTANT: If you have a problem please see <<_bugs,the reporting bugs>>
    81   section.
     75.. topic:: Bug Reporting
    83 Quick Start
    84 ###########
    86 The quick start will show you how to build a set of RTEMS tools for a supported
    87 architecture. The tools are installed into a build *prefix*. The *prefix* is the
    88 top of a group of directories containing all the files needed to develop RTEMS
    89 applications. Building an RTEMS build set will build all that you need. This
    90 includes autoconf, automake, assemblers, linkers, compilers, debuggers,
    91 standard libraries and RTEMS itself.
    93 There is no need to become root or the administrator and we recommend you
    94 avoid doing this. You can build and install the tools anywhere on the
    95 host's file system you, as a standard user, have read and write access
    96 too. I recommend you use your home directory and work under the directory
    97 ``~/development/rtems``. The examples shown here will do this.
    99 You can use the build *prefix* to install and maintain different versions of
    100 the tools. Doing this lets you try a new set of tools while not touching your
    101 proven working production set of tools. Once you have proven the new tools are
    102 working rebuild with the 'production' prefix switching your development to them.
    104 I also suggest you keep your environment to the bare minimum, particularly the
    105 path variable. Using environment variables has been proven over the years to be
    106 difficult to manage in production systems.
    108 .. comment   Host Setup
    110 .. note:: Host Setup
    111     IMPORTANT: Before proceeding to the next section please refer to the
    112     :ref:`Host Setups` for your host and install any extra
    113     packages. The RSB assumes the needed packages are installed and work.
    115 .. comment .Path to use when building applications
    117 .. note:: Path to use when building applications
    118     TIP: Do not forget to do this before you use the tools such as build RTEMS.
    120 The RSB by default will install (copy) the executables under the prefix
    121 you supply. To use the tools once finished just set your path to the
    122 'bin' directory under the *prefix* you use. In the examples that follow
    123 the *prefix* is ``$HOME/development/rtems/4.11`` and is set using
    124 the ``--prefix`` option so the path you need to configure to build
    125 applications can be set with the following
    126 in a BASH shell:
    128 .. code-block:: shell
    130     $ export PATH=$HOME/development/rtems/4.11/bin:$PATH
    132 Make sure you place the RTEMS tool path at the front of your path so they are
    133 searched first. RTEMS can provide newer versions of some tools your operating
    134 system provides and placing the RTEMS tools path at the front means it is
    135 searched first and the RTEMS needed versions of the tools are used.
    137 .. note::
    139     RSB and RTEMS have matching ``git branch`` for each version of RTEMS.
    140     For example, if you want to build a toolchain for 4.11, then you
    141     should checkout the 4.11 branch of the RSB:
    143     ``$ git checkout -t origin/4.11``
    145     Branches are available for the 4.9, 4.10, and 4.11 versions of RTEMS.
    147 Setup
    148 ~~~~~
    150 Setup a development work space:
    152 .. code-block:: shell
    154     $ cd
    155     $ mkdir -p development/rtems/src
    156     $ cd development/rtems/src
    158 The RTEMS Source Builder is distributed as source. It is Python code so all you
    159 need to do is head over to the RTEMS GIT repository and clone the code directly
    160 from git:
    162 .. code-block:: shell
    164     $ git clone git://
    165     $ cd rtems-source-builder
    167 Checking
    168 ~~~~~~~~
    170 The next step is to check if your host is set up correctly. The RTEMS Source
    171 Builder provides a tool to help:
    173 .. code-block:: shell
    175     $ source-builder/sb-check
    176     warning: exe: absolute exe found in path: (__objcopy) /usr/local/bin/objcopy <1>
    177     warning: exe: absolute exe found in path: (__objdump) /usr/local/bin/objdump
    178     error: exe: not found: (_xz) /usr/local/bin/xz <2>
    179     RTEMS Source Builder environment is not correctly set up
    180     $ source-builder/sb-check
    181     RTEMS Source Builder environment is ok <3>
    184 - *<1>* A tool is in the environment path but does not match the
    185   expected path.
    187 - *<2>* The executable 'xz' is not found.
    189 - *<3>* The host's environment is set up correct.
    191 The checking tool will output a list of executable files not found if problems
    192 are detected. Locate those executable files and install them. You may also be
    193 given a list of warnings about executable files not in the expected location
    194 however the executable was located somewhere in your environment's path. You
    195 will need to check each tool to determine if this is an issue. An executable
    196 not in the standard location may indicate it is not the host operating system's
    197 standard tool. It maybe ok or it could be buggy, only you can determine this.
    199 The :ref:`Host Setups` section lists packages you should install for
    200 common host operating systems. It maybe worth checking if you have
    201 those installed.
    203 Build Sets
    204 ~~~~~~~~~~
    206 The RTEMS tools can be built within the RTEMS Source Builder's source tree. We
    207 recommend you do this so lets change into the RTEMS directory in the RTEMS
    208 Source Builder package:
    210 .. code-block:: shell
    212     $ cd rtems
    214 If you are unsure how to specify the build set for the architecture you wish to
    215 build ask the tool:
    217 .. code-block:: shell
    219     $ ../source-builder/sb-set-builder --list-bsets <1>
    220     RTEMS Source Builder - Set Builder, v0.2.0
    221     Examining: config <2>
    222     Examining: ../source-builder/config <2>
    223         4.10/rtems-all.bset <3>
    224         4.10/rtems-arm.bset <4>
    225         4.10/rtems-autotools.bset
    226         4.10/rtems-avr.bset
    227         4.10/rtems-bfin.bset
    228         4.10/rtems-h8300.bset
    229         4.10/rtems-i386.bset
    230         4.10/rtems-lm32.bset
    231         4.10/rtems-m32c.bset
    232         4.10/rtems-m32r.bset
    233         4.10/rtems-m68k.bset
    234         4.10/rtems-mips.bset
    235         4.10/rtems-nios2.bset
    236         4.10/rtems-powerpc.bset
    237         4.10/rtems-sh.bset
    238         4.10/rtems-sparc.bset
    239         4.11/rtems-all.bset
    240         4.11/rtems-arm.bset
    241         4.11/rtems-autotools.bset
    242         4.11/rtems-avr.bset
    243         4.11/rtems-bfin.bset
    244         4.11/rtems-h8300.bset
    245         4.11/rtems-i386.bset
    246         4.11/rtems-lm32.bset
    247         4.11/rtems-m32c.bset
    248         4.11/rtems-m32r.bset
    249         4.11/rtems-m68k.bset
    250         4.11/rtems-microblaze.bset
    251         4.11/rtems-mips.bset
    252         4.11/rtems-moxie.bset
    253         4.11/rtems-nios2.bset
    254         4.11/rtems-powerpc.bset
    255         4.11/rtems-sh.bset
    256         4.11/rtems-sparc.bset
    257         4.11/rtems-sparc64.bset
    258         4.11/rtems-v850.bset
    259         4.9/rtems-all.bset
    260         4.9/rtems-arm.bset
    261         4.9/rtems-autotools.bset
    262         4.9/rtems-i386.bset
    263         4.9/rtems-m68k.bset
    264         4.9/rtems-mips.bset
    265         4.9/rtems-powerpc.bset
    266         4.9/rtems-sparc.bset
    267         gnu-tools-4.6.bset
    268         rtems-4.10-base.bset <5>
    269         rtems-4.11-base.bset
    270         rtems-4.9-base.bset
    271         rtems-base.bset <5>
    272         unstable/4.11/rtems-all.bset <6>
    273         unstable/4.11/rtems-arm.bset
    274         unstable/4.11/rtems-avr.bset
    275         unstable/4.11/rtems-bfin.bset
    276         unstable/4.11/rtems-h8300.bset
    277         unstable/4.11/rtems-i386.bset
    278         unstable/4.11/rtems-lm32.bset
    279         unstable/4.11/rtems-m32c.bset
    280         unstable/4.11/rtems-m32r.bset
    281         unstable/4.11/rtems-m68k.bset
    282         unstable/4.11/rtems-microblaze.bset
    283         unstable/4.11/rtems-mips.bset
    284         unstable/4.11/rtems-moxie.bset
    285         unstable/4.11/rtems-powerpc.bset
    286         unstable/4.11/rtems-sh.bset
    287         unstable/4.11/rtems-sparc.bset
    288         unstable/4.11/rtems-sparc64.bset
    289         unstable/4.11/rtems-v850.bset
    291 - *<1>* Only option needed is ``--list-bsets``
    293 - *<2>* The paths inspected. See <<X1,``_configdir``>> variable.
    295 - *<3>* Build all RTEMS 4.10 supported architectures.
    297 - *<4>* The build set for the ARM architecture on RTEMS 4.10.
    299 - *<5>* Support build set file with common functionality included by
    300   other build set files.
    302 - *<6>* Unstable tool sets are used by RTEMS developers to test new
    303   tool sets. You are welcome to try them but you must remember they are
    304   unstable, can change at any point in time and your application may
    305   not work. If you have an issue with a production tool it may pay to
    306   try the unstable tool to see if it has been resolved.
    308 Building
    309 ~~~~~~~~
    311 In this quick start I will build a SPARC tool set.
    313 .. code-block:: shell
    315     $ ../source-builder/sb-set-builder --log=l-sparc.txt <1> \
    316           --prefix=$HOME/development/rtems/4.11 <2> 4.11/rtems-sparc <3>
    317     Source Builder - Set Builder, v0.2.0
    318     Build Set: 4.11/rtems-sparc
    319     config: expat-2.1.0-1.cfg <4>
    320     package: expat-2.1.0-x86_64-freebsd9.1-1
    321     building: expat-2.1.0-x86_64-freebsd9.1-1
    322     config: tools/rtems-binutils-2.22-1.cfg <5>
    323     package: sparc-rtems4.11-binutils-2.22-1
    324     building: sparc-rtems4.11-binutils-2.22-1
    325     config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg <6>
    326     package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    327     building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    328     config: tools/rtems-gdb-7.5.1-1.cfg <7>
    329     package: sparc-rtems4.11-gdb-7.5.1-1
    330     building: sparc-rtems4.11-gdb-7.5.1-1
    331     installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <8>
    332     installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
    333     installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
    334     installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
    335     cleaning: expat-2.1.0-x86_64-freebsd9.1-1 <9>
    336     cleaning: sparc-rtems4.11-binutils-2.22-1
    337     cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    338     cleaning: sparc-rtems4.11-gdb-7.5.1-1
    339     Build Set: Time 0:13:43.616383 <10>
    341 - *<1>* Providing a log file redirects the build output into a file. Logging the
    342   build output provides a simple way to report problems.
    344 - *<2>* The prefix is the location on your file system the tools are installed
    345   into. Provide a prefix to a location you have read and write access. You
    346   can use the prefix to install different versions or builds of tools. Just
    347   use the path to the tools you want to use when building RTEMS.
    349 - *<3>* The build set. This is the SPARC build set. First a specifically
    350   referenced file is checked for and if not found the '%{_configdir} path
    351   is searched. The set builder will first look for files with a ``.bset``
    352   extension and then for a configuration file with a ``.cfg`` extension.
    354 - *<4>* The SPARC build set first builds the expat library as it is used in GDB.
    355   This is the expat configuration used.
    357 - *<5>* The binutils build configuration.
    359 - *<6>* The GCC and Newlib build configuration.
    361 - *<7>* The GDB build configuration.
    363 - *<8>* Installing the built packages to the install prefix.
    365 - *<9>* All the packages built are cleaned at the end. If the build fails
    366   all the needed files are present. You may have to clean up by deleting
    367   the build directory if the build fails.
    369 - *<10>* The time to build the package. This lets you see how different
    370   host hardware or configurations perform.
    372 Your SPARC RTEMS 4.11 tool set will be installed and ready to build RTEMS and
    373 RTEMS applications. When the build runs you will notice the tool fetch the
    374 source code from the internet. These files are cached in a directory called
    375 ``source``. If you run the build again the cached files are used. This is what
    376 happened in the shown example before.
    378 TIP: The RSB for releases will automatically build and install RTEMS. The
    379 development version require adding ``--with-rtems``. Use this for a single
    380 command to get the tools and RTEMS with one command.
    382 The installed tools:
    384 .. code-block:: shell
    386     $ ls $HOME/development/rtems/4.11
    387     bin         include     lib         libexec     share       sparc-rtems4.11
    388     $ ls $HOME/development/rtems/4.11/bin
    389     sparc-rtems4.11-addr2line       sparc-rtems4.11-cpp
    390     sparc-rtems4.11-gcc-ar          sparc-rtems4.11-gprof
    391     sparc-rtems4.11-objdump         sparc-rtems4.11-size
    392     sparc-rtems4.11-ar              sparc-rtems4.11-elfedit
    393     sparc-rtems4.11-gcc-nm          sparc-rtems4.11-ld
    394     sparc-rtems4.11-ranlib          sparc-rtems4.11-strings
    395     sparc-rtems4.11-as              sparc-rtems4.11-g++
    396     sparc-rtems4.11-gcc-ranlib      sparc-rtems4.11-ld.bfd
    397     sparc-rtems4.11-readelf         sparc-rtems4.11-strip
    398     sparc-rtems4.11-c++             sparc-rtems4.11-gcc
    399     sparc-rtems4.11-gcov            sparc-rtems4.11-nm
    400     sparc-rtems4.11-run             xmlwf
    401     sparc-rtems4.11-c++filt         sparc-rtems4.11-gcc-4.7.2
    402     sparc-rtems4.11-gdb             sparc-rtems4.11-objcopy
    403     sparc-rtems4.11-sis
    404     $ $HOME/development/rtems/4.11/bin/sparc-rtems4.11-gcc -v
    405     Using built-in specs.
    406     COLLECT_GCC=/home/chris/development/rtems/4.11/bin/sparc-rtems4.11-gcc
    407     COLLECT_LTO_WRAPPER=/usr/home/chris/development/rtems/4.11/bin/../ \
    408     libexec/gcc/sparc-rtems4.11/4.7.2/lto-wrapper
    409     Target: sparc-rtems4.11 <1>
    410     Configured with: ../gcc-4.7.2/configure <2>
    411     --prefix=/home/chris/development/rtems/4.11
    412     --bindir=/home/chris/development/rtems/4.11/bin
    413     --exec_prefix=/home/chris/development/rtems/4.11
    414     --includedir=/home/chris/development/rtems/4.11/include
    415     --libdir=/home/chris/development/rtems/4.11/lib
    416     --libexecdir=/home/chris/development/rtems/4.11/libexec
    417     --mandir=/home/chris/development/rtems/4.11/share/man
    418     --infodir=/home/chris/development/rtems/4.11/share/info
    419     --datadir=/home/chris/development/rtems/4.11/share
    420     --build=x86_64-freebsd9.1 --host=x86_64-freebsd9.1 --target=sparc-rtems4.11
    421     --disable-libstdcxx-pch --with-gnu-as --with-gnu-ld --verbose --with-newlib
    422     --with-system-zlib --disable-nls --without-included-gettext
    423     --disable-win32-registry --enable-version-specific-runtime-libs --disable-lto
    424     --enable-threads --enable-plugin --enable-newlib-io-c99-formats
    425     --enable-newlib-iconv --enable-languages=c,c++
    426     Thread model: rtems <3>
    427     gcc version 4.7.2 20120920 <4>
    428      (RTEMS4.11-RSB(cb12e4875c203f794a5cd4b3de36101ff9a88403)-1,gcc-4.7.2/newlib-2.0.0) (GCC)
    430 - *<1>* The target the compiler is built for.
    432 - *<2>* The configure options used to build GCC.
    434 - *<3>* The threading model is always RTEMS. This makes the RTEMS tools
    435   difficult for bare metal development more difficult.
    437 - *<4>* The version string. It contains the Git hash of the RTEMS Source Builder
    438   you are using. If your local clone has been modifed that state is also
    439   recorded in the version string. The hash allows you to track from a GCC
    440   executable back to the original source used to build it.
    442 NOTE: The RTEMS thread model enables specific hooks in GCC so applications
    443 built with RTEMS tools need the RTEMS runtime to operate correctly. You can use
    444 RTEMS tools to build bare metal component but it is more difficult than with a
    445 bare metal tool chain and you need to know what you are doing at a low
    446 level. The RTEMS Source Builder can build bare metal tool chains as well. Look
    447 in the top level ``bare`` directory.
    449 Distributing and Archiving A Build
    450 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    452 If you wish to create and distribute your build or you want to archive a build
    453 you can create a tar file. This is a more advanced method for binary packaging
    454 and installing of tools.
    456 By default the RTEMS Source Builder installs the built packages directly and
    457 optionally it can also create a *build set tar file* or a *package tar file*
    458 per package built. The normal and default behaviour is to let the RTEMS Source
    459 Builder install the tools. The source will be downloaded, built, installed and
    460 cleaned up.
    462 The tar files are created with the full build prefix present and if you follow
    463 the examples given in this documentation the path is absolute. This can cause
    464 problems if you are installing on a host you do not have super user or
    465 administrator rights on because the prefix path may references part you do not
    466 have write access too and tar will not extract the files. You can use the
    467 ``--strip-components`` option in tar if your host tar application supports it to
    468 remove the parts you do not have write access too or you may need to unpack the
    469 tar file somewhere and copy the file tree from the level you have write access
    470 from. Embedding the full prefix path in the tar files lets you know what the
    471 prefix is and is recommended. For example if
    472 ``/home/chris/development/rtems/4.11`` is the prefix used you cannot change
    473 directory to the root (``/``) and install because the ``/home`` is root access
    474 only. To install you would:
    476 .. code-block:: shell
    478     $ cd
    479     $ tar --strip-components=3 -xjf rtems-4.11-sparc-rtems4.11-1.tar.bz2
    482 A build set tar file is created by adding ``--bset-tar-file`` option to the
    483 ``sb-set-builder`` command.
    485 .. code-block:: shell
    487     $ ../source-builder/sb-set-builder --log=l-sparc.txt \
    488              --prefix=$HOME/development/rtems/4.11 \
    489              --bset-tar-file <1> 4.11/rtems-sparc
    490     Source Builder - Set Builder, v0.2.0
    491     Build Set: 4.11/rtems-sparc
    492     config: expat-2.1.0-1.cfg
    493     package: expat-2.1.0-x86_64-freebsd9.1-1
    494     building: expat-2.1.0-x86_64-freebsd9.1-1
    495     config: tools/rtems-binutils-2.22-1.cfg
    496     package: sparc-rtems4.11-binutils-2.22-1
    497     building: sparc-rtems4.11-binutils-2.22-1
    498     config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
    499     package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    500     building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    501     config: tools/rtems-gdb-7.5.1-1.cfg
    502     package: sparc-rtems4.11-gdb-7.5.1-1
    503     building: sparc-rtems4.11-gdb-7.5.1-1
    504     installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <2>
    505     installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
    506     installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
    507     installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
    508     tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3>
    509     cleaning: expat-2.1.0-x86_64-freebsd9.1-1
    510     cleaning: sparc-rtems4.11-binutils-2.22-1
    511     cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    512     cleaning: sparc-rtems4.11-gdb-7.5.1-1
    513     Build Set: Time 0:15:25.92873
    516 - *<1>* The option to create a build set tar file.
    518 - *<2>* The installation still happens unless you specify ``--no-install``.
    520 - *<3>* Creating the build set tar file.
    522 You can also suppress installing the files using the ``--no-install`` option to
    523 the ``sb-set-builder`` command. This is usefu if your prefix is not accessiable
    524 when building Canadian cross compiled tool sets.
    526 .. code-block:: shell
    528     $ ../source-builder/sb-set-builder --log=l-sparc.txt \
    529                 --prefix=$HOME/development/rtems/4.11 \
    530                 --bset-tar-file --no-install <1> 4.11/rtems-sparc
    531     Source Builder - Set Builder, v0.2.0
    532     Build Set: 4.11/rtems-sparc
    533     config: expat-2.1.0-1.cfg
    534     package: expat-2.1.0-x86_64-freebsd9.1-1
    535     building: expat-2.1.0-x86_64-freebsd9.1-1
    536     config: tools/rtems-binutils-2.22-1.cfg
    537     package: sparc-rtems4.11-binutils-2.22-1
    538     building: sparc-rtems4.11-binutils-2.22-1
    539     config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
    540     package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    541     building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    542     config: tools/rtems-gdb-7.5.1-1.cfg
    543     package: sparc-rtems4.11-gdb-7.5.1-1
    544     building: sparc-rtems4.11-gdb-7.5.1-1
    545     tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 <2>
    546     cleaning: expat-2.1.0-x86_64-freebsd9.1-1
    547     cleaning: sparc-rtems4.11-binutils-2.22-1
    548     cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    549     cleaning: sparc-rtems4.11-gdb-7.5.1-1
    550     Build Set: Time 0:14:11.721274
    551     $ ls tar
    552     rtems-4.11-sparc-rtems4.11-1.tar.bz2
    554 - *<1>* The option to supressing installing the packages.
    556 - *<2>* Create the build set tar.
    558 A package tar file can be created by adding the ``--pkg-tar-files`` to the
    559 ``sb-set-builder`` command. This creates a tar file per package built in the
    560 build set.
    562 .. code-block:: shell
    564     $ ../source-builder/sb-set-builder --log=l-sparc.txt \
    565             --prefix=$HOME/development/rtems/4.11 \
    566             --bset-tar-file --pkg-tar-files <1> --no-install 4.11/rtems-sparc
    567     Source Builder - Set Builder, v0.2.0
    568     Build Set: 4.11/rtems-sparc
    569     config: expat-2.1.0-1.cfg
    570     package: expat-2.1.0-x86_64-freebsd9.1-1
    571     building: expat-2.1.0-x86_64-freebsd9.1-1
    572     config: tools/rtems-binutils-2.22-1.cfg
    573     package: sparc-rtems4.11-binutils-2.22-1
    574     building: sparc-rtems4.11-binutils-2.22-1
    575     config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
    576     package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    577     building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    578     config: tools/rtems-gdb-7.5.1-1.cfg
    579     package: sparc-rtems4.11-gdb-7.5.1-1
    580     building: sparc-rtems4.11-gdb-7.5.1-1
    581     tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2
    582     cleaning: expat-2.1.0-x86_64-freebsd9.1-1
    583     cleaning: sparc-rtems4.11-binutils-2.22-1
    584     cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    585     cleaning: sparc-rtems4.11-gdb-7.5.1-1
    586     Build Set: Time 0:14:37.658460
    587     $ ls tar
    588     expat-2.1.0-x86_64-freebsd9.1-1.tar.bz2           sparc-rtems4.11-binutils-2.22-1.tar.bz2
    589     sparc-rtems4.11-gdb-7.5.1-1.tar.bz2 <2>           rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3>
    590     sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1.tar.bz2
    592 - *<1>* The option to create packages tar files.
    594 - *<2>* The GDB package tar file.
    596 - *<3>* The build set tar file. All the others in a single tar file.
    598 Controlling the Build
    599 ~~~~~~~~~~~~~~~~~~~~~
    601 Build sets can be controlled via the command line to enable and disable various
    602 features. There is no definitive list of build options that can be listed
    603 because they are implemented with the configuration scripts. The best way to
    604 find what is available is to grep the configuration files. for ``with`` and
    605 ``without``.
    607 Following are currentlt available:
    609 '--without-rtems':: Do not build RTEMS when building an RTEMS build set.
    610 '--without-cxx':: Do not build a C++ compiler.
    611 '--with-objc':: Attempt to build a C++ compiler.
    612 '--with-fortran':: Attempt to build a Fortran compiler.
     77   If you think you have found a problem please see :ref:`Bugs, Crashes, and
     78   Build Failures`.
    61480Why Build from Source?
    615 ######################
    61783The RTEMS Source Builder is not a replacement for the binary install systems
    61884you have with commercial operating systems or open source operating system
    61985distributions. Those products and distributions are critically important and
    620 are the base that allows the Source Builder to work. The RTEMS Source Builder
    621 sits somewhere between you manually entering the commands to build a tool set
    622 and a tool such as ``yum`` or ``apt-get`` to install binary packages made
     86are the base that allows the RSB to work. The RTEMS Source Builder sits
     87somewhere between you manually entering the commands to build a tool set and a
     88tool such as ``yum`` or ``apt-get`` to install binary packages made
    62389specifically for your host operating system. Building manually or installing a
    624 binary package from a remote repository are valid and real alternatives while
    625 the Source Builder is attempting to provide a specific service of repeatably
    626 being able to build tool sets from source code.
     90binary package from a remote repository are valid and real alternatives. The
     91RSB provides the specific service of repeatably being able to build tool sets
     92from source code. The process leaves you with the source code used to build
     93the tools and the ability to rebuilt it.
    62895If you are developing a system or product that has a long shelf life or is used
    652119often difficult to resolve problems. On the other side you need to make sure
    653120your tools build and work with newer versions of the host operating
    654 system. Given the stability of standards based libraries like 'libc' and ever
     121system. Given the stability of standards based libraries like ``libc`` and ever
    655122improving support for standard header file locations this task is becoming
    667134computing environment.
    669 .. comment [[_bugs]]
    671 Bugs, Crashes, and Build Failures
    672 #################################
    674 The RTEMS Source Builder is a Python program and every care is taken to test
    675 the code however bugs, crashes, and build failures can and do happen. If you
    676 find a bug please report it via the RTEMS Bug tracker tool Bugzilla or via
    677 email on the RTEMS Users list. RTEMS's bugzilla is found at
    680 Please include the generated RSB report. If you see the following a report has
    681 been generated:
    683 .. code-block:: shell
    685      ...
    686      ...
    687     Build FAILED <1>
    688       See error report: rsb-report-4.11-rtems-lm32.txt <2>
    690 - *<1>* The build has failed.
    692 - *<2>* The report's file name.
    694 The generated report contains the command line, version of the RSB, your host's
    695 ``uname`` details, the version of Python and the last 200 lines of the log.
    697 If for some reason there is no report please send please report the following:
    699 - Command line,
    701 - The git hash,
    703 - Host details with the output of the ``uname -a`` command,
    705 - If you have made any modifications.
    707 If there is a Python crash please cut and paste the Python backtrace
    708 into the bug report. If the tools fail to build please locate the first
    709 error in the log file. This can be difficult to find on hosts with many
    710 cores so it sometimes pays to re-run the command with the ``--jobs=none``
    711 option to get a log that is correctly sequenced. If searching the log
    712 file seach for ``error:`` and the error should be just above it.
    714 .. comment [[_contributing]]
    716 Contributing
    717 ############
    719 We welcome all users adding, fixing, updating and upgrading packages and their
    720 configurations. The RSB is open source and open to contributions. These can be
    721 bug fixes, new features or new configurations. Please break patches down into
    722 changes to the core Python code, configuration changes or new configurations.
    724 Please email me patches via git so I can maintain your commit messages so you
    725 are acknowledged as the contributor.
    727 Most of what follows is related to the development of RSB and it's
    728 configurations.
    730 Project Sets
    731 ############
    733 The RTEMS Source Builder supports project configurations. Project
    734 configurations can be public or private and can be contained in the RTEMS
    735 Source Builder project if suitable, other projects they use the RTEMS Source
    736 Builder or privately on your local file system.
    738 The configuration file loader searches the macro ``_configdir`` and by
    739 default this is set to ``%{\_topdir}/config:%{\_sbdir}/config`` where
    740 ``_topdir`` is the your current working direct, in other words the
    741 directory you invoke the RTEMS Source Builder command in, and ``_sbdir``
    742 is the directory where the RTEMS Source Builder command resides. Therefore
    743 the ``config`` directory under each of these is searched so all you need
    744 to do is create a ``config`` in your project and add your configuration
    745 files. They do not need to be under the RTEMS Source Builder source
    746 tree. Public projects are included in the main RTEMS Source Builder such
    747 as RTEMS.
    749 You can also add your own ``patches`` directory next to your
    750 ``config`` directory as the ``%patch`` command searches the
    751 ``_patchdir`` macro variable and it is by default set to
    752 ``%{\_topdir}/patches:%{\_sbdir}/patches``.
    754 The ``source-builder/config`` directory provides generic scripts for building
    755 various tools. You can specialise these in your private configurations to make
    756 use of them. If you add new generic configurations please contribute them back
    757 to the project
    759 Bare Metal
    760 ~~~~~~~~~~
    762 The RSB contains a 'bare' configuration tree and you can use this to add
    763 packages you use on the hosts. For example 'qemu' is supported on a range of
    764 hosts. RTEMS tools live in the ``rtems/config`` directory tree. RTEMS packages
    765 include tools for use on your host computer as well as packages you can build
    766 and run on RTEMS.
    768 The 'bare metal' support for GNU Tool chains. An example is the 'lang/gcc491'
    769 build set. You need to provide a target via the command line '--target'
    770 option and this is in the standard 2 or 3 tuple form. For example for an ARM
    771 compiler you would use 'arm-eabi' or 'arm-eabihf', and for SPARC you would
    772 use 'sparc-elf'.
    774 .. code-block:: shell
    776     $ cd rtems-source-builder/bare
    777     $../source-builder/sb-set-builder --log=log_arm_eabihf \
    778         --prefix=$HOME/development/bare --target=arm-eabihf lang/gcc491
    779     RTEMS Source Builder - Set Builder, v0.3.0
    780     Build Set: lang/gcc491
    781     config: devel/expat-2.1.0-1.cfg
    782     package: expat-2.1.0-x86_64-apple-darwin13.2.0-1
    783     building: expat-2.1.0-x86_64-apple-darwin13.2.0-1
    784     config: devel/binutils-2.24-1.cfg
    785     package: arm-eabihf-binutils-2.24-1
    786     building: arm-eabihf-binutils-2.24-1
    787     config: devel/gcc-4.9.1-newlib-2.1.0-1.cfg
    788     package: arm-eabihf-gcc-4.9.1-newlib-2.1.0-1
    789     building: arm-eabihf-gcc-4.9.1-newlib-2.1.0-1
    790     config: devel/gdb-7.7-1.cfg
    791     package: arm-eabihf-gdb-7.7-1
    792     building: arm-eabihf-gdb-7.7-1
    793     installing: expat-2.1.0-x86_64-apple-darwin13.2.0-1 -> /Users/chris/development/bare
    794     installing: arm-eabihf-binutils-2.24-1 -> /Users/chris/development/bare
    795     installing: arm-eabihf-gcc-4.9.1-newlib-2.1.0-1 -> /Users/chris/development/bare
    796     installing: arm-eabihf-gdb-7.7-1 -> /Users/chris/development/bare
    797     cleaning: expat-2.1.0-x86_64-apple-darwin13.2.0-1
    798     cleaning: arm-eabihf-binutils-2.24-1
    799     cleaning: arm-eabihf-gcc-4.9.1-newlib-2.1.0-1
    800     cleaning: arm-eabihf-gdb-7.7-1
    802 RTEMS
    803 ~~~~~
    805 The RTEMS Configurations found in the 'rtems' directory. The configurations are
    806 grouped by RTEMS version. In RTEMS the tools are specific to a specific version
    807 because of variations between Newlib and RTEMS. Restructuring in RTEMS and
    808 Newlib sometimes moves *libc* functionality between these two parts and this
    809 makes existing tools incompatible with RTEMS.
    811 RTEMS allows architectures to have different tool versions and patches. The
    812 large number of architectures RTEMS supports can make it difficult to get a
    813 common stable version of all the packages. An architecture may require a recent
    814 GCC because an existing bug has been fixed, however the more recent version may
    815 have a bug in other architecture. Architecture specific patches should be
    816 limited to the architecture it relates to. The patch may fix a problem on the
    817 effect architecture however it could introduce a problem in another
    818 architecture. Limit exposure limits any possible crosstalk between
    819 architectures.
    821 RTEMS supports *stable* and *unstable*. Stable configurations are fixed while
    822 unstable configurations are supporting using snapshots of user macros and
    823 reference release candidates or source extracted directly from version
    824 control. The stable build sets are referenced as ``<version>/rtems-<arch>`` and
    825 include ``autoconf`` and ``automake``.
    827 If you are building a released version of RTEMS the release RTEMS tar file will
    828 be downloaded and built as part of the build process. If you are building a
    829 tool set for use with the development branch of RTEMS, the development branch
    830 will be cloned directly from the RTEMS GIT repository and built.
    832 When building RTEMS within the RTEMS Source Builder it needs a suitable working
    833 ``autoconf`` and ``automake``. These packages need to built and installed in their
    834 prefix in order for them to work. The RTEMS Source Builder installs all
    835 packages only after they have been built so if you host does not have a
    836 recent enough version of ``autoconf`` and ``automake`` you first need to build them
    837 and install them then build your tool set. The commands are:
    839 .. code-block:: shell
    841     $ ../source-builder/sb-set-builder --log=l-4.11-at.txt \
    842        --prefix=$HOME/development/rtems/4.11 4.11/rtems-autotools
    843     $ export PATH=~/development/rtems/4.11/bin:$PATH <1>
    844     $ ../source-builder/sb-set-builder --log=l-4.11-sparc.txt \
    845        --prefix=$HOME/development/rtems/4.11 4.11/rtems-sparc
    847 - *<1>* Setting the path.
    849 TIP: If this is your first time building the tools and RTEMS it pays to add the
    850 ``--dry-run`` option. This will run through all the configuration files and if
    851 any checks fail you will see this quickly rather than waiting for until the
    852 build fails a check.
    854 To build snapshots for testing purposes you use the available macro maps
    855 passing them on the command line using the ``--macros`` option. For RTEMS these
    856 are held in ``config/snapshots`` directory. The following builds *newlib* from
    857 CVS:
    859 .. code-block:: shell
    861     $ ../source-builder/sb-set-builder --log=l-4.11-sparc.txt \
    862        --prefix=$HOME/development/rtems/4.11 \
    863        --macros=snapshots/ \
    864        4.11/rtems-sparc
    866 and the following uses the version control heads for *binutils*, *gcc*,
    867 *newlib*, *gdb* and *RTEMS*:
    869 .. code-block:: shell
    871     $ ../source-builder/sb-set-builder --log=l-heads-sparc.txt \
    872        --prefix=$HOME/development/rtems/4.11-head \
    873        --macros=snapshots/ \
    874        4.11/rtems-sparc
    876 Patches
    879 Packages being built by the RSB need patches from time to time and the RSB
    880 supports patching upstream packages. The patches are held in a seperate
    881 directory called ``patches`` relative to the configuration directory you are
    882 building. For example ``%{\_topdir}/patches:%{\_sbdir}/patches``. Patches are
    883 declared in the configuration files in a similar manner to the package's source
    884 so please refer to the ``%source`` documentation. Patches, like the source, are
    885 to be made publically available for configurations that live in the RSB package
    886 and are downloaded on demand.
     139The RTEMS Source Builder is a stand alone tool based on another tool called the
     140*SpecBuilder* written by Chris Johns. The *SpecBuilder* was written around 2010
     141for the RTEMS project to provide Chris with a way to build tools on hosts that
     142did not support RPMs. At the time the RTEMS tools maintainer only supported
     143*spec* files and these files held all the vital configuration data needed to
     144create suitable tool sets. Available SRPM and *spec* files by themselves where
     145useless because a suitable ``rpm`` tool to use them was needed. At the time
     146available versions of ``rpm`` for a number of non-RPM hosts were broken and
     147randomly maintained. The solution Chris settled on was to use the *spec* files
     148and write to a Python based tool that parsed the *spec* file format creating a
     149shell script that could be run to build the package. The approach proved
     150successful and Chris was able to track the RPM version of the RTEMS tools on a
     151non-RPM host for a number of years.
    888 If a package has a patch management tool it is recommended you reference the
    889 package's patch management tools directly. If the RSB does not support the
    890 specific patch manage tool please contact the mailing list to see if support
    891 can be added.
    893 Patches for packages developed by the RTEMS project can be placed in the RTEMS
    894 Tools Git repository. The ``tools`` directory in the repository has various
    895 places a patch can live. The tree is broken down in RTEMS releases and then
    896 tools within that release. If the package is not specific to any release the
    897 patch can be added closer to the top under the package's name. Patches to fix
    898 specific tool related issues for a specific architecture should be grouped
    899 under the specific architecture and only applied when building that
    900 architecture avoiding a patch breaking an uneffected architecture.
    902 Patches in the RTEMS Tools repository need to be submitted to the upstream
    903 project. It should not be a clearing house for patches that will not be
    904 accepted upstream.
    906 Patches are added to a component's name and in the ``%prep:`` section the
    907 patches can be set up, meaning they are applied to source. The patches
    908 are applied in the order they are added. If there is a dependency make
    909 sure you order the patches correctly when you add them. You can add any
    910 number of patches and the RSB will handle them efficently.
    912 Patches can have options. These are added before the patch URL. If no options
    913 are provided the patch's setup default options are used.
    915 Patches can be declared in build set up files.
    917 This examples shows how to declare a patch for gdb in the ``lm32`` architecture:
    919 .. code-block:: shell
    921     %patch add <1> gdb <2> %{rtems_gdb_patches}/lm32/gdb-sim-lm32uart.diff <3>
    923 - *<1>* The patch's ``add`` command.
    925 - *<2>* The group of patches this patch belongs too.
    927 - *<3>* The patch's URL. It is downloaded from here.
    929 Patches require a checksum to avoid a warning. The ``%hash`` directive can be
    930 used to add a checksum for a patch that is used to verify the patch:
    932 .. code-block:: shell
    934     %hash md5 <1> gdb-sim-lm32uart.diff <2> 77d070878112783292461bd6e7db17fb <3>
    936 - *<1>* The type of checksum, in the case an MD5 hash.
    938 - *<2>* The patch file the checksum is for.
    940 - *<3>* The MD5 hash.
    942 The patches are applied when a patch ``setup`` command is issued in the
    943 ``%prep:`` section. All patches in the group are applied. To apply the
    944 GDB patch above use:
    946 .. code-block:: shell
    948     %patch setup <1> gdb <2> -p1 <3>
    950 - *<1>* The patch's ``setup`` command.
    952 - *<2>* The group of patches to apply.
    954 - *<3>* The patch group's default options. If no option is given with
    955   the patch these options are used.
    957 Architecture specific patches live in the architecture build set file isolating
    958 the patch to that specific architecture. If a patch is common to a tool it
    959 resides in the RTEMS tools configuration file. Do not place patches for tools
    960 in the ``source-builder/config`` template configuration files.
    962 To test a patch simply copy it to your local ``patches`` directory. The RSB will
    963 see the patch is present and will not attempt to download it. Once you are
    964 happy with the patch submit it to the project and a core developer will review
    965 it and add it to the RTEMS Tools git repository.
    966 For example, to test a local patch for newlib, add the following two lines to
    967 the .cfg file in ``rtems/config/tools/`` that is included by the bset you use:
    969 .. code-block:: shell
    971     %patch add newlib file://0001-this-is-a-newlib-patch.patch <1>
    972     %hash md5 0001-this-is-a-newlib-patch.diff 77d070878112783292461bd6e7db17fb <2>
    974 - *<1>* The diff file prepended with ``file://`` to tell RSB this is a
    975   local file.
    977 - *<2>* The output from md5sum on the diff file.
    979 Cross and Canadian Cross Building
    980 #################################
    982 Cross building and Canadian Cross building is the process of building on one
    983 machine an executable that runs on another machine. An example is building a
    984 set of RTEMS tools on Linux to run on Windows. The RSB supports cross building
    985 and Canadian cross building.
    987 This sections details how to the RSB to cross and Canadian cross build.
    989 Cross Building
    990 ~~~~~~~~~~~~~~
    992 Cross building is where the _build_ machine and _host_ are different. The
    993 _build_ machine runs the RSB and the _host_ machine is where the output from
    994 the build runs. An example is building a package such as NTP for RTEMS on your
    995 development machine.
    997 To build the NTP package for RTEMS you enter the RSB command:
    999 .. code-block:: shell
    1001     $ ../source-builder/sb-set-builder \
    1002        --log=log_ntp_arm.txt \
    1003        --prefix=$HOME/development/rtems/4.11 <1> \
    1004        --host=arm-rtems4.11 <2> \
    1005        --with-rtems-bsp=xilinx_zynq_zc706 <3> \
    1006        4.11/net/ntp
    1008 - *<1>* The tools and the RTEMS BSP are installed under the same prefix.
    1010 - *<2>* The ``--host`` command is the RTEMS architecture and version.
    1012 - *<3>* The BSP is built and installed in the prefix. The arhcitecture must
    1013   match the ``--host`` architecture.
    1015 .. note: Installing Into Different Directories
    1016   TIP: If you install BSPs into a different path to the prefix use the
    1017   ``--with-tools`` option to specify the path to the tools. Do not add the 'bin'
    1018   directory at the end of the path.
    1020 Canadian Cross Building
    1021 ~~~~~~~~~~~~~~~~~~~~~~~
    1023 A Canadian cross builds are where the *build*, *host* and *target* machines all
    1024 differ. For example building an RTEMS compiler for an ARM processor that runs
    1025 on Windows is built using a Linux machine. The process is controlled by setting
    1026 the build triplet to the host you are building, the host triplet to the host
    1027 the tools will run on and the target to the RTEMS architecture you require. The
    1028 tools needed by the RSB are:
    1030 - Build host C and C++ compiler
    1032 - Host C and C++ cross compiler
    1034 The RTEMS Source Builder requires you provide the build host C and C++
    1035 compiler and the final host C and C++ cross-compiler. The RSB will build the
    1036 build host RTEMS compiler and the final host RTEMS C and C++ compiler, the
    1037 output of this process.
    1039 The Host C and C++ compiler is a cross-compiler that builds executables for
    1040 the host you want the tools for. You need to provide these tools. For Windows a
    1041 number of Unix operating systems provide MinGW tool sets as packages.
    1043 The RSB will build an RTEMS tool set for the build host. This is needed when
    1044 building the final host's RTEMS compiler as it needs to build RTEMS runtime
    1045 code such as *libc* on the build host.
    1047 TIP: Make sure the host's cross-compiler tools are in your path before run the
    1048 RSB build command.
    1050 TIP: Canadian Cross built tools will not run on the machine being used to build
    1051 them so you should provide the ``--bset-tar-files`` and ``--no-install``
    1052 options. The option to not install the files lets you provide a prefix that
    1053 does not exist or you cannot access.
    1055 To perform a cross build add ``--host=`` to the command line. For example
    1056 to build a MinGW tool set on FreeBSD for Windows add ``--host=mingw32``
    1057 if the cross compiler is ``mingw32-gcc``:
    1059 .. code-block:: shell
    1061     $ ../source-builder/sb-set-builder --host=mingw32 \
    1062        --log=l-mingw32-4.11-sparc.txt \
    1063        --prefix=$HOME/development/rtems/4.11 \
    1064        4.11/rtems-sparc
    1066 If you are on a Linux Fedora build host with the MinGW packages installed the
    1067 command line is:
    1069 .. code-block:: shell
    1071     $ ../source-builder/sb-set-builder --host=i686-w64-mingw32 \
    1072        --log=l-mingw32-4.11-sparc.txt \
    1073        --prefix=$HOME/development/rtems/4.11 \
    1074        4.11/rtems-sparc
    1076 RTEMS 3rd Party Packages
    1077 ########################
    1079 This section describes how to build and add an RTEMS 3rd party package to the
    1080 RSB.
    1082 A 3rd party package is a library or software package built to run on RTEMS,
    1083 examples are NTP, Net-Snmp, libjpeg or Python. These pieces of software can be
    1084 used to help build RTEMS applications. The package is built for a specific
    1085 BSP and so requires a working RTEMS tool chain and an installed RTEMS Board
    1086 Support Package (BSP).
    1088 The RSB support for building 3rd part packages is based around the pkconfig
    1089 files (PC) installed with the BSP. The pkgconfig support in RTEMS is considered
    1090 experimental and can have some issues for some BSPs. This issue is rooted deep
    1091 in the RTEMS build system. If you have any issues with this support please ask
    1092 on the RTEMS developers mailing list.
    1094 Building
    1095 ~~~~~~~~
    1097 To build a package you need to have a suitable RTEMS tool chain and RTEMS BSP
    1098 installed. The set builder command line requires you provide the tools path,
    1099 the RTEMS host, and the prefix path to the installed RTEMS BSP. The prefix
    1100 needs to be the same as the prefix used to build RTEMS.
    1102 To build Net-SNMP the command is:
    1104 .. code-block:: shell
    1106     cd rtems-source-builder/rtems
    1107     $ ../source-builder/sb-set-builder --log=log_sis_net_snmp \
    1108         --prefix=$HOME/development/rtems/bsps/4.11 \
    1109         --with-tools=$HOME/development/rtems/4.11 \
    1110         --host=sparc-rtems4.11 --with-rtems-bsp=sis 4.11/net-mgmt/net-snmp
    1111     RTEMS Source Builder - Set Builder, v0.3.0
    1112     Build Set: 4.11/net-mgmt/net-snmp
    1113     config: net-mgmt/net-snmp-
    1114     package: net-snmp-
    1115     building: net-snmp-
    1116     installing: net-snmp- -> /Users/chris/development/rtems/bsps/4.11
    1117     cleaning: net-snmp-
    1118     Build Set: Time 0:01:10.651926
    1120 Adding
    1121 ~~~~~~
    1123 Adding a package requires you first build it manually by downloading the source
    1124 for the package and building it for RTEMS using the command line of a standard
    1125 shell. If the package has not been ported to RTEMS you will need to port it and
    1126 this may require you asking questions on the package's user or development
    1127 support lists as well as RTEMS's developers list. Your porting effort may end
    1128 up with a patch. RTEMS requires a patch be submitted upstream to the project's
    1129 community as well as RTEMS so it can be added to the RTEMS Tools git
    1130 repository. A patch in the RTEMS Tools git reposiitory can then be referenced
    1131 by an RSB configuration file.
    1133 A package may create executables, for example NTP normally creates
    1134 executables such as ``ntdp``, ``ntpupdate``, or ``ntpdc``. These
    1135 executables can be useful when testing the package however they are
    1136 of limited use by RTEMS users because they cannot be directly linked
    1137 into a user application. Users need to link to the functions in these
    1138 executables or even the executable as a function placed in libraries. If
    1139 the package does not export the code in a suitable manner please contact
    1140 the project's commuinity and see if you can work them to provide a way for
    1141 the code to be exported. This may be difficult because exporting internal
    1142 headers and functions opens the project up to API compatibility issues
    1143 they did not have before. In the simplest case attempting to get the
    1144 code into a static library with a single call entry point exported in a
    1145 header would give RTEMS user's access to the package's main functionality.
    1147 A package requires 3 files to be created:
    1149 - The first file is the RTEMS build set file and it resides in the
    1150   ``$$rtems/config/%{rtems_version}$$`` path in a directory tree based on the
    1151   FreeBSD ports collection. For the NTP package and RTEMS 4.11 this is
    1152   ``rtems/config/4.11/net/ntp.bset``. If you do not know the FreeBSD port path
    1153   for the package you are adding please ask. The build set file references a
    1154   specific configuration file therefore linking the RTEMS version to a specific
    1155   version of the package you are adding. Updating the package to a new version
    1156   requires changing the build set to the new configuration file.
    1158 - The second file is an RTEMS version specific configuration file
    1159   and it includes the RSB RTEMS BSP support. These configuration
    1160   files reside in the ``rtems/config`` tree again under the FreeBSD
    1161   port's path name. For example the NTP package is found in the ``net``
    1162   directory of the FreeBSD ports tree so the NTP configuration path is
    1163   ``rtems/config/net/ntp-4.2.6p5-1.cfg`` for that specific version. The
    1164   configuration file name typically provides version specific references
    1165   and the RTEMS build set file references a specific version. This
    1166   configuration file references the build configuration file held in the
    1167   common configuration file tree.
    1169 - The build configuration. This is a common script that builds the package. It
    1170   resides in the ``source-builder/config`` directory and typically has the
    1171   packages's name with the major version number. If the build script does not
    1172   change for each major version number a *common* base script can be created
    1173   and included by each major version configuration script. The *gcc* compiler
    1174   configuration is an example. This approach lets you branch a version if
    1175   something changes that is not backwards compatible. It is important to keep
    1176   existing versions building. The build configuration should be able to build a
    1177   package for the build host as well as RTEMS as the RSB abstracts the RTEMS
    1178   specific parts. See :ref:`Configuration` for more details.
    1180 BSP Support
    1181 ~~~~~~~~~~~
    1183 The RSB provides support to help build packages for RTEMS. RTEMS applications
    1184 can be viewed as statically linked executables operating in a single address
    1185 space. As a result only the static libraries a package builds are required and
    1186 these libraries need to be ABI compatible with the RTEMS kernel and application
    1187 code meaning compiler ABI flags cannot be mixed when building code. The 3rd
    1188 party package need to use the same compiler flags as the BSP used to build
    1189 RTEMS.
    1191 .. comment [TIP]
    1193 .. note::
    1195     RTEMS's dynamic loading support does not use the standard shared library
    1196     support found in Unix and the ELF standard. RTEMS's loader uses static
    1197     libraries and the runtime link editor performs a similar function to a host
    1198     based static linker. RTEMS will only reference static libraries even
    1199     if dynamic libraries are created and installed.
    1201 The RSB provides the configuration file ``rtems/config/rtems-bsp.cfg``
    1202 to support building 3rd party packages and you need to include this
    1203 file in your RTEMS version specific configuration file. For example the
    1204 Net-SNMP configuration file (``rtems/config/net-mgmt/net-snmp-``):
    1206 .. code-block:: shell
    1208     #
    1209     # NetSNMP
    1210     #
    1212     %if %{release} == %{nil}
    1213      %define release 1 <1>
    1214     %endif
    1216     %include %{_configdir}/rtems-bsp.cfg <2>
    1218     #
    1219     # NetSNMP Version
    1220     #
    1221     %define net_snmp_version <3>
    1223     #
    1224     # We need some special flags to build this version.
    1225     #
    1226     %define net_snmp_cflags <4> -DNETSNMP_CAN_USE_SYSCTL=1 -DARP_SCAN_FOUR_ARGUMENTS=1 -DINP_IPV6=0
    1228     #
    1229     # Patch for RTEMS support.
    1230     #
    1231     %patch add net-snmp %{rtems_git_tools}/net-snmp/rtems-net-snmp- <5>
    1233     #
    1234     # NetSNMP Build configuration
    1235     #
    1236     %include %{_configdir}/net-snmp-5-1.cfg <6>
    1238 - *<1>* The release number.
    1240 - *<2>* Include the RSB RTEMS BSP support.
    1242 - *<3>* The Net-SNMP package's version.
    1244 - *<4>* Add specific CFLAGS to the build process. See the
    1245   ``net-snmp-`` for details.
    1247 - *<5>* The RTEMS Net-SNMP patch downloaded from the RTEMS Tools git repo.
    1249 - *<6>* The Net-SNMP standard build configuration.
    1251 The RSB RTEMS BSP support file ``rtems/config/rtems-bsp.cfg`` checks
    1252 to make sure standard command line options are provided. These include
    1253 ``--host`` and ``--with-rtems-bsp``. If the ``--with-tools`` command
    1254 line option is not given the ``${\_prefix}`` is used.
    1256 .rtems/config/rtems-bsp.cfg
    1258 .. code-block:: shell
    1260     %if %{_host} == %{nil} <1>
    1261      %error No RTEMS target specified: --host=host
    1262     %endif
    1264     %ifn %{defined with_rtems_bsp} <2>
    1265      %error No RTEMS BSP specified: --with-rtems-bsp=bsp
    1266     %endif
    1268     %ifn %{defined with_tools} <3>
    1269      %define with_tools %{_prefix}
    1270     %endif
    1272     #
    1273     # Set the path to the tools.
    1274     #
    1275     %{path prepend %{with_tools}/bin} <4>
    1277 - *<1>* Check the host has been set.
    1279 - *<2>* Check a BSP has been specified.
    1281 - *<3>* If no tools path has been provided assume they are under the
    1282   %{\_prefix}.
    1284 - *<4>* Add the tools ``bin`` path to the system path.
    1286 RTEMS exports the build flags used in pkgconfig (.pc) files and the RSB can
    1287 read and manage them even when there is no pkgconfig support installed on your
    1288 build machine. Using this support we can obtain a BSP's configuration and set
    1289 some standard macros variables:
    1291 .rtems/config/rtems-bsp.cfg
    1292 .. code-block:: shell
    1294     %{pkgconfig prefix %{_prefix}/lib/pkgconfig} <1>
    1295     %{pkgconfig crosscompile yes} <2>
    1296     %{pkgconfig filter-flags yes} <3>
    1298     #
    1299     # The RTEMS BSP Flags
    1300     #
    1301     %define rtems_bsp           %{with_rtems_bsp}
    1302     %define rtems_bsp_ccflags   %{pkgconfig ccflags %{_host}-%{rtems_bsp}} <4>
    1303     %define rtems_bsp_cflags    %{pkgconfig cflags  %{_host}-%{rtems_bsp}}
    1304     %define rtems_bsp_ldflags   %{pkgconfig ldflags %{_host}-%{rtems_bsp}}
    1305     %define rtems_bsp_libs      %{pkgconfig libs    %{_host}-%{rtems_bsp}}
    1307 - *<1>* Set the path to the BSP's pkgconfig file.
    1309 - *<2>* Let pkgconfig know this is a cross-compile build.
    1311 - *<3>* Filter flags such as warnings. Warning flags are specific to a package.
    1313 - *<4>* Ask pkgconfig for the various items we require.
    1316 The flags obtain by pkgconfig and given a ``rtems_bsp_`` prefix and we uses these
    1317 to set the RSB host support CFLAGS, LDFLAGS and LIBS flags. When we build a 3rd
    1318 party library your host computer is the _build_ machine and RTEMS is the _host_
    1319 machine therefore we set the ``host`` variables:
    1321 .rtems/config/rtems-bsp.cfg
    1322 .. code-block:: shell
    1324     %define host_cflags  %{rtems_bsp_cflags}
    1325     %define host_ldflags %{rtems_bsp_ldflags}
    1326     %define host_libs    %{rtems_bsp_libs}
    1329 Finally we provide all the paths you may require when configuring a
    1330 package. Packages by default consider the ``_prefix`` the base and install
    1331 various files under this tree. The package you are building is specific to a
    1332 BSP and so needs to install into the specific BSP path under the
    1333 ``_prefix``. This allows more than BSP build of this package to be install under
    1334 the same ``_prefix`` at the same time:
    1336 .rtems/config/rtems-bsp.cfg
    1337 .. code-block:: shell
    1339     %define rtems_bsp_prefix  %{_prefix}/%{_host}/%{rtems_bsp} <1>
    1340     %define _exec_prefix      %{rtems_bsp_prefix}
    1341     %define _bindir           %{_exec_prefix}/bin
    1342     %define _sbindir          %{_exec_prefix}/sbin
    1343     %define _libexecdir       %{_exec_prefix}/libexec
    1344     %define _datarootdir      %{_exec_prefix}/share
    1345     %define _datadir          %{_datarootdir}
    1346     %define _sysconfdir       %{_exec_prefix}/etc
    1347     %define _sharedstatedir   %{_exec_prefix}/com
    1348     %define _localstatedir    %{_exec_prefix}/var
    1349     %define _includedir       %{_libdir}/include
    1350     %define _lib              lib
    1351     %define _libdir           %{_exec_prefix}/%{_lib}
    1352     %define _libexecdir       %{_exec_prefix}/libexec
    1353     %define _mandir           %{_datarootdir}/man
    1354     %define _infodir          %{_datarootdir}/info
    1355     %define _localedir        %{_datarootdir}/locale
    1356     %define _localedir        %{_datadir}/locale
    1357     %define _localstatedir    %{_exec_prefix}/var
    1359 - *<1>* The path to the BSP.
    1361 When you configure a package you can reference these paths and the RSB will
    1362 provide sensible default or in this case map them to the BSP:
    1364 .source-builder/config/ntp-4-1.cfg
    1365 .. code-block:: shell
    1367       ../${source_dir_ntp}/configure \ <1>
    1368         --host=%{_host} \
    1369         --prefix=%{_prefix} \
    1370         --bindir=%{_bindir} \
    1371         --exec_prefix=%{_exec_prefix} \
    1372         --includedir=%{_includedir} \
    1373         --libdir=%{_libdir} \
    1374         --libexecdir=%{_libexecdir} \
    1375         --mandir=%{_mandir} \
    1376         --infodir=%{_infodir} \
    1377         --datadir=%{_datadir} \
    1378         --disable-ipv6 \
    1379         --disable-HOPFPCI
    1381 - *<1>* The configure command for NTP.
    1383 RTEMS BSP Configuration
    1384 ~~~~~~~~~~~~~~~~~~~~~~~
    1386 To build a package for RTEMS you need to build it with the matching BSP
    1387 configuration. A BSP can be built with specific flags that require all code
    1388 being used needs to be built with the same flags.
    1391 .. comment [[H1]]
    1393 .. _Configuration:
    1395 Configuration
    1396 #############
    1398 The RTEMS Source Builder has two types of configuration data:
    1400 - Build Sets
    1402 - Package Build Configurations
    1404 By default these files can be located in two separate directories and
    1405 searched. The first directory is ``config`` in your current working
    1406 directory (``_topdir``) and the second is ``config`` located in the base
    1407 directory of the RTEMS Source Builder command you run (``_sbdir``). The
    1408 RTEMS directory ``rtems``` located at the top of the RTEMS Source
    1409 Builder source code is an example of a specific build configuration
    1410 directory. You can create custom or private build configurations and
    1411 if you run the RTEMS Source Builder command from that directory your
    1412 configurations will be used.
    1414 [[X1]] The configuration search path is a macro variable and is reference as
    1415 ``%\{_configdir\}``. It's default is defined as:
    1417 .. code-block:: shell
    1419     _configdir   : dir  optional<2>  %{_topdir}/config:%{_sbdir}/config <1>
    1421 - *<1>* The ``_topdir`` is the directory you run the command from and
    1422   ``_sbdir`` is the location of the RTEMS Source Builder command.
    1424 - *<2>* A macro definition in a macro file has 4 fields, the label, type,
    1425   constraint and the definition.
    1427 Build set files have the file extension ``.bset`` and the package build
    1428 configuration files have the file extension of ``.cfg``. The ``sb-set-builder``
    1429 command will search for *build sets* and the ``sb-builder`` commands works with
    1430 package build configuration files.
    1432 Both types of configuration files use the \'#' character as a comment
    1433 character. Anything after this character on the line is ignored. There is no
    1434 block comment.
    1436 Source and Patches
    1437 ~~~~~~~~~~~~~~~~~~
    1439 The RTEMS Source Builder provides a flexible way to manage source. Source and
    1440 patches are declare in configurations file using the ``source`` and ``patch``
    1441 directives. These are a single line containing a Universal Resource Location or
    1442 URL and can contain macros and shell expansions. The <<_prep,%prep>> section
    1443 details the source and patch directives
    1445 The URL can reference remote and local source and patch resources. The
    1446 following schemes are provided:
    1448 - ``http``: Remote access using the HTTP protocol.
    1450 - ``https``: Remote access using the Secure HTTP protocol.
    1452 - ``ftp``: Remote access using the FTP protocol.
    1454 - ``git``: Remote access to a GIT repository.
    1456 - ``cvs``: Remote access to a CVS repository.
    1458 - ``pm``: Remote access to a patch management repository.
    1460 - ``file``: Local access to an existing source directory.
    1462 HTTP, HTTPS, and FTP
    1463 ^^^^^^^^^^^^^^^^^^^^
    1465 Remote access to TAR or ZIP files is provided using HTTP, HTTPS and FTP
    1466 protocols. The full URL provided is used to access the remote file including
    1467 any query components. The URL is parsed to extract the file component and the
    1468 local source directory is checked for that file. If the file is located locally
    1469 the remote file is not downloaded. Currently no other checks are made. If a
    1470 download fails you need to manually remove the file from the source directory
    1471 and start the build process again.
    1473 The URL can contain macros. These are expanded before issuing the request to
    1474 download the file. The standard GNU GCC compiler source URL is:
    1476 .. code-block:: shell
    1478     %source set<1> gcc<2>{gcc_version}/gcc-%{gcc_version}.tar.bz2
    1480 - *<1>* The ``%source`` command's set command sets the source. The first
    1481   is set and following sets are ignored.
    1483 - *<2>* The source is part of the ``gcc`` group.
    1485 The type of compression is automatically detected from the file extension. The
    1486 supported compression formats are:
    1488 - ``gz``: GNU ZIP
    1490 - ``bzip2``: BZIP2
    1492 - ``zip``: ZIP
    1494 - ``xy``: XY
    1496 The output of the decompression tool is feed to the standard ``tar`` utility if
    1497 not a ZIP file and unpacked into the build directory. ZIP files are unpacked by
    1498 the decompression tool and all other files must be in the tar file format.
    1500 The ``%source`` directive typically supports a single source file tar or
    1501 zip file. The ``set`` command is used to set the URL for a specific source
    1502 group. The first set command encoutner is registered and any further set
    1503 commands are ignored. This allows you to define a base standard source
    1504 location and override it in build and architecture specific files. You
    1505 can also add extra source files to a group. This is typically done when a
    1506 collection of source is broken down in a number of smaller files and you
    1507 require the full package. The source's ``setup`` command must reide in
    1508 the ``%prep:`` section and it unpacks the source code ready to be built.
    1510 If the source URL references the GitHub API server '' a
    1511 tarball of the specified version is download. For example the URL for the
    1512 STLINK project on GitHub and version is:
    1514 .. code-block:: shell
    1516     %define stlink_version 3494c11
    1517     %source set stlink{stlink_version}.tar.gz
    1520 GIT
    1521 ^^^
    1523 A GIT repository can be cloned and used as source. The GIT repository resides
    1524 in the 'source' directory under the ``git`` directory. You can edit, update and
    1525 use the repository as you normally do and the results will used to build the
    1526 tools. This allows you to prepare and test patches in the build environment the
    1527 tools are built in. The GIT URL only supports the GIT protocol. You can control
    1528 the repository via the URL by appending options and arguments to the GIT
    1529 path. The options are delimited by ``?`` and option arguments are delimited from
    1530 the options with ``=``. The options are:
    1532 - ``protocol``: Use a specific protocol. The supported values are *ssh*,
    1533   *git*, *http*, *https*, *ftp*, *ftps*, *rsync*, and *none*.
    1535 - ``branch``: Checkout the specified branch.
    1537 - ``pull``: Perform a pull to update the repository.
    1539 - ``fetch``: Perform a fetch to get any remote updates.
    1541 - ``reset``: Reset the repository. Useful to remove any local
    1542   changes. You can pass the ``hard`` argument to force a hard reset.
    1544 .. code-block:: shell
    1546     %source set gcc git://
    1548 This will clone the GCC git repository and checkout the 4.7-branch and perform
    1549 a hard reset. You can select specific branches and apply patches. The
    1550 repository is cleaned up before each build to avoid various version control
    1551 errors that can arise.
    1553 The protocol option lets you set a specific protocol. The 'git://' prefix used
    1554 by the RSB to select a git repository can be removed using *none* or replaced
    1555 with one of the standard git protcols.
    1557 CVS
    1558 ^^^
    1560 A CVS repository can be checked out. CVS is more complex than GIT to handle
    1561 because of the modules support. This can effect the paths the source ends up
    1562 in. The CVS URL only supports the CVS protocol. You can control the repository
    1563 via the URL by appending options and arguments to the CVS path. The options are
    1564 delimited by ``?`` and option arguments are delimited from the options with
    1565 ``=``. The options are:
    1567 - ``module``: The module to checkout.
    1569 - ``src-prefix``: The path into the source where the module starts.
    1571 - ``tag``: The CVS tag to checkout.
    1573 - ``date``: The CVS date to checkout.
    1575 The following is an example of checking out from a CVS repository:
    1577 .. code-block:: shell
    1579     %source set newlib cvs://
    1581 Macros and Defaults
    1582 ~~~~~~~~~~~~~~~~~~~
    1584 The RTEMS Source Builder uses tables of *macros* read in when the tool
    1585 runs. The initial global set of macros is called the *defaults*. These values
    1586 are read from a file called ```` and modified to suite your host. This
    1587 host specific adaption lets the Source Builder handle differences in the build
    1588 hosts.
    1590 Build set and configuration files can define new values updating and extending
    1591 the global macro table. For example builds are given a release number. This is
    1592 typically a single number at the end of the package name. For example:
    1594 .. code-block:: shell
    1596     %define release 1
    1598 Once defined if can be accessed in a build set or package configuration file
    1599 with:
    1601 .. code-block:: shell
    1603     %{release}
    1605 The ``sb-defaults`` command lists the defaults for your host. I will not include
    1606 the output of this command because of its size.
    1608 .. code-block:: shell
    1610     $ ../source-builder/sb-defaults
    1612 A nested build set is given a separate copy of the global macro maps. Changes
    1613 in one change set are not seen in other build sets. That same happens with
    1614 configuration files unless inline includes are used. Inline includes are seen
    1615 as part of the same build set and configuration and changes are global to that
    1616 build set and configuration.
    1618 Macro Maps and Files
    1619 ^^^^^^^^^^^^^^^^^^^^
    1621 Macros are read in from files when the tool starts. The default settings are
    1622 read from the defaults macro file called ```` located in the top level
    1623 RTEMS Source Builder command directory. User macros can be read in at start up
    1624 by using the ``--macros`` command line option.
    1626 The format for a macro in macro files is:
    1628 ==== ==== ========= ======
    1629 Name Type Attribute String
    1630 ==== ==== ========= ======
    1632 where 'Name' is a case insensitive macro name, the 'Type' field is:
    1634 - ``none``: Nothing, ignore.
    1636 - ``dir``: A directory path.
    1638 - ``exe``: An executable path.
    1640 - ``triplet``: A GNU style architecture, platform, operating system string.
    1642 the 'Attribute' field is:
    1644 - ``none``:: Nothing, ignore
    1646 - ``required``:: The host check must find the executable or path.
    1648 - ``optional``:: The host check generates a warning if not found.
    1650 - ``override``:: Only valid outside of the ``global`` map to indicate
    1651   this macro overrides the same one in the ``global`` map when the map
    1652   containing it is selected.
    1654 - ``undefine``:: Only valid outside of the ``global`` map to undefine
    1655   the macro if it exists in the ``global`` map when the map containing it
    1656   is selected. The ``global`` map's macro is not visible but still exists.
    1658 and the 'String' field is a single or tripled multiline quoted string. The
    1659 'String' can contain references to other macros. Macro that loop are not
    1660 currently detected and will cause the tool to lock up.
    1662 Maps are declared anywhere in the map using the map directive:
    1664 .. code-block:: shell
    1666     # Comments
    1667     [my-special-map] <1>
    1668     _host:  none, override, 'abc-xyz'
    1669     multiline: none, override, '''First line,
    1670     second line,
    1671     and finally the last line'''
    1673 - *<1>* The map is set to ``my-special-map``.
    1675 Any macro defintions following a map declaration are placed in that map
    1676 and the default map is ``global`` when loading a file. Maps are selected
    1677 in configuration files by using the ``%select`` directive.
    1679 .. code-block:: shell
    1681     %select my-special-map
    1683 Selecting a map means all requests for a macro first check the selected map and
    1684 if present return that value else the ``global`` map is used. Any new macros or
    1685 changes update only the ``global`` map. This may change in future releases so
    1686 please make sure you use the ``override`` attribute.
    1688 The macro files specificed on the command line are looked for in the
    1689 ``_configdir`` paths. See <<X1,``_configdir``>> variable for details. Included
    1690 files need to add the ``%{_configdir}`` macro to the start of the file.
    1692 Macro map files can include other macro map files using the ``%include``
    1693 directive. The macro map to build *binutils*, *gcc*, *newlib*, *gdb* and
    1694 *RTEMS* from version control heads is:
    1696 .. code-block:: shell
    1698     # <1>
    1699     # Build all tool parts from version control head.
    1700     #
    1701     %include %{_configdir}/snapshots/
    1702     %include %{_configdir}/snapshots/
    1703     %include %{_configdir}/snapshots/
    1704     %include %{_configdir}/snapshots/
    1706 - *<1>* The file is ``config/snapshots/``.
    1708 The macro map defaults to ``global`` at the start of each included file and the
    1709 map setting of the macro file including the other macro files does not change.
    1711 Personal Macros
    1712 ^^^^^^^^^^^^^^^
    1714 When the tools start to run they will load personal macros. Personal macros are
    1715 in the standard format for macros in a file. There are two places personal
    1716 macros can be configured. The first is the environment variable
    1717 ``RSB_MACROS``. If present the macros from the file the environment variable
    1718 points to are loaded. The second is a file called ``.rsb_macros`` in your home
    1719 directory. You need to have the environment variable ``HOME`` defined for this
    1720 work.
    1722 Report Mailing
    1723 ~~~~~~~~~~~~~~
    1725 The build reports can be mailed to a specific email address to logging and
    1726 monitoring. Mailing requires a number of parameters to function. These are:
    1728 - To mail address
    1730 - From mail address
    1732 - SMTP host
    1734 .. _To Mail Address:
    1736 The ``to`` mail address is taken from the macro ``%{_mail_tools_to}`` and the
    1737 default is *rtems-tooltestresults at*. You can override the default
    1738 with a personal or user macro file or via the command line option *--mail-to*.
    1740 .. _From Mail Address:
    1742 The ``from`` mail address is taken from:
    1744 - GIT configuration
    1746 - User ``.mailrc`` file
    1748 - Command line
    1750 If you have configured an email and name in git it will be used used. If you do
    1751 not a check is made for a ``.mailrc`` file. The environment variable *MAILRC* is
    1752 used if present else your home directory is check. If found the file is scanned
    1753 for the ``from`` setting:
    1755   set from="Foo Bar <foo@bar>"
    1757 You can also support a from address on the command line with the *--mail-from*
    1758 option.
    1760 .SMTP Host
    1762 The SMTP host is taken from the macro ``%{_mail_smtp_host}`` and the
    1763 default is ``localhost``. You can override the default with a personal
    1764 or user macro file or via the command line option *--smtp-host*.
    1766 Build Set Files
    1767 ~~~~~~~~~~~~~~~
    1769 Build set files lets you list the packages in the build set you are defining
    1770 and have a file extension of ``.bset``. Build sets can define macro variables,
    1771 inline include other files and reference other build set or package
    1772 configuration files.
    1774 Defining macros is performed with the ``%define`` macro:
    1776 .. code-block:: shell
    1778     %define _target m32r-rtems4.11
    1780 Inline including another file with the ``%include`` macro continues processing
    1781 with the specified file returning to carry on from just after the include
    1782 point.
    1784 .. code-block:: shell
    1786     %include rtems-4.11-base.bset
    1788 This includes the RTEMS 4.11 base set of defines and checks. The configuration
    1789 paths as defined by ``_configdir`` are scanned. The file extension is optional.
    1791 You reference build set or package configuration files by placing the file name
    1792 on a single line.
    1794 .. code-block:: shell
    1796     tools/rtems-binutils-2.22-1
    1798 The ``_configdir`` path is scanned for ``tools/rtems-binutils-2.22-1.bset`` or
    1799 ``tools/rtems-binutils-2.22-1.cfg``. Build set files take precedent over package
    1800 configuration files. If ``tools/rtems-binutils-2.22-1`` is a build set a new
    1801 instance of the build set processor is created and if the file is a package
    1802 configuration the package is built with the package builder. This all happens
    1803 once the build set file has finished being scanned.
    1805 Configuration Control
    1806 ~~~~~~~~~~~~~~~~~~~~~
    1808 The RTEMS Souce Builder is designed to fit within most verification and
    1809 validation processes. All of the RTEMS Source Builder is source code. The
    1810 Python code is source and comes with a commercial friendly license. All
    1811 configuration data is text and can be read or parsed with standard text based
    1812 tools.
    1814 File naming provides configuration management. A specific version of a package
    1815 is captured in a specific set of configuration files. The top level
    1816 configuration file referenced in a *build set* or passed to the +sb-builder+
    1817 command relates to a specific configuration of the package being built. For
    1818 example the RTEMS configuration file +rtems-gcc-4.7.2-newlib-2.0.0-1.cfg+
    1819 creates an RTEMS GCC and Newlib package where the GCC version is 4.7.2, the
    1820 Newlib version is 2.0.0, plus any RTEMS specific patches that related to this
    1821 version. The configuration defines the version numbers of the various parts
    1822 that make up this package:
    1824 .. code-block:: shell
    1826     %define gcc_version    4.7.2
    1827     %define newlib_version 2.0.0
    1828     %define mpfr_version   3.0.1
    1829     %define mpc_version    0.8.2
    1830     %define gmp_version    5.0.5
    1832 The package build options, if there are any are also defined:
    1834 .. code-block:: shell
    1836     %define with_threads 1
    1837     %define with_plugin  0
    1838     %define with_iconv   1
    1840 The generic configuration may provide defaults in case options are not
    1841 specified. The patches this specific version of the package requires can be
    1842 included:
    1844 .. code-block:: shell
    1846     Patch0: gcc-4.7.2-rtems4.11-20121026.diff
    1848 Finally including the GCC 4.7 configuration script:
    1850 .. code-block:: shell
    1852     %include %{_configdir}/gcc-4.7-1.cfg
    1854 The +gcc-4.7-1.cfg+ file is a generic script to build a GCC 4.7 compiler with
    1855 Newlib. It is not specific to RTEMS. A bare no operating system tool set can be
    1856 built with this file.
    1858 The +-1+ part of the file names is a revision. The GCC 4.7 script maybe revised
    1859 to fix a problem and if this fix effects an existing script the file is copied
    1860 and given a +-2+ revision number. Any dependent scripts referencing the earlier
    1861 revision number will not be effected by the change. This locks down a specific
    1862 configuration over time.
    1864 Personal Configurations
    1865 ~~~~~~~~~~~~~~~~~~~~~~~
    1867 The RSB supports personal configurations. You can view the RTEMS support in the
    1868 +rtems+ directory as a private configuration tree that resides within the RSB
    1869 source. There is also the +bare+ set of configurations. You can create your own
    1870 configurations away from the RSB source tree yet use all that the RSB provides.
    1872 To create a private configuration change to a suitable directory:
    1874 .. code-block:: shell
    1876     $ cd ~/work
    1877     $ mkdir test
    1878     $ cd test
    1879     $ mkdir config
    1881 and create a +config+ directory. Here you can add a new configuration or build
    1882 set file. The section 'Adding New Configurations' details how to add a new
    1883 confguration.
    1885 New Configurations
    1886 ~~~~~~~~~~~~~~~~~~
    1888 This section describes how to add a new configuration to the RSB. We will add a
    1889 configuration to build the Device Tree Compiler. The Device Tree Compiler or
    1890 DTC is part of the Flattened Device Tree project and compiles Device Tree
    1891 Source (DTS) files into Device Tree Blobs (DTB). DTB files can be loaded by
    1892 operating systems and used to locate the various resources such as base
    1893 addresses of devices or interrupt numbers allocated to devices. The Device Tree
    1894 Compiler source code can be downloaded from The
    1895 DTC is supported in the RSB and you can find the configuration files under the
    1896 +bare/config+ tree. I suggest you have a brief look over these files.
    1898 Layering by Including
    1899 ^^^^^^^^^^^^^^^^^^^^^
    1901 Configurations can be layered using the +%include+ directive. The user invokes
    1902 the outer layers which include inner layers until all the required
    1903 configuration is present and the package can be built. The outer layers can
    1904 provide high level details such as the version and the release and the inner
    1905 layers provide generic configuration details that do not change from one
    1906 release to another. Macro variables are used to provide the specific
    1907 configuration details.
    1909 Configuration File Numbering
    1910 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    1912 Configuration files have a number at the end. This is a release number for that
    1913 configuration and it gives us the ability to track a specific configuration for
    1914 a specific version. For example lets say the developers of the DTC package
    1915 change the build system from a single makefile to autoconf and automake between
    1916 version 1.3.0 and version 1.4.0. The configuration file used to build the
    1917 package would change have to change. If we did not number the configuration
    1918 files the ability to build 1.1.0, 1.2.0 or 1.3.0 would be lost if we update a
    1919 common configuration file to build an autoconf and automake version. For
    1920 version 1.2.0 the same build script can be used so we can share the same
    1921 configuration file between version 1.1.0 and version 1.2.0. An update to any
    1922 previous release lets us still build the package.
    1924 Common Configuration Scripts
    1925 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    1927 Common configuration scripts that are independent of version, platform and
    1928 architecture are useful to everyone. These live in the Source Builder's
    1929 configuration directory. Currently there are scripts to build binutils, expat,
    1930 DTC, GCC, GDB and libusb. These files contain the recipes to build these
    1931 package without the specific details of the versions or patches being
    1932 built. They expect to be wrapped by a configuration file that ties the package
    1933 to a specific version and optionally specific patches.
    1935 DTC Example
    1936 ^^^^^^^^^^^
    1938 We will be building the DTC for your host rather than a package for RTEMS. We
    1939 will create a file called +source-builder/config/dtc-1-1.cfg+. This is a common
    1940 script that can be used to build a specific version using a general recipe. The
    1941 file name is 'dtc-1-1.cfg' where the 'cfg' extension indicates this is a
    1942 configuration file. The first *1* says this is for the major release 1 of the
    1943 package and the last *1* is the build configuration version.
    1945 The file starts with some comments that detail the configuration. If there is
    1946 anything unusual about the configuration it is a good idea to add something in
    1947 the comments here. The comments are followed by a check for the release. In
    1948 this case if a release is not provided a default of 1 is used.
    1950 .. code-block:: shell
    1952     #
    1953     # DTC 1.x.x Version 1.
    1954     #
    1955     # This configuration file configure's, make's and install's DTC.
    1956     #
    1958     %if %{release} == %{nil}
    1959     %define release 1
    1960     %endif
    1962 The next section defines some information about the package. It does not effect
    1963 the build and is used to annotate the reports. It is recommended this
    1964 information is kept updated and accurate.
    1966 .. code-block:: shell
    1968     Name:      dtc-%{dtc_version}-%{_host}-%{release}
    1969     Summary:   Device Tree Compiler v%{dtc_version} for target %{_target} on host %{_host}
    1970     Version:   %{dtc_version}
    1971     Release:   %{release}
    1972     URL: 
    1973     BuildRoot: %{_tmppath}/%{name}-root-%(%{__id_u} -n)
    1975 The next section defines the source and any patches. In this case there is a
    1976 single source package and it can be downloaded using the HTTP protocol. The RSB
    1977 knows this is GZip'ped tar file. If more than one package package is needed add
    1978 them increasing the index. The +gcc-4.8-1.cfg+ configuration contains examples
    1979 of more than one source package as well as conditionally including source
    1980 packages based on the outer configuration options.
    1982 .. code-block:: shell
    1984     #
    1985     # Source
    1986     #
    1987     %source set dtc{dtc_version}.tgz
    1988     -------------------------------------------------------------
    1990 The remainder of the script is broken in to the various phases of a build. They
    1991 are:
    1993 . Preperation
    1994 . Bulding
    1995 . Installing, and
    1996 . Cleaning
    1998 Preparation is the unpacking of the source, applying any patches as well as any
    1999 package specific set ups. This part of the script is a standard Unix shell
    2000 script. Be careful with the use of '%' and '$'. The RSB uses '%' while the
    2001 shell scripts use '$'.
    2003 A standard pattern you will observe is the saving of the build's top
    2004 directory. This is used instead of changing into a subdirectory and then
    2005 changing to the parent when finished. Some hosts will change in a subdirectory
    2006 that is a link however changing to the parent does not change back to the
    2007 parent of the link rather it changes to the parent of the target of the link
    2008 and that is something the RSB nor you can track easily. The RSB configuration
    2009 script's are a collection of various subtle issues so please ask if you are
    2010 unsure why something is being done a particular way.
    2012 The preparation phase will often include source and patch setup commands. Outer
    2013 layers can set the source package and add patches as needed while being able to
    2014 use a common recipe for the build. Users can override the standard build and
    2015 supply a custom patch for testing using the user macro command line interface.
    2017 .. code-block:: shell
    2019     #
    2020     # Prepare the source code.
    2021     #
    2022     %prep
    2023       build_top=$(pwd)
    2025       %source setup dtc -q -n dtc-v%{dtc_version}
    2026       %patch setup dtc -p1
    2028       cd ${build_top}
    2030 The configuration file 'gcc-common-1.cfg' is a complex example of source
    2031 preparation. It contains a number of source packages and patches and it
    2032 combines these into a single source tree for building. It uses links to map
    2033 source into the GCC source tree so GCC can be built using the *single source
    2034 tree* method. It also shows how to fetch source code from version
    2035 control. Newlib is taken directly from its CVS repository.
    2037 Next is the building phase and for the DTC example this is simply a matter of
    2038 running +make+. Note the use of the RSB macros for commands. In the case of
    2039 '%{\__make}' it maps to the correct make for your host. In the case of BSD
    2040 systems we need to use the GNU make and not the GNU make.
    2042 If your package requires a configuration stage you need to run this before the
    2043 make stage. Again the GCC common configuration file provides a detailed example.
    2045 .. code-block:: shell
    2047     %build
    2048       build_top=$(pwd)
    2050       cd dtc-v%{dtc_version}
    2052       %{build_build_flags}
    2054       %{__make} PREFIX=%{_prefix}
    2056       cd ${build_top}
    2058 You can invoke make with the macro '%{?_smp_flags}' as a command line
    2059 argument. This macro is controlled by the '--jobs' command line option and the
    2060 host CPU detection support in the RSB. If you are on a multicore host you can
    2061 increase the build speed using this macro. It also lets you disabled building on
    2062 multicores to aid debugging when testing.
    2064 Next is the install phase. This phase is a little more complex because you may
    2065 be building a tar file and the end result of the build is never actually
    2066 installed into the prefix on the build host and you may not even have
    2067 permissions to perform a real install. Most packages install to the +prefix+
    2068 and the prefix is typically supplied via the command to the RSB or the
    2069 package's default is used. The default can vary depending on the host's
    2070 operating system. To install to a path that is not the prefix the +DESTDIR+
    2071 make variable is used. Most packages should honour the +DISTDIR+ make variables
    2072 and you can typically specify it on the command line to make when invoking the
    2073 install target. This results in the package being installed to a location that
    2074 is not the prefix but one you can control. The RSB provides a shell variable
    2075 called +SB_BUILD_ROOT+ you can use. In a build set where you are building a
    2076 number of packages you can collect all the built packages in a single tree that
    2077 is captured in the tar file.
    2079 Also note the use of the macro +%{\__rmdir}+. The use of these macros allow the
    2080 RSB to vary specific commands based on the host. This can help on hosts like
    2081 Windows where bugs can effect the standard commands such as 'rm'. There are
    2082 many many macros to help you. You can find these listed in the
    2083 file and in the trace output. If you are new to creating and editing
    2084 configurations learning these can take a little time.
    2086 .. code-block:: shell
    2088     %install
    2089       build_top=$(pwd)
    2091       %{__rmdir} -rf $SB_BUILD_ROOT
    2093       cd dtc-v%{dtc_version}
    2094       %{__make} DESTDIR=$SB_BUILD_ROOT PREFIX=%{_prefix} install
    2096       cd ${build_top}
    2098 Finally there is an optional clean section. The RSB will run this section if
    2099 +--no-clean+ has not been provided on the command line. The RSB does clean up
    2100 for you.
    2102 Once we have the configuration files we can execute the build using the
    2103 ``sb-builder`` command. The command will perform the build and create a tar file
    2104 in the +tar+ directory.
    2106 .. code-block:: shell
    2108     $  ../source-builder/sb-builder --prefix=/usr/local \
    2109          --log=log_dtc devel/dtc-1.2.0
    2110     RTEMS Source Builder, Package Builder v0.2.0
    2111     config: devel/dtc-1.2.0
    2112     package: dtc-1.2.0-x86_64-freebsd9.1-1
    2113     download: -> sources/dtc-v1.2.0.tgz
    2114     building: dtc-1.2.0-x86_64-freebsd9.1-1
    2115     $ ls tar
    2116     dtc-1.2.0-x86_64-freebsd9.1-1.tar.bz2
    2118 If you want to have the package installed automatically you need to create a
    2119 build set. A build set can build one or more packages from their configurations
    2120 at once to create a single package. For example the GNU tools is typically seen
    2121 as binutils, GCC and GDB and a build set will build each of these packages and
    2122 create a single build set tar file or install the tools on the host into the
    2123 prefix path.
    2125 The DTC build set file is called +dtc.bset+ and contains:
    2127 .. code-block:: shell
    2129     #
    2130     # Build the DTC.
    2131     #
    2133     %define release 1
    2135     devel/dtc-1.2.0.cfg
    2137 To build this you can use something similar to:
    2139 .. code-block:: shell
    2141     $ ../source-builder/sb-set-builder --prefix=/usr/local --log=log_dtc \
    2142        --trace --bset-tar-file --no-install dtc
    2143     RTEMS Source Builder - Set Builder, v0.2.0
    2144     Build Set: dtc
    2145     config: devel/dtc-1.2.0.cfg
    2146     package: dtc-1.2.0-x86_64-freebsd9.1-1
    2147     building: dtc-1.2.0-x86_64-freebsd9.1-1
    2148     tarball: tar/x86_64-freebsd9.1-dtc-set.tar.bz2
    2149     cleaning: dtc-1.2.0-x86_64-freebsd9.1-1
    2150     Build Set: Time 0:00:02.865758
    2151     $ ls tar
    2152     dtc-1.2.0-x86_64-freebsd9.1-1.tar.bz2   x86_64-freebsd9.1-dtc-set.tar.bz2
    2154 The build is for a FreeBSD host and the prefix is for user installed
    2155 packages. In this example I cannot let the source builder perform the install
    2156 because I never run the RSB with root priviledges so a build set or bset tar
    2157 file is created. This can then be installed using root privildges.
    2159 The command also supplies the --trace option. The output in the log file will
    2160 contian all the macros.
    2162 Debugging
    2163 ^^^^^^^^^
    2165 New configuration files require debugging. There are two types of
    2166 debugging. The first is debugging RSB script bugs. The +--dry-run+ option is
    2167 used here. Suppling this option will result in most of the RSB processing to be
    2168 performed and suitable output placed in the log file. This with the +--trace+
    2169 option should help you resolve any issues.
    2171 The second type of bug to fix are related to the execution of one of
    2172 phases. These are usually a mix of shell script bugs or package set up or
    2173 configuration bugs. Here you can use any normal shell script type debug
    2174 technique such as +set -x+ to output the commands or +echo+
    2175 statements. Debugging package related issues may require you start a build with
    2176 teh RSB and supply +--no-clean+ option and then locate the build directories
    2177 and change directory into them and manually run commands until to figure what
    2178 the package requires.
    2180 Snapshot Testing
    2181 ~~~~~~~~~~~~~~~~
    2183 *TBD: This section needs to be updated once I sort out snapshot testing.*
    2185 Testing of release canidates and snapshots is important to those helping
    2186 maintain tool sets. The RTEMS Source Builder helps by providing a simple and
    2187 flexible way to use existing build sets and configuration without needing to
    2188 change them or creating new temporary build sets and configurations.
    2190 The process uses snapshot macro files loaded via the command line option
    2191 ``--macros``. These files provide macros that override the standard
    2192 build set and configuration file macros.
    2194 Lets consider testing a GCC 4.7 snapshot for RTEMS 4.11. Lets assume the
    2195 current RTEMS 4.11 tools reference GCC 4.7.3 with a patch as the stable tool
    2196 set. We want to use a recent snapshot with no patches. In the
    2197 ``rtems/config/snapshots`` directoy create a file called ````
    2198 containing:
    2200 .. code-block:: shell
    2202     [gcc-4.7-snapshot]
    2203     GCC_Version: none, override, '4.7-20130413'
    2204     Source:     none, override, '
    2205     snapshots/%{gcc_version}/gcc-%{gcc_version}.tar.bz2'
    2206     Patch0:      none, udefine,  ''
    2208 In the standard configuration file ``source-builder/config/gcc-4.7-1.cfg`` the
    2209 map is selected with:
    2211 .. code-block:: shell
    2213     #
    2214     # Select the GCC 4.7 Snapshot Macro Map
    2215     #
    2216     %select gcc-4.7-snapshot
    2218 On the command line add ``--macros=snapshots/`` and this
    2219 snapshot will be built. With careful use of the ``--prefix`` option you can
    2220 locate the tools in a specific directory and test them without needing to
    2221 effect your production environment.
    2223 Scripting
    2224 ~~~~~~~~~
    2226 Configuration files specify how to build a package. Configuration files are
    2227 scripts and have a +.cfg+ file extension. The script format is based loosely on
    2228 the RPM spec file format however the use and purpose in this tool does not
    2229 compare with the functionality and therefore the important features of the spec
    2230 format RPM needs and uses.
    2232 The script language is implemented in terms of macros. The built-in list is:
    2234 - *%{}*: Macro expansion with conditional logic.
    2236 - *%()*: Shell expansion.
    2238 - *%prep*: The source preparation shell commands.
    2240 - *%build*: The build shell commands.
    2242 - *%install*: The package install shell commands.
    2244 - *%clean*: The package clean shell commands.
    2246 - *%include*: Inline include another configuration file.
    2248 - *%name*: The name of the package.
    2250 - *%summary*: A brief package description. Useful when reporting about a build.
    2252 - *%release*: The package release. A number that is the release as built
    2253   by this tool.
    2255 - *%version*: The package's version string.
    2257 - *%buildarch*: The build architecture.
    2259 - *%source*: Define a source code package. This macro has a number appended.
    2261 - *%patch*: Define a patch. This macro has a is number appended.
    2263 - *%hash*: Define a checksum for a source or patch file.
    2265 - *%echo*: Print the following string as a message.
    2267 - *%warning*: Print the following string as a warning and continue.
    2269 - *%error*: Print the following string as an error and exit.
    2271 - *%select*: Select the macro map. If there is no map nothing is reported.
    2273 - *%define*: Define a macro. Macros cannot be redefined, you must first
    2274   undefine it.
    2276 - *%undefine*: Undefine a macro.
    2278 - *%if*: Start a conditional logic block that ends with a +%endif+.
    2280 - *%ifn*: Inverted start of a conditional logic block.
    2282 - *%ifarch*: Test the architecture against the following string.
    2284 - *%ifnarch*: Inverted test of the architecture
    2286 - *%ifos*: Test the host operating system.
    2288 - *%else*: Start the *else* conditional logic block.
    2290 - *%endfi*: End the conditional logic block.
    2292 - *%bconf_with*: Test the build condition *with* setting. This is the
    2293   +--with-*+ command line option.
    2295 - *%bconf_without*: Test the build condition *without* setting. This is
    2296   the +--without-*+ command line option.
    2298 Expanding
    2299 ^^^^^^^^^
    2301 A macro can be ``%{string}`` or the equivalent of ``%string``. The following macro
    2302 expansions supported are:
    2304 - ``%{string}``: Expand the 'string' replacing the entire macro text
    2305   with the text in the table for the entry 'string . For example if 'var'
    2306   is 'foo' then ``${var}`` would become ``foo``.
    2308 - ``%{expand: string}``: Expand the 'string' and then use it as a
    2309   ````string'' to the macro expanding the macro. For example if *foo*
    2310   is set to 'bar' and 'bar' is set to 'foobar' then ``%{expand:foo}``
    2311   would result in ``foobar``. Shell expansion can also be used.
    2313 - ``%{with string}``: Expand the macro to '1' if the macro
    2314   ``with_``'string' is defined else expand to *0*. Macros with the name
    2315   ``with_``'string' can be define with command line arguments to the RTEMS
    2316   Source Builder commands.
    2318 - ``%{defined string}``: Expand the macro to '1' if a macro of name
    2319   'string' is defined else expand to '0'.
    2321 - ``%{?string: expression}``: Expand the macro to 'expression' if a
    2322   macro of name 'string' is defined else expand to ``%{nil}``.
    2324 - ``%{!?string: expression}``: Expand the macro to 'expression' if a
    2325   macro of name 'string' is not defined. If the macro is define expand to
    2326   ``%{nil}``.
    2328 - ``%(expression)``: Expand the macro to the result of running the
    2329   'expression' in a host shell. It is assumed this is a Unix type shell. For
    2330   example ``%(whoami)`` will return your user name and ``%(date)`` will
    2331   return the current date string.
    2333 %prep
    2334 ^^^^^
    2336 The +%prep+ macro starts a block that continues until the next block macro. The
    2337 *prep* or preparation block defines the setup of the package's source and is a
    2338 mix of RTEMS Source Builder macros and shell scripting. The sequence is
    2339 typically +%source+ macros for source, +%patch+ macros to patch the source
    2340 mixed with some shell commands to correct any source issues.
    2342 .. code-block:: shell
    2344                   <1>                <2>      <3>
    2345 %source setup gcc -q -c -T -n %{name}-%{version}
    2347 - *<1>* The source group to set up.
    2349 - *<2>* The source's name.
    2351 - *<3>* The version of the source.
    2353 The source set up are declared with the source +set+ and +add+ commands. For
    2354 example:
    2356 .. code-block:: shell
    2358     %source set gdb{gdb_version}.tar.bz2
    2360 This URL is the primary location of the GNU GDB source code and the RTEMS
    2361 Source Builder can download the file from this location and by inspecting the
    2362 file extension use +bzip2+ decompression with +tar+. When the +%prep+ section
    2363 is processed a check of the local +source+ directory is made to see if the file
    2364 has already been downloaded. If not found in the source cache directory the
    2365 package is downloaded from the URL. You can append other base URLs via the
    2366 command line option +--url+. This option accepts a comma delimited list of
    2367 sites to try.
    2369 You could optionally have a few source files that make up the package. For
    2370 example GNU's GCC was a few tar files for a while and it is now a single tar
    2371 file. Support for multiple source files can be conditionally implemented with
    2372 the following scripting:
    2374 .. code-block:: shell
    2376     %source set gcc{gcc_version}/gcc-code-%{gcc_version}.tar.bz2
    2377     %source add gcc{gcc_version}/gcc-g++-%{gcc_version}.tar.bz2
    2378     %source setup gcc -q -T -D -n gcc-%{gcc_version}
    2380 Separate modules use separate source groups. The GNU GCC compiler for RTEMS
    2381 uses Newlib, MPFR, MPC, and GMP source packages. You define the source with:
    2383 .. code-block:: shell
    2385     %source set gcc{gcc_version}/gcc-%{gcc_version}.tar.bz2
    2386     %source set newlib{newlib_version}.tar.gz
    2387     %source set mpfr{mpfr_version}/mpfr-%{mpfr_version}.tar.bz2
    2388     %source set mpc{mpc_version}.tar.gz
    2389     %source set gmp{gmp_version}.tar.bz2
    2391 and set up with:
    2393 .. code-block:: shell
    2395     %source setup gcc -q -n gcc-%{gcc_version}
    2396     %source setup newlib -q -D -n newlib-%{newlib_version}
    2397     %source setup mpfr -q -D -n mpfr-%{mpfr_version}
    2398     %source setup mpc -q -D -n mpc-%{mpc_version}
    2399     %source setup gmp -q -D -n gmp-%{gmp_version}
    2401 Patching also occurs during the preparation stage. Patches are handled in a
    2402 similar way to the source packages except you only +add+ patches. Patches are
    2403 applied using the +setup+ command. The +setup+ command takes the default patch
    2404 option. You can provide options with each patch by adding them as arguments
    2405 before the patch URL. Patches with no options uses the +setup+ default.
    2407 .. code-block:: shell
    2409     %patch add gdb %{rtems_gdb_patches}/gdb-sim-arange-inline.diff
    2410     %patch add gdb -p0 <1> %{rtems_gdb_patches}/gdb-sim-cgen-inline.diff
    2412 - *<1>* This patch has a custom option.
    2414 To apply these patches:
    2416 .. code-block:: shell
    2418     %patch setup gdb -p1 <1>
    2420 - *<1>* The default options.
    2422 %build
    2423 ^^^^^^
    2425 The +%build+ macro starts a block that continues until the next block
    2426 macro. The build block is a series of shell commands that execute to build the
    2427 package. It assumes all source code has been unpacked, patch and adjusted so
    2428 the build will succeed.
    2430 The following is an example take from the GutHub STLink project:
    2432 NOTE: STLink is a JTAG debugging device for the ST ARM family of processors.
    2434 .. code-block:: shell
    2436     %build
    2437       export PATH="%{_bindir}:${PATH}" <1>
    2439       cd texane-stlink-%{stlink_version} <2>
    2441       ./ <3>
    2443     %if "%{_build}" != "%{_host}"
    2444       CFLAGS_FOR_BUILD="-g -O2 -Wall" \ <4>
    2445     %endif
    2446       CPPFLAGS="-I $SB_TMPPREFIX/include/libusb-1.0" \ <5>
    2447       CFLAGS="$SB_OPT_FLAGS" \
    2448       LDFLAGS="-L $SB_TMPPREFIX/lib" \
    2449       ./configure \ <6>
    2450         --build=%{_build} --host=%{_host} \
    2451         --verbose \
    2452         --prefix=%{_prefix} --bindir=%{_bindir} \
    2453         --exec-prefix=%{_exec_prefix} \
    2454         --includedir=%{_includedir} --libdir=%{_libdir} \
    2455         --mandir=%{_mandir} --infodir=%{_infodir}
    2457       %{__make} %{?_smp_mflags} all <7>
    2459       cd ..
    2461 - *<1>* Setup the PATH environment variable. This is not always needed.
    2463 - *<2>* This package builds in the source tree so enter it.
    2465 - *<3>* The package is actually checked directly out from the github
    2466   project and so it needs its autoconf and automake files generated.
    2468 - *<4>* Flags for a cross-compiled build.
    2470 - *<5>* Various settings passed to configure to customise the build. In
    2471   this example an include path is being set to the install point of
    2472   *libusb*. This package requires *libusb* is built before it.
    2474 - *<6>* The +configure+ command. The RTEMS Source Builder provides
    2475   all the needed paths as macro variables. You just need to provide them
    2476   to +configure+.
    2478 - *<7>* Running make. Do not use +make+ directly, use the RTEMS Source
    2479   Builder's defined value. This value is specific to the host. A large
    2480   number of packages need GNU make and on BSD systems this is +gmake+. You
    2481   can optionally add the SMP flags if the packages build system can
    2482   handle parallel building with multiple jobs. The +_smp_mflags+ value
    2483   is automatically setup for SMP hosts to match the number of cores the
    2484   host has.
    2486 %install
    2487 ^^^^^^^^
    2489 The +%install+ macro starts a block that continues until the next block
    2490 macro. The install block is a series of shell commands that execute to install
    2491 the package. You can assume the package has build correctly when this block
    2492 starts executing.
    2494 Never install the package to the actual *prefix* the package was built
    2495 with. Always install to the RTEMS Source Builder's temporary path defined in
    2496 the macro variable +\__tmpdir+. The RTEMS Source Builder sets up a shell
    2497 environment variable called +SB_BUILD_ROOT+ as the standard install point. Most
    2498 packages support adding +DESTDIR=+ to the *make install* command.
    2500 Looking at the same example as in <<_build, %build>>:
    2502 .. code-block:: shell
    2504     %install
    2505       export PATH="%{_bindir}:${PATH}" <1>
    2506       rm -rf $SB_BUILD_ROOT <2>
    2508       cd texane-stlink-%{stlink_version} <3>
    2509       %{__make} DESTDIR=$SB_BUILD_ROOT install <4>
    2511       cd ..
    2513 - *<1>* Setup the PATH environment variable. This is not always needed.
    2515 - *<2>* Clean any installed files. This make sure the install is just
    2516   what the package installs and not any left over files from a broken
    2517   build or install.
    2519 - *<3>* Enter the build directory. In this example it just happens to
    2520   be the source directory.
    2522 - *<4>* Run +make install+ to install the package overriding the +DESTDIR+
    2523   make variable.
    2525 %clean
    2526 ^^^^^^
    2528 The +%clean+ macro starts a block that continues until the next block
    2529 macro. The clean block is a series of shell commands that execute to clean up
    2530 after a package has been built and install. This macro is currenly not been
    2531 used because the RTEMS Source Builder automatically cleans up.
    2533 %include
    2534 ^^^^^^^^
    2536 The +%include+ macro inline includes the specific file. The +\__confdir+
    2537 path is searched. Any relative path component of the include file is appended
    2538 to each part of the +\__configdir+. Adding an extension is optional as files
    2539 with +.bset+ and +.cfg+ are automatically searched for.
    2541 Inline including means the file is processed as part of the configuration at
    2542 the point it is included. Parsing continues from the next line in the
    2543 configuration file that contains the +%include+ macro.
    2545 Including files allow a kind of configuration file reuse. The outer
    2546 configuration files provide specific information such as package version
    2547 numbers and patches and then include a generic configuration script which
    2548 builds the package.
    2550 .. code-block:: shell
    2552     %include %{_configdir}/gcc-4.7-1.cfg
    2554 %name
    2555 ^^^^^
    2557 The name of the package being built. The name typically contains the components
    2558 of the package and their version number plus a revision number. For the GCC
    2559 with Newlib configuration the name is typically:
    2561 .. code-block:: shell
    2563     Name: %{_target}-gcc-%{gcc_version}-newlib-%{newlib_version}-%{release}
    2565 %summary
    2566 ^^^^^^^^
    2568 The +%summary+ is a brief description of the package. It is useful when
    2569 reporting. This information is not capture in the package anywhere. For the GCC
    2570 with Newlib configuration the summary is typically:
    2572 .. code-block:: shell
    2574     Summary: GCC v%{gcc_version} and Newlib v%{newlib_version} for target %{_target} on host %{_host}
    2576 %release
    2577 ^^^^^^^^
    2579 The +%release+ is packaging number that allows revisions of a package to happen
    2580 where none package versions change. This value typically increases when the
    2581 configuration building the package changes.
    2583 .. code-block:: shell
    2585     %define release 1
    2587 %version
    2588 ^^^^^^^^
    2590 The +%version% macro sets the version the package. If the package is a single
    2591 component it tracks that component's version number. For example in the
    2592 *libusb* configuration the +%version+ is the same as +%libusb_version+, however
    2593 in a GCC with Newlib configuration there is no single version number. In this
    2594 case the GCC version is used.
    2596 .. code-block:: shell
    2598     Version: %{gcc_version}
    2600 %buildarch
    2601 ^^^^^^^^^^
    2603 The +%buildarch+ macro is set to the architecture the package contains. This is
    2604 currently not used in the RTEMS Source Builder and may go away. This macro is
    2605 more important in a real packaging system where the package could end up on the
    2606 wrong architecture.
    2608 %source
    2609 ^^^^^^^
    2611 The +%source+ macro has 3 commands that controls what it does. You can +set+
    2612 the source files, +add+ source files to a source group, and +setup+ the source
    2613 file group getting it ready to be used.
    2615 Source files are source code files in tar or zip files that are unpacked,
    2616 copied or symbolically linked into the package's build tree. Building a package
    2617 requires one or more dependent packages. These are typically the packages
    2618 source code plus dependent libraries or modules. You can create any number of
    2619 these source groups and set each of them up with a separe source group for each
    2620 needed library or module. Each source group normally has a single tar, zip or
    2621 repository and the +set+ defines this. Some projects split the source code into
    2622 separate tar or zip files and you install them by using the +add+ command.
    2624 The first instance of a +set+ command creates the source group and sets the
    2625 source files to be set up. Subsequence +set+ commands for the same source group
    2626 are ignored. this lets you define the standard source files and override them
    2627 for specific releases or snapshots.. To set a source file group:
    2629 .. code-block:: shell
    2631     %source set gcc <1>{gcc_version}/gcc-%{gcc_version}.tar.bz2
    2633 - *<1>* The source group is +gcc+.
    2635 To add another source package to be installed into the same source tree you use
    2636 the +add+ command:
    2638 .. code-block:: shell
    2640     %source add gcc{gcc_version}/g++-%{gcc_version}.tar.bz2
    2642 The source +setup+ command can only be issued in the +%prep:+ section. The
    2643 setup is:
    2645 .. code-block:: shell
    2647     %source gcc setup -q -T -D -n %{name}-%{version}
    2649 Accepted options are:
    2651 [horizontal]
    2652 *Switch*:: *Description*
    2653 +-n+:: The -n option is used to set the name of the software's build
    2654 directory. This is necessary only when the source archive unpacks into a
    2655 directory named other than +<name>-<version>+.
    2656 +-c+:: The -c option is used to direct %setup to create the top-level build
    2657 directory before unpacking the sources.
    2658 +-D+:: The -D option is used to direct %setup to not delete the build directory
    2659 prior to unpacking the sources. This option is used when more than one source
    2660 archive is to be unpacked into the build directory, normally with the +-b+ or
    2661 +-a+ options.
    2662 +-T+:: The -T option is used to direct %setup to not perform the default
    2663 unpacking of the source archive specified by the first Source: macro. It is used
    2664 with the +-a+ or +-b+ options.
    2665 +-b <n>+:: The -b option is used to direct %setup to unpack the source archive
    2666 specified on the nth Source: macro line before changing directory into the build
    2667 directory.
    2669 %patch
    2670 ^^^^^^
    2672 The +%patch+ macro has the same 3 command as the +%source+ command however the
    2673 +set+ commands is not really that useful with the with command. You add patches
    2674 with the +add+ command and +setup+ applies the patches. Patch options can be
    2675 added to each patch by placing them before the patch URL. If no patch option is
    2676 provided the default options passed to the +setup+ command are used. An option
    2677 starts with a '-'. The +setup+ command must reside inside the +%prep+ section.
    2679 Patches are grouped in a similar way to the +%source+ macro so you can control
    2680 applying a group of patches to a specific source tree.
    2682 The +__patchdir+ path is search.
    2684 To add a patch:
    2686 .. code-block:: shell
    2688     %patch add gcc <1>  gcc-4.7.2-rtems4.11-20121026.diff
    2689     %patch add gcc -p0 <2>  gcc-4.7.2-rtems4.11-20121101.diff
    2691 - *<1>* The patch group is +gcc+.
    2693 - *<2>* Option for this specific patch.
    2695 Placing +%patch setup+ in the +%prep+ section will apply the groups patches.
    2697 .. code-block:: shell
    2699     %patch setup gcc <1>  -p1 <2>
    2701 - *<1>* The patch group.
    2703 - *<2>* The default option used to apply the patch.
    2705 %hash
    2706 ^^^^^
    2708 The +%hash+ macro requires 3 arguments and defines a checksum for a specific
    2709 file. The checksum is not applied until the file is checked before downloading
    2710 and once downloaded. A patch or source file that does not has a hash defined
    2711 generates a warning.
    2713 A file to be checksum must be unqiue in the any of the source and patch
    2714 directories. The basename of the file is used as the key for the hash.
    2716 The hash algorthim can be 'md5', 'sha1', 'sha224', 'sha256', 'sha384', and
    2717 'sha512' and we typically use 'md5'.
    2719 To add a hash:
    2721 .. code-block:: shell
    2723     %hash md5 <1> net-snmp-%{net_snmp_version}.tar.gz <2> 7db683faba037249837b226f64d566d4 <3>
    2725 - *<1>* The type of checksum.
    2727 - *<2>* The file to checksum. It can contain macros that are expanded for you.
    2729 - *<3>* The MD5 hash for the Net-SNMP file +net-snmp-
    2731 Do not include a path with the file name. Only the basename is required. Files
    2732 can be searched for from a number of places and having a path conponent would
    2733 create confusion. This does mean files with hashes must be unique.
    2735 Downloading of repositories such as git and cvs cannot be checksumed. It is
    2736 assumed those protocols and tools manage the state of the files.
    2738 %echo
    2739 ^^^^^
    2741 The +%echo+ macro outputs the following string to stdout. This can also be used
    2742 as ``%{echo: message}``.
    2744 %warning
    2745 ^^^^^^^^
    2747 The +%warning+ macro outputs the following string as a warning. This can also
    2748 be used as ``%{warning: message}``.
    2750 %error
    2751 ^^^^^^
    2753 The +%error+ macro outputs the follow string as an error and exits the RTEMS
    2754 Source Builder. This can also be used as ``%{error: message}``.
    2756 %select
    2757 ^^^^^^^
    2759 The +%select+ macro selects the map specified. If there is no map no error or
    2760 warning is generated. Macro maps provide a simple way for a user to override
    2761 the settings is a configuration file without having to edit it. The changes are
    2762 recorded in the build report so can be traced.
    2764 Configuration use different maps so macro overrides can target a specific
    2765 package.
    2767 The default map is ``global``.
    2769 .. code-block:: shell
    2771     %select gcc-4.8-snapshot <1>
    2772     %define one_plus_one 2 <2>
    2774 - *<1>* The map switches to ``gcc-4.8-snapshot``. Any overrides in this
    2775   map will be used.
    2777 - *<2>* Defining macros only updates the ``global`` map and not the
    2778   selected map.
    2780 %define
    2781 ^^^^^^^
    2783 The +%define+ macro defines a new macro or updates an existing one. If no value
    2784 is given it is assumed to be 1.
    2786 .. code-block:: shell
    2788     %define foo bar
    2789     %define one_plus_one 2
    2790     %define one <1>
    2792 - *<1>* The macro _one_ is set to 1.
    2794 %undefine
    2795 ^^^^^^^^^
    2797 The +%undefine+ macro removes a macro if it exists. Any further references to
    2798 it will result in an undefine macro error.
    2800 %if
    2801 ^^^
    2803 The +%if+ macro starts a conditional logic block that can optionally have a
    2804 *else* section. A test follows this macro and can have the following operators:
    2806 .. list-table:: Operators
    2807    : header-rows: 1
    2809   * - %{}
    2810     - Check the macro is set or *true*, ie non-zero.
    2811          %if ${foo}
    2812           %warning The test passes, must not be empty or is non-zero
    2813          %else
    2814           %error The test fails, must be empty or zero
    2815          %endif
    2816   * - \!
    2817     - The *not* operator inverts the test of the macro.
    2818          %if ! ${foo}
    2819           %warning The test passes, must be empty or zero
    2820          %else
    2821           %error The test fails, must not be empty or is non-zero
    2822          %endif
    2823   * - ==
    2824     - The left hand size must equal the right hand side. For example:
    2825          %define one 1
    2826          %if ${one} == 1
    2827           %warning The test passes
    2828          %else
    2829           %error The test fails
    2830          %endif
    2831       You can also check to see if a macro is empty:
    2832          %if ${nothing} == %{nil}
    2833           %warning The test passes
    2834          %else
    2835           %error The test fails
    2836   * - !=
    2837     - The left hand size does not equal the right hand side. For example:
    2838          %define one 1
    2839          %if ${one} != 2
    2840           %warning The test passes
    2841          %else
    2842           %error The test fails
    2843          %endif
    2844        You can also check to see if something is set:
    2845           %if ${something} != %{nil}
    2846             %warning The test passes
    2847           %else
    2848            %error The test fails
    2849           %endif
    2850   * - >
    2851     - The left hand side is numerically greater than the right hand side.
    2852   * - >
    2853     - The left hand side is numerically greater than or equal to the
    2854       right hand side.
    2855   * - <
    2856     - The left hand side is numerically less than the right hand side.
    2857   * - <=
    2858     - The left hand side is numerically less than or equal to the
    2859       right hand side.
    2861 %ifn
    2862 ^^^^
    2864 The +%ifn+ macro inverts the normal +%if+ logic. It avoids needing to provide
    2865 empty *if* blocks followed by *else* blocks. It is useful when checking if a
    2866 macro is defined:
    2868 .. code-block:: shell
    2870     %ifn %{defined foo}
    2871      %define foo bar
    2872     %endif
    2874 %ifarch
    2875 ^^^^^^^
    2877 The +%ifarch+ is a short cut for "+%if %{\_arch} == i386+". Currently not used.
    2879 %ifnarch
    2880 ^^^^^^^^
    2882 The +%ifnarch+ is a short cut for "+%if %{\_arch} != i386+". Currently not
    2883 used.
    2885 %ifos
    2886 ^^^^^
    2888 The +%ifos+ is a short cut for "+%if %{\_os} != mingw32+". It allows
    2889 conditional support for various operating system differences when building
    2890 packages.
    2892 %else
    2893 ^^^^^
    2895 The +%else+ macro starts the conditional *else* block.
    2897 %endfi
    2898 ^^^^^^
    2900 The +%endif+ macro ends a conditional logic block.
    2902 %bconf_with
    2903 ^^^^^^^^^^^
    2905 The +%bconf_with+ macro provides a way to test if the user has passed a
    2906 specific option on the command line with the +--with-<label>+ option. This
    2907 option is only available with the +sb-builder+ command.
    2909 %bconf_without
    2910 ^^^^^^^^^^^^^^
    2912 The +%bconf_without+ macro provides a way to test if the user has passed a
    2913 specific option on the command line with the +--without-<label>+ option. This
    2914 option is only available with the +sb-builder+ command.
    2916 Commands
    2917 ########
    2919 Checker (sb-check)
    2920 ~~~~~~~~~~~~~~~~~~
    2922 This commands checks your system is set up correctly. Most options are ignored.
    2924 .. code-block:: shell
    2926     $ ../source-builder/sb-check --help
    2927     sb-check: [options] [args]
    2928     RTEMS Source Builder, an RTEMS Tools Project (c) 2012-2013 Chris Johns
    2929     Options and arguments:
    2930     --force                : Force the build to proceed
    2931     --quiet                : Quiet output (not used)
    2932     --trace                : Trace the execution
    2933     --dry-run              : Do everything but actually run the build
    2934     --warn-all             : Generate warnings
    2935     --no-clean             : Do not clean up the build tree
    2936     --always-clean         : Always clean the build tree, even with an error
    2937     --jobs                 : Run with specified number of jobs, default: num CPUs.
    2938     --host                 : Set the host triplet
    2939     --build                : Set the build triplet
    2940     --target               : Set the target triplet
    2941     --prefix path          : Tools build prefix, ie where they are installed
    2942     --topdir path          : Top of the build tree, default is $PWD
    2943     --configdir path       : Path to the configuration directory, default: ./config
    2944     --builddir path        : Path to the build directory, default: ./build
    2945     --sourcedir path       : Path to the source directory, default: ./source
    2946     --tmppath path         : Path to the temp directory, default: ./tmp
    2947     --macros file[,[file]  : Macro format files to load after the defaults
    2948     --log file             : Log file where all build out is written too
    2949     --url url[,url]        : URL to look for source
    2950     --no-download          : Disable the source downloader
    2951     --targetcflags flags   : List of C flags for the target code
    2952     --targetcxxflags flags : List of C++ flags for the target code
    2953     --libstdcxxflags flags : List of C++ flags to build the target libstdc++ code
    2954     --with-<label>         : Add the --with-<label> to the build
    2955     --without-<label>      : Add the --without-<label> to the build
    2956     --regression           : Set --no-install, --keep-going and --always-clean
    2957     $ ../source-builder/sb-check
    2958     RTEMS Source Builder - Check, v0.2.0
    2959     Environment is ok
    2961 Defaults (sb-defaults)
    2962 ~~~~~~~~~~~~~~~~~~~~~~
    2964 This commands outputs and the default macros for your when given no
    2965 arguments. Most options are ignored.
    2967 .. code-block:: shell
    2969     $ ../source-builder/sb-defaults --help
    2970     sb-defaults: [options] [args]
    2971     RTEMS Source Builder, an RTEMS Tools Project (c) 2012-2013 Chris Johns
    2972     Options and arguments:
    2973     --force                : Force the build to proceed
    2974     --quiet                : Quiet output (not used)
    2975     --trace                : Trace the execution
    2976     --dry-run              : Do everything but actually run the build
    2977     --warn-all             : Generate warnings
    2978     --no-clean             : Do not clean up the build tree
    2979     --always-clean         : Always clean the build tree, even with an error
    2980     --jobs                 : Run with specified number of jobs, default: num CPUs.
    2981     --host                 : Set the host triplet
    2982     --build                : Set the build triplet
    2983     --target               : Set the target triplet
    2984     --prefix path          : Tools build prefix, ie where they are installed
    2985     --topdir path          : Top of the build tree, default is $PWD
    2986     --configdir path       : Path to the configuration directory, default: ./config
    2987     --builddir path        : Path to the build directory, default: ./build
    2988     --sourcedir path       : Path to the source directory, default: ./source
    2989     --tmppath path         : Path to the temp directory, default: ./tmp
    2990     --macros file[,[file]  : Macro format files to load after the defaults
    2991     --log file             : Log file where all build out is written too
    2992     --url url[,url]        : URL to look for source
    2993     --no-download          : Disable the source downloader
    2994     --targetcflags flags   : List of C flags for the target code
    2995     --targetcxxflags flags : List of C++ flags for the target code
    2996     --libstdcxxflags flags : List of C++ flags to build the target libstdc++ code
    2997     --with-<label>         : Add the --with-<label> to the build
    2998     --without-<label>      : Add the --without-<label> to the build
    2999     --regression           : Set --no-install, --keep-going and --always-clean
    3001 Set Builder (sb-set-builder)
    3002 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    3004 This command builds a set.
    3006 .. code-block:: shell
    3008     $ ../source-builder/sb-set-builder --help
    3009     RTEMS Source Builder, an RTEMS Tools Project (c) 2012-2013 Chris Johns
    3010     Options and arguments:
    3011     --force                : Force the build to proceed
    3012     --quiet                : Quiet output (not used)
    3013     --trace                : Trace the execution
    3014     --dry-run              : Do everything but actually run the build
    3015     --warn-all             : Generate warnings
    3016     --no-clean             : Do not clean up the build tree
    3017     --always-clean         : Always clean the build tree, even with an error
    3018     --regression           : Set --no-install, --keep-going and --always-clean
    3019     ---jobs                 : Run with specified number of jobs, default: num CPUs.
    3020     --host                 : Set the host triplet
    3021     --build                : Set the build triplet
    3022     --target               : Set the target triplet
    3023     --prefix path          : Tools build prefix, ie where they are installed
    3024     --topdir path          : Top of the build tree, default is $PWD
    3025     --configdir path       : Path to the configuration directory, default: ./config
    3026     --builddir path        : Path to the build directory, default: ./build
    3027     --sourcedir path       : Path to the source directory, default: ./source
    3028     --tmppath path         : Path to the temp directory, default: ./tmp
    3029     --macros file[,[file]  : Macro format files to load after the defaults
    3030     --log file             : Log file where all build out is written too
    3031     --url url[,url]        : URL to look for source
    3032     --no-download          : Disable the source downloader
    3033     --no-install           : Do not install the packages to the prefix
    3034     --targetcflags flags   : List of C flags for the target code
    3035     --targetcxxflags flags : List of C++ flags for the target code
    3036     --libstdcxxflags flags : List of C++ flags to build the target libstdc++ code
    3037     --with-<label>         : Add the --with-<label> to the build
    3038     --without-<label>      : Add the --without-<label> to the build
    3039     --mail-from            : Email address the report is from.
    3040     --mail-to              : Email address to send the email too.
    3041     --mail                 : Send email report or results.
    3042     --smtp-host            : SMTP host to send via.
    3043     --no-report            : Do not create a package report.
    3044     --report-format        : The report format (text, html, asciidoc).
    3045     --bset-tar-file        : Create a build set tar file
    3046     --pkg-tar-files        : Create package tar files
    3047     --list-bsets           : List available build sets
    3048     --list-configs         : List available configurations
    3049     --list-deps            : List the dependent files.
    3051 .Arguments
    3052 The +[args]+ are a list build sets to build.
    3054 .Options
    3055 +--force+;;
    3056 Force the build to proceed even if the host check fails. Typically this happens
    3057 if executable files are found in the path at a different location to the host
    3058 defaults.
    3059 +--trace+;;
    3060 Trace enable printing of debug information to stdout. It is really only of use
    3061 to RTEMS Source Builder's developers.
    3062 +--dry-run+;;
    3063 Do everything but actually run the build commands. This is useful when checking
    3064 a new configuration parses cleanly.
    3065 +--warn-all+;;
    3066 Generate warnings.
    3067 +--no-clean+;;
    3068 Do not clean up the build tree during the cleaning phase of the build. This
    3069 leaves the source and the build output on disk so you can make changes, or
    3070 amend or generate new patches. It also allows you to review configure type
    3071 output such as +config.log+.
    3072 +--always-clean+;;
    3073 Clean away the results of a build even if the build fails. This is normally
    3074 used with ``--keep-going`` when regression testing to see which build sets
    3075 fail to build. It keeps the disk usage down.
    3076 +--jobs+;;
    3077 Control the number of jobs make is given. The jobs can be 'none' for only 1
    3078 job, 'half' so the number of jobs is half the number of detected cores, a
    3079 fraction such as '0.25' so the number of jobs is a quarter of the number of
    3080 detected cores and a number such as '25' which forces the number of jobs to
    3081 that number.
    3082 +--host+;;
    3083 Set the host triplet value. Be careful with this option.
    3084 +--build+;;
    3085 Set the build triplet. Be careful with this option.
    3086 +--target+;;
    3087 Set the target triplet. Be careful with this option. This is useful if you have
    3088 a generic configuration script that can work for a range of architectures.
    3089 +--prefix path+;;
    3090 Tools build prefix, ie where they are installed.
    3091 +--topdir path+;;
    3092 Top of the build tree, that is the current directory you are in.
    3093 +--configdir path+;;
    3094 Path to the configuration directory. This overrides the built in defaults.
    3095 +--builddir path+;;
    3096 Path to the build directory. This overrides the default of +build+.
    3097 +--sourcedir path+;;
    3098 Path to the source directory. This overrides the default of +source+.
    3099 +--tmppath path+;;
    3100 Path to the temporary directory. This overrides the default of +tmp+.
    3101 +--macros files+;;
    3102 Macro files to load. The configuration directory path is searched.
    3103 +--log file+;;
    3104 Log all the output from the build process. The output is directed to +stdout+
    3105 if no log file is provided.
    3106 +--url url+;;
    3107 URL to look for source when downloading. This is can be comma separate list.
    3108 +--no-download+;;
    3109 Disable downloading of source and patches. If the source is not found an error
    3110 is raised.
    3111 +--targetcflags flags+;;
    3112 List of C flags for the target code. This allows for specific local
    3113 customisation when testing new variations.
    3114 +--targetcxxflags flags+;;
    3115 List of C++ flags for the target code. This allows for specific local
    3116 customisation when testing new variations.
    3117 +--libstdcxxflags flags+;;
    3118 List of C\++ flags to build the target libstdc++ code. This allows for specific
    3119 local customisation when testing new variations.
    3120 +--with-<label>+;;
    3121 Add the --with-<label> to the build. This can be tested for in a script with
    3122 the +%bconf_with+ macro.
    3123 +--without-<label>+;;
    3124 Add the --without-<label> to the build. This can be tested for in a script with
    3125 the +%bconf_without+ macro.
    3126 +--mail-from+;;
    3127 Set the from mail address if report mailing is enabled.
    3128 +--mail-to+;;
    3129 Set the to mail address if report mailing is enabled. The report is mailed to
    3130 this address.
    3131 +--mail+;;
    3132 Mail the build report to the mail to address.
    3133 +--smtp-host+;;
    3134 The SMTP host to use to send the email. The default is +localhost+.
    3135 +--no-report+;;
    3136 Do not create a report format.
    3137 +--report-format format+;;
    3138 The report format can be 'text' or 'html'. The default is 'html'.
    3139 +--keep-going+;;
    3140 Do not stop on error. This is useful if your build sets performs a large number
    3141 of testing related builds and there are errors.
    3142 +--always-clean+.
    3143 Always clean the build tree even with a failure.
    3144 +--no-install+;;
    3145 Do not install the packages to the prefix. Use this if you are only after the
    3146 tar files.
    3147 +--regression+;;
    3148 A convenience option which is the same as +--no-install+, +--keep-going+ and
    3149 +--bset-tar-file+;;
    3150 Create a build set tar file. This is a single tar file of all the packages in
    3151 the build set.
    3152 +--pkg-tar-files+;;
    3153 Create package tar files. A tar file will be created for each package built in
    3154 a build set.
    3155 +--list-bsets+;;
    3156 List available build sets.
    3157 +--list-configs+;;
    3158 List available configurations.
    3159 +--list-deps+;;
    3160 Print a list of dependent files used by a build set. Dependent files have a
    3161 'dep[?]' prefix where '?' is a number. The files are listed alphabetically.
    3163 Set Builder (sb-builder)
    3164 ~~~~~~~~~~~~~~~~~~~~~~~~
    3166 This command builds a configuration as described in a configuration
    3167 file. Configuration files have the extension of +.cfg+.
    3169 .. code-block:: shell
    3171     $ ./source-builder/sb-builder --help
    3172     sb-builder: [options] [args]
    3173     RTEMS Source Builder, an RTEMS Tools Project (c) 2012 Chris Johns
    3174     Options and arguments:
    3175     --force                : Force the build to proceed
    3176     --quiet                : Quiet output (not used)
    3177     --trace                : Trace the execution
    3178     --dry-run              : Do everything but actually run the build
    3179     --warn-all             : Generate warnings
    3180     --no-clean             : Do not clean up the build tree
    3181     --always-clean         : Always clean the build tree, even with an error
    3182     --jobs                 : Run with specified number of jobs, default: num CPUs.
    3183     --host                 : Set the host triplet
    3184     --build                : Set the build triplet
    3185     --target               : Set the target triplet
    3186     --prefix path          : Tools build prefix, ie where they are installed
    3187     --topdir path          : Top of the build tree, default is $PWD
    3188     --configdir path       : Path to the configuration directory, default: ./config
    3189     --builddir path        : Path to the build directory, default: ./build
    3190     --sourcedir path       : Path to the source directory, default: ./source
    3191     --tmppath path         : Path to the temp directory, default: ./tmp
    3192     --macros file[,[file]  : Macro format files to load after the defaults
    3193     --log file             : Log file where all build out is written too
    3194     --url url[,url]        : URL to look for source
    3195     --targetcflags flags   : List of C flags for the target code
    3196     --targetcxxflags flags : List of C++ flags for the target code
    3197     --libstdcxxflags flags : List of C++ flags to build the target libstdc++ code
    3198     --with-<label>         : Add the --with-<label> to the build
    3199     --without-<label>      : Add the --without-<label> to the build
    3200     --list-configs         : List available configurations
    3202 .. _Host Setups:
    3204 Host Setups
    3205 ###########
    3207 The host versions are listed. If a later version of the host operating system
    3208 exists it should work unless listed.
    3210 Please provide patches to update these sections if they are wrong or need
    3211 updating. I cannot install and test each one and rely on getting your feedback.
    3213 Linux
    3214 ~~~~~
    3216 A number of different Linux distrubutions are known to work. The following have
    3217 been tested and report as working.
    3219 .. _ArchLinux:
    3221 ArchLinux
    3222 ^^^^^^^^^
    3224 The following packages are required on a fresh Archlinux 64bit installation:
    3226 .. code-block:: shell
    3228     # pacman -S base-devel gdb xz unzip ncurses git zlib
    3230 Archlinux, by default installs ``texinfo-5`` which is incompatible for building
    3231 GCC 4.7 tree. You will have to obtain ``texinfo-legacy`` from ``AUR`` and provide
    3232 a manual override.
    3234 .. code-block:: shell
    3236     # pacman -R texinfo
    3237     $ yaourt -S texinfo-legacy
    3238     # ln -s /usr/bin/makeinfo-4.13a /usr/bin/makeinfo
    3240 .. _CentOS:
    3242 CentOS
    3243 ^^^^^^
    3245 The following packages are required on a minimal CentOS 6.3 64bit installation:
    3247 .. code-block:: shell
    3249     # yum install autoconf automake binutils gcc gcc-c++ gdb make patch \
    3250     bison flex xz unzip ncurses-devel texinfo zlib-devel python-devel git
    3252 The minimal CentOS distribution is a specific DVD that installs a minimal
    3253 system. If you use a full system some of these packages may have been
    3254 installed.
    3256 .. _Fedora:
    3258 Fedora
    3259 ^^^^^^
    3261 The RTEMS Source Builder has been tested on Fedora 19 64bit with the following packages.
    3263 .. code-block:: shell
    3265     # yum install ncurses-devel python-devel git bison gcc cvs gcc-c++ \
    3266          flex texinfo patch perl-Text-ParseWords zlib-devel
    3268 .. _Raspbian:
    3270 Raspbian
    3271 ^^^^^^^^
    3273 The is the Debian distribution for the Raspberry Pi. The following packages are
    3274 required.
    3276 .. code-block:: shell
    3278     $ sudo apt-get install autoconf automake bison flex binutils gcc g++ gdb \
    3279     texinfo unzip ncurses-dev python-dev git
    3281 It is recommended you get Model B of the Pi with 512M of memory and to mount a
    3282 remote disk over the network. The tools can be build with a prefix under your
    3283 home directory as recommended and end up on the SD card.
    3285 .. _Ubuntu:
    3286 .. _Xubuntu:
    3288 Ubuntu
    3289 ^^^^^^
    3291 The latest testing was with Ubuntu 16.04.1 LTS 64bit. This section also
    3292 includes Xubuntu. A minimal installation was used and the following
    3293 packages installed.
    3295 .. code-block:: shell
    3297     $ sudo apt-get build-dep binutils gcc g++ gdb unzip git
    3298     $ sudo apt-get install python2.7-dev
    3300 .. _Linux Mint:
    3302 Linux Mint
    3303 ^^^^^^^^^^
    3305 zlib package is required on Linux Mint. It has a different name (other
    3306 than the usual zlib-dev):
    3308 .. code-block:: shell
    3310     # sudo apt-get install zlib1g-dev
    3312 .. _openSUSE:
    3314 openSUSE
    3315 ^^^^^^^^
    3317 This has been reported to work but no instructions were provided. This is
    3318 an opportunity to contribute. Please submit any guidance you can provide.
    3320 .. _FreeBSD:
    3322 FreeBSD
    3323 ~~~~~~~
    3325 The RTEMS Source Builder has been tested on FreeBSD 9.1 and 10.0 64bit. You
    3326 need to install some ports. They are:
    3328 .. code-block:: shell
    3330     # cd /usr/ports
    3331     # portinstall --batch lang/python27
    3333 If you wish to build Windows (mingw32) tools please install the following
    3334 ports:
    3336 .. code-block:: shell
    3338     # cd /usr/ports
    3339     # portinstall --batch devel/mingw32-binutils devel/mingw32-gcc
    3340     # portinstall --batch devel/mingw32-zlib devel/mingw32-pthreads
    3342 The +zlip+ and +pthreads+ ports for MinGW32 are used for builiding a Windows
    3343 QEMU.
    3345 If you are on FreeBSD 10.0 and you have pkgng installed you can use 'pkg
    3346 install' rather than 'portinstall'.
    3348 .. _NetBSD:
    3350 NetBSD
    3351 ~~~~~~
    3353 The RTEMS Source Builder has been tested on NetBSD 6.1 i386. Packages to add
    3354 are:
    3356 .. code-block:: shell
    3358     # pkg_add
    3359     # pkg_add
    3360     # pkg_add
    3362 .. _MacOS:
    3364 MacOS
    3365 ~~~~~
    3367 The RTEMS Source Builder has been tested on Mountain Lion. You will need to
    3368 install the Xcode app using the *App Store* tool, run Xcode and install the
    3369 Developers Tools package within Xcode.
    3371 .. _Mavericks:
    3373 Mavericks
    3374 ^^^^^^^^^
    3376 The RSB works on Mavericks and the GNU tools can be built for RTEMS using the
    3377 Mavericks clang LLVM tool chain. You will need to build and install a couple of
    3378 packages to make the RSB pass the +sb-check+. These are CVS and XZ. You can get
    3379 these tools from a packaging tool for MacOS such as *MacPorts* or *HomeBrew*.
    3381 I do not use 3rd party packaging on MacOS and prefer to build the packages from
    3382 source using a prefix of '/usr/local'. There are good 3rd party packages around
    3383 however they sometimes bring in extra dependence and that complicates my build
    3384 environment and I want to know the minimal requirements when building
    3385 tools. The following are required:
    3387 . The XZ package's home page is and I use version
    3388   5.0.5. XZ builds and installs cleanly.
    3390 . CVS can be found at and I use version 1.11.23. CVS
    3391   requires the following patch
    3393   to build. Place the diff in the same directory as the unpacked cvs-1.11.23
    3394   and apply with +patch -p0 < cvs-1.11.23-osx-maverick.diff+.
    3396 .. _Windows:
    3398 Windows
    3399 ~~~~~~~
    3401 Windows tool sets are supported. The tools are native Windows executable which
    3402 means they do not need an emulation layer to run once built. The tools
    3403 understand and use standard Windows paths and integrate easily into Windows IDE
    3404 environments because they understand and use standard Windows paths. Native
    3405 Windows tools have proven over time to be stable and reliable with good
    3406 performance. If you are a Windows user or you are required to use Windows you
    3407 can still develop RTEMS application as easily as a Unix operating system. Some
    3408 debugging experiences may vary and if this is an issue please raised the topic
    3409 on the RTEMS Users mailing list.
    3411 Building the tools or some other packages may require a Unix or POSIX type
    3412 shell. There are a few options, Cygwin and MSYS2. I recommend MSYS2.
    3414 .Ready To Go Windows Tools
    3415 NOTE: From time to time I provide tools for Windows at
    3418 .. _MSYS2:
    3420 MSYS2
    3422 This is a new version of the old MinGW project's original MSYS based around the
    3423 Arch Linux pacman packager. MSYS and MSYS2 are a specific fork of the Cygwin
    3424 project with some fundamental changes in the handling of paths and mounts that
    3425 allow easy interaction between the emulated POSIX environment and the native
    3426 Windows environment.
    3428 Install MSYS2 using the installer you can download from
    3429 Follow the instructions on the install page and make
    3430 sure you remove any global path entries to any other Cygwin, MinGW, MSYS or
    3431 packages that may uses a Cygwin DLL, for example some ports of Git.
    3433 To build the tools you need install the following packages using pacman:
    3435 .. code-block:: shell
    3437  $ pacman -S git cvs bison make texinfo patch unzip diffutils tar \
    3438           mingw64/mingw-w64-x86_64-gcc mingw64/mingw-w64-x86_64-binutils
    3440 To build make sure you add '--without-python --jobs=none' to the standard RSB
    3441 command line. MSYS2 has a temp file name issue and so the GNU AR steps on
    3442 itself when running in parallel on SMP hardware which means we have to set the
    3443 jobs option to none.
    3445 Install a suitable version of Python from and add it to
    3446 the start of your path. The MSYS2 python does not work with waf.
    3448 .. _Cygwin:
    3450 Cygwin
    3452 Building on Windows is a little more complicated because the Cygwin shell is
    3453 used rather than the MSYS2 shell. The MSYS2 shell is simpler because the
    3454 detected host triple is MinGW so the build is standard cross-compiler build.
    3455 A Canadian cross-build using Cygwin is supported if you would like native tools.
    3457 Install a recent Cygwin version using the Cygwin setup tool. Select and install
    3458 the groups and packages listed:
    3460 .Cygwin Packages
    3461 [options="header,compact",width="50%",cols="20%,80%"]
    3462 |================================
    3463 |Group   |Package
    3464 |Archive |bsdtar
    3465 |        |unzip
    3466 |        |xz
    3467 |Devel   |autoconf
    3468 |        |autoconf2.1
    3469 |        |autoconf2.5
    3470 |        |automake
    3471 |        |binutils
    3472 |        |bison
    3473 |        |flex
    3474 |        |gcc4-core
    3475 |        |gcc4-g++
    3476 |        |git
    3477 |        |make
    3478 |        |mingw64-x86_64-binutils
    3479 |        |mingw64-x86_64-gcc-core
    3480 |        |mingw64-x86_64-g++
    3481 |        |mingw64-x86_64-runtime
    3482 |        |mingw64-x86_64-zlib
    3483 |        |patch
    3484 |        |zlib-devel
    3485 |MinGW   |mingw-zlib-devel
    3486 |Python  |python
    3487 |================================
    3489 The setup tool will add a number of dependent package and it is ok to accept
    3490 them.
    3492 I have found turning off Windows Defender improves performance if you have
    3493 another up to date virus detection tool installed and enabled. I used the
    3494 excellent ``Process Hacker 2`` tool to monitor the performance and I found the
    3495 Windows Defender service contributed a high load. In my case I had a 3rd party
    3496 virus tool installed so the Windows Defender service was not needed.
    3498 A Canadian cross-compile (Cxc) is required on Cygwin because the host is Cygwin
    3499 therefore a traditional cross-compile will result in Cygiwn binaries. With a
    3500 Canadian cross-compile a Cygwin cross-compiler is built as well as the MinGW
    3501 RTEMS cross-compiler. The Cygwin cross-compiler is required to build the C
    3502 runtime for the RTEMS target because we are building under Cygiwn. The build
    3503 output for an RTEMS 4.10 ARM tool set is:
    3505 .. code-block:: shell
    3507     chris@cygthing ~/development/rtems/src/rtems-source-builder/rtems
    3508     $ ../source-builder/sb-set-builder --log=l-arm.txt --prefix=$HOME/development/rtems/4.10 4.10/rtems-arm
    3509     RTEMS Source Builder - Set Builder, v0.2
    3510     Build Set: 4.10/rtems-arm
    3511     config: expat-2.1.0-1.cfg
    3512     package: expat-2.1.0-x86_64-w64-mingw32-1
    3513     building: expat-2.1.0-x86_64-w64-mingw32-1
    3514     reporting: expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-w64-mingw32-1.html
    3515     config: tools/rtems-binutils-2.20.1-1.cfg
    3516     package: arm-rtems4.10-binutils-2.20.1-1 <1>
    3517     building: arm-rtems4.10-binutils-2.20.1-1
    3518     package: (Cxc) arm-rtems4.10-binutils-2.20.1-1 <2>
    3519     building: (Cxc) arm-rtems4.10-binutils-2.20.1-1
    3520     reporting: tools/rtems-binutils-2.20.1-1.cfg ->
    3521     arm-rtems4.10-binutils-2.20.1-1.html
    3522     config: tools/rtems-gcc-4.4.7-newlib-1.18.0-1.cfg
    3523     package: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
    3524     building: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
    3525     package: (Cxc) arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
    3526     building: (Cxc) arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
    3527     reporting: tools/rtems-gcc-4.4.7-newlib-1.18.0-1.cfg ->
    3528     arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1.html
    3529     config: tools/rtems-gdb-7.3.1-1.cfg
    3530     package: arm-rtems4.10-gdb-7.3.1-1
    3531     building: arm-rtems4.10-gdb-7.3.1-1
    3532     reporting: tools/rtems-gdb-7.3.1-1.cfg -> arm-rtems4.10-gdb-7.3.1-1.html
    3533     config: tools/rtems-kernel-4.10.2.cfg
    3534     package: arm-rtems4.10-kernel-4.10.2-1
    3535     building: arm-rtems4.10-kernel-4.10.2-1
    3536     reporting: tools/rtems-kernel-4.10.2.cfg -> arm-rtems4.10-kernel-4.10.2-1.html
    3537     installing: expat-2.1.0-x86_64-w64-mingw32-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
    3538     installing: arm-rtems4.10-binutils-2.20.1-1 -> /cygdrive/c/Users/chris/development/rtems/4.10 <3>
    3539     installing: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
    3540     installing: arm-rtems4.10-gdb-7.3.1-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
    3541     installing: arm-rtems4.10-kernel-4.10.2-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
    3542     cleaning: expat-2.1.0-x86_64-w64-mingw32-1
    3543     cleaning: arm-rtems4.10-binutils-2.20.1-1
    3544     cleaning: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
    3545     cleaning: arm-rtems4.10-gdb-7.3.1-1
    3546     cleaning: arm-rtems4.10-kernel-4.10.2-1
    3547     Build Set: Time 10:09:42.810547 <4>
    3549 - *<1>* The Cygwin version of the ARM cross-binutils.
    3550 - *<2>* The +(Cxc)+ indicates this is the MinGW build of the package.
    3551 - *<3>* Only the MinGW version is installed.
    3552 - *<4>* Cygwin is slow so please be patient. This time was on an AMD
    3553   Athlon 64bit Dual Core 6000+ running at 3GHz with 4G RAM running Windows
    3554   7 64bit.
    3556 CAUTION: Cygwin documents the 'Big List Of Dodgy Apps' or 'BLODA'. The link is
    3557 and it is worth a
    3558 look. You will see a large number of common pieces of software found on Windows
    3559 systems that can cause problems. My testing has been performed with NOD32
    3560 running and I have seen some failures. The list is for all of Cygwin so I am
    3561 not sure which of the listed programs effect the RTEMS Source Biulder. The
    3562 following FAQ item talks about +fork+ failures and presents some technical
    3563 reasons they cannot be avoided in all cases. Cygwin and it's fork MSYS are
    3564 fantastic pieces of software in a difficult environment. I have found building
    3565 a single tool tends to work, building all at once is harder.
    3568 History
    3569 #######
    3571 The RTEMS Source Builder is a stand alone tool based on another tool called the
    3572 'SpecBuilder'. The SpecBuilder was written for the RTEMS project to give me a
    3573 way to build tools on hosts that did not support RPMs. At the time the RTEMS
    3574 tools maintainer only used spec files to create various packages. This meant I
    3575 had either spec files, RPM files or SRPM files. The RPM and SPRM files where
    3576 useless because you needed an 'rpm' type tool to extract and manage them. There
    3577 are versions of 'rpm' for a number of non-RPM hosts however these proved to be
    3578 in various broken states and randomly maintained. The solution I settled on was
    3579 to use spec files so I wrote a Python based tool that parsed the spec file
    3580 format and allowed me to create a shell script I could run to build the
    3581 package. This approach proved successful and I was able to track the RPM
    3582 version of the RTEMS tools on a non-RPM host over a number of years. however
    3583 the SpecBuilder tool did not help me build tools or other packages not related
    3584 to the RTEMS project where there was no spec file I could use so I needed
    3585 another tool. Rather than start again I decided to take the parsing code for
    3586 the spec file format and build a new tool called the RTEMS Source Builder.
     153The *SpecBuilder* tool did not build tools or packages unrelated to the RTEMS
     154project where no suitable *spec* file was available so another tool was
     155needed. Rather than start again Chris decided to take the parsing code for the
     156*spec* file format and build a new tool called the RTEMS Source Builder.
Note: See TracChangeset for help on using the changeset viewer.