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