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