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

4.104.114.9
Last change on this file since eef0d0c was eef0d0c, checked in by Chris Johns <chrisj@…>, on Aug 14, 2013 at 4:08:06 AM

doc: Add the patch module to cygwn.

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