Changeset 8b64335 in rtems-docs


Ignore:
Timestamp:
Nov 2, 2016, 1:09:54 AM (4 years ago)
Author:
Chris Johns <chrisj@…>
Branches:
4.11, 5, am, master
Children:
005f0e8
Parents:
75e787d
Message:

RSB: Finish reformatting after moving from asciidocs.

Location:
rsb
Files:
9 added
2 edited

Legend:

Unmodified
Added
Removed
  • rsb/index.rst

    r75e787d r8b64335  
    3737
    3838        source-builder
     39        quick-start
     40        hosts
     41        project-sets
     42        cross-canadian-cross
     43        third-party-packages
     44        configuration
     45        commands
     46        bug-reporting
    3947
    4048*       :ref:`genindex`
  • rsb/source-builder.rst

    r75e787d r8b64335  
    44.. comment Chris Johns <chrisj@rtems.org>
    55
    6 RTEMS Tools From Source
    7 #######################
     6RTEMS Source Builder
     7####################
    88
    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.
    1815
    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.
    2620
    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.
    2828
    29 - :ref:`ArchLinux`
     29The RTEMS Source Builder has been tested on:
    3030
    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
    3242
    33 - :ref:`Fedora`
     43.. topic:: Setting up your Host
    3444
    35 - :ref:`Raspbian`
    36 
    37 - :ref:`Ubuntu` (includes XUbuntu)
    38 
    39 - :ref:`Linux Mint`
    40 
    41 - :ref:`openSUSE`
    42 
    43 - :ref:`FreeBSD`
    44 
    45 - :ref:`NetBSD`
    46 
    47 - :ref:`MacOS`
    48 
    49 - :ref:`Windows`
     45   :ref:`Hosts` details setting up hosts.
    5046
    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.
    6157
     
    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`.
    6965
    7066.. comment: TBD: The section "Installing and Tar Files" does not exist.
     
    7773configuration can read the remaining sections.
    7874
    79 .. sidebar: Bug Reporting:
    80   IMPORTANT: If you have a problem please see <<_bugs,the reporting bugs>>
    81   section.
     75.. topic:: Bug Reporting
    8276
    83 Quick Start
    84 ###########
    85 
    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.
    92 
    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.
    98 
    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.
    103 
    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.
    107 
    108 .. comment   Host Setup
    109 
    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.
    114 
    115 .. comment .Path to use when building applications
    116 
    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.
    119 
    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:
    127 
    128 .. code-block:: shell
    129 
    130     $ export PATH=$HOME/development/rtems/4.11/bin:$PATH
    131 
    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.
    136 
    137 .. note::
    138 
    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:
    142 
    143     ``$ git checkout -t origin/4.11``
    144 
    145     Branches are available for the 4.9, 4.10, and 4.11 versions of RTEMS.
    146 
    147 Setup
    148 ~~~~~
    149 
    150 Setup a development work space:
    151 
    152 .. code-block:: shell
    153 
    154     $ cd
    155     $ mkdir -p development/rtems/src
    156     $ cd development/rtems/src
    157 
    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:
    161 
    162 .. code-block:: shell
    163 
    164     $ git clone git://git.rtems.org/rtems-source-builder.git
    165     $ cd rtems-source-builder
    166 
    167 Checking
    168 ~~~~~~~~
    169 
    170 The next step is to check if your host is set up correctly. The RTEMS Source
    171 Builder provides a tool to help:
    172 
    173 .. code-block:: shell
    174 
    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>
    182 
    183 
    184 - *<1>* A tool is in the environment path but does not match the
    185   expected path.
    186 
    187 - *<2>* The executable 'xz' is not found.
    188 
    189 - *<3>* The host's environment is set up correct.
    190 
    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.
    198 
    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.
    202 
    203 Build Sets
    204 ~~~~~~~~~~
    205 
    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:
    209 
    210 .. code-block:: shell
    211 
    212     $ cd rtems
    213 
    214 If you are unsure how to specify the build set for the architecture you wish to
    215 build ask the tool:
    216 
    217 .. code-block:: shell
    218 
    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
    290 
    291 - *<1>* Only option needed is ``--list-bsets``
    292 
    293 - *<2>* The paths inspected. See <<X1,``_configdir``>> variable.
    294 
    295 - *<3>* Build all RTEMS 4.10 supported architectures.
    296 
    297 - *<4>* The build set for the ARM architecture on RTEMS 4.10.
    298 
    299 - *<5>* Support build set file with common functionality included by
    300   other build set files.
    301 
    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.
    307 
    308 Building
    309 ~~~~~~~~
    310 
    311 In this quick start I will build a SPARC tool set.
    312 
    313 .. code-block:: shell
    314 
    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>
    340 
    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.
    343 
    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.
    348 
    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.
    353 
    354 - *<4>* The SPARC build set first builds the expat library as it is used in GDB.
    355   This is the expat configuration used.
    356 
    357 - *<5>* The binutils build configuration.
    358 
    359 - *<6>* The GCC and Newlib build configuration.
    360 
    361 - *<7>* The GDB build configuration.
    362 
    363 - *<8>* Installing the built packages to the install prefix.
    364 
    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.
    368 
    369 - *<10>* The time to build the package. This lets you see how different
    370   host hardware or configurations perform.
    371 
    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.
    377 
    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.
    381 
    382 The installed tools:
    383 
    384 .. code-block:: shell
    385 
    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)
    429 
    430 - *<1>* The target the compiler is built for.
    431 
    432 - *<2>* The configure options used to build GCC.
    433 
    434 - *<3>* The threading model is always RTEMS. This makes the RTEMS tools
    435   difficult for bare metal development more difficult.
    436 
    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.
    441 
    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.
    448 
    449 Distributing and Archiving A Build
    450 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    451 
    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.
    455 
    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.
    461 
    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:
    475 
    476 .. code-block:: shell
    477 
    478     $ cd
    479     $ tar --strip-components=3 -xjf rtems-4.11-sparc-rtems4.11-1.tar.bz2
    480 
    481 
    482 A build set tar file is created by adding ``--bset-tar-file`` option to the
    483 ``sb-set-builder`` command.
    484 
    485 .. code-block:: shell
    486 
    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
    514 
    515 
    516 - *<1>* The option to create a build set tar file.
    517 
    518 - *<2>* The installation still happens unless you specify ``--no-install``.
    519 
    520 - *<3>* Creating the build set tar file.
    521 
    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.
    525 
    526 .. code-block:: shell
    527 
    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
    553 
    554 - *<1>* The option to supressing installing the packages.
    555 
    556 - *<2>* Create the build set tar.
    557 
    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.
    561 
    562 .. code-block:: shell
    563 
    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
    591 
    592 - *<1>* The option to create packages tar files.
    593 
    594 - *<2>* The GDB package tar file.
    595 
    596 - *<3>* The build set tar file. All the others in a single tar file.
    597 
    598 Controlling the Build
    599 ~~~~~~~~~~~~~~~~~~~~~
    600 
    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``.
    606 
    607 Following are currentlt available:
    608 
    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`.
    61379
    61480Why Build from Source?
    615 ######################
     81~~~~~~~~~~~~~~~~~~~~~~
    61682
    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.
    62794
    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
    656123easier.
     
    667134computing environment.
    668135
    669 .. comment [[_bugs]]
    670 
    671 Bugs, Crashes, and Build Failures
    672 #################################
    673 
    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
    678 https://www.rtems.org/bugzilla/.
    679 
    680 Please include the generated RSB report. If you see the following a report has
    681 been generated:
    682 
    683 .. code-block:: shell
    684 
    685      ...
    686      ...
    687     Build FAILED <1>
    688       See error report: rsb-report-4.11-rtems-lm32.txt <2>
    689 
    690 - *<1>* The build has failed.
    691 
    692 - *<2>* The report's file name.
    693 
    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.
    696 
    697 If for some reason there is no report please send please report the following:
    698 
    699 - Command line,
    700 
    701 - The git hash,
    702 
    703 - Host details with the output of the ``uname -a`` command,
    704 
    705 - If you have made any modifications.
    706 
    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.
    713 
    714 .. comment [[_contributing]]
    715 
    716 Contributing
    717 ############
    718 
    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.
    723 
    724 Please email me patches via git so I can maintain your commit messages so you
    725 are acknowledged as the contributor.
    726 
    727 Most of what follows is related to the development of RSB and it's
    728 configurations.
    729 
    730 Project Sets
    731 ############
    732 
    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.
    737 
    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.
    748 
    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``.
    753 
    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
    758 
    759 Bare Metal
    760 ~~~~~~~~~~
    761 
    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.
    767 
    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'.
    773 
    774 .. code-block:: shell
    775 
    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
    801 
    802 RTEMS
    803 ~~~~~
    804 
    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.
    810 
    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.
    820 
    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``.
    826 
    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.
    831 
    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:
    838 
    839 .. code-block:: shell
    840 
    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
    846 
    847 - *<1>* Setting the path.
    848 
    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.
    853 
    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:
    858 
    859 .. code-block:: shell
    860 
    861     $ ../source-builder/sb-set-builder --log=l-4.11-sparc.txt \
    862        --prefix=$HOME/development/rtems/4.11 \
    863        --macros=snapshots/newlib-head.mc \
    864        4.11/rtems-sparc
    865 
    866 and the following uses the version control heads for *binutils*, *gcc*,
    867 *newlib*, *gdb* and *RTEMS*:
    868 
    869 .. code-block:: shell
    870 
    871     $ ../source-builder/sb-set-builder --log=l-heads-sparc.txt \
    872        --prefix=$HOME/development/rtems/4.11-head \
    873        --macros=snapshots/binutils-gcc-newlib-gdb-head.mc \
    874        4.11/rtems-sparc
    875 
    876 Patches
     136History
    877137~~~~~~~
    878138
    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.
    887152
    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.
    892 
    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.
    901 
    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.
    905 
    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.
    911 
    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.
    914 
    915 Patches can be declared in build set up files.
    916 
    917 This examples shows how to declare a patch for gdb in the ``lm32`` architecture:
    918 
    919 .. code-block:: shell
    920 
    921     %patch add <1> gdb <2> %{rtems_gdb_patches}/lm32/gdb-sim-lm32uart.diff <3>
    922 
    923 - *<1>* The patch's ``add`` command.
    924 
    925 - *<2>* The group of patches this patch belongs too.
    926 
    927 - *<3>* The patch's URL. It is downloaded from here.
    928 
    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:
    931 
    932 .. code-block:: shell
    933 
    934     %hash md5 <1> gdb-sim-lm32uart.diff <2> 77d070878112783292461bd6e7db17fb <3>
    935 
    936 - *<1>* The type of checksum, in the case an MD5 hash.
    937 
    938 - *<2>* The patch file the checksum is for.
    939 
    940 - *<3>* The MD5 hash.
    941 
    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:
    945 
    946 .. code-block:: shell
    947 
    948     %patch setup <1> gdb <2> -p1 <3>
    949 
    950 - *<1>* The patch's ``setup`` command.
    951 
    952 - *<2>* The group of patches to apply.
    953 
    954 - *<3>* The patch group's default options. If no option is given with
    955   the patch these options are used.
    956 
    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.
    961 
    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:
    968 
    969 .. code-block:: shell
    970 
    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>
    973 
    974 - *<1>* The diff file prepended with ``file://`` to tell RSB this is a
    975   local file.
    976 
    977 - *<2>* The output from md5sum on the diff file.
    978 
    979 Cross and Canadian Cross Building
    980 #################################
    981 
    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.
    986 
    987 This sections details how to the RSB to cross and Canadian cross build.
    988 
    989 Cross Building
    990 ~~~~~~~~~~~~~~
    991 
    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.
    996 
    997 To build the NTP package for RTEMS you enter the RSB command:
    998 
    999 .. code-block:: shell
    1000 
    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
    1007 
    1008 - *<1>* The tools and the RTEMS BSP are installed under the same prefix.
    1009 
    1010 - *<2>* The ``--host`` command is the RTEMS architecture and version.
    1011 
    1012 - *<3>* The BSP is built and installed in the prefix. The arhcitecture must
    1013   match the ``--host`` architecture.
    1014 
    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.
    1019 
    1020 Canadian Cross Building
    1021 ~~~~~~~~~~~~~~~~~~~~~~~
    1022 
    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:
    1029 
    1030 - Build host C and C++ compiler
    1031 
    1032 - Host C and C++ cross compiler
    1033 
    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.
    1038 
    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.
    1042 
    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.
    1046 
    1047 TIP: Make sure the host's cross-compiler tools are in your path before run the
    1048 RSB build command.
    1049 
    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.
    1054 
    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``:
    1058 
    1059 .. code-block:: shell
    1060 
    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
    1065 
    1066 If you are on a Linux Fedora build host with the MinGW packages installed the
    1067 command line is:
    1068 
    1069 .. code-block:: shell
    1070 
    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
    1075 
    1076 RTEMS 3rd Party Packages
    1077 ########################
    1078 
    1079 This section describes how to build and add an RTEMS 3rd party package to the
    1080 RSB.
    1081 
    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).
    1087 
    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.
    1093 
    1094 Building
    1095 ~~~~~~~~
    1096 
    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.
    1101 
    1102 To build Net-SNMP the command is:
    1103 
    1104 .. code-block:: shell
    1105 
    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-5.7.2.1-1.cfg
    1114     package: net-snmp-5.7.2.1-sparc-rtems4.11-1
    1115     building: net-snmp-5.7.2.1-sparc-rtems4.11-1
    1116     installing: net-snmp-5.7.2.1-sparc-rtems4.11-1 -> /Users/chris/development/rtems/bsps/4.11
    1117     cleaning: net-snmp-5.7.2.1-sparc-rtems4.11-1
    1118     Build Set: Time 0:01:10.651926
    1119 
    1120 Adding
    1121 ~~~~~~
    1122 
    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.
    1132 
    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.
    1146 
    1147 A package requires 3 files to be created:
    1148 
    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.
    1157 
    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.
    1168 
    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.
    1179 
    1180 BSP Support
    1181 ~~~~~~~~~~~
    1182 
    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.
    1190 
    1191 .. comment [TIP]
    1192 
    1193 .. note::
    1194 
    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.
    1200 
    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-5.7.2.1-1.cfg``):
    1205 
    1206 .. code-block:: shell
    1207 
    1208     #
    1209     # NetSNMP 5.7.2.1
    1210     #
    1211 
    1212     %if %{release} == %{nil}
    1213      %define release 1 <1>
    1214     %endif
    1215 
    1216     %include %{_configdir}/rtems-bsp.cfg <2>
    1217 
    1218     #
    1219     # NetSNMP Version
    1220     #
    1221     %define net_snmp_version 5.7.2.1 <3>
    1222 
    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
    1227 
    1228     #
    1229     # Patch for RTEMS support.
    1230     #
    1231     %patch add net-snmp %{rtems_git_tools}/net-snmp/rtems-net-snmp-5.7.2.1-20140623.patch <5>
    1232 
    1233     #
    1234     # NetSNMP Build configuration
    1235     #
    1236     %include %{_configdir}/net-snmp-5-1.cfg <6>
    1237 
    1238 - *<1>* The release number.
    1239 
    1240 - *<2>* Include the RSB RTEMS BSP support.
    1241 
    1242 - *<3>* The Net-SNMP package's version.
    1243 
    1244 - *<4>* Add specific CFLAGS to the build process. See the
    1245   ``net-snmp-5.7.2.1-1.cfg`` for details.
    1246 
    1247 - *<5>* The RTEMS Net-SNMP patch downloaded from the RTEMS Tools git repo.
    1248 
    1249 - *<6>* The Net-SNMP standard build configuration.
    1250 
    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.
    1255 
    1256 .rtems/config/rtems-bsp.cfg
    1257 
    1258 .. code-block:: shell
    1259 
    1260     %if %{_host} == %{nil} <1>
    1261      %error No RTEMS target specified: --host=host
    1262     %endif
    1263 
    1264     %ifn %{defined with_rtems_bsp} <2>
    1265      %error No RTEMS BSP specified: --with-rtems-bsp=bsp
    1266     %endif
    1267 
    1268     %ifn %{defined with_tools} <3>
    1269      %define with_tools %{_prefix}
    1270     %endif
    1271 
    1272     #
    1273     # Set the path to the tools.
    1274     #
    1275     %{path prepend %{with_tools}/bin} <4>
    1276 
    1277 - *<1>* Check the host has been set.
    1278 
    1279 - *<2>* Check a BSP has been specified.
    1280 
    1281 - *<3>* If no tools path has been provided assume they are under the
    1282   %{\_prefix}.
    1283 
    1284 - *<4>* Add the tools ``bin`` path to the system path.
    1285 
    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:
    1290 
    1291 .rtems/config/rtems-bsp.cfg
    1292 .. code-block:: shell
    1293 
    1294     %{pkgconfig prefix %{_prefix}/lib/pkgconfig} <1>
    1295     %{pkgconfig crosscompile yes} <2>
    1296     %{pkgconfig filter-flags yes} <3>
    1297 
    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}}
    1306 
    1307 - *<1>* Set the path to the BSP's pkgconfig file.
    1308 
    1309 - *<2>* Let pkgconfig know this is a cross-compile build.
    1310 
    1311 - *<3>* Filter flags such as warnings. Warning flags are specific to a package.
    1312 
    1313 - *<4>* Ask pkgconfig for the various items we require.
    1314 
    1315 
    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:
    1320 
    1321 .rtems/config/rtems-bsp.cfg
    1322 .. code-block:: shell
    1323 
    1324     %define host_cflags  %{rtems_bsp_cflags}
    1325     %define host_ldflags %{rtems_bsp_ldflags}
    1326     %define host_libs    %{rtems_bsp_libs}
    1327 
    1328 
    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:
    1335 
    1336 .rtems/config/rtems-bsp.cfg
    1337 .. code-block:: shell
    1338 
    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
    1358 
    1359 - *<1>* The path to the BSP.
    1360 
    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:
    1363 
    1364 .source-builder/config/ntp-4-1.cfg
    1365 .. code-block:: shell
    1366 
    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
    1380 
    1381 - *<1>* The configure command for NTP.
    1382 
    1383 RTEMS BSP Configuration
    1384 ~~~~~~~~~~~~~~~~~~~~~~~
    1385 
    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.
    1389 
    1390 
    1391 .. comment [[H1]]
    1392 
    1393 .. _Configuration:
    1394 
    1395 Configuration
    1396 #############
    1397 
    1398 The RTEMS Source Builder has two types of configuration data:
    1399 
    1400 - Build Sets
    1401 
    1402 - Package Build Configurations
    1403 
    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.
    1413 
    1414 [[X1]] The configuration search path is a macro variable and is reference as
    1415 ``%\{_configdir\}``. It's default is defined as:
    1416 
    1417 .. code-block:: shell
    1418 
    1419     _configdir   : dir  optional<2>  %{_topdir}/config:%{_sbdir}/config <1>
    1420 
    1421 - *<1>* The ``_topdir`` is the directory you run the command from and
    1422   ``_sbdir`` is the location of the RTEMS Source Builder command.
    1423 
    1424 - *<2>* A macro definition in a macro file has 4 fields, the label, type,
    1425   constraint and the definition.
    1426 
    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.
    1431 
    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.
    1435 
    1436 Source and Patches
    1437 ~~~~~~~~~~~~~~~~~~
    1438 
    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
    1444 
    1445 The URL can reference remote and local source and patch resources. The
    1446 following schemes are provided:
    1447 
    1448 - ``http``: Remote access using the HTTP protocol.
    1449 
    1450 - ``https``: Remote access using the Secure HTTP protocol.
    1451 
    1452 - ``ftp``: Remote access using the FTP protocol.
    1453 
    1454 - ``git``: Remote access to a GIT repository.
    1455 
    1456 - ``cvs``: Remote access to a CVS repository.
    1457 
    1458 - ``pm``: Remote access to a patch management repository.
    1459 
    1460 - ``file``: Local access to an existing source directory.
    1461 
    1462 HTTP, HTTPS, and FTP
    1463 ^^^^^^^^^^^^^^^^^^^^
    1464 
    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.
    1472 
    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:
    1475 
    1476 .. code-block:: shell
    1477 
    1478     %source set<1> gcc<2> ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
    1479 
    1480 - *<1>* The ``%source`` command's set command sets the source. The first
    1481   is set and following sets are ignored.
    1482 
    1483 - *<2>* The source is part of the ``gcc`` group.
    1484 
    1485 The type of compression is automatically detected from the file extension. The
    1486 supported compression formats are:
    1487 
    1488 - ``gz``: GNU ZIP
    1489 
    1490 - ``bzip2``: BZIP2
    1491 
    1492 - ``zip``: ZIP
    1493 
    1494 - ``xy``: XY
    1495 
    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.
    1499 
    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.
    1509 
    1510 If the source URL references the GitHub API server 'https://api.github.com/' a
    1511 tarball of the specified version is download. For example the URL for the
    1512 STLINK project on GitHub and version is:
    1513 
    1514 .. code-block:: shell
    1515 
    1516     %define stlink_version 3494c11
    1517     %source set stlink https://api.github.com/repos/texane/stlink/texane-stlink-%{stlink_version}.tar.gz
    1518 
    1519 
    1520 GIT
    1521 ^^^
    1522 
    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:
    1531 
    1532 - ``protocol``: Use a specific protocol. The supported values are *ssh*,
    1533   *git*, *http*, *https*, *ftp*, *ftps*, *rsync*, and *none*.
    1534 
    1535 - ``branch``: Checkout the specified branch.
    1536 
    1537 - ``pull``: Perform a pull to update the repository.
    1538 
    1539 - ``fetch``: Perform a fetch to get any remote updates.
    1540 
    1541 - ``reset``: Reset the repository. Useful to remove any local
    1542   changes. You can pass the ``hard`` argument to force a hard reset.
    1543 
    1544 .. code-block:: shell
    1545 
    1546     %source set gcc git://gcc.gnu.org/git/gcc.git?branch=gcc-4_7-branch?reset=hard
    1547 
    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.
    1552 
    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.
    1556 
    1557 CVS
    1558 ^^^
    1559 
    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:
    1566 
    1567 - ``module``: The module to checkout.
    1568 
    1569 - ``src-prefix``: The path into the source where the module starts.
    1570 
    1571 - ``tag``: The CVS tag to checkout.
    1572 
    1573 - ``date``: The CVS date to checkout.
    1574 
    1575 The following is an example of checking out from a CVS repository:
    1576 
    1577 .. code-block:: shell
    1578 
    1579     %source set newlib cvs://pserver:anoncvs@sourceware.org/cvs/src?module=newlib?src-prefix=src
    1580 
    1581 Macros and Defaults
    1582 ~~~~~~~~~~~~~~~~~~~
    1583 
    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 ``defaults.mc`` and modified to suite your host. This
    1587 host specific adaption lets the Source Builder handle differences in the build
    1588 hosts.
    1589 
    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:
    1593 
    1594 .. code-block:: shell
    1595 
    1596     %define release 1
    1597 
    1598 Once defined if can be accessed in a build set or package configuration file
    1599 with:
    1600 
    1601 .. code-block:: shell
    1602 
    1603     %{release}
    1604 
    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.
    1607 
    1608 .. code-block:: shell
    1609 
    1610     $ ../source-builder/sb-defaults
    1611 
    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.
    1617 
    1618 Macro Maps and Files
    1619 ^^^^^^^^^^^^^^^^^^^^
    1620 
    1621 Macros are read in from files when the tool starts. The default settings are
    1622 read from the defaults macro file called ``defaults.mc`` 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.
    1625 
    1626 The format for a macro in macro files is:
    1627 
    1628 ==== ==== ========= ======
    1629 Name Type Attribute String
    1630 ==== ==== ========= ======
    1631 
    1632 where 'Name' is a case insensitive macro name, the 'Type' field is:
    1633 
    1634 - ``none``: Nothing, ignore.
    1635 
    1636 - ``dir``: A directory path.
    1637 
    1638 - ``exe``: An executable path.
    1639 
    1640 - ``triplet``: A GNU style architecture, platform, operating system string.
    1641 
    1642 the 'Attribute' field is:
    1643 
    1644 - ``none``:: Nothing, ignore
    1645 
    1646 - ``required``:: The host check must find the executable or path.
    1647 
    1648 - ``optional``:: The host check generates a warning if not found.
    1649 
    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.
    1653 
    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.
    1657 
    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.
    1661 
    1662 Maps are declared anywhere in the map using the map directive:
    1663 
    1664 .. code-block:: shell
    1665 
    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'''
    1672 
    1673 - *<1>* The map is set to ``my-special-map``.
    1674 
    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.
    1678 
    1679 .. code-block:: shell
    1680 
    1681     %select my-special-map
    1682 
    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.
    1687 
    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.
    1691 
    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:
    1695 
    1696 .. code-block:: shell
    1697 
    1698     # <1>
    1699     # Build all tool parts from version control head.
    1700     #
    1701     %include %{_configdir}/snapshots/binutils-head.mc
    1702     %include %{_configdir}/snapshots/gcc-head.mc
    1703     %include %{_configdir}/snapshots/newlib-head.mc
    1704     %include %{_configdir}/snapshots/gdb-head.mc
    1705 
    1706 - *<1>* The file is ``config/snapshots/binutils-gcc-newlib-gdb-head.mc``.
    1707 
    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.
    1710 
    1711 Personal Macros
    1712 ^^^^^^^^^^^^^^^
    1713 
    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.
    1721 
    1722 Report Mailing
    1723 ~~~~~~~~~~~~~~
    1724 
    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:
    1727 
    1728 - To mail address
    1729 
    1730 - From mail address
    1731 
    1732 - SMTP host
    1733 
    1734 .. _To Mail Address:
    1735 
    1736 The ``to`` mail address is taken from the macro ``%{_mail_tools_to}`` and the
    1737 default is *rtems-tooltestresults at rtems.org*. You can override the default
    1738 with a personal or user macro file or via the command line option *--mail-to*.
    1739 
    1740 .. _From Mail Address:
    1741 
    1742 The ``from`` mail address is taken from:
    1743 
    1744 - GIT configuration
    1745 
    1746 - User ``.mailrc`` file
    1747 
    1748 - Command line
    1749 
    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:
    1754 
    1755   set from="Foo Bar <foo@bar>"
    1756 
    1757 You can also support a from address on the command line with the *--mail-from*
    1758 option.
    1759 
    1760 .SMTP Host
    1761 
    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*.
    1765 
    1766 Build Set Files
    1767 ~~~~~~~~~~~~~~~
    1768 
    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.
    1773 
    1774 Defining macros is performed with the ``%define`` macro:
    1775 
    1776 .. code-block:: shell
    1777 
    1778     %define _target m32r-rtems4.11
    1779 
    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.
    1783 
    1784 .. code-block:: shell
    1785 
    1786     %include rtems-4.11-base.bset
    1787 
    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.
    1790 
    1791 You reference build set or package configuration files by placing the file name
    1792 on a single line.
    1793 
    1794 .. code-block:: shell
    1795 
    1796     tools/rtems-binutils-2.22-1
    1797 
    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.
    1804 
    1805 Configuration Control
    1806 ~~~~~~~~~~~~~~~~~~~~~
    1807 
    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.
    1813 
    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:
    1823 
    1824 .. code-block:: shell
    1825 
    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
    1831 
    1832 The package build options, if there are any are also defined:
    1833 
    1834 .. code-block:: shell
    1835 
    1836     %define with_threads 1
    1837     %define with_plugin  0
    1838     %define with_iconv   1
    1839 
    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:
    1843 
    1844 .. code-block:: shell
    1845 
    1846     Patch0: gcc-4.7.2-rtems4.11-20121026.diff
    1847 
    1848 Finally including the GCC 4.7 configuration script:
    1849 
    1850 .. code-block:: shell
    1851 
    1852     %include %{_configdir}/gcc-4.7-1.cfg
    1853 
    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.
    1857 
    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.
    1863 
    1864 Personal Configurations
    1865 ~~~~~~~~~~~~~~~~~~~~~~~
    1866 
    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.
    1871 
    1872 To create a private configuration change to a suitable directory:
    1873 
    1874 .. code-block:: shell
    1875 
    1876     $ cd ~/work
    1877     $ mkdir test
    1878     $ cd test
    1879     $ mkdir config
    1880 
    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.
    1884 
    1885 New Configurations
    1886 ~~~~~~~~~~~~~~~~~~
    1887 
    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 http://www.jdl.com/software. 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.
    1897 
    1898 Layering by Including
    1899 ^^^^^^^^^^^^^^^^^^^^^
    1900 
    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.
    1908 
    1909 Configuration File Numbering
    1910 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    1911 
    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.
    1923 
    1924 Common Configuration Scripts
    1925 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    1926 
    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.
    1934 
    1935 DTC Example
    1936 ^^^^^^^^^^^
    1937 
    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.
    1944 
    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.
    1949 
    1950 .. code-block:: shell
    1951 
    1952     #
    1953     # DTC 1.x.x Version 1.
    1954     #
    1955     # This configuration file configure's, make's and install's DTC.
    1956     #
    1957 
    1958     %if %{release} == %{nil}
    1959     %define release 1
    1960     %endif
    1961 
    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.
    1965 
    1966 .. code-block:: shell
    1967 
    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:           http://www.jdl.com/software/
    1973     BuildRoot: %{_tmppath}/%{name}-root-%(%{__id_u} -n)
    1974 
    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.
    1981 
    1982 .. code-block:: shell
    1983 
    1984     #
    1985     # Source
    1986     #
    1987     %source set dtc http://www.jdl.com/software/dtc-v%{dtc_version}.tgz
    1988     -------------------------------------------------------------
    1989 
    1990 The remainder of the script is broken in to the various phases of a build. They
    1991 are:
    1992 
    1993 . Preperation
    1994 . Bulding
    1995 . Installing, and
    1996 . Cleaning
    1997 
    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 '$'.
    2002 
    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.
    2011 
    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.
    2016 
    2017 .. code-block:: shell
    2018 
    2019     #
    2020     # Prepare the source code.
    2021     #
    2022     %prep
    2023       build_top=$(pwd)
    2024    
    2025       %source setup dtc -q -n dtc-v%{dtc_version}
    2026       %patch setup dtc -p1
    2027 
    2028       cd ${build_top}
    2029 
    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.
    2036 
    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.
    2041 
    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.
    2044 
    2045 .. code-block:: shell
    2046 
    2047     %build
    2048       build_top=$(pwd)
    2049 
    2050       cd dtc-v%{dtc_version}
    2051 
    2052       %{build_build_flags}
    2053 
    2054       %{__make} PREFIX=%{_prefix}
    2055 
    2056       cd ${build_top}
    2057 
    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.
    2063 
    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.
    2078 
    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 +defaults.mc+
    2083 file and in the trace output. If you are new to creating and editing
    2084 configurations learning these can take a little time.
    2085 
    2086 .. code-block:: shell
    2087 
    2088     %install
    2089       build_top=$(pwd)
    2090 
    2091       %{__rmdir} -rf $SB_BUILD_ROOT
    2092 
    2093       cd dtc-v%{dtc_version}
    2094       %{__make} DESTDIR=$SB_BUILD_ROOT PREFIX=%{_prefix} install
    2095 
    2096       cd ${build_top}
    2097 
    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.
    2101 
    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.
    2105 
    2106 .. code-block:: shell
    2107 
    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: http://www.jdl.com/software/dtc-v1.2.0.tgz -> 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
    2117 
    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.
    2124 
    2125 The DTC build set file is called +dtc.bset+ and contains:
    2126 
    2127 .. code-block:: shell
    2128 
    2129     #
    2130     # Build the DTC.
    2131     #
    2132 
    2133     %define release 1
    2134 
    2135     devel/dtc-1.2.0.cfg
    2136 
    2137 To build this you can use something similar to:
    2138 
    2139 .. code-block:: shell
    2140 
    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
    2153 
    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.
    2158 
    2159 The command also supplies the --trace option. The output in the log file will
    2160 contian all the macros.
    2161 
    2162 Debugging
    2163 ^^^^^^^^^
    2164 
    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.
    2170 
    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.
    2179 
    2180 Snapshot Testing
    2181 ~~~~~~~~~~~~~~~~
    2182 
    2183 *TBD: This section needs to be updated once I sort out snapshot testing.*
    2184 
    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.
    2189 
    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.
    2193 
    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 ``gcc-4.7-snapshot.mc``
    2198 containing:
    2199 
    2200 .. code-block:: shell
    2201 
    2202     [gcc-4.7-snapshot]
    2203     GCC_Version: none, override, '4.7-20130413'
    2204     Source:     none, override, 'http://mirrors.kernel.org/sources.redhat.com/gcc/
    2205     snapshots/%{gcc_version}/gcc-%{gcc_version}.tar.bz2'
    2206     Patch0:      none, udefine,  ''
    2207 
    2208 In the standard configuration file ``source-builder/config/gcc-4.7-1.cfg`` the
    2209 map is selected with:
    2210 
    2211 .. code-block:: shell
    2212 
    2213     #
    2214     # Select the GCC 4.7 Snapshot Macro Map
    2215     #
    2216     %select gcc-4.7-snapshot
    2217 
    2218 On the command line add ``--macros=snapshots/gcc-4.7-snapshot.mc`` 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.
    2222 
    2223 Scripting
    2224 ~~~~~~~~~
    2225 
    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.
    2231 
    2232 The script language is implemented in terms of macros. The built-in list is:
    2233 
    2234 - *%{}*: Macro expansion with conditional logic.
    2235 
    2236 - *%()*: Shell expansion.
    2237 
    2238 - *%prep*: The source preparation shell commands.
    2239 
    2240 - *%build*: The build shell commands.
    2241 
    2242 - *%install*: The package install shell commands.
    2243 
    2244 - *%clean*: The package clean shell commands.
    2245 
    2246 - *%include*: Inline include another configuration file.
    2247 
    2248 - *%name*: The name of the package.
    2249 
    2250 - *%summary*: A brief package description. Useful when reporting about a build.
    2251 
    2252 - *%release*: The package release. A number that is the release as built
    2253   by this tool.
    2254 
    2255 - *%version*: The package's version string.
    2256 
    2257 - *%buildarch*: The build architecture.
    2258 
    2259 - *%source*: Define a source code package. This macro has a number appended.
    2260 
    2261 - *%patch*: Define a patch. This macro has a is number appended.
    2262 
    2263 - *%hash*: Define a checksum for a source or patch file.
    2264 
    2265 - *%echo*: Print the following string as a message.
    2266 
    2267 - *%warning*: Print the following string as a warning and continue.
    2268 
    2269 - *%error*: Print the following string as an error and exit.
    2270 
    2271 - *%select*: Select the macro map. If there is no map nothing is reported.
    2272 
    2273 - *%define*: Define a macro. Macros cannot be redefined, you must first
    2274   undefine it.
    2275 
    2276 - *%undefine*: Undefine a macro.
    2277 
    2278 - *%if*: Start a conditional logic block that ends with a +%endif+.
    2279 
    2280 - *%ifn*: Inverted start of a conditional logic block.
    2281 
    2282 - *%ifarch*: Test the architecture against the following string.
    2283 
    2284 - *%ifnarch*: Inverted test of the architecture
    2285 
    2286 - *%ifos*: Test the host operating system.
    2287 
    2288 - *%else*: Start the *else* conditional logic block.
    2289 
    2290 - *%endfi*: End the conditional logic block.
    2291 
    2292 - *%bconf_with*: Test the build condition *with* setting. This is the
    2293   +--with-*+ command line option.
    2294 
    2295 - *%bconf_without*: Test the build condition *without* setting. This is
    2296   the +--without-*+ command line option.
    2297 
    2298 Expanding
    2299 ^^^^^^^^^
    2300 
    2301 A macro can be ``%{string}`` or the equivalent of ``%string``. The following macro
    2302 expansions supported are:
    2303 
    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``.
    2307 
    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.
    2312 
    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.
    2317 
    2318 - ``%{defined string}``: Expand the macro to '1' if a macro of name
    2319   'string' is defined else expand to '0'.
    2320 
    2321 - ``%{?string: expression}``: Expand the macro to 'expression' if a
    2322   macro of name 'string' is defined else expand to ``%{nil}``.
    2323 
    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}``.
    2327 
    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.
    2332 
    2333 %prep
    2334 ^^^^^
    2335 
    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.
    2341 
    2342 .. code-block:: shell
    2343 
    2344                   <1>                <2>      <3>
    2345 %source setup gcc -q -c -T -n %{name}-%{version}
    2346 
    2347 - *<1>* The source group to set up.
    2348 
    2349 - *<2>* The source's name.
    2350 
    2351 - *<3>* The version of the source.
    2352 
    2353 The source set up are declared with the source +set+ and +add+ commands. For
    2354 example:
    2355 
    2356 .. code-block:: shell
    2357 
    2358     %source set gdb http://ftp.gnu.org/gnu/gdb/gdb-%{gdb_version}.tar.bz2
    2359 
    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.
    2368 
    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:
    2373 
    2374 .. code-block:: shell
    2375 
    2376     %source set gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-code-%{gcc_version}.tar.bz2
    2377     %source add gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-g++-%{gcc_version}.tar.bz2
    2378     %source setup gcc -q -T -D -n gcc-%{gcc_version}
    2379 
    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:
    2382 
    2383 .. code-block:: shell
    2384 
    2385     %source set gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
    2386     %source set newlib ftp://sourceware.org/pub/newlib/newlib-%{newlib_version}.tar.gz
    2387     %source set mpfr http://www.mpfr.org/mpfr-%{mpfr_version}/mpfr-%{mpfr_version}.tar.bz2
    2388     %source set mpc http://www.multiprecision.org/mpc/download/mpc-%{mpc_version}.tar.gz
    2389     %source set gmp ftp://ftp.gnu.org/gnu/gmp/gmp-%{gmp_version}.tar.bz2
    2390 
    2391 and set up with:
    2392 
    2393 .. code-block:: shell
    2394 
    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}
    2400 
    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.
    2406 
    2407 .. code-block:: shell
    2408 
    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
    2411 
    2412 - *<1>* This patch has a custom option.
    2413 
    2414 To apply these patches:
    2415 
    2416 .. code-block:: shell
    2417 
    2418     %patch setup gdb -p1 <1>
    2419 
    2420 - *<1>* The default options.
    2421 
    2422 %build
    2423 ^^^^^^
    2424 
    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.
    2429 
    2430 The following is an example take from the GutHub STLink project:
    2431 
    2432 NOTE: STLink is a JTAG debugging device for the ST ARM family of processors.
    2433 
    2434 .. code-block:: shell
    2435 
    2436     %build
    2437       export PATH="%{_bindir}:${PATH}" <1>
    2438 
    2439       cd texane-stlink-%{stlink_version} <2>
    2440 
    2441       ./autogen.sh <3>
    2442 
    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}
    2456 
    2457       %{__make} %{?_smp_mflags} all <7>
    2458 
    2459       cd ..
    2460 
    2461 - *<1>* Setup the PATH environment variable. This is not always needed.
    2462 
    2463 - *<2>* This package builds in the source tree so enter it.
    2464 
    2465 - *<3>* The package is actually checked directly out from the github
    2466   project and so it needs its autoconf and automake files generated.
    2467 
    2468 - *<4>* Flags for a cross-compiled build.
    2469 
    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.
    2473 
    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+.
    2477 
    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.
    2485 
    2486 %install
    2487 ^^^^^^^^
    2488 
    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.
    2493 
    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.
    2499 
    2500 Looking at the same example as in <<_build, %build>>:
    2501 
    2502 .. code-block:: shell
    2503 
    2504     %install
    2505       export PATH="%{_bindir}:${PATH}" <1>
    2506       rm -rf $SB_BUILD_ROOT <2>
    2507 
    2508       cd texane-stlink-%{stlink_version} <3>
    2509       %{__make} DESTDIR=$SB_BUILD_ROOT install <4>
    2510 
    2511       cd ..
    2512 
    2513 - *<1>* Setup the PATH environment variable. This is not always needed.
    2514 
    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.
    2518 
    2519 - *<3>* Enter the build directory. In this example it just happens to
    2520   be the source directory.
    2521 
    2522 - *<4>* Run +make install+ to install the package overriding the +DESTDIR+
    2523   make variable.
    2524 
    2525 %clean
    2526 ^^^^^^
    2527 
    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.
    2532 
    2533 %include
    2534 ^^^^^^^^
    2535 
    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.
    2540 
    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.
    2544 
    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.
    2549 
    2550 .. code-block:: shell
    2551 
    2552     %include %{_configdir}/gcc-4.7-1.cfg
    2553 
    2554 %name
    2555 ^^^^^
    2556 
    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:
    2560 
    2561 .. code-block:: shell
    2562 
    2563     Name: %{_target}-gcc-%{gcc_version}-newlib-%{newlib_version}-%{release}
    2564 
    2565 %summary
    2566 ^^^^^^^^
    2567 
    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:
    2571 
    2572 .. code-block:: shell
    2573 
    2574     Summary: GCC v%{gcc_version} and Newlib v%{newlib_version} for target %{_target} on host %{_host}
    2575 
    2576 %release
    2577 ^^^^^^^^
    2578 
    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.
    2582 
    2583 .. code-block:: shell
    2584 
    2585     %define release 1
    2586 
    2587 %version
    2588 ^^^^^^^^
    2589 
    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.
    2595 
    2596 .. code-block:: shell
    2597 
    2598     Version: %{gcc_version}
    2599 
    2600 %buildarch
    2601 ^^^^^^^^^^
    2602 
    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.
    2607 
    2608 %source
    2609 ^^^^^^^
    2610 
    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.
    2614 
    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.
    2623 
    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:
    2628 
    2629 .. code-block:: shell
    2630 
    2631     %source set gcc <1> ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
    2632 
    2633 - *<1>* The source group is +gcc+.
    2634 
    2635 To add another source package to be installed into the same source tree you use
    2636 the +add+ command:
    2637 
    2638 .. code-block:: shell
    2639 
    2640     %source add gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/g++-%{gcc_version}.tar.bz2
    2641 
    2642 The source +setup+ command can only be issued in the +%prep:+ section. The
    2643 setup is:
    2644 
    2645 .. code-block:: shell
    2646 
    2647     %source gcc setup -q -T -D -n %{name}-%{version}
    2648 
    2649 Accepted options are:
    2650 
    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.
    2668 
    2669 %patch
    2670 ^^^^^^
    2671 
    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.
    2678 
    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.
    2681 
    2682 The +__patchdir+ path is search.
    2683 
    2684 To add a patch:
    2685 
    2686 .. code-block:: shell
    2687 
    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
    2690 
    2691 - *<1>* The patch group is +gcc+.
    2692 
    2693 - *<2>* Option for this specific patch.
    2694 
    2695 Placing +%patch setup+ in the +%prep+ section will apply the groups patches.
    2696 
    2697 .. code-block:: shell
    2698 
    2699     %patch setup gcc <1>  -p1 <2>
    2700 
    2701 - *<1>* The patch group.
    2702 
    2703 - *<2>* The default option used to apply the patch.
    2704 
    2705 %hash
    2706 ^^^^^
    2707 
    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.
    2712 
    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.
    2715 
    2716 The hash algorthim can be 'md5', 'sha1', 'sha224', 'sha256', 'sha384', and
    2717 'sha512' and we typically use 'md5'.
    2718 
    2719 To add a hash:
    2720 
    2721 .. code-block:: shell
    2722 
    2723     %hash md5 <1> net-snmp-%{net_snmp_version}.tar.gz <2> 7db683faba037249837b226f64d566d4 <3>
    2724 
    2725 - *<1>* The type of checksum.
    2726 
    2727 - *<2>* The file to checksum. It can contain macros that are expanded for you.
    2728 
    2729 - *<3>* The MD5 hash for the Net-SNMP file +net-snmp-5.7.2.1.tar.gz+.
    2730 
    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.
    2734 
    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.
    2737 
    2738 %echo
    2739 ^^^^^
    2740 
    2741 The +%echo+ macro outputs the following string to stdout. This can also be used
    2742 as ``%{echo: message}``.
    2743 
    2744 %warning
    2745 ^^^^^^^^
    2746 
    2747 The +%warning+ macro outputs the following string as a warning. This can also
    2748 be used as ``%{warning: message}``.
    2749 
    2750 %error
    2751 ^^^^^^
    2752 
    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}``.
    2755 
    2756 %select
    2757 ^^^^^^^
    2758 
    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.
    2763 
    2764 Configuration use different maps so macro overrides can target a specific
    2765 package.
    2766 
    2767 The default map is ``global``.
    2768 
    2769 .. code-block:: shell
    2770 
    2771     %select gcc-4.8-snapshot <1>
    2772     %define one_plus_one 2 <2>
    2773 
    2774 - *<1>* The map switches to ``gcc-4.8-snapshot``. Any overrides in this
    2775   map will be used.
    2776 
    2777 - *<2>* Defining macros only updates the ``global`` map and not the
    2778   selected map.
    2779 
    2780 %define
    2781 ^^^^^^^
    2782 
    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.
    2785 
    2786 .. code-block:: shell
    2787 
    2788     %define foo bar
    2789     %define one_plus_one 2
    2790     %define one <1>
    2791 
    2792 - *<1>* The macro _one_ is set to 1.
    2793 
    2794 %undefine
    2795 ^^^^^^^^^
    2796 
    2797 The +%undefine+ macro removes a macro if it exists. Any further references to
    2798 it will result in an undefine macro error.
    2799 
    2800 %if
    2801 ^^^
    2802 
    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:
    2805 
    2806 .. list-table:: Operators
    2807    : header-rows: 1
    2808 
    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.
    2860 
    2861 %ifn
    2862 ^^^^
    2863 
    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:
    2867 
    2868 .. code-block:: shell
    2869 
    2870     %ifn %{defined foo}
    2871      %define foo bar
    2872     %endif
    2873 
    2874 %ifarch
    2875 ^^^^^^^
    2876 
    2877 The +%ifarch+ is a short cut for "+%if %{\_arch} == i386+". Currently not used.
    2878 
    2879 %ifnarch
    2880 ^^^^^^^^
    2881 
    2882 The +%ifnarch+ is a short cut for "+%if %{\_arch} != i386+". Currently not
    2883 used.
    2884 
    2885 %ifos
    2886 ^^^^^
    2887 
    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.
    2891 
    2892 %else
    2893 ^^^^^
    2894 
    2895 The +%else+ macro starts the conditional *else* block.
    2896 
    2897 %endfi
    2898 ^^^^^^
    2899 
    2900 The +%endif+ macro ends a conditional logic block.
    2901 
    2902 %bconf_with
    2903 ^^^^^^^^^^^
    2904 
    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.
    2908 
    2909 %bconf_without
    2910 ^^^^^^^^^^^^^^
    2911 
    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.
    2915 
    2916 Commands
    2917 ########
    2918 
    2919 Checker (sb-check)
    2920 ~~~~~~~~~~~~~~~~~~
    2921 
    2922 This commands checks your system is set up correctly. Most options are ignored.
    2923 
    2924 .. code-block:: shell
    2925 
    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
    2960 
    2961 Defaults (sb-defaults)
    2962 ~~~~~~~~~~~~~~~~~~~~~~
    2963 
    2964 This commands outputs and the default macros for your when given no
    2965 arguments. Most options are ignored.
    2966 
    2967 .. code-block:: shell
    2968 
    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
    3000 
    3001 Set Builder (sb-set-builder)
    3002 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    3003 
    3004 This command builds a set.
    3005 
    3006 .. code-block:: shell
    3007 
    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.
    3050 
    3051 .Arguments
    3052 The +[args]+ are a list build sets to build.
    3053 
    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.
    3162 
    3163 Set Builder (sb-builder)
    3164 ~~~~~~~~~~~~~~~~~~~~~~~~
    3165 
    3166 This command builds a configuration as described in a configuration
    3167 file. Configuration files have the extension of +.cfg+.
    3168 
    3169 .. code-block:: shell
    3170 
    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
    3201 
    3202 .. _Host Setups:
    3203 
    3204 Host Setups
    3205 ###########
    3206 
    3207 The host versions are listed. If a later version of the host operating system
    3208 exists it should work unless listed.
    3209 
    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.
    3212 
    3213 Linux
    3214 ~~~~~
    3215 
    3216 A number of different Linux distrubutions are known to work. The following have
    3217 been tested and report as working.
    3218 
    3219 .. _ArchLinux:
    3220 
    3221 ArchLinux
    3222 ^^^^^^^^^
    3223 
    3224 The following packages are required on a fresh Archlinux 64bit installation:
    3225 
    3226 .. code-block:: shell
    3227 
    3228     # pacman -S base-devel gdb xz unzip ncurses git zlib
    3229 
    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.
    3233 
    3234 .. code-block:: shell
    3235 
    3236     # pacman -R texinfo
    3237     $ yaourt -S texinfo-legacy
    3238     # ln -s /usr/bin/makeinfo-4.13a /usr/bin/makeinfo
    3239 
    3240 .. _CentOS:
    3241 
    3242 CentOS
    3243 ^^^^^^
    3244 
    3245 The following packages are required on a minimal CentOS 6.3 64bit installation:
    3246 
    3247 .. code-block:: shell
    3248 
    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
    3251 
    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.
    3255 
    3256 .. _Fedora:
    3257 
    3258 Fedora
    3259 ^^^^^^
    3260 
    3261 The RTEMS Source Builder has been tested on Fedora 19 64bit with the following packages.
    3262 
    3263 .. code-block:: shell
    3264 
    3265     # yum install ncurses-devel python-devel git bison gcc cvs gcc-c++ \
    3266          flex texinfo patch perl-Text-ParseWords zlib-devel
    3267 
    3268 .. _Raspbian:
    3269 
    3270 Raspbian
    3271 ^^^^^^^^
    3272 
    3273 The is the Debian distribution for the Raspberry Pi. The following packages are
    3274 required.
    3275 
    3276 .. code-block:: shell
    3277 
    3278     $ sudo apt-get install autoconf automake bison flex binutils gcc g++ gdb \
    3279     texinfo unzip ncurses-dev python-dev git
    3280 
    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.
    3284 
    3285 .. _Ubuntu:
    3286 .. _Xubuntu:
    3287 
    3288 Ubuntu
    3289 ^^^^^^
    3290 
    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.
    3294 
    3295 .. code-block:: shell
    3296 
    3297     $ sudo apt-get build-dep binutils gcc g++ gdb unzip git
    3298     $ sudo apt-get install python2.7-dev
    3299 
    3300 .. _Linux Mint:
    3301 
    3302 Linux Mint
    3303 ^^^^^^^^^^
    3304 
    3305 zlib package is required on Linux Mint. It has a different name (other
    3306 than the usual zlib-dev):
    3307 
    3308 .. code-block:: shell
    3309 
    3310     # sudo apt-get install zlib1g-dev
    3311 
    3312 .. _openSUSE:
    3313 
    3314 openSUSE
    3315 ^^^^^^^^
    3316 
    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.
    3319 
    3320 .. _FreeBSD:
    3321 
    3322 FreeBSD
    3323 ~~~~~~~
    3324 
    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:
    3327 
    3328 .. code-block:: shell
    3329 
    3330     # cd /usr/ports
    3331     # portinstall --batch lang/python27
    3332 
    3333 If you wish to build Windows (mingw32) tools please install the following
    3334 ports:
    3335 
    3336 .. code-block:: shell
    3337 
    3338     # cd /usr/ports
    3339     # portinstall --batch devel/mingw32-binutils devel/mingw32-gcc
    3340     # portinstall --batch devel/mingw32-zlib devel/mingw32-pthreads
    3341 
    3342 The +zlip+ and +pthreads+ ports for MinGW32 are used for builiding a Windows
    3343 QEMU.
    3344 
    3345 If you are on FreeBSD 10.0 and you have pkgng installed you can use 'pkg
    3346 install' rather than 'portinstall'.
    3347 
    3348 .. _NetBSD:
    3349 
    3350 NetBSD
    3351 ~~~~~~
    3352 
    3353 The RTEMS Source Builder has been tested on NetBSD 6.1 i386. Packages to add
    3354 are:
    3355 
    3356 .. code-block:: shell
    3357 
    3358     # pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/devel/gmake-3.82nb7.tgz
    3359     # pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/devel/bison-2.7.1.tgz
    3360     # pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/archivers/xz-5.0.4.tgz
    3361 
    3362 .. _MacOS:
    3363 
    3364 MacOS
    3365 ~~~~~
    3366 
    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.
    3370 
    3371 .. _Mavericks:
    3372 
    3373 Mavericks
    3374 ^^^^^^^^^
    3375 
    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*.
    3380 
    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:
    3386 
    3387 . The XZ package's home page is http://tukaani.org/xz/ and I use version
    3388   5.0.5. XZ builds and installs cleanly.
    3389 
    3390 . CVS can be found at http://cvs.nongnu.org/ and I use version 1.11.23. CVS
    3391   requires the following patch
    3392   http://ftp.rtems.org/pub/rtems/people/chrisj/source-builder/cvs-1.11.23-osx-maverick.diff
    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+.
    3395 
    3396 .. _Windows:
    3397 
    3398 Windows
    3399 ~~~~~~~
    3400 
    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.
    3410 
    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.
    3413 
    3414 .Ready To Go Windows Tools
    3415 NOTE: From time to time I provide tools for Windows at
    3416 http://ftp.rtems.org/pub/rtems/people/chrisj/source-builder/4.11/mingw32/
    3417 
    3418 .. _MSYS2:
    3419 
    3420 MSYS2
    3421 
    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.
    3427 
    3428 Install MSYS2 using the installer you can download from
    3429 https://msys2.github.io/. 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.
    3432 
    3433 To build the tools you need install the following packages using pacman:
    3434 
    3435 .. code-block:: shell
    3436 
    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
    3439 
    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.
    3444 
    3445 Install a suitable version of Python from http://www.python.org/ and add it to
    3446 the start of your path. The MSYS2 python does not work with waf.
    3447 
    3448 .. _Cygwin:
    3449 
    3450 Cygwin
    3451 
    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.
    3456 
    3457 Install a recent Cygwin version using the Cygwin setup tool. Select and install
    3458 the groups and packages listed:
    3459 
    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 |================================
    3488 
    3489 The setup tool will add a number of dependent package and it is ok to accept
    3490 them.
    3491 
    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.
    3497 
    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:
    3504 
    3505 .. code-block:: shell
    3506 
    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>
    3548 
    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.
    3555 
    3556 CAUTION: Cygwin documents the 'Big List Of Dodgy Apps' or 'BLODA'. The link is
    3557 http://cygwin.com/faq/faq.html#faq.using.bloda 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.
    3566 
    3567 
    3568 History
    3569 #######
    3570 
    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.