source: rtems-source-builder/doc/source-builder.txt @ 8dc8b26

4.104.114.95
Last change on this file since 8dc8b26 was 8dc8b26, checked in by Chris Johns <chrisj@…>, on 08/31/13 at 02:12:37

doc: Add a cross build section.

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