source: rtems-source-builder/doc/source-builder.txt @ e0c00e8

4.104.114.95
Last change on this file since e0c00e8 was e0c00e8, checked in by Chris Johns <chrisj@…>, on 09/10/13 at 06:19:09

doc: Add NetBSD.

  • Property mode set to 100644
File size: 99.7 KB
Line 
1RTEMS Source Builder
2====================
3:doctype: book
4:toc2:
5:toclevels: 5
6:icons:
7:numbered:
8
9image:images/rtemswhitebg.jpg["RTEMS",width="30%"]
10
11Chris Johns <chrisj@rtems.org>
121.4, August 2013
13
14RTEMS Tools From Source
15-----------------------
16
17The RTEMS Source Builder is a tool to aid building packages from source used by
18the RTEMS project. It helps consolidate the details you need to build a package
19from source in a controlled and verifiable way. The tool is aimed at developers
20of software who use tool sets for embedded type development and is not limited
21to building just for RTEMS. Embedded development typically uses cross-compiling
22tool chains, debuggers, and debugging aids. Together we call these a 'tool
23set'. The RTEMS Source Builder is not limited to this role but designed to fit
24with-in this specific niche. It can be used outside of the RTEMS project and we
25welcome this happening in other open source or commercial projects.
26
27The RTEMS Source Builder is typically used to build a set of tools or a 'build
28set'. A 'build set' is a collection of packages and a package is a specific
29tool, for example gcc or gdb. The RTEMS Source Builder attempts to support any
30host environment that runs Python and you can build the package on. It is not
31some sort of magic that can take any piece of source code and make it
32build. Someone at some point in time has figured out how to build that package
33from source and taught this tool. The RTEMS Source Builder has been tested on:
34
35* <<_archlinux,Archlinux>>
36* <<_centos,Centos>>
37* <<_fedora,Fedora>>
38* <<_freebsd,FreeBSD>>
39* <<_netbsd,NetBSD>>
40* <<_macos,MacOS>>
41* <<_opensuse,openSUSE>>
42* <<_raspbian,Raspbian>>
43* <<_ubuntu,Ubuntu>>
44* <<_windows,Windows>>
45
46The RTEMS Source Builder has two types configuration data. The first is the
47'build set'. A _build set_ describes a collection of packages that define a set
48of tools you would use when developing software for RTEMS. For example the
49basic GNU tool set is binutils, gcc, and gdb and is the typical base suite of
50tools you need for an embedded cross-development type project. The second type
51of configuration data is the configuration files and they define how a package
52is built. Configuration files are scripts loosely based on the RPM spec file
53format and detail the steps needed to build a package. The steps are
54'preparation', 'building', and 'installing'. Scripts support macros, shell
55expansion, logic, includes plus many more features useful when build packages.
56
57The RTEMS Source Builder does not interact with any host package management
58systems. There is no automatic dependence checking between various packages you
59build or packages and software your host system you may have installed. We
60assume the build sets and configuration files you are using have been created
61by developers who do. If you have a problem please ask on the RTEMS Users
62mailing list.
63
64IMPORTANT: If you have a problem please see <<_bugs,the reporting bugs>>
65           section.
66
67Quick Start
68-----------
69
70The quick start will show you how to build a set of RTEMS tools for a supported
71architecture. The tools are installed into a build _prefix_ and this is top of
72a group of directories containing all the files needed to develop RTEMS
73applications. Building an RTEMS build set will build all that you need. This
74includes autoconf, automake, assemblers, linkers, compilers, debuggers,
75standard libraries and RTEMS itself.
76
77There is no need to become root or the administrator and we recommend you avoid
78doing this. You can build and install the tools anywhere on the host's file
79system you, as a standard user, have read and write access too. I recommend you
80use your home directory and work under the directory `~/development/rtems`. The
81examples shown here will do this.
82
83You can use the build _prefix_ to install and maintain different versions of
84the tools. Doing this lets you try a new set of tools while not touching your
85proven working production set of tools. Once you have proven the new tools are
86working rebuild with the 'production' prefix switching your development to them.
87
88I also suggest you keep your environment to the bare minimum, particularly the
89path variable. Using environment variables has been proven over the years to be
90difficult to manage in production systems.
91
92.Path to use when building applications
93*************************************************************
94To use the tools once finished just set your path to the 'bin' directory under
95the _prefix_ you use. In the examples that follow the _prefix_ is
96`$HOME/development/rtems/4.11` and is set using the `--prefix` option so the
97path you need to configure to build applications can be set with the following
98in a BASH shell:
99-------------------------------------------------------------
100$ export PATH=$HOME/development/rtems/4.11/bin:$PATH
101-------------------------------------------------------------
102Make sure you place the RTEMS tool path at the front of your path so they are
103searched first. RTEMS can provide newer versions of some tools your operating
104system provides and placing the RTEMS tools path at the front means it is
105searched first and the RTEMS needed versions of the tools are used.
106*************************************************************
107
108Setup
109~~~~~
110
111Setup a development work space:
112
113-------------------------------------------------------------
114$ cd
115$ mkdir -p development/rtems/src
116$ cd development/rtems/src
117-------------------------------------------------------------
118
119The RTEMS Source Builder is distributed as source. It is Python code so all you
120need to do is head over to the RTEMS GIT repository and clone the code directly
121from git:
122
123-------------------------------------------------------------
124$ git clone git://git.rtems.org/rtems-source-builder.git
125$ cd rtems-source-builder
126-------------------------------------------------------------
127
128Checking
129~~~~~~~~
130
131The next step is to check if your host is set up correctly. The RTEMS Source
132Builder provides a tool to help:
133
134-------------------------------------------------------------
135$ source-builder/sb-check
136warning: exe: absolute exe found in path: (__objcopy) /usr/local/bin/objcopy <1>
137warning: exe: absolute exe found in path: (__objdump) /usr/local/bin/objdump
138error: exe: not found: (_xz) /usr/local/bin/xz <2>
139RTEMS Source Builder environment is not correctly set up
140$ source-builder/sb-check
141RTEMS Source Builder environment is ok <3>
142-------------------------------------------------------------
143
144<1> A tool is in the environment path but does not match the expected path.
145<2> The executable 'xz' is not found.
146<3> The host's environment is set up correct.
147
148The checking tool will output a list of executable files not found if problems
149are detected. Locate those executable files and install them. You may also be
150given a list of warnings about executable files not in the expected location
151however the executable was located somewhere in your environment's path. You
152will need to check each tool to determine if this is an issue. An executable
153not in the standard location may indicate it is not the host operating system's
154standard tool. It maybe ok or it could be buggy, only you can determine this.
155
156The <<_host_setups,Host Setups>> section lists packages you should install for
157common host operating systems. It maybe worth checking if you have those
158installed.
159
160Build Sets
161~~~~~~~~~~
162
163The RTEMS tools can be built within the RTEMS Source Builder's source tree. We
164recommend you do this so lets change into the RTEMS directory in the RTEMS
165Source Builder package:
166
167-------------------------------------------------------------
168$ cd rtems
169-------------------------------------------------------------
170
171If you are unsure how to specify the build set for the architecture you wish to
172build ask the tool:
173
174-------------------------------------------------------------
175$ ../source-builder/sb-set-builder --list-bsets <1>
176RTEMS Source Builder - Set Builder, v0.2.0
177Examining: config <2>
178Examining: ../source-builder/config <2>
179    4.10/rtems-all.bset <3>
180    4.10/rtems-arm.bset <4>
181    4.10/rtems-autotools.bset
182    4.10/rtems-avr.bset
183    4.10/rtems-bfin.bset
184    4.10/rtems-h8300.bset
185    4.10/rtems-i386.bset
186    4.10/rtems-lm32.bset
187    4.10/rtems-m32c.bset
188    4.10/rtems-m32r.bset
189    4.10/rtems-m68k.bset
190    4.10/rtems-mips.bset
191    4.10/rtems-nios2.bset
192    4.10/rtems-powerpc.bset
193    4.10/rtems-sh.bset
194    4.10/rtems-sparc.bset
195    4.11/rtems-all.bset
196    4.11/rtems-arm.bset
197    4.11/rtems-autotools.bset
198    4.11/rtems-avr.bset
199    4.11/rtems-bfin.bset
200    4.11/rtems-h8300.bset
201    4.11/rtems-i386.bset
202    4.11/rtems-lm32.bset
203    4.11/rtems-m32c.bset
204    4.11/rtems-m32r.bset
205    4.11/rtems-m68k.bset
206    4.11/rtems-microblaze.bset
207    4.11/rtems-mips.bset
208    4.11/rtems-moxie.bset
209    4.11/rtems-nios2.bset
210    4.11/rtems-powerpc.bset
211    4.11/rtems-sh.bset
212    4.11/rtems-sparc.bset
213    4.11/rtems-sparc64.bset
214    4.11/rtems-v850.bset
215    4.9/rtems-all.bset
216    4.9/rtems-arm.bset
217    4.9/rtems-autotools.bset
218    4.9/rtems-i386.bset
219    4.9/rtems-m68k.bset
220    4.9/rtems-mips.bset
221    4.9/rtems-powerpc.bset
222    4.9/rtems-sparc.bset
223    gnu-tools-4.6.bset
224    rtems-4.10-base.bset <5>
225    rtems-4.11-base.bset
226    rtems-4.9-base.bset
227    rtems-base.bset <5>
228    unstable/4.11/rtems-all.bset <6>
229    unstable/4.11/rtems-arm.bset
230    unstable/4.11/rtems-avr.bset
231    unstable/4.11/rtems-bfin.bset
232    unstable/4.11/rtems-h8300.bset
233    unstable/4.11/rtems-i386.bset
234    unstable/4.11/rtems-lm32.bset
235    unstable/4.11/rtems-m32c.bset
236    unstable/4.11/rtems-m32r.bset
237    unstable/4.11/rtems-m68k.bset
238    unstable/4.11/rtems-microblaze.bset
239    unstable/4.11/rtems-mips.bset
240    unstable/4.11/rtems-moxie.bset
241    unstable/4.11/rtems-powerpc.bset
242    unstable/4.11/rtems-sh.bset
243    unstable/4.11/rtems-sparc.bset
244    unstable/4.11/rtems-sparc64.bset
245    unstable/4.11/rtems-v850.bset
246-------------------------------------------------------------
247<1> Only option needed is +--list-bsets+
248<2> The paths inspected. See <<X1,+_configdir+>> variable.
249<3> Build all RTEMS 4.10 supported architectures.
250<4> The build set for the ARM architecture on RTEMS 4.10.
251<5> Support build set file with common functionality included by other build
252    set files.
253<6> Unstable tool sets are used by RTEMS developers to test new tool sets. You
254    are welcome to try them but you must remember they are unstable, can change
255    at any point in time and your application may not work. If you have an
256    issue with a production tool it may pay to try the unstable tool to see if
257    it has been resolved.
258
259Building
260~~~~~~~~
261
262In this quick start I will build a SPARC tool set.
263
264-------------------------------------------------------------
265$ ../source-builder/sb-set-builder --log=l-sparc.txt <1> \
266                --prefix=$HOME/development/rtems/4.11 <2> 4.11/rtems-sparc <3>
267Source Builder - Set Builder, v0.2.0
268Build Set: 4.11/rtems-sparc
269config: expat-2.1.0-1.cfg <4>
270package: expat-2.1.0-x86_64-freebsd9.1-1
271building: expat-2.1.0-x86_64-freebsd9.1-1
272config: tools/rtems-binutils-2.22-1.cfg <5>
273package: sparc-rtems4.11-binutils-2.22-1
274building: sparc-rtems4.11-binutils-2.22-1
275config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg <6>
276package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
277building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
278config: tools/rtems-gdb-7.5.1-1.cfg <7>
279package: sparc-rtems4.11-gdb-7.5.1-1
280building: sparc-rtems4.11-gdb-7.5.1-1
281installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <8>
282installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
283installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
284installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
285cleaning: expat-2.1.0-x86_64-freebsd9.1-1 <9>
286cleaning: sparc-rtems4.11-binutils-2.22-1
287cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
288cleaning: sparc-rtems4.11-gdb-7.5.1-1
289Build Set: Time 0:13:43.616383 <10>
290-------------------------------------------------------------
291
292<1> Providing a log file redirects the build output into a file. Logging the
293    build output provides a simple way to report problems.
294<2> The prefix is the location on your file system the tools are installed
295    into. Provide a prefix to a location you have read and write access. You
296    can use the prefix to install different versions or builds of tools. Just
297    use the path to the tools you want to use when building RTEMS.
298<3> The build set. This is the SPARC build set. First a specifically referenced
299    file is checked for and if not found the '%{_configdir} path is
300    searched. The set builder will first look for files with a +.bset+
301    extension and then for a configuration file with a +.cfg+ extension.
302<4> The SPARC build set first builds the expat library as is used in GDB. This
303    is the expat configuration used.
304<5> The binutils build configuration.
305<6> The GCC and Newlib build configuration.
306<7> The GDB build configuration.
307<8> Installing the built packages to the install prefix.
308<9> All the packages built are cleaned at the end. If the build fails all the
309    needed files are present. You may have to clean up by deleting the build
310    directory if the build fails.
311<10> The time to build the package. This lets you see how different host
312     hardware or configurations perform.
313
314Your SPARC RTEMS 4.11 tool set will be installed and ready to build RTEMS and
315RTEMS applications. When the build runs you will notice the tool fetch the
316source code from the internet. These files are cached in a directory called
317+source+. If you run the build again the cached files are used. This is what
318happened in the show example before.
319
320The installed tools:
321
322-------------------------------------------------------------
323$ ls $HOME/development/rtems/4.11
324bin         include     lib         libexec     share       sparc-rtems4.11
325$ ls $HOME/development/rtems/4.11/bin
326sparc-rtems4.11-addr2line       sparc-rtems4.11-cpp
327sparc-rtems4.11-gcc-ar          sparc-rtems4.11-gprof
328sparc-rtems4.11-objdump         sparc-rtems4.11-size
329sparc-rtems4.11-ar              sparc-rtems4.11-elfedit
330sparc-rtems4.11-gcc-nm          sparc-rtems4.11-ld
331sparc-rtems4.11-ranlib          sparc-rtems4.11-strings
332sparc-rtems4.11-as              sparc-rtems4.11-g++
333sparc-rtems4.11-gcc-ranlib      sparc-rtems4.11-ld.bfd
334sparc-rtems4.11-readelf         sparc-rtems4.11-strip
335sparc-rtems4.11-c++             sparc-rtems4.11-gcc
336sparc-rtems4.11-gcov            sparc-rtems4.11-nm
337sparc-rtems4.11-run             xmlwf
338sparc-rtems4.11-c++filt         sparc-rtems4.11-gcc-4.7.2
339sparc-rtems4.11-gdb             sparc-rtems4.11-objcopy
340sparc-rtems4.11-sis
341$ $HOME/development/rtems/4.11/bin/sparc-rtems4.11-gcc -v
342Using built-in specs.
343COLLECT_GCC=/home/chris/development/rtems/4.11/bin/sparc-rtems4.11-gcc
344COLLECT_LTO_WRAPPER=/usr/home/chris/development/rtems/4.11/bin/../ \
345libexec/gcc/sparc-rtems4.11/4.7.2/lto-wrapper
346Target: sparc-rtems4.11 <1>
347Configured with: ../gcc-4.7.2/configure <2>
348--prefix=/home/chris/development/rtems/4.11
349--bindir=/home/chris/development/rtems/4.11/bin
350--exec_prefix=/home/chris/development/rtems/4.11
351--includedir=/home/chris/development/rtems/4.11/include
352--libdir=/home/chris/development/rtems/4.11/lib
353--libexecdir=/home/chris/development/rtems/4.11/libexec
354--mandir=/home/chris/development/rtems/4.11/share/man
355--infodir=/home/chris/development/rtems/4.11/share/info
356--datadir=/home/chris/development/rtems/4.11/share
357--build=x86_64-freebsd9.1 --host=x86_64-freebsd9.1 --target=sparc-rtems4.11
358--disable-libstdcxx-pch --with-gnu-as --with-gnu-ld --verbose --with-newlib
359--with-system-zlib --disable-nls --without-included-gettext
360--disable-win32-registry --enable-version-specific-runtime-libs --disable-lto
361--enable-threads --enable-plugin --enable-newlib-io-c99-formats
362--enable-newlib-iconv --enable-languages=c,c++
363Thread model: rtems <3>
364gcc version 4.7.2 20120920 <4>
365 (RTEMS4.11-RSB(cb12e4875c203f794a5cd4b3de36101ff9a88403)-1,gcc-4.7.2/newlib-2.0.0) (GCC)
366-------------------------------------------------------------
367
368<1> The target the compiler is built for.
369<2> The configure options used to build GCC.
370<3> The threading model is always RTEMS. This makes the RTEMS tools difficult
371    for bare metal development more difficult.
372<4> The version string. It contains the Git hash of the RTEMS Source Builder
373    you are using. If your local clone has been modifed that state is also
374    recorded in the version string. The hash allows you to track from a GCC
375    executable back to the original source used to build it.
376
377NOTE: The RTEMS thread model enables specific hooks in GCC so applications
378built with RTEMS tools need the RTEMS runtime to operate correctly. You can use
379RTEMS tools to build bare metal component but it is more difficult than with a
380bare metal tool chain and you need to know what you are doing at a low
381level. The RTEMS Source Builder can build bare metal tool chains.
382
383Installing and Tar Files
384~~~~~~~~~~~~~~~~~~~~~~~~
385
386The RTEMS Source Builder can install the built packages directly and optionally
387it can create a build set tar file or a tar file per package built. The normal
388and default behaviour is to let the RTEMS Source Builder install the tools. The
389source will be downloaded, built, installed and cleaned up.
390
391The tar files are created with the full build prefix present and if you follow
392the examples given in this documentation the path is absolute. This can cause
393problems if you are installing on a host you do not have super user or
394administrator rights on because the prefix path may references part you do not
395have write access too and tar will not extract the files. You can use the
396+--strip-components+ option in tar if your host tar application supports it to
397remove the parts you do not have write access too or you may need to unpack the
398tar file somewhere and copy the file tree from the level you have write access
399from. Embedding the full prefix path in the tar files lets you know what the
400prefix is and is recommended. For example if
401`/home/chris/development/rtems/4.11` is the prefix used you cannot change
402directory to the root (`/`) and install because the `/home` is root access
403only. To install you would:
404
405-------------------------------------------------------------
406$ cd
407$ tar --strip-components=3 -xjf rtems-4.11-sparc-rtems4.11-1.tar.bz2
408-------------------------------------------------------------
409
410A build set tar file is created by adding `--bset-tar-file` option to the
411`sb-set-builder` command.
412
413-------------------------------------------------------------
414$ ../source-builder/sb-set-builder --log=l-sparc.txt \
415         --prefix=$HOME/development/rtems/4.11 \
416         --bset-tar-file <1> 4.11/rtems-sparc
417Source Builder - Set Builder, v0.2.0
418Build Set: 4.11/rtems-sparc
419config: expat-2.1.0-1.cfg
420package: expat-2.1.0-x86_64-freebsd9.1-1
421building: expat-2.1.0-x86_64-freebsd9.1-1
422config: tools/rtems-binutils-2.22-1.cfg
423package: sparc-rtems4.11-binutils-2.22-1
424building: sparc-rtems4.11-binutils-2.22-1
425config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
426package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
427building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
428config: tools/rtems-gdb-7.5.1-1.cfg
429package: sparc-rtems4.11-gdb-7.5.1-1
430building: sparc-rtems4.11-gdb-7.5.1-1
431installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <2>
432installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
433installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
434installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
435tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3>
436cleaning: expat-2.1.0-x86_64-freebsd9.1-1
437cleaning: sparc-rtems4.11-binutils-2.22-1
438cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
439cleaning: sparc-rtems4.11-gdb-7.5.1-1
440Build Set: Time 0:15:25.92873
441-------------------------------------------------------------
442
443<1> The option to create a build set tar file.
444<2> The installation still happens unless you specify `--no-install`.
445<3> Creating the build set tar file.
446
447You can also suppress installing the files using the `--no-install` option to
448the `sb-set-builder` command.
449
450-------------------------------------------------------------
451$ ../source-builder/sb-set-builder --log=l-sparc.txt \
452            --prefix=$HOME/development/rtems/4.11 \
453            --bset-tar-file --no-install <1> 4.11/rtems-sparc
454Source Builder - Set Builder, v0.2.0
455Build Set: 4.11/rtems-sparc
456config: expat-2.1.0-1.cfg
457package: expat-2.1.0-x86_64-freebsd9.1-1
458building: expat-2.1.0-x86_64-freebsd9.1-1
459config: tools/rtems-binutils-2.22-1.cfg
460package: sparc-rtems4.11-binutils-2.22-1
461building: sparc-rtems4.11-binutils-2.22-1
462config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
463package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
464building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
465config: tools/rtems-gdb-7.5.1-1.cfg
466package: sparc-rtems4.11-gdb-7.5.1-1
467building: sparc-rtems4.11-gdb-7.5.1-1
468tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 <2>
469cleaning: expat-2.1.0-x86_64-freebsd9.1-1
470cleaning: sparc-rtems4.11-binutils-2.22-1
471cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
472cleaning: sparc-rtems4.11-gdb-7.5.1-1
473Build Set: Time 0:14:11.721274
474$ ls tar
475rtems-4.11-sparc-rtems4.11-1.tar.bz2
476-------------------------------------------------------------
477
478<1> The option to supressing installing the packages.
479<2> Create the build set tar.
480
481A package tar file can be created by adding the +--pkg-tar-files+ to the
482+sb-set-builder+ command. This creates a tar file per package built in the
483build set.
484
485-------------------------------------------------------------
486$ ../source-builder/sb-set-builder --log=l-sparc.txt \
487            --prefix=$HOME/development/rtems/4.11 \
488            --bset-tar-file --pkg-tar-files <1> --no-install 4.11/rtems-sparc
489Source Builder - Set Builder, v0.2.0
490Build Set: 4.11/rtems-sparc
491config: expat-2.1.0-1.cfg
492package: expat-2.1.0-x86_64-freebsd9.1-1
493building: expat-2.1.0-x86_64-freebsd9.1-1
494config: tools/rtems-binutils-2.22-1.cfg
495package: sparc-rtems4.11-binutils-2.22-1
496building: sparc-rtems4.11-binutils-2.22-1
497config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
498package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
499building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
500config: tools/rtems-gdb-7.5.1-1.cfg
501package: sparc-rtems4.11-gdb-7.5.1-1
502building: sparc-rtems4.11-gdb-7.5.1-1
503tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2
504cleaning: expat-2.1.0-x86_64-freebsd9.1-1
505cleaning: sparc-rtems4.11-binutils-2.22-1
506cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
507cleaning: sparc-rtems4.11-gdb-7.5.1-1
508Build Set: Time 0:14:37.658460
509$ ls tar
510expat-2.1.0-x86_64-freebsd9.1-1.tar.bz2           sparc-rtems4.11-binutils-2.22-1.tar.bz2
511sparc-rtems4.11-gdb-7.5.1-1.tar.bz2 <2>           rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3>
512sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1.tar.bz2
513-------------------------------------------------------------
514
515<1> The option to create packages tar files.
516<2> The GDB package tar file.
517<3> The build set tar file. All the others in a single tar file.
518
519Controlling the Build
520~~~~~~~~~~~~~~~~~~~~~
521
522Build sets can be controlled via the command line to enable and disable various
523features. There is no definitive list of build options that can be listed
524because they are implemented with the configuration scripts. The best way to
525find what is available is to grep the configuration files. for +with+ and
526+without+.
527
528Following are currentlt available:
529
530'--without-rtems':: Do not build RTEMS when building an RTEMS build set.
531'--without-cxx':: Do not build a C++ compiler.
532'--with-objc':: Attempt to build a C++ compiler.
533'--with-fortran':: Attempt to build a Fortran compiler.
534
535Why Build from Source ?
536-----------------------
537
538The RTEMS Source Builder is not a replacement for the binary install systems
539you have with commercial operating systems or open source operating system
540distributions. Those products and distributions are critically important and
541are the base that allows the Source Builder to work. The RTEMS Source Builder
542sits somewhere between you manually entering the commands to build a tool set
543and a tool such as +yum+ or +apt-get+ to install binary packages made
544specifically for your host operating system. Building manually or installing a
545binary package from a remote repository are valid and real alternatives while
546the Source Builder is attempting to provide a specific service of repeatably
547being able to build tool sets from source code.
548
549If you are developing a system or product that has a long shelf life or is used
550in a critical piece of infrastructure that has a long life cycle being able to
551build from source is important. It insulates the project from the fast ever
552changing world of the host development machines. If your tool set is binary and
553you have lost the ability to build it you have lost a degree of control and
554flexibility open source gives you. Fast moving host environments are
555fantastic. We have powerful multi-core computers with huge amounts of memory
556and state of the art operating systems to run on them however the product or
557project you are part of may need to be maintained well past the life time of
558these host. Being able to build from source an important and critical part of
559this process because you can move to a newer host and create an equivalent tool
560set.
561
562Building from source provides you with control over the configuration of the
563package you are building. If all or the most important dependent parts are
564built from source you limit the exposure to host variations. For example the
565GNU C compiler (gcc) currently uses a number of 3rd party libraries internally
566(gmp, mpfr, etc). If your validated compiler generating code for your target
567processor is dynamically linked against the host's version of these libraries
568any change in the host's configuration may effect you. The changes the host's
569package management system makes may be perfectly reasonable in relation to the
570distribution being managed however this may not extend to you and your
571tools. Building your tools from source and controlling the specific version of
572these dependent parts means you are not exposing yourself to unexpected and
573often difficult to resolve problems. On the other side you need to make sure
574your tools build and work with newer versions of the host operating
575system. Given the stability of standards based libraries like 'libc' and ever
576improving support for standard header file locations this task is becoming
577easier.
578
579The RTEMS Source Builder is designed to be audited and incorporated into a
580project's verification and validation process. If your project is developing
581critical applications that needs to be traced from source to executable code in
582the target, you need to also consider the tools and how to track them.
583
584If your IT department maintains all your computers and you do not have suitable
585rights to install binary packages, building from source lets you create your
586own tool set that you install under your home directory. Avoiding installing
587any extra packages as a super user is always helpful in maintaining a secure
588computing environment.
589
590[[_bugs]]
591Bugs, Crashes, and Build Failures
592---------------------------------
593
594The RTEMS Source Builder is a Python program and every care is taken to test
595the code however bugs, crashes, and build failure can and do happen. If you
596find a bug please report it via the RTEMS Bug tracker tool Bugzilla:
597
598https://www.rtems.org/bugzilla/
599
600or via email on the RTEMS Users list.
601
602Please include the:
603
604. Command line,
605. The git hash,
606. Host details with the output of the +uname -a+ command,
607. If you have made any modifications.
608
609If there is a crash please cut and paste the Python backtrace into the bug
610report. If the tools fail to build please locate the first error in the log
611file. This can be difficult to find on hosts with many cores so it sometimes
612pays to run the command with the +--jobs=none+ option to get a log that is
613correctly sequenced. If searching the log file seach for +error:+ and the error
614should be just above it.
615
616Project Sets
617------------
618
619The RTEMS Source Builder supports project configurations. Project
620configurations can be public or private and can be contained in the RTEMS
621Source Builder project if suitable, other projects they use the RTEM Source
622Builder or privately on your local file system.
623
624The configuration file loader searches the macro +_configdir+ and by default
625this is set to +%{\_topdir}/config:%{\_sbdir}/config+ where +_topdir+ is the
626your current working direct, in other words the directory you invoke the RTEMS
627Source Builder command in, and +_sbdir+ is the directory where the RTEMS Source
628Builder command resides. Therefore the +config+ directory under each of these
629is searched so all you need to do is create a +config+ in your project and add
630your configuration files. They do not need to be under the RTEMS Source Builder
631source tree. Public projects are included in the main RTEMS Source Builder such
632as RTEMS.
633
634You can also add your own +patches+ directory next to your +config+ directory
635as the +%patch+ command searches the +_patchdir+ macro variable and it is
636by default set to +%{\_topdir}/patches:%{\_sbdir}/patches+.
637
638The +source-builder/config+ directory provides generic scripts for building
639various tools. You can specialise these in your private configurations to make
640use of them. If you add new generic configurations please contribute them back
641to the project
642
643RTEMS Configurations
644~~~~~~~~~~~~~~~~~~~~
645
646The RTEMS Configurations are grouped by RTEMS version. In RTEMS the tools are
647specific to a specific version because of variations between Newlib and
648RTEMS. Restructuring in RTEMS and Newlib sometimes moves _libc_ functionality
649between these two parts and this makes existing tools incompatible with RTEMS.
650
651RTEMS allows architectures to have different tool versions and patches. The
652large number of architectures RTEMS supports can make it difficult to get a
653common stable version of all the packages. An architecture may require a recent
654GCC because an existing bug has been fixed, however the more recent version may
655have a bug in other architecture. Architecture specific patches should be
656limited to the architecture it relates to. The patch may fix a problem on the
657effect architecture however it could introduce a problem in another
658architecture. Limit exposure limits any possible crosstalk between
659architectures.
660
661RTEMS supports _stable_ and _unstable_. Stable configurations are fixed while
662unstable configurations are supporting using snapshots of user macros and
663reference release candidates or source extracted directly from version
664control. The stable build sets are referenced as +<version>/rtems-<arch>+ and
665include `autoconf` and `automake`.
666
667If you are building a released version of RTEMS the release RTEMS tar file will
668be downloaded and built as part of the build process. If you are building a
669tool set for use with the development branch of RTEMS, the development branch
670will be cloned directly from the RTEMS GIT repository and built.
671
672When building RTEMS within the RTEMS Source Builder it needs a suitable working
673`autoconf` and `automake`. These packages need to built and installed in their
674prefix in order for them to work. The RTEMS Source Builder installs all
675packages only after they have been built so if you host does not have a
676recent enough version of `autoconf` and `automake` you first need to build them
677and install them then build your tool set. The commands are:
678
679-------------------------------------------------------------
680$ ../source-builder/sb-set-builder --log=l-4.11-at.txt \
681   --prefix=$HOME/development/rtems/4.11 4.11/rtems-autotools
682$ export PATH=~/development/rtems/4.11/bin:$PATH <1>
683$ ../source-builder/sb-set-builder --log=l-4.11-sparc.txt \
684   --prefix=$HOME/development/rtems/4.11 4.11/rtems-sparc
685-------------------------------------------------------------
686<1> Setting the path.
687
688TIP: If this is your first time building the tools and RTEMS it pays to add the
689`--dry-run` option. This will run through all the configuration files and if
690any checks fail you will see this quickly rather than waiting for until the
691build fails a check.
692
693To build snapshots for testing purposes you use the available macro maps
694passing them on the command line using the `--macros` option. For RTEMS these
695are held in `config/snapshots` directory. The following builds _newlib_ from
696CVS:
697
698-------------------------------------------------------------
699$ ../source-builder/sb-set-builder --log=l-4.11-sparc.txt \
700   --prefix=$HOME/development/rtems/4.11 \
701   --macros=snapshots/newlib-head.mc \
702   4.11/rtems-sparc
703-------------------------------------------------------------
704
705and the following uses the version control heads for _binutils_, _gcc_,
706_newlib_, _gdb_ and _RTEMS_:
707
708-------------------------------------------------------------
709$ ../source-builder/sb-set-builder --log=l-heads-sparc.txt \
710   --prefix=$HOME/development/rtems/4.11-head \
711   --macros=snapshots/binutils-gcc-newlib-gdb-head.mc \
712   4.11/rtems-sparc
713-------------------------------------------------------------
714
715Cross Building
716--------------
717
718Cross building or Canadian cross compiling is the process of building a set of
719RTEMS tools for one type of host on another host. The RSB is a source builder
720so the need for this is not often called on because you can just build the
721tools for the host you wish to run on. There are however a few special cases
722where this is needed. The host may not have a stable reliable means of building
723the tools, such as Windows, or you wish to manage the configuration of tools on
724different hosts from a single environment because of auditing or verfication
725reasons.
726
727Canadian Cross Building
728~~~~~~~~~~~~~~~~~~~~~~~
729
730The process of building cross compilers on one host for another host is
731commonly referred to as a Canadian cross build. The process is controlled by
732setting the build triplet to the host you are building, the host triplet to the
733host the tools will run on and the target to the RTEMS architecture you
734require. The tools needed by the RSB are:
735
736. Build host C and C++ compiler
737. Host C and C++ cross compiler
738
739The RTEMS Source Builder requires you provide the build host C and C\++
740compiler and the final host C and C\++ cross-compiler. The RSB will build the
741build host RTEMS compiler and the final host RTEMS C and C++ compiler, the
742output of this process.
743
744The Host C and C++ compiler is a cross-compiler that builds executables for
745the host you want the tools for. You need to provide these tools. For Windows a
746number of Unix operating systems provide MinGW tool sets as packages.
747
748The RSB will build an RTEMS tool set for the build host. This is needed when
749building the final host's RTEMS compiler as it needs to build RTEMS runtime
750code such as _libc_ on the build host.
751
752TIP: Make sure the host's cross-compiler tools are in your path before run the
753RSB build command.
754
755Command Line
756~~~~~~~~~~~~
757
758To perform a cross build add +--host=+ to the command line. For example to
759build a MinGW tool set on FreeBSD for Windows add +--host=mingw32+ if the cross
760compiler is +mingw32-gcc+:
761
762-------------------------------------------------------------
763$ ../source-builder/sb-set-builder --host=mingw32 \
764   --log=l-mingw32-4.11-sparc.txt \
765   --prefix=$HOME/development/rtems/4.11 \
766   4.11/rtems-sparc
767-------------------------------------------------------------
768
769If you are on a Linux Fedora build host with the MinGW packages installed the
770command line is:
771
772-------------------------------------------------------------
773$ ../source-builder/sb-set-builder --host=i686-w64-mingw32 \
774   --log=l-mingw32-4.11-sparc.txt \
775   --prefix=$HOME/development/rtems/4.11 \
776   4.11/rtems-sparc
777-------------------------------------------------------------
778
779Configuration
780-------------
781
782The RTEMS Source Builder has two types of configuration data:
783
784. Build Sets
785. Package Build Configurations
786
787By default these files can be located in two separate directories and
788searched. The first directory is +config+ in your current working directory
789(+_topdir+) and the second is +config+ located in the base directory of the
790RTEMS Source Builder command you run (+_sbdir+). The RTEMS directory +rtems+
791located at the top of the RTEMS Source Builder source code is an example of a
792specific build configuration directory. You can create custom or private build
793configurations and if you run the RTEMS Source Builder command from that
794directory your configurations will be used.
795
796[[X1]] The configuration search path is a macro variable and is reference as
797+%\{_configdir\}+. It's default is defined as:
798
799-------------------------------------------------------------
800_configdir          : dir      optional   %{_topdir}/config:%{_sbdir}/config <1>
801-------------------------------------------------------------
802
803<1> The +_topdir+ is the directory you run the command from and +_sbdir+ is the
804location of the RTEMS Source Builder command.
805
806Build set files have the file extension +.bset+ and the package build
807configuration files have the file extension of +.cfg+. The +sb-set-builder+
808command will search for _build sets_ and the +sb-builder+ commands works with
809package build configuration files.
810
811Both types of configuration files use the \'#' character as a comment
812character. Anything after this character on the line is ignored. There is no
813block comment.
814
815Source and Patches
816~~~~~~~~~~~~~~~~~~
817
818The RTEMS Source Builder provides a flexible way to manage source. Source and
819patches are declare in configurations file using the +source+ and +patch+
820directives. There are a single line containing a Universal Resource Location or
821URL and can contain macros and shell expansions. The <<_prep,%prep>> section
822details the source and patch directives
823
824The URL can reference remote and local source and patch resources. The
825following schemes are provided:
826
827'http':: Remote access using the HTTP protocol.
828'https':: Remote access using the Secure HTTP protocol.
829'ftp:: Remote access using the FTP protocol.
830'git:: Remote access to a GIT repository.
831'cvs:: Remote access to a CVS repository.
832'file:: Local access to an existing source directory.
833
834HTTP, HTTPS, and FTP
835^^^^^^^^^^^^^^^^^^^^
836
837Remote access to TAR files is provided using HTTP, HTTPS and FTP protocols. The
838full URL provided is used to access the remote file including any query
839components. The URL is parsed to extract the file component and the local
840source directory is checked for that file. If the file is located the remote
841file is not downloaded. Currently no other checks are made. If a download fails
842you need to manually remove the file from the source directory and start the
843build process again.
844
845The URL can contain macros. These are expand before issuing the request to
846download the file. The GNU GCC compiler source URL is:
847
848-------------------------------------------------------------
849Source0: ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
850-------------------------------------------------------------
851
852The type of compression is automatically detected from the file extension. The
853supported compression formats are:
854
855`gz`:: GNU ZIP
856`bzip2`:: BZIP2 ??
857`zip`:: ??
858'xy':: XY ??
859
860The output of the decompression tool is feed to the standard `tar` utility and
861unpacked into the build directory.
862
863If the URL references the GitHub API server 'https://api.github.com/' a tarball
864of the specified version is download. For example the URL for the STLINK
865project on GitHub and version is:
866
867-------------------------------------------------------------
868%define stlink_version 3494c11
869Source0: https://api.github.com/repos/texane/stlink/texane-stlink-%{stlink_version}.tar.gz
870-------------------------------------------------------------
871
872the TAR file is downloaded and used.
873
874GIT
875^^^
876
877A GIT repository can be cloned and used as source. The GIT repository resides
878in the 'source' directory under the `git` directory. You can edit, update and
879use the repository as you normally do and the results will used to build the
880tools. This allows you to prepare and test patches in the build environment the
881tools are built in. The GIT URL only supports the GIT protocol. You can control
882the repository via the URL by appending options and arguments to the GIT
883path. The options are delimited by `?` and option arguments are delimited from
884the options with `=`. The options are:
885
886`branch`:: Checkout the specified branch.
887`pull`:: Perform a pull to update the repository.
888`fetch`:: Perform a fetch to get any remote updates.
889`reset`:: Reset the repository. Useful to remove any local changes. You can
890pass the `hard` argument to force a hard reset.
891
892-------------------------------------------------------------
893Source0: git://gcc.gnu.org/git/gcc.git?branch=gcc-4_7-branch?reset=hard
894-------------------------------------------------------------
895
896This will clone the GCC git repository and checkout the 4.7-branch and perform
897a hard reset.
898
899CVS
900^^^
901
902A CVS repository can be checked out. CVS is more complex than GIT to handle
903because of the modules support. This can effect the paths the source ends up
904in. The CVS URL only supports the CVS protocol. You can control the repository
905via the URL by appending options and arguments to the CVS path. The options are
906delimited by `?` and option arguments are delimited from the options with
907`=`. The options are:
908
909`module`:: The module to checkout.
910`src-prefix`:: The path into the source where the module starts.
911`tag`:: The CVS tag to checkout.
912`date`:: The CVS date to checkout.
913
914-------------------------------------------------------------
915Source0: cvs://pserver:anoncvs@sourceware.org/cvs/src?module=newlib?src-prefix=src
916-------------------------------------------------------------
917
918Macros and Defaults
919~~~~~~~~~~~~~~~~~~~
920
921The RTEMS Source Builder uses tables of _macros_ read in when the tool
922runs. The initial global set of macros is called the _defaults_. These values
923are read from a file called `defaults.mc` and modified to suite your host. This
924host specific adaption lets the Source Builder handle differences in the build
925hosts.
926
927Build set and configuration files can define new values updating and extending
928the global macro table. For example builds are given a release number. This is
929typically a single number at the end of the package name. For example:
930
931-------------------------------------------------------------
932%define release 1
933-------------------------------------------------------------
934
935Once defined if can be accessed in a build set or package configuration file
936with:
937
938-------------------------------------------------------------
939%{release}
940-------------------------------------------------------------
941
942The +sb-defaults+ command lists the defaults for your host. I will not include
943the output of this command becauses of its size.
944
945-------------------------------------------------------------
946$ ../source-builder/sb-defaults
947-------------------------------------------------------------
948
949A nested build set is given a separate copy of the global macro maps. Changes
950in one change set are not seen in other build sets. That same happens with
951configuration files unless inline includes are used. Inline includes are seen
952as part of the same build set and configuration and changes are global to that
953build set and configuration.
954
955Macro Maps and Files
956^^^^^^^^^^^^^^^^^^^^
957
958Macros are read in from files when the tool starts. The default settings are
959read from the defaults macro file called `defaults.mc` located in the top level
960RTEMS Source Builder command directory. User macros can be read in at start up
961by using the `--macros` command line option.
962
963The format for a macro in macro files is:
964
965[options="header,compact",width="50%",cols="15%,15%,15%,55%"]
966|=================================
967| Name | Type | Attribute | String
968|=================================
969
970where 'Name' is a case insensitive macro name, the 'Type' field is:
971
972[horizontal]
973`none`:: Nothing, ignore.
974`dir`:: A directory path.
975`exe`:: An executable path.
976`triplet`:: A GNU style architecture, platform, operating system string.
977
978the 'Attribute' field is:
979
980[horizontal]
981`none`:: Nothing, ignore
982`required`:: The host check must find the executable or path.
983`optional`:: The host check generates a warning if not found.
984`override`:: Only valid outside of the `global` map to indicate this macro
985             overrides the same one in the `global` map when the map containing
986             it is selected.
987`undefine`:: Only valid outside of the `global` map to undefine the macro if it
988             exists in the `global` map when the map containing it is
989             selected. The `global` map's macro is not visible but still
990             exists.
991
992and the 'String' field is a single or tripled multiline quoted string. The
993'String' can contain references to other macros. Macro that loop are not
994currently detected and will cause the tool to lock up.
995
996Maps are declared anywhere in the map using the map directive:
997
998-------------------------------------------------------------
999# Comments
1000[my-special-map] <1>
1001_host:  none, override, 'abc-xyz'
1002multiline: none, override, '''First line,
1003second line,
1004and finally the last line'''
1005-------------------------------------------------------------
1006<1> The map is set to `my-special-map`.
1007
1008Any macro defintions following a map declaration are placed in that map and the
1009default map is `global` when loading a file. Maps are selected in configuration
1010files by using the `%select` directive.
1011
1012-------------------------------------------------------------
1013%select my-special-map
1014-------------------------------------------------------------
1015
1016Selecting a map means all requests for a macro first check the selected map and
1017if present return that value else the `global` map is used. Any new macros or
1018changes update only the `global` map. This may change in future releases so
1019please make sure you use the `override` attibute.
1020
1021The macro files specificed on the command line are looked for in the
1022`_configdir` paths. See <<X1,+_configdir+>> variable for details. Included
1023files need to add the `%{_configdir}` macro to the start of the file.
1024
1025Macro map files can include other macro map files using the `%include`
1026directive. The macro map to build _binutils_, _gcc_, _newlib_, _gdb_ and
1027_RTEMS_ from version control heads is:
1028
1029-------------------------------------------------------------
1030# <1>
1031# Build all tool parts from version control head.
1032#
1033%include %{_configdir}/snapshots/binutils-head.mc
1034%include %{_configdir}/snapshots/gcc-head.mc
1035%include %{_configdir}/snapshots/newlib-head.mc
1036%include %{_configdir}/snapshots/gdb-head.mc
1037-------------------------------------------------------------
1038<1> The file is `config/snapshots/binutils-gcc-newlib-gdb-head.mc`.
1039
1040The macro map defaults to `global` at the start of each included file and the
1041map setting of the macro file including the other macro files does not change.
1042
1043Personal Macros
1044^^^^^^^^^^^^^^^
1045
1046When the tools start to run they will load personal macros. Personal macros are
1047in the standard format for macros in a file. There are two places personal
1048macros can be configured. The first is the environment variable
1049`RSB_MACROS`. If presentthe macros from the file the environment variable
1050points to are loaded. The second is a file called `.rsb_macros` in your home
1051directory. You need to have the environment variable `HOME` defined for this
1052work.
1053
1054Report Mailing
1055~~~~~~~~~~~~~~
1056
1057The build reports can be mailed to a specific email address to logging and
1058monitoring. Mailing requires a number of parameters to function. These are:
1059
1060. To mail address
1061. From mail address
1062. SMTP host
1063
1064.To Mail Address
1065
1066The +to+ mail address is taken from the macro `%{_mail_tools_to}` and the
1067default is _rtems-tooltestresults at rtems.org_. You can override the default
1068with a personal or user macro file or via the command line option _--mail-to_.
1069
1070.From Mail Address
1071
1072The +from+ mail address is taken from:
1073
1074. GIT configuration
1075. User `.mailrc` file
1076. Command line
1077
1078If you have configured an email and name in git it will be used used. If you do
1079not a check is made for a `.mailrc` file. The environment variable _MAILRC_ is
1080used if present else your home directory is check. If found the file is scanned
1081for the `from` setting:
1082
1083  set from="Foo Bar <foo@bar>"
1084
1085You can also support a from address on the command line with the _--mail-from_
1086option.
1087
1088.SMTP Host
1089
1090The SMTP host is taken from the macro `%{_mail_smtp_host}` and the default is
1091`localhost`. You can override the default with a personal or user macro file or
1092via the command line option _--smtp-host_.
1093
1094Build Set Files
1095~~~~~~~~~~~~~~~
1096
1097Build set files lets you list the packages in the build set you are defining
1098and have a file extension of +.bset+. Build sets can define macro variables,
1099inline include other files and reference other build set or package
1100configuration files.
1101
1102Defining macros is performed with the +%define+ macro:
1103
1104-------------------------------------------------------------
1105%define _target m32r-rtems4.11
1106-------------------------------------------------------------
1107
1108Inline including another file with the +%include+ macro continues processing
1109with the specified file returning to carry on from just after the include
1110point.
1111
1112-------------------------------------------------------------
1113%include rtems-4.11-base.bset
1114-------------------------------------------------------------
1115
1116This includes the RTEMS 4.11 base set of defines and checks. The configuration
1117paths as defined by +_configdir+ are scanned. The file extension is optional.
1118
1119You reference build set or package configuration files by placing the file name
1120on a single line.
1121
1122-------------------------------------------------------------
1123tools/rtems-binutils-2.22-1
1124-------------------------------------------------------------
1125
1126The +_configdir+ path is scanned for +tools/rtems-binutils-2.22-1.bset+ or
1127+tools/rtems-binutils-2.22-1.cfg+. Build set files take precedent over package
1128configuration files. If +tools/rtems-binutils-2.22-1+ is a build set a new
1129instance of the build set processor is created and if the file is a package
1130configuration the package is built with the package builder. This all happens
1131once the build set file has finished being scanned.
1132
1133Configuration Control
1134~~~~~~~~~~~~~~~~~~~~~
1135
1136The RTEMS Souce Builder is designed to fit within most verification and
1137validation processes. All of the RTEMS Source Builder is source code. The
1138Python code is source and comes with a commercial friendly license. All
1139configuration data is text and can be read or parsed with standard text based
1140tools.
1141
1142File naming provides configuration management. A specific version of a package
1143is captured in a specific set of configuration files. The top level
1144configuration file referenced in a _build set_ or passed to the +sb-builder+
1145command relates to a specific configuration of the package being built. For
1146example the RTEMS configuration file +rtems-gcc-4.7.2-newlib-2.0.0-1.cfg+
1147creates an RTEMS GCC and Newlib package where the GCC version is 4.7.2, the
1148Newlib version is 2.0.0, plus any RTEMS specific patches that related to this
1149version. The configuration defines the version numbers of the various parts
1150that make up this package:
1151
1152-------------------------------------------------------------
1153%define gcc_version    4.7.2
1154%define newlib_version 2.0.0
1155%define mpfr_version   3.0.1
1156%define mpc_version    0.8.2
1157%define gmp_version    5.0.5
1158-------------------------------------------------------------
1159
1160The package build options, if there are any are also defined:
1161
1162-------------------------------------------------------------
1163%define with_threads 1
1164%define with_plugin  0
1165%define with_iconv   1
1166-------------------------------------------------------------
1167
1168The generic configuration may provide defaults in case options are not
1169specified. The patches this specific version of the package requires can be
1170included:
1171
1172-------------------------------------------------------------
1173Patch0: gcc-4.7.2-rtems4.11-20121026.diff
1174-------------------------------------------------------------
1175
1176Finally including the GCC 4.7 configuration script:
1177
1178-------------------------------------------------------------
1179%include %{_configdir}/gcc-4.7-1.cfg
1180-------------------------------------------------------------
1181
1182The +gcc-4.7-1.cfg+ file is a generic script to build a GCC 4.7 compiler with
1183Newlib. It is not specific to RTEMS. A bare no operating system tool set can be
1184built with this file.
1185
1186The +-1+ part of the file names is a revision. The GCC 4.7 script maybe revised
1187to fix a problem and if this fix effects an existing script the file is copied
1188and given a +-2+ revision number. Any dependent scripts referencing the earlier
1189revision number will not be effected by the change. This locks down a specific
1190configuration over time.
1191
1192Snapshot Testing
1193~~~~~~~~~~~~~~~~
1194
1195Testing of release canidates and snapshots is important to those helping
1196maintain tool sets. The RTEMS Source Builder helps by providing a simple and
1197flexible way to use existing build sets and configuration without needing to
1198change them or creating new temporary build sets and configurations.
1199
1200The process uses snapshot macro files loaded via the command line option
1201`--macros`. These files provide macros that override the standard build set and
1202configuration file macros.
1203
1204Lets consider testing a GCC 4.7 snapshot for RTEMS 4.11. Lets assume the
1205current RTEMS 4.11 tools reference GCC 4.7.3 with a patch as the stable tool
1206set. We want to use a recent snapshot with no patches. In the
1207`rtems/config/snapshots` directoy create a file called `gcc-4.7-snapshot.mc`
1208containing:
1209
1210-------------------------------------------------------------
1211[gcc-4.7-snapshot]
1212GCC_Version: none, override, '4.7-20130413'
1213Source0:     none, override, 'http://mirrors.kernel.org/sources.redhat.com/gcc/
1214snapshots/%{gcc_version}/gcc-%{gcc_version}.tar.bz2'
1215Patch0:      none, udefine,  ''
1216-------------------------------------------------------------
1217
1218In the standard configuration file `source-builder/config/gcc-4.7-1.cfg` the
1219map is selected with:
1220
1221-------------------------------------------------------------
1222#
1223# Select the GCC 4.7 Snapshot Macro Map
1224#
1225%select gcc-4.7-snapshot
1226-------------------------------------------------------------
1227
1228On the command line add `--macros=snapshots/gcc-4.7-snapshot.mc` and this
1229snapshot will be built. With careful use of the `--prefix` option you can
1230locate the tools in a specific directory and test them without needing to
1231effect your production environment.
1232
1233Scripting
1234~~~~~~~~~
1235
1236Configuration files specify how to build a package. Configuration files are
1237scripts and have a +.cfg+ file extension. The script format is based loosely on
1238the RPM spec file format however the use and purpose in this tool does not
1239compare with the functionality and therefore the important features of the spec
1240format RPM needs and uses.
1241
1242The script language is implemented in terms of macros. The built-in list is:
1243
1244[horizontal]
1245+%{}+:: Macro expansion with conditional logic.
1246+%()+:: Shell expansion.
1247+%prep+:: The source preparation shell commands.
1248+%build+:: The build shell commands.
1249+%install+:: The package install shell commands.
1250+%clean+:: The package clean shell commands.
1251+%include+:: Inline include another configuration file.
1252+%name+:: The name of the package.
1253+%summary+:: A brief package description. Useful when reporting about a build.
1254+%release+:: The package release. A number that is the release as built by this tool.
1255+%version+:: The package's version string.
1256+%buildarch+:: The build architecture.
1257+%setup+:: Setup a source package.
1258+%source+:: Define a source code package. This macro has a number appended.
1259+%patch+:: Define a patch. This macro has a is number appended.
1260+%echo+:: Print the following string as a message.
1261+%warning+:: Print the following string as a warning and continue.
1262+%error+:: Print the following string as an error and exit.
1263+%select+:: Select the macro map. If there is no map nothing is reported.
1264+%define+:: Define a macro. Macros cannot be redefined, you must first undefine it.
1265+%undefine+:: Undefine a macro.
1266+%if+:: Start a conditional logic block that ends with a +%endif+.
1267+%ifn+:: Inverted start of a conditional logic block.
1268+%ifarch+:: Test the architecture against the following string.
1269+%ifnarch+:: Inverted test of the architecture
1270+%ifos+:: Test the host operating system.
1271+%else+:: Start the _else_ conditional logic block.
1272+%endfi+:: End the conditional logic block.
1273+%bconf_with+:: Test the build condition _with_ setting. This is the +--with-*+
1274command line option.
1275+%bconf_without+:: Test the build condition _without_ setting. This is the
1276+--without-*+ command line option.
1277
1278Expanding
1279^^^^^^^^^
1280
1281A macro can be `%{string}` or the equivalent of `%string`. The following macro
1282expansions supported are:
1283
1284`%{string}`;;
1285Expand the 'string' replacing the entire macro text with the text in the table
1286for the entry 'string . For example if 'var' is 'foo' then `${var}` would
1287become `foo`.
1288
1289`%{expand: string}`;;
1290Expand the 'string' and then use it as a ``string'' to the macro expanding the
1291macro. For example if _foo_ is set to 'bar' and 'bar' is set to 'foobar' then
1292`%{expand:foo}` would result in `foobar`. Shell expansion can also be used.
1293
1294`%{with string}`;;
1295Expand the macro to '1' if the macro `with_`'string' is defined else expand to
1296_0_. Macros with the name `with_`'string' can be define with command line
1297arguments to the RTEMS Source Builder commands.
1298
1299`%{defined string}`;;
1300Expand the macro to '1' if a macro of name 'string' is defined else expand to '0'.
1301
1302`%{?string: expression}`;;
1303Expand the macro to 'expression' if a macro of name 'string' is defined else expand to `%{nil}`.
1304
1305`%{!?string: expression}`;;
1306Expand the macro to 'expression' if a macro of name 'string' is not defined. If
1307the macro is define expand to `%{nil}`.
1308
1309`%(expression)`;;
1310Expand the macro to the result of running the 'expression' in a host shell. It
1311is assumed this is a Unix type shell. For example `%(whoami)` will return your
1312user name and `%(date)` will return the current date string.
1313
1314%prep
1315^^^^^
1316
1317The +%prep+ macro starts a block that continues until the next block macro. The
1318_prep_ or preparation block defines the setup of the package's source and is a
1319mix of RTEMS Source Builder macros and shell scripting. The sequence is
1320typically +%setup+ macros for source, +%patch+ macros to patch the source
1321mixed with some shell commands to correct any source issues.  A +%prep+ section
1322starts with a +%setup+ command. This creates the package source top level
1323directory then is followed by the first source file.
1324
1325-------------------------------------------------------------
1326                     <1>       <2>
1327%setup -q -c -T -n %{name}-%{version}
1328%setup -q -T -D -n %{name}-%{version} -a0
1329-------------------------------------------------------------
1330
1331<1> The package's name.
1332<2> The version of the package.
1333
1334The source for a package is declared with the +%source*+ macro where +*+ is
1335a number. For example +%source0+ is the source 0 tar file and is defined with
1336something similar to this:
1337
1338-------------------------------------------------------------
1339Source0: http://ftp.gnu.org/gnu/gdb/gdb-%{gdb_version}.tar.bz2
1340-------------------------------------------------------------
1341
1342This URL is the primary location of the GNU GCC source code and the RTEMS
1343Source Builder can download the file from this location and by inspecting the
1344file extension use +bzip2+ decompression. When the +%prep+ section is processed
1345a check of the local +source+ directory is made to see if the file has already
1346been downloaded. If not found in the source cache directory the package is
1347downloaded from the URL. You can append other base URLs via the command line
1348option +--url+. This option accepts a comma delimited list of sites to try.
1349
1350You can combine the source macro with conditional logic to implement a default
1351that can be over-riden in the top level files. This lets you reuse a generic
1352build script with different sources. This happens if you have a private source
1353package with local modifications. The following example is taken from the
1354+gcc-4.8-1.cfg+ build script.
1355
1356-------------------------------------------------------------
1357%ifn %{defined Source0}
1358 Source0: ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
1359%endif
1360-------------------------------------------------------------
1361
1362You could optionally have a few source files that make up the package. For
1363example GNU's GCC was a few tar files for a while and it is now a single tar
1364file. Support for multiple source files can be conditionally implemented with
1365the following scripting:
1366
1367-------------------------------------------------------------
1368%{?source1:%setup -q -T -D -n %{name}-%{version} -a1}
1369-------------------------------------------------------------
1370
1371The +source1+ macro value is checked and if present the command string after
1372the +:+ is executed. It is common to see a number of these present allowing top
1373level configuration files including a base configuration the ability to define
1374a number of source packages.
1375
1376-------------------------------------------------------------
1377%{?source1:%setup -q -T -D -n %{name}-%{version} -a1}
1378%{?source2:%setup -q -T -D -n %{name}-%{version} -a2}
1379%{?source3:%setup -q -T -D -n %{name}-%{version} -a3}
1380-------------------------------------------------------------
1381
1382Patching also occurs during the preparation stage. Patches are handled in a
1383similar way to the source packages. Most patches are based around the top of
1384the source tree. This is an example of the patch scripting for the GCC 4.8
1385series of compilers:
1386
1387-------------------------------------------------------------
1388cd gcc-%{gcc_version} <1>
1389%{?patch0:%patch0 -p1} <2>
1390%{?patch1:%patch1 -p1}
1391%{?patch2:%patch2 -p1}
1392%{?patch3:%patch3 -p1}
1393%{?patch4:%patch4 -p1}
1394%{?patch5:%patch5 -p1}
1395%{?patch6:%patch6 -p1}
1396%{?patch7:%patch7 -p1}
1397%{?patch8:%patch8 -p1}
1398%{?patch9:%patch9 -p1}
1399cd .. <3>
1400-------------------------------------------------------------
1401
1402<1> Change from the top of the source tree into the package being patched's top
1403    directory.
1404<2> The conditional macro expansion checks if +%patch0+ is defined and if
1405    defined issues the +%patch0" macro giving +-p1+ to the patch command.
1406<3> Return back to the top of the source tree.
1407
1408%build
1409^^^^^^
1410
1411The +%build+ macro starts a block that continues until the next block
1412macro. The build block is a series of shell commands that execute to build the
1413package. It assumes all source code has been unpacked, patch and adjusted so
1414the build will succeed.
1415
1416The following is an example take from the GutHub STLink project:
1417
1418NOTE: STLink is a JTAG debugging device for the ST ARM family of processors.
1419
1420-------------------------------------------------------------
1421%build
1422  export PATH="%{_bindir}:${PATH}" <1>
1423
1424  cd texane-stlink-%{stlink_version} <2>
1425
1426  ./autogen.sh <3>
1427
1428%if "%{_build}" != "%{_host}"
1429  CFLAGS_FOR_BUILD="-g -O2 -Wall" \ <4>
1430%endif
1431  CPPFLAGS="-I $SB_TMPPREFIX/include/libusb-1.0" \ <5>
1432  CFLAGS="$SB_OPT_FLAGS" \
1433  LDFLAGS="-L $SB_TMPPREFIX/lib" \
1434  ./configure \ <6>
1435    --build=%{_build} --host=%{_host} \
1436    --verbose \
1437    --prefix=%{_prefix} --bindir=%{_bindir} \
1438    --exec-prefix=%{_exec_prefix} \
1439    --includedir=%{_includedir} --libdir=%{_libdir} \
1440    --mandir=%{_mandir} --infodir=%{_infodir}
1441
1442  %{__make} %{?_smp_mflags} all <7>
1443
1444  cd ..
1445-------------------------------------------------------------
1446
1447<1> Setup the PATH environment variable. This is not always needed.
1448<2> This package builds in the source tree so enter it.
1449<3> The package is actually checked directly out from the github project and so
1450    it needs its autoconf and automake files generated.
1451<4> Flags for a cross-compiled build.
1452<5> Various settings passed to configure to customise the build. In this
1453    example an include path is being set to the install point of _libusb_. This
1454    package requires _libusb_ is built before it.
1455<6> The +configure+ command. The RTEMS Source Builder provides all the needed
1456    paths as macro variables. You just need to provide them to +configure+.
1457<7> Running make. Do not use +make+ directly, use the RTEMS Source Builder's
1458    defined value. This value is specific to the host. A large number of
1459    packages need GNU make and on BSD systems this is +gmake+. You can
1460    optionally add the SMP flags if the packages build system can handle
1461    parallel building with multiple jobs. The +_smp_mflags+ value is
1462    automatically setup for SMP hosts to match the number of cores the host has.
1463
1464%install
1465^^^^^^^^
1466
1467The +%install+ macro starts a block that continues until the next block
1468macro. The install block is a series of shell commands that execute to install
1469the package. You can assume the package has build correctly when this block
1470starts executing.
1471
1472Never install the package to the actual _prefix_ the package was built
1473with. Always install to the RTEMS Source Builder's temporary path defined in
1474the macro variable +\__tmpdir+. The RTEMS Source Builder sets up a shell
1475environment variable called +SB_BUILD_ROOT+ as the standard install point. Most
1476packages support adding +DESTDIR=+ to the _make install_ command.
1477
1478Looking at the same example as in <<_build, %build>>:
1479
1480-------------------------------------------------------------
1481%install
1482  export PATH="%{_bindir}:${PATH}" <1>
1483  rm -rf $SB_BUILD_ROOT <2>
1484
1485  cd texane-stlink-%{stlink_version} <3>
1486  %{__make} DESTDIR=$SB_BUILD_ROOT install <4>
1487
1488  cd ..
1489-------------------------------------------------------------
1490
1491<1> Setup the PATH environment variable. This is not always needed.
1492<2> Clean any installed files. This make sure the install is just what
1493    the package installs and not any left over files from a broken build or
1494    install.
1495<3> Enter the build directory. In this example it just happens to be the source
1496    directory.
1497<4> Run +make install+ to install the package overriding the +DESTDIR+ make
1498    variable.
1499
1500%clean
1501^^^^^^
1502
1503The +%clean+ macro starts a block that continues until the next block
1504macro. The clean block is a series of shell commands that execute to clean up
1505after a package has been built and install. This macro is currenly not been
1506used because the RTEMS Source Builder automatically cleans up.
1507
1508%include
1509^^^^^^^^
1510
1511The +%include+ macro inline includes the specific file. The +\__confdir+
1512path is searched. Any relative path component of the include file is appended
1513to each part of the +\__configdir+. Adding an extension is optional as files
1514with +.bset+ and +.cfg+ are automatically searched for.
1515
1516Inline including means the file is processed as part of the configuration at
1517the point it is included. Parsing continues from the next line in the
1518configuration file that contains the +%include+ macro.
1519
1520Including files allow a kind of configuration file reuse. The outer
1521configuration files provide specific information such as package version
1522numbers and patches and then include a generic configuration script which
1523builds the package.
1524
1525-------------------------------------------------------------
1526%include %{_configdir}/gcc-4.7-1.cfg
1527-------------------------------------------------------------
1528
1529%name
1530^^^^^
1531
1532The name of the package being built. The name typically contains the components
1533of the package and their version number plus a revision number. For the GCC
1534with Newlib configuration the name is typically:
1535
1536-------------------------------------------------------------
1537Name: %{_target}-gcc-%{gcc_version}-newlib-%{newlib_version}-%{release}
1538-------------------------------------------------------------
1539
1540%summary
1541^^^^^^^^
1542
1543The +%summary+ is a brief description of the package. It is useful when
1544reporting. This information is not capture in the package anywhere. For the GCC
1545with Newlib configuration the summary is typically:
1546
1547-------------------------------------------------------------
1548Summary: GCC v%{gcc_version} and Newlib v%{newlib_version} for target %{_target} on host %{_host}
1549-------------------------------------------------------------
1550
1551%release
1552^^^^^^^^
1553
1554The +%release+ is packaging number that allows revisions of a package to happen
1555where none package versions change. This value typically increases when the
1556configuration building the package changes.
1557
1558-------------------------------------------------------------
1559%define release 1
1560-------------------------------------------------------------
1561
1562%version
1563^^^^^^^^
1564
1565The +%version% macro sets the version the package. If the package is a single
1566component it tracks that component's version number. For example in the
1567_libusb_ configuration the +%version+ is the same as +%libusb_version+, however
1568in a GCC with Newlib configuration there is no single version number. In this
1569case the GCC version is used.
1570
1571-------------------------------------------------------------
1572Version: %{gcc_version}
1573-------------------------------------------------------------
1574
1575%buildarch
1576^^^^^^^^^^
1577
1578The +%buildarch+ macro is set to the architecture the package contains. This is
1579currently not used in the RTEMS Source Builder and may go away. This macro is
1580more important in a real packaging system where the package could end up on the
1581wrong architecture.
1582
1583%setup
1584^^^^^^
1585
1586The +%setup+ macro sets up the source code tree and is used in the +%prep+
1587section of the script. The options are:
1588
1589[horizontal]
1590*Switch*:: *Description*
1591+-n+:: The -n option is used to set the name of the software's build
1592directory. This is necessary only when the source archive unpacks into a
1593directory named other than +<name>-<version>+.
1594+-c+:: The -c option is used to direct %setup to create the top-level build
1595directory before unpacking the sources.
1596+-D+:: The -D option is used to direct %setup to not delete the build directory
1597prior to unpacking the sources. This option is used when more than one source
1598archive is to be unpacked into the build directory, normally with the +-b+ or
1599+-a+ options.
1600+-T+:: The -T option is used to direct %setup to not perform the default
1601unpacking of the source archive specified by the first Source: macro. It is used
1602with the +-a+ or +-b+ options.
1603+-b <n>+:: The -b option is used to direct %setup to unpack the source archive
1604specified on the nth Source: macro line before changing directory into the build
1605directory.
1606+-a <n>+:: The -a option is used to direct %setup to unpack the source archive
1607specified on the nth Source: macro line after changing directory into the build
1608directory.
1609
1610%source
1611^^^^^^^
1612
1613The +%source+ macro is numbered and defines a source tar file used in the
1614package. The +%setup+ macro references the packages defined here. A macro is
1615defined as:
1616
1617-------------------------------------------------------------
1618Source0: ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
1619-------------------------------------------------------------
1620
1621The setup script is:
1622
1623-------------------------------------------------------------
1624%setup -q -T -D -n %{name}-%{version} -a0
1625-------------------------------------------------------------
1626
1627The +-a0+ means use +%source0+.
1628
1629%patch
1630^^^^^^
1631
1632The +%patch+ macro is numbered and can define a patch and in the +%prep+
1633section applies the patch. To define a patch append a +:+ followed by the patch
1634filename:
1635
1636-------------------------------------------------------------
1637Patch0: gcc-4.7.2-rtems4.11-20121026.diff
1638-------------------------------------------------------------
1639
1640The +__patchdir+ path is search.
1641
1642Placing +%patch+ in the +%prep+ section will apply it with any trailing options
1643passed to the +patch+ command. This allows the +-p+ option to be passed to
1644strip any leading path components from the patch contents.
1645
1646-------------------------------------------------------------
1647%patch0 -p1
1648-------------------------------------------------------------
1649
1650You will typically see the patch conditionally used as:
1651
1652-------------------------------------------------------------
1653%{patch0:%patch0 -p1}
1654-------------------------------------------------------------
1655
1656In this case the patch will only be applied if it is defined.
1657
1658%echo
1659^^^^^
1660
1661The +%echo+ macro outputs the following string to stdout. This can also be used
1662as `%{echo: message}`.
1663
1664%warning
1665^^^^^^^^
1666
1667The +%warning+ macro outputs the following string as a warning. This can also
1668be used as `%{warning: message}`.
1669
1670%error
1671^^^^^^
1672
1673The +%error+ macro outputs the follow string as an error and exits the RTEMS
1674Source Builder. This can also be used as `%{error: message}`.
1675
1676%select
1677^^^^^^^
1678
1679The +%select+ macro selects the map specified. If there is no map no error or
1680warning is generated. Macro maps provide a simple way for a user to override
1681the settings is a configuration file without having to edit it. The changes are
1682recorded in the build report so can be traced.
1683
1684Configuration use different maps so macro overrides can target a specific
1685package.
1686
1687The default map is `global'.
1688
1689-------------------------------------------------------------
1690%select gcc-4.8-snapshot <1>
1691%define one_plus_one 2 <2>
1692-------------------------------------------------------------
1693
1694<1> The map switches to `gcc-4.8-snapshot`. Any overrides in this map will be
1695    used.
1696<2> Defining macros only updates the `global` map and not the selected map.
1697
1698%define
1699^^^^^^^
1700
1701The +%define+ macro defines a new macro or updates an existing one. If no value
1702is given it is assumed to be 1.
1703
1704-------------------------------------------------------------
1705%define foo bar
1706%define one_plus_one 2
1707%define one <1>
1708-------------------------------------------------------------
1709
1710<1> The macro _one_ is set to 1.
1711
1712%undefine
1713^^^^^^^^^
1714
1715The +%undefine+ macro removes a macro if it exists. Any further references to
1716it will result in an undefine macro error.
1717
1718%if
1719^^^
1720
1721The +%if+ macro starts a conditional logic block that can optionally have a
1722_else_ section. A test follows this macro and can have the following operators:
1723
1724[horizontal]
1725*Operator*:: *Description*
1726+%{}+:: Check the macro is set or _true_, ie non-zero.
1727+
1728-------------------------------------------------------------
1729%if ${foo}
1730 %warning The test passes, must not be empty or is non-zero
1731%else
1732 %error The test fails, must be empty or zero
1733%endif
1734-------------------------------------------------------------
1735+!+:: The _not_ operator inverts the test of the macro.
1736+
1737-------------------------------------------------------------
1738%if ! ${foo}
1739 %warning The test passes, must be empty or zero
1740%else
1741 %error The test fails, must not be empty or is non-zero
1742%endif
1743-------------------------------------------------------------
1744+==+:: The left hand size must equal the right hand side. For example:
1745+
1746-------------------------------------------------------------
1747%define one 1
1748%if ${one} == 1
1749 %warning The test passes
1750%else
1751 %error The test fails
1752%endif
1753-------------------------------------------------------------
1754+
1755You can also check to see if a macro is empty:
1756+
1757-------------------------------------------------------------
1758%if ${nothing} == %{nil}
1759 %warning The test passes
1760%else
1761 %error The test fails
1762%endif
1763-------------------------------------------------------------
1764+!=+:: The left hand size does not equal the right hand side. For example:
1765+
1766-------------------------------------------------------------
1767%define one 1
1768%if ${one} != 2
1769 %warning The test passes
1770%else
1771 %error The test fails
1772%endif
1773-------------------------------------------------------------
1774+
1775You can also check to see if something is set:
1776+
1777-------------------------------------------------------------
1778%if ${something} != %{nil}
1779 %warning The test passes
1780%else
1781 %error The test fails
1782%endif
1783-------------------------------------------------------------
1784+>+:: The left hand side is numerically greater than the right hand side.
1785+>=+:: The left hand side is numerically greater than or equal to the right
1786hand side.
1787+<+:: The left hand side is numerically less than the right hand side.
1788+\<=+:: The left hand side is numerically less than or equal to the right hand
1789side.
1790
1791%ifn
1792^^^^
1793
1794The +%ifn+ macro inverts the normal +%if+ logic. It avoids needing to provide
1795empty _if_ blocks followed by _else_ blocks. It is useful when checking if a
1796macro is defined:
1797
1798-------------------------------------------------------------
1799%ifn %{defined foo}
1800 %define foo bar
1801%endif
1802-------------------------------------------------------------
1803
1804%ifarch
1805^^^^^^^
1806
1807The +%ifarch+ is a short cut for "+%if %{\_arch} == i386+". Currently not used.
1808
1809%ifnarch
1810^^^^^^^^
1811
1812The +%ifnarch+ is a short cut for "+%if %{\_arch} != i386+". Currently not
1813used.
1814
1815%ifos
1816^^^^^
1817
1818The +%ifos+ is a short cut for "+%if %{\_os} != mingw32+". It allows
1819conditional support for various operating system differences when building
1820packages.
1821
1822%else
1823^^^^^
1824
1825The +%else+ macro starts the conditional _else_ block.
1826
1827%endfi
1828^^^^^^
1829
1830The +%endif+ macro ends a conditional logic block.
1831
1832%bconf_with
1833^^^^^^^^^^^
1834
1835The +%bconf_with+ macro provides a way to test if the user has passed a
1836specific option on the command line with the +--with-<label>+ option. This
1837option is only available with the +sb-builder+ command.
1838
1839%bconf_without
1840^^^^^^^^^^^^^^
1841
1842The +%bconf_without+ macro provides a way to test if the user has passed a
1843specific option on the command line with the +--without-<label>+ option. This
1844option is only available with the +sb-builder+ command.
1845
1846
1847Commands
1848--------
1849
1850Checker (sb-check)
1851~~~~~~~~~~~~~~~~~~
1852
1853This commands checks your system is set up correctly. Most options are ignored.
1854
1855-------------------------------------------------------------
1856$ ../source-builder/sb-check --help
1857sb-check: [options] [args]
1858RTEMS Source Builder, an RTEMS Tools Project (c) 2012-2013 Chris Johns
1859Options and arguments:
1860--force                : Force the build to proceed
1861--quiet                : Quiet output (not used)
1862--trace                : Trace the execution
1863--dry-run              : Do everything but actually run the build
1864--warn-all             : Generate warnings
1865--no-clean             : Do not clean up the build tree
1866--always-clean         : Always clean the build tree, even with an error
1867--jobs                 : Run with specified number of jobs, default: num CPUs.
1868--host                 : Set the host triplet
1869--build                : Set the build triplet
1870--target               : Set the target triplet
1871--prefix path          : Tools build prefix, ie where they are installed
1872--topdir path          : Top of the build tree, default is $PWD
1873--configdir path       : Path to the configuration directory, default: ./config
1874--builddir path        : Path to the build directory, default: ./build
1875--sourcedir path       : Path to the source directory, default: ./source
1876--tmppath path         : Path to the temp directory, default: ./tmp
1877--macros file[,[file]  : Macro format files to load after the defaults
1878--log file             : Log file where all build out is written too
1879--url url[,url]        : URL to look for source
1880--no-download          : Disable the source downloader
1881--targetcflags flags   : List of C flags for the target code
1882--targetcxxflags flags : List of C++ flags for the target code
1883--libstdcxxflags flags : List of C++ flags to build the target libstdc++ code
1884--with-<label>         : Add the --with-<label> to the build
1885--without-<label>      : Add the --without-<label> to the build
1886--regression           : Set --no-install, --keep-going and --always-clean
1887$ ../source-builder/sb-check
1888RTEMS Source Builder - Check, v0.2.0
1889Environment is ok
1890-------------------------------------------------------------
1891
1892Defaults (sb-defaults)
1893~~~~~~~~~~~~~~~~~~~~~~
1894
1895This commands outputs and the default macros for your when given no
1896arguments. Most options are ignored.
1897
1898-------------------------------------------------------------
1899$ ../source-builder/sb-defaults --help
1900sb-defaults: [options] [args]
1901RTEMS Source Builder, an RTEMS Tools Project (c) 2012-2013 Chris Johns
1902Options and arguments:
1903--force                : Force the build to proceed
1904--quiet                : Quiet output (not used)
1905--trace                : Trace the execution
1906--dry-run              : Do everything but actually run the build
1907--warn-all             : Generate warnings
1908--no-clean             : Do not clean up the build tree
1909--always-clean         : Always clean the build tree, even with an error
1910--jobs                 : Run with specified number of jobs, default: num CPUs.
1911--host                 : Set the host triplet
1912--build                : Set the build triplet
1913--target               : Set the target triplet
1914--prefix path          : Tools build prefix, ie where they are installed
1915--topdir path          : Top of the build tree, default is $PWD
1916--configdir path       : Path to the configuration directory, default: ./config
1917--builddir path        : Path to the build directory, default: ./build
1918--sourcedir path       : Path to the source directory, default: ./source
1919--tmppath path         : Path to the temp directory, default: ./tmp
1920--macros file[,[file]  : Macro format files to load after the defaults
1921--log file             : Log file where all build out is written too
1922--url url[,url]        : URL to look for source
1923--no-download          : Disable the source downloader
1924--targetcflags flags   : List of C flags for the target code
1925--targetcxxflags flags : List of C++ flags for the target code
1926--libstdcxxflags flags : List of C++ flags to build the target libstdc++ code
1927--with-<label>         : Add the --with-<label> to the build
1928--without-<label>      : Add the --without-<label> to the build
1929--regression           : Set --no-install, --keep-going and --always-clean
1930-------------------------------------------------------------
1931
1932Set Builder (sb-set-builder)
1933~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1934
1935This command builds a set.
1936
1937-------------------------------------------------------------
1938$ ../source-builder/sb-set-builder --help
1939RTEMS Source Builder, an RTEMS Tools Project (c) 2012-2013 Chris Johns
1940Options and arguments:
1941--force                : Force the build to proceed
1942--quiet                : Quiet output (not used)
1943--trace                : Trace the execution
1944--dry-run              : Do everything but actually run the build
1945--warn-all             : Generate warnings
1946--no-clean             : Do not clean up the build tree
1947--always-clean         : Always clean the build tree, even with an error
1948--regression           : Set --no-install, --keep-going and --always-clean
1949---jobs                 : Run with specified number of jobs, default: num CPUs.
1950--host                 : Set the host triplet
1951--build                : Set the build triplet
1952--target               : Set the target triplet
1953--prefix path          : Tools build prefix, ie where they are installed
1954--topdir path          : Top of the build tree, default is $PWD
1955--configdir path       : Path to the configuration directory, default: ./config
1956--builddir path        : Path to the build directory, default: ./build
1957--sourcedir path       : Path to the source directory, default: ./source
1958--tmppath path         : Path to the temp directory, default: ./tmp
1959--macros file[,[file]  : Macro format files to load after the defaults
1960--log file             : Log file where all build out is written too
1961--url url[,url]        : URL to look for source
1962--no-download          : Disable the source downloader
1963--no-install           : Do not install the packages to the prefix
1964--targetcflags flags   : List of C flags for the target code
1965--targetcxxflags flags : List of C++ flags for the target code
1966--libstdcxxflags flags : List of C++ flags to build the target libstdc++ code
1967--with-<label>         : Add the --with-<label> to the build
1968--without-<label>      : Add the --without-<label> to the build
1969--mail-from            : Email address the report is from.
1970--mail-to              : Email address to send the email too.
1971--mail                 : Send email report or results.
1972--smtp-host            : SMTP host to send via.
1973--no-report            : Do not create a package report.
1974--report-format        : The report format (text, html, asciidoc).
1975--bset-tar-file        : Create a build set tar file
1976--pkg-tar-files        : Create package tar files
1977--list-bsets           : List available build sets
1978--list-configs         : List available configurations
1979--list-deps            : List the dependent files.
1980-------------------------------------------------------------
1981
1982.Arguments
1983The +[args]+ are a list build sets to build.
1984
1985.Options
1986+--force+;;
1987Force the build to proceed even if the host check fails. Typically this happens
1988if executable files are found in the path at a different location to the host
1989defaults.
1990+--trace+;;
1991Trace enable printing of debug information to stdout. It is really only of use
1992to RTEMS Source Builder's developers.
1993+--dry-run+;;
1994Do everything but actually run the build commands. This is useful when checking
1995a new configuration parses cleanly.
1996+--warn-all+;;
1997Generate warnings.
1998+--no-clean+;;
1999Do not clean up the build tree during the cleaning phase of the build. This
2000leaves the source and the build output on disk so you can make changes, or
2001amend or generate new patches. It also allows you to review configure type
2002output such as +config.log+.
2003+--always-clean+;;
2004Clean away the results of a build even if the build fails. This is normally
2005used with `--keep-going` when regression testing to see which build sets
2006fail to build. It keeps the disk usage down.
2007+--jobs+;;
2008Control the number of jobs make is given. The jobs can be 'none' for only 1
2009job, 'half' so the number of jobs is half the number of detected cores, a
2010fraction such as '0.25' so the number of jobs is a quarter of the number of
2011detected cores and a number such as '25' which forces the number of jobs to
2012that number.
2013+--host+;;
2014Set the host triplet value. Be careful with this option.
2015+--build+;;
2016Set the build triplet. Be careful with this option.
2017+--target+;;
2018Set the target triplet. Be careful with this option. This is useful if you have
2019a generic configuration script that can work for a range of architectures.
2020+--prefix path+;;
2021Tools build prefix, ie where they are installed.
2022+--topdir path+;;
2023Top of the build tree, that is the current directory you are in.
2024+--configdir path+;;
2025Path to the configuration directory. This overrides the built in defaults.
2026+--builddir path+;;
2027Path to the build directory. This overrides the default of +build+.
2028+--sourcedir path+;;
2029Path to the source directory. This overrides the default of +source+.
2030+--tmppath path+;;
2031Path to the temporary directory. This overrides the default of +tmp+.
2032+--macros files+;;
2033Macro files to load. The configuration directory path is searched.
2034+--log file+;;
2035Log all the output from the build process. The output is directed to +stdout+
2036if no log file is provided.
2037+--url url+;;
2038URL to look for source when downloading. This is can be comma separate list.
2039+--no-download+;;
2040Disable downloading of source and patches. If the source is not found an error
2041is raised.
2042+--targetcflags flags+;;
2043List of C flags for the target code. This allows for specific local
2044customisation when testing new variations.
2045+--targetcxxflags flags+;;
2046List of C++ flags for the target code. This allows for specific local
2047customisation when testing new variations.
2048+--libstdcxxflags flags+;;
2049List of C\++ flags to build the target libstdc++ code. This allows for specific
2050local customisation when testing new variations.
2051+--with-<label>+;;
2052Add the --with-<label> to the build. This can be tested for in a script with
2053the +%bconf_with+ macro.
2054+--without-<label>+;;
2055Add the --without-<label> to the build. This can be tested for in a script with
2056the +%bconf_without+ macro.
2057+--mail-from+;;
2058Set the from mail address if report mailing is enabled.
2059+--mail-to+;;
2060Set the to mail address if report mailing is enabled. The report is mailed to
2061this address.
2062+--mail+;;
2063Mail the build report to the mail to address.
2064+--smtp-host+;;
2065The SMTP host to use to send the email. The default is +localhost+.
2066+--no-report+;;
2067Do not create a report format.
2068+--report-format format+;;
2069The report format can be 'text' or 'html'. The default is 'html'.
2070+--keep-going+;;
2071Do not stop on error. This is useful if your build sets performs a large number
2072of testing related builds and there are errors.
2073+--always-clean+.
2074Always clean the build tree even with a failure.
2075+--no-install+;;
2076Do not install the packages to the prefix. Use this if you are only after the
2077tar files.
2078+--regression+;;
2079A convenience option which is the same as +--no-install+, +--keep-going+ and
2080+--bset-tar-file+;;
2081Create a build set tar file. This is a single tar file of all the packages in
2082the build set.
2083+--pkg-tar-files+;;
2084Create package tar files. A tar file will be created for each package built in
2085a build set.
2086+--list-bsets+;;
2087List available build sets.
2088+--list-configs+;;
2089List available configurations.
2090+--list-deps+;;
2091Print a list of dependent files used by a build set. Dependent files have a
2092'dep[?]' prefix where '?' is a number. The files are listed alphabetically.
2093
2094Set Builder (sb-builder)
2095~~~~~~~~~~~~~~~~~~~~~~~~
2096
2097This command builds a configuration as described in a configuration
2098file. Configuration files have the extension of +.cfg+.
2099
2100-------------------------------------------------------------
2101$ ./source-builder/sb-builder --help
2102sb-builder: [options] [args]
2103RTEMS Source Builder, an RTEMS Tools Project (c) 2012 Chris Johns
2104Options and arguments:
2105--force                : Force the build to proceed
2106--quiet                : Quiet output (not used)
2107--trace                : Trace the execution
2108--dry-run              : Do everything but actually run the build
2109--warn-all             : Generate warnings
2110--no-clean             : Do not clean up the build tree
2111--always-clean         : Always clean the build tree, even with an error
2112--jobs                 : Run with specified number of jobs, default: num CPUs.
2113--host                 : Set the host triplet
2114--build                : Set the build triplet
2115--target               : Set the target triplet
2116--prefix path          : Tools build prefix, ie where they are installed
2117--topdir path          : Top of the build tree, default is $PWD
2118--configdir path       : Path to the configuration directory, default: ./config
2119--builddir path        : Path to the build directory, default: ./build
2120--sourcedir path       : Path to the source directory, default: ./source
2121--tmppath path         : Path to the temp directory, default: ./tmp
2122--macros file[,[file]  : Macro format files to load after the defaults
2123--log file             : Log file where all build out is written too
2124--url url[,url]        : URL to look for source
2125--targetcflags flags   : List of C flags for the target code
2126--targetcxxflags flags : List of C++ flags for the target code
2127--libstdcxxflags flags : List of C++ flags to build the target libstdc++ code
2128--with-<label>         : Add the --with-<label> to the build
2129--without-<label>      : Add the --without-<label> to the build
2130--list-configs         : List available configurations
2131-------------------------------------------------------------
2132
2133Host Setups
2134-----------
2135
2136The host versions are listed. If a later version of the host operating system
2137exists it should unless listed.
2138
2139Linux
2140~~~~~
2141
2142A number of different Linux distrubutions are known to work. The following have
2143been tested and report as working.
2144
2145Archlinux
2146^^^^^^^^^
2147
2148The following packages are required on a fresh Archlinux 64bit installation:
2149
2150--------------------------------------------------------------
2151# pacman -S base-devel gdb xz unzip ncurses git zlib
2152--------------------------------------------------------------
2153
2154Archlinux, by default installs `texinfo-5` which is incompatible for building
2155GCC 4.7 tree. You will have to obtain `texinfo-legacy` from `AUR` and provide
2156a manual override.
2157
2158--------------------------------------------------------------
2159# pacman -R texinfo
2160$ yaourt -S texinfo-legacy
2161# ln -s /usr/bin/makeinfo-4.13a /usr/bin/makeinfo
2162--------------------------------------------------------------
2163
2164CentOS
2165^^^^^^
2166
2167The following packages are required on a minimal CentOS 6.3 64bit installation:
2168
2169-------------------------------------------------------------
2170# yum install autoconf automake binutils gcc gcc-c++ gdb make patch \
2171bison flex xz unzip ncurses-devel texinfo zlib-devel python-devel git
2172-------------------------------------------------------------
2173
2174The minimal CentOS distribution is a specific DVD that installs a minimal
2175system. If you use a full system some of these packages may have been
2176installed.
2177
2178Fedora
2179^^^^^^
2180
2181The RTEMS Source Builder has been tested on Fedora 18 64bit.
2182
2183Raspbian
2184^^^^^^^^
2185
2186The is the Debian distribution for the Raspberry Pi. The following packages are
2187required.
2188
2189-------------------------------------------------------------
2190$ sudo apt-get install autoconf automake bison flex binutils gcc g++ gdb \
2191texinfo unzip ncurses-dev python-dev git
2192-------------------------------------------------------------
2193
2194It is recommended you get Model B of the Pi with 512M of memory and to mount a
2195remote disk over the network. The tools can be build with a prefix under your
2196home directory as recommended and end up on the SD card.
2197
2198Ubuntu
2199^^^^^^
2200
2201The latest testing was with Ubuntu 12.10 64bit. A minimal installation was used
2202and the following packages installed.
2203
2204-------------------------------------------------------------
2205$ sudo apt-get build-dep binutils gcc g++ gdb unzip git
2206-------------------------------------------------------------
2207
2208FreeBSD
2209~~~~~~~
2210
2211The RTEMS Source Builder has been tested on FreeBSD 9.1 64bit.
2212
2213NetBSD
2214~~~~~~
2215
2216The RTEMS Source Builder has been tested on NetBSD 6.1 i386. Packages to add
2217are:
2218
2219-------------------------------------------------------------
2220# pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/devel/gmake-3.82nb7.tgz
2221# pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/devel/bison-2.7.1.tgz
2222# pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/archivers/xz-5.0.4.tgz
2223-------------------------------------------------------------
2224
2225MacOS X
2226~~~~~~~
2227
2228The RTEMS Source Builder has been tested on Mountain Lion. You will need to
2229install the Xcode app using the _App Store_ tool, run Xcode and install the
2230Developers Tools package within Xcode.
2231
2232Windows
2233~~~~~~~
2234
2235Windows tool sets are supported creating native Windows executable. Native
2236Windows tools are built using a MinGW compiler and do not need any extra
2237libraries or emulation layer to run once built. The tools understand and use
2238standard Windows paths and integrate easly into Windows IDE environments. A
2239shell maybe needed to build other parts of your system however if your
2240development tools are all native Windows tool you can easly integrate these
2241tool sets.
2242
2243.Ready To Go Windows Tools
2244NOTE: I provide tools for Windows at
2245http://www.rtems.org/ftp/pub/rtems/people/chrisj/source-builder/4.11/mingw32/
2246
2247Building on Windows is a little more complicated because the Cygwin shell is
2248used rather than the MinGW MSYS shell. The MSYS shell is simpler because the
2249detected host triple is MinGW so the build is standard cross-compiler build.
2250The age of the MSYS code base, its stability and ability to to complete a build
2251with limitations such as the length of file names support make using MSYS
2252difficult therefore the more complex path of a Canadian cross-build using
2253Cygwin is supported.
2254
2255Install a recent Cygwin version using the Cygwin setup tool. Select and install
2256the groups and packages listed:
2257
2258.Cygwin Packages
2259[options="header,compact",width="50%",cols="20%,80%"]
2260|================================
2261|Group   |Package
2262|Archive |bsdtar
2263|        |unzip
2264|        |xz
2265|Devel   |autoconf
2266|        |autoconf2.1
2267|        |autoconf2.5
2268|        |automake
2269|        |binutils
2270|        |bison
2271|        |flex
2272|        |gcc4-core
2273|        |gcc4-g++
2274|        |git
2275|        |make
2276|        |mingw64-x86_64-binutils
2277|        |mingw64-x86_64-gcc-core
2278|        |mingw64-x86_64-g++
2279|        |mingw64-x86_64-runtime
2280|        |mingw64-x86_64-zlib
2281|        |patch
2282|        |zlib-devel
2283|MinGW   |mingw-zlib-devel
2284|Python  |python
2285|================================
2286
2287The setup tool will add a number of dependent package and it is ok to accept
2288them.
2289
2290I have found turning off Windows Defender improves performance if you have
2291another up to date virus detection tool installed and enabled. I used the
2292excellent `Process Hacker 2` tool to monitor the performance and I found the
2293Windows Defender service contributed a high load. In my case I had a 3rd party
2294virus tool installed so the Windows Defender service was not needed.
2295
2296A Canadian cross-compile (Cxc) is required on Cygwin because the host is Cygwin
2297therefore a traditional cross-compile will result in Cygiwn binaries. With a
2298Canadian cross-compile a Cygwin cross-compiler is built as well as the MinGW
2299RTEMS cross-compiler. The Cygwin cross-compiler is required to build the C
2300runtime for the RTEMS target because we are building under Cygiwn. The build
2301output for an RTEMS 4.10 ARM tool set is:
2302
2303-------------------------------------------------------------
2304chris@cygthing ~/development/rtems/src/rtems-source-builder/rtems
2305$ ../source-builder/sb-set-builder --log=l-arm.txt --prefix=$HOME/development/rtems/4.10 4.10/rtems-arm
2306RTEMS Source Builder - Set Builder, v0.2
2307Build Set: 4.10/rtems-arm
2308config: expat-2.1.0-1.cfg
2309package: expat-2.1.0-x86_64-w64-mingw32-1
2310building: expat-2.1.0-x86_64-w64-mingw32-1
2311reporting: expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-w64-mingw32-1.html
2312config: tools/rtems-binutils-2.20.1-1.cfg
2313package: arm-rtems4.10-binutils-2.20.1-1 <1>
2314building: arm-rtems4.10-binutils-2.20.1-1
2315package: (Cxc) arm-rtems4.10-binutils-2.20.1-1 <2>
2316building: (Cxc) arm-rtems4.10-binutils-2.20.1-1
2317reporting: tools/rtems-binutils-2.20.1-1.cfg ->
2318arm-rtems4.10-binutils-2.20.1-1.html
2319config: tools/rtems-gcc-4.4.7-newlib-1.18.0-1.cfg
2320package: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
2321building: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
2322package: (Cxc) arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
2323building: (Cxc) arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
2324reporting: tools/rtems-gcc-4.4.7-newlib-1.18.0-1.cfg ->
2325arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1.html
2326config: tools/rtems-gdb-7.3.1-1.cfg
2327package: arm-rtems4.10-gdb-7.3.1-1
2328building: arm-rtems4.10-gdb-7.3.1-1
2329reporting: tools/rtems-gdb-7.3.1-1.cfg -> arm-rtems4.10-gdb-7.3.1-1.html
2330config: tools/rtems-kernel-4.10.2.cfg
2331package: arm-rtems4.10-kernel-4.10.2-1
2332building: arm-rtems4.10-kernel-4.10.2-1
2333reporting: tools/rtems-kernel-4.10.2.cfg -> arm-rtems4.10-kernel-4.10.2-1.html
2334installing: expat-2.1.0-x86_64-w64-mingw32-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
2335installing: arm-rtems4.10-binutils-2.20.1-1 -> /cygdrive/c/Users/chris/development/rtems/4.10 <3>
2336installing: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
2337installing: arm-rtems4.10-gdb-7.3.1-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
2338installing: arm-rtems4.10-kernel-4.10.2-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
2339cleaning: expat-2.1.0-x86_64-w64-mingw32-1
2340cleaning: arm-rtems4.10-binutils-2.20.1-1
2341cleaning: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
2342cleaning: arm-rtems4.10-gdb-7.3.1-1
2343cleaning: arm-rtems4.10-kernel-4.10.2-1
2344Build Set: Time 10:09:42.810547 <4>
2345-------------------------------------------------------------
2346
2347<1> The Cygwin version of the ARM cross-binutils.
2348<2> The +(Cxc)+ indicates this is the MinGW build of the package.
2349<3> Only the MinGW version is installed.
2350<4> Cygwin is slow so please be patient. This time was on an AMD Athlon 64bit
2351    Dual Core 6000+ running at 3GHz with 4G RAM running Windows 7 64bit.
2352
2353CAUTION: Cygwin documents the 'Big List Of Dodgy Apps' or 'BLODA'. The link is
2354http://cygwin.com/faq/faq.html#faq.using.bloda and it is worth a
2355look. You will see a large number of common pieces of software found on Windows
2356systems that can cause problems. My testing has been performed with NOD32
2357running and I have seen some failures. The list is for all of Cygwin so I am
2358not sure which of the listed programs effect the RTEMS Source Biulder. The
2359following FAQ item talks about +fork+ failures and presents some technical
2360reasons they cannot be avoided in all cases. Cygwin and it's fork MSYS are
2361fantastic pieces of software in a difficult environment. I have found building
2362a single tool tends to work, building all at once is harder.
2363
2364
2365Build Status By Host
2366~~~~~~~~~~~~~~~~~~~~
2367
2368This table lists the current build and testing status for reported hosts:
2369
2370[grid="rows",format="csv"]
2371[options="header",cols="<,<,<,<,<,<"]
2372|===========================
2373OS,Uname,4.9,4.10,4.11,Comments
2374include::host-results.csv[]
2375|===========================
2376
2377[NOTE]
2378==================================================================
2379Report any unlisted hosts as a patch.
2380==================================================================
2381
2382History
2383-------
2384
2385The RTEMS Source Builder is a stand alone tool based on another tool called the
2386'SpecBuilder'. The SpecBuilder was written for the RTEMS project to give me a
2387way to build tools on hosts that did not support RPMs. At the time the RTEMS
2388tools maintainer only used spec files to create various packages. This meant I
2389had either spec files, RPM files or SRPM files. The RPM and SPRM files where
2390useless because you needed an 'rpm' type tool to extract and manage them. There
2391are versions of 'rpm' for a number of non-RPM hosts however these proved to be
2392in various broken states and randomly maintained. The solution I settled on was
2393to use spec files so I wrote a Python based tool that parsed the spec file
2394format and allowed me to create a shell script I could run to build the
2395package. This approach proved successful and I was able to track the RPM
2396version of the RTEMS tools on a non-RPM host over a number of years. however
2397the SpecBuilder tool did not help me build tools or other packages not related
2398to the RTEMS project where there was no spec file I could use so I needed
2399another tool. Rather than start again I decided to take the parsing code for
2400the spec file format and build a new tool called the RTEMS Source Builder.
Note: See TracBrowser for help on using the repository browser.