source: rtems-source-builder/doc/source-builder.txt @ 374ba95

4.104.114.9
Last change on this file since 374ba95 was 374ba95, checked in by Chris Johns <chrisj@…>, on Apr 8, 2014 at 3:18:56 AM

doc: Updated after GSoC student feedback.

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