1 | RTEMS Source Builder |
---|
2 | ==================== |
---|
3 | :doctype: book |
---|
4 | :toc2: |
---|
5 | :toclevels: 5 |
---|
6 | :icons: |
---|
7 | :numbered: |
---|
8 | |
---|
9 | image:images/rtemswhitebg.jpg["RTEMS",width="30%"] |
---|
10 | |
---|
11 | Chris Johns <chrisj@rtems.org> |
---|
12 | 1.0, February 2013 |
---|
13 | |
---|
14 | RTEMS Tools From Source |
---|
15 | ----------------------- |
---|
16 | |
---|
17 | The RTEMS Source Builder is a tool to aid building packages from source. It is |
---|
18 | not a package manager. It helps consolidate the details you need to build a |
---|
19 | package from source in a controlled and verifiable way. The tool is aimed at |
---|
20 | developers of software who use tool sets for embedded type |
---|
21 | development. Embedded development typically uses cross-compiling tool chains, |
---|
22 | debuggers, and debugging aids. Together we call these a 'tool set'. The RTEMS |
---|
23 | Source Builder is not limited to this role but designed to fit with-in this |
---|
24 | specific niche. It can be used outside of the RTEMS project and we welcome this |
---|
25 | happening in other open source or commercial projects. |
---|
26 | |
---|
27 | The RTEMS Source Builder is typically used to build a set of tools or a 'build |
---|
28 | set'. A 'build set' is a collection of packages and a package is a specific |
---|
29 | tool, for example gcc or gdb. The RTEMS Source Builder attempts to support any |
---|
30 | host environment that runs Python and you can build the package on. It is not |
---|
31 | some sort of magic that can take any piece of source code and make it |
---|
32 | build. Someone at some point in time has figured out how to build that package |
---|
33 | from source and taught this tool. The RTEMS Source Builder has been tested on: |
---|
34 | |
---|
35 | * FreeBSD |
---|
36 | * MacOS (Mountain Lion) |
---|
37 | * Ubuntu |
---|
38 | * Centos |
---|
39 | * Fedora |
---|
40 | * Raspbian |
---|
41 | |
---|
42 | Windows support is being added how-ever there are issues with the Python |
---|
43 | threading used in the RTEMS Source Builder and the MinGW project's MSYS process |
---|
44 | handling of `make`. |
---|
45 | |
---|
46 | The RTEMS Source Builder has two types configuration data. The first is the |
---|
47 | 'build set'. A _build set_ describes a collection of packages that define a set |
---|
48 | of tools you would use when developing software for RTEMS. For example the |
---|
49 | basic GNU tool set is binutils, gcc, and gdb and is the typical base suite of |
---|
50 | tools you need for an embedded cross-development type project. The second type |
---|
51 | of configuration data is the configuration files and they define how a package |
---|
52 | is built. Configuration files are scripts loosely based on the RPM spec file |
---|
53 | format and detail the steps needed to build a package. The steps are |
---|
54 | 'preparation', 'building', and 'installing'. Scripts support macros, shell |
---|
55 | expansion, logic, includes plus many more features useful when build packages. |
---|
56 | |
---|
57 | The RTEMS Source Builder does not interact with any host package management |
---|
58 | systems. There is no automatic dependence checking between various packages you |
---|
59 | build or packages and software your host system you may have installed. We |
---|
60 | assume the build sets and configuration files you are using have been created |
---|
61 | by developers who do. If you have a problem please ask on the RTEMS Users |
---|
62 | mailing list. |
---|
63 | |
---|
64 | Quick Start |
---|
65 | ----------- |
---|
66 | |
---|
67 | The quick start will show you how to build a set of RTEMS tools for a supported |
---|
68 | architecture. |
---|
69 | |
---|
70 | There is no need to become root or the administrator and we recommend you avoid |
---|
71 | doing this. You can build and install the tools anywhere on the host's file |
---|
72 | system you, as a standard user, have read and write access too. I recommend you |
---|
73 | use your home directory and work under the directory `~/development/rtems`. The |
---|
74 | examples shown here will do this. |
---|
75 | |
---|
76 | You can use the build _prefix_ to install and maintain different versions of |
---|
77 | the tools. Doing this lets you try a new set of tools while not touching your |
---|
78 | proven working production set of tools. Once you have proven the new tools are |
---|
79 | working rebuild with the 'production' prefix switching your development to them. |
---|
80 | |
---|
81 | I also suggest you keep your environment to the bare minimum, particularly the |
---|
82 | path variable. Using environment variables has been proven over the years to be |
---|
83 | difficult to manage in production systems. |
---|
84 | |
---|
85 | Setup |
---|
86 | ~~~~~ |
---|
87 | |
---|
88 | Setup a development work space: |
---|
89 | |
---|
90 | ------------------------------------------------------------- |
---|
91 | $ cd |
---|
92 | $ mkdir -p development/rtems/src |
---|
93 | $ cd development/rtems/src |
---|
94 | ------------------------------------------------------------- |
---|
95 | |
---|
96 | The RTEMS Source Builder is distributed as source. It is Python code so all you |
---|
97 | need to do is head over to the RTEMS GIT repository and clone the code directly |
---|
98 | from git: |
---|
99 | |
---|
100 | ------------------------------------------------------------- |
---|
101 | $ git clone git://git.rtems.org/chrisj/rtems-source-builder.git |
---|
102 | $ cd rtems-source-builder |
---|
103 | ------------------------------------------------------------- |
---|
104 | |
---|
105 | Checking |
---|
106 | ~~~~~~~~ |
---|
107 | |
---|
108 | The next step is to check if your host is set up correctly. The RTEMS Source |
---|
109 | Builder provides a tool to help: |
---|
110 | |
---|
111 | ------------------------------------------------------------- |
---|
112 | $ source-builder/sb-check |
---|
113 | warning: exe: absolute exe found in path: (__objcopy) /usr/local/bin/objcopy <1> |
---|
114 | warning: exe: absolute exe found in path: (__objdump) /usr/local/bin/objdump |
---|
115 | error: exe: not found: (_xz) /usr/local/bin/xz <2> |
---|
116 | RTEMS Source Builder environment is not correctly set up |
---|
117 | $ source-builder/sb-check |
---|
118 | RTEMS Source Builder environment is ok <3> |
---|
119 | ------------------------------------------------------------- |
---|
120 | |
---|
121 | <1> A tool is in the environment path but does not match the expected path. |
---|
122 | <2> The executable 'xz' is not found. |
---|
123 | <3> The host's environment is set up correct. |
---|
124 | |
---|
125 | The checking tool will output a list of executable files not found if problems |
---|
126 | are detected. Locate those executable files and install them. You may also be |
---|
127 | given a list of warnings about executable files not in the expected location |
---|
128 | how-ever the executable was located somewhere in your environment's path. You |
---|
129 | will need to check each tool to determine if this is an issue. An executable |
---|
130 | not in the standard location may indicate it is not the host operating system's |
---|
131 | standard tool. It maybe ok or it could be buggy, only you can determine this. |
---|
132 | |
---|
133 | The <<_host_setups,Host Setups>> section lists packages you should install for |
---|
134 | common host operating systems. It maybe worth checking if you have those |
---|
135 | installed. |
---|
136 | |
---|
137 | Build Sets |
---|
138 | ~~~~~~~~~~ |
---|
139 | |
---|
140 | The RTEMS tools can be built within the RTEMS Source Builder's source tree. We |
---|
141 | recommend you do this so lets change into the RTEMS directory in the RTEMS |
---|
142 | Source Builder package: |
---|
143 | |
---|
144 | ------------------------------------------------------------- |
---|
145 | $ cd rtems |
---|
146 | ------------------------------------------------------------- |
---|
147 | |
---|
148 | If you are unsure how to specify the build set for the architecture you wish to |
---|
149 | build ask the tool: |
---|
150 | |
---|
151 | ------------------------------------------------------------- |
---|
152 | $ ../source-builder/sb-set-builder --list-bsets <1> |
---|
153 | RTEMS Source Builder - Set Builder, v0.1 |
---|
154 | Examining: config <2> |
---|
155 | Examining: ../source-builder/config <2> |
---|
156 | 4.11/rtems-all.bset <3> |
---|
157 | 4.11/rtems-arm.bset <4> |
---|
158 | 4.11/rtems-avr.bset |
---|
159 | 4.11/rtems-bfin.bset |
---|
160 | 4.11/rtems-h8300.bset |
---|
161 | 4.11/rtems-m32c.bset |
---|
162 | 4.11/rtems-m32r.bset |
---|
163 | 4.11/rtems-m68k.bset |
---|
164 | 4.11/rtems-microblaze.bset |
---|
165 | 4.11/rtems-mips.bset |
---|
166 | 4.11/rtems-moxie.bset |
---|
167 | 4.11/rtems-nios2.bset |
---|
168 | 4.11/rtems-powerpc.bset |
---|
169 | 4.11/rtems-sh.bset |
---|
170 | 4.11/rtems-sparc.bset |
---|
171 | gnu-tools-4.6.bset |
---|
172 | rtems-4.11-base.bset |
---|
173 | unstable/4.11/rtems-all.bset <5> |
---|
174 | unstable/4.11/rtems-arm.bset |
---|
175 | unstable/4.11/rtems-avr.bset |
---|
176 | unstable/4.11/rtems-bfin.bset |
---|
177 | unstable/4.11/rtems-h8300.bset |
---|
178 | unstable/4.11/rtems-m32c.bset |
---|
179 | unstable/4.11/rtems-m32r.bset |
---|
180 | unstable/4.11/rtems-m68k.bset |
---|
181 | unstable/4.11/rtems-microblaze.bset |
---|
182 | unstable/4.11/rtems-mips.bset |
---|
183 | unstable/4.11/rtems-moxie.bset |
---|
184 | unstable/4.11/rtems-powerpc.bset |
---|
185 | unstable/4.11/rtems-sh.bset |
---|
186 | unstable/4.11/rtems-sparc.bset |
---|
187 | ------------------------------------------------------------- |
---|
188 | <1> Only option needed is +--list-bsets+ |
---|
189 | <2> The paths inspected. See <<X1,+_configdir+>> variable. |
---|
190 | <3> Build all the architectures. |
---|
191 | <4> The build set for the ARM architecture. |
---|
192 | <5> Unstable tool sets are used by RTEMS developers to test new tool sets. You |
---|
193 | are welcome to try them but you must remember they are unstable, can change |
---|
194 | at point in time and your application may not work. If you have an issue |
---|
195 | with a production tool it may pay to try the unstable tool to see if it has |
---|
196 | been resolved. |
---|
197 | |
---|
198 | Building |
---|
199 | ~~~~~~~~ |
---|
200 | |
---|
201 | In this quick start I will build a SPARC tool set. |
---|
202 | |
---|
203 | ------------------------------------------------------------- |
---|
204 | $ ../source-builder/sb-set-builder --log=l-sparc.txt <1> \ |
---|
205 | --prefix=$HOME/development/rtems/4.11 <2> 4.11/rtems-sparc <3> |
---|
206 | Source Builder - Set Builder, v0.1 |
---|
207 | Build Set: 4.11/rtems-sparc |
---|
208 | config: expat-2.1.0-1.cfg <4> |
---|
209 | package: expat-2.1.0-x86_64-freebsd9.1-1 |
---|
210 | building: expat-2.1.0-x86_64-freebsd9.1-1 |
---|
211 | installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <5> |
---|
212 | config: tools/rtems-binutils-2.22-1.cfg <6> |
---|
213 | package: sparc-rtems4.11-binutils-2.22-1 |
---|
214 | building: sparc-rtems4.11-binutils-2.22-1 |
---|
215 | installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 |
---|
216 | config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg <7> |
---|
217 | package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 |
---|
218 | building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 |
---|
219 | installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 |
---|
220 | config: tools/rtems-gdb-7.5.1-1.cfg <8> |
---|
221 | package: sparc-rtems4.11-gdb-7.5.1-1 |
---|
222 | building: sparc-rtems4.11-gdb-7.5.1-1 |
---|
223 | installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 |
---|
224 | cleaning: expat-2.1.0-x86_64-freebsd9.1-1 <9> |
---|
225 | cleaning: sparc-rtems4.11-binutils-2.22-1 |
---|
226 | cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 |
---|
227 | cleaning: sparc-rtems4.11-gdb-7.5.1-1 |
---|
228 | Build Set: Time 0:13:43.616383 <10> |
---|
229 | ------------------------------------------------------------- |
---|
230 | |
---|
231 | <1> Providing a log file redirects the build output into a file. Logging the |
---|
232 | build output provides a simple way to report problems. |
---|
233 | <2> The prefix is the location on your file system the tools are installed |
---|
234 | into. Provide a prefix to a location you have read and write access. You |
---|
235 | can use the prefix to install different versions or builds of tools. Just |
---|
236 | use the path to the tools you want to use when building RTEMS. |
---|
237 | <3> The build set. This is the SPARC build set. |
---|
238 | <4> The SPARC build set first builds the expat library as is used in GDB. This |
---|
239 | is the expat configuration used. |
---|
240 | <5> Installing the expat package to the install prefix. |
---|
241 | <6> The binutils build configuration. |
---|
242 | <7> The GCC and Newlib build configuration. |
---|
243 | <8> The GDB build configuration. |
---|
244 | <9> All the packages built are cleaned at the end. If the build fails all the |
---|
245 | needed files are present. You may have to clean up by deleting the build |
---|
246 | directory if the build fails. |
---|
247 | <10> The time to build the package. This lets you see how different host |
---|
248 | hardware or configurations perform. |
---|
249 | |
---|
250 | Your SPARC RTEMS 4.11 tool set will be installed and ready to build RTEMS and |
---|
251 | RTEMS applications. When the build runs you will notice the tool fetch the |
---|
252 | source code from the internet. These files are cached in a directory called |
---|
253 | +source+. If you run the build again the cached files are used. This is what |
---|
254 | happened in the show example before. |
---|
255 | |
---|
256 | The installed tools: |
---|
257 | |
---|
258 | ------------------------------------------------------------- |
---|
259 | $ ls $HOME/development/rtems/4.11 |
---|
260 | bin include lib libexec share sparc-rtems4.11 |
---|
261 | $ ls $HOME/development/rtems/4.11/bin |
---|
262 | sparc-rtems4.11-addr2line sparc-rtems4.11-cpp |
---|
263 | sparc-rtems4.11-gcc-ar sparc-rtems4.11-gprof |
---|
264 | sparc-rtems4.11-objdump sparc-rtems4.11-size |
---|
265 | sparc-rtems4.11-ar sparc-rtems4.11-elfedit |
---|
266 | sparc-rtems4.11-gcc-nm sparc-rtems4.11-ld |
---|
267 | sparc-rtems4.11-ranlib sparc-rtems4.11-strings |
---|
268 | sparc-rtems4.11-as sparc-rtems4.11-g++ |
---|
269 | sparc-rtems4.11-gcc-ranlib sparc-rtems4.11-ld.bfd |
---|
270 | sparc-rtems4.11-readelf sparc-rtems4.11-strip |
---|
271 | sparc-rtems4.11-c++ sparc-rtems4.11-gcc |
---|
272 | sparc-rtems4.11-gcov sparc-rtems4.11-nm |
---|
273 | sparc-rtems4.11-run xmlwf |
---|
274 | sparc-rtems4.11-c++filt sparc-rtems4.11-gcc-4.7.2 |
---|
275 | sparc-rtems4.11-gdb sparc-rtems4.11-objcopy |
---|
276 | sparc-rtems4.11-sis |
---|
277 | $ $HOME/development/rtems/4.11/bin/sparc-rtems4.11-gcc -v |
---|
278 | Using built-in specs. |
---|
279 | COLLECT_GCC=/home/chris/development/rtems/4.11/bin/sparc-rtems4.11-gcc |
---|
280 | COLLECT_LTO_WRAPPER=/usr/home/chris/development/rtems/4.11/bin/../ \ |
---|
281 | libexec/gcc/sparc-rtems4.11/4.7.2/lto-wrapper |
---|
282 | Target: sparc-rtems4.11 |
---|
283 | Configured with: ../gcc-4.7.2/configure |
---|
284 | --prefix=/home/chris/development/rtems/4.11 |
---|
285 | --bindir=/home/chris/development/rtems/4.11/bin |
---|
286 | --exec_prefix=/home/chris/development/rtems/4.11 |
---|
287 | --includedir=/home/chris/development/rtems/4.11/include |
---|
288 | --libdir=/home/chris/development/rtems/4.11/lib |
---|
289 | --libexecdir=/home/chris/development/rtems/4.11/libexec |
---|
290 | --mandir=/home/chris/development/rtems/4.11/share/man |
---|
291 | --infodir=/home/chris/development/rtems/4.11/share/info |
---|
292 | --datadir=/home/chris/development/rtems/4.11/share |
---|
293 | --build=x86_64-freebsd9.1 --host=x86_64-freebsd9.1 --target=sparc-rtems4.11 |
---|
294 | --disable-libstdcxx-pch --with-gnu-as --with-gnu-ld --verbose --with-newlib |
---|
295 | --with-system-zlib --disable-nls --without-included-gettext |
---|
296 | --disable-win32-registry --enable-version-specific-runtime-libs --disable-lto |
---|
297 | --enable-threads --enable-plugin --enable-newlib-io-c99-formats |
---|
298 | --enable-newlib-iconv --enable-languages=c,c++ |
---|
299 | Thread model: rtems |
---|
300 | gcc version 4.7.2 20120920 (RTEMS) (GCC) |
---|
301 | ------------------------------------------------------------- |
---|
302 | |
---|
303 | Installing and Tar Files |
---|
304 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
305 | |
---|
306 | The RTEMS Source Builder can install the built packages directly and optionally it can |
---|
307 | create a build set tar file or a tar file per package built. The normal and |
---|
308 | default behaviour is to let the RTEMS Source Builder install the tools. The |
---|
309 | source will be downloaded, built, installed and cleaned up. |
---|
310 | |
---|
311 | The tar files are created with the full build prefix present. This can cause |
---|
312 | problems if you are installing on a host you do not have super user or |
---|
313 | administrator rights on if the prefix path references part you do not have |
---|
314 | write access t0o. You can use the +--strip-components+ option in tar if your |
---|
315 | tar file supports it to remove the parts you do not have write access too or |
---|
316 | you may need to unpack the tar file somewhere and copy the file tree from the |
---|
317 | level you have write access from. Embedding the full prefix path in the tar |
---|
318 | files lets you know what the prefix is. |
---|
319 | |
---|
320 | A build set tar file is created by adding `--bset-tar-file` option to the |
---|
321 | `sb-set-builder` command. |
---|
322 | |
---|
323 | ------------------------------------------------------------- |
---|
324 | $ ../source-builder/sb-set-builder --log=l-sparc.txt \ |
---|
325 | --prefix=$HOME/development/rtems/4.11 \ |
---|
326 | --bset-tar-file <1> 4.11/rtems-sparc |
---|
327 | Source Builder - Set Builder, v0.1 |
---|
328 | Build Set: 4.11/rtems-sparc |
---|
329 | config: expat-2.1.0-1.cfg |
---|
330 | package: expat-2.1.0-x86_64-freebsd9.1-1 |
---|
331 | building: expat-2.1.0-x86_64-freebsd9.1-1 |
---|
332 | installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <2> |
---|
333 | config: tools/rtems-binutils-2.22-1.cfg |
---|
334 | package: sparc-rtems4.11-binutils-2.22-1 |
---|
335 | building: sparc-rtems4.11-binutils-2.22-1 |
---|
336 | installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 |
---|
337 | config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg |
---|
338 | package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 |
---|
339 | building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 |
---|
340 | installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 |
---|
341 | config: tools/rtems-gdb-7.5.1-1.cfg |
---|
342 | package: sparc-rtems4.11-gdb-7.5.1-1 |
---|
343 | building: sparc-rtems4.11-gdb-7.5.1-1 |
---|
344 | installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 |
---|
345 | tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3> |
---|
346 | cleaning: expat-2.1.0-x86_64-freebsd9.1-1 |
---|
347 | cleaning: sparc-rtems4.11-binutils-2.22-1 |
---|
348 | cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 |
---|
349 | cleaning: sparc-rtems4.11-gdb-7.5.1-1 |
---|
350 | Build Set: Time 0:15:25.92873 |
---|
351 | ------------------------------------------------------------- |
---|
352 | |
---|
353 | <1> The option to create a build set tar file. |
---|
354 | <2> The installation still happens. |
---|
355 | <3> Creating the build set tar file. |
---|
356 | |
---|
357 | You can also suppress installing the files using the `--no-install` option to |
---|
358 | the `sb-set-builder` command. |
---|
359 | |
---|
360 | ------------------------------------------------------------- |
---|
361 | $ ../source-builder/sb-set-builder --log=l-sparc.txt \ |
---|
362 | --prefix=$HOME/development/rtems/4.11 \ |
---|
363 | --bset-tar-file --no-install <1> 4.11/rtems-sparc |
---|
364 | Source Builder - Set Builder, v0.1 |
---|
365 | Build Set: 4.11/rtems-sparc |
---|
366 | config: expat-2.1.0-1.cfg |
---|
367 | package: expat-2.1.0-x86_64-freebsd9.1-1 |
---|
368 | building: expat-2.1.0-x86_64-freebsd9.1-1 |
---|
369 | config: tools/rtems-binutils-2.22-1.cfg |
---|
370 | package: sparc-rtems4.11-binutils-2.22-1 |
---|
371 | building: sparc-rtems4.11-binutils-2.22-1 |
---|
372 | config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg |
---|
373 | package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 |
---|
374 | building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 |
---|
375 | config: tools/rtems-gdb-7.5.1-1.cfg |
---|
376 | package: sparc-rtems4.11-gdb-7.5.1-1 |
---|
377 | building: sparc-rtems4.11-gdb-7.5.1-1 |
---|
378 | tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 <2> |
---|
379 | cleaning: expat-2.1.0-x86_64-freebsd9.1-1 |
---|
380 | cleaning: sparc-rtems4.11-binutils-2.22-1 |
---|
381 | cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 |
---|
382 | cleaning: sparc-rtems4.11-gdb-7.5.1-1 |
---|
383 | Build Set: Time 0:14:11.721274 |
---|
384 | $ ls tar |
---|
385 | rtems-4.11-sparc-rtems4.11-1.tar.bz2 |
---|
386 | ------------------------------------------------------------- |
---|
387 | |
---|
388 | <1> The option to supressing installing the packages. |
---|
389 | <2> Create the build set tar. |
---|
390 | |
---|
391 | A package tar file can be created by adding the +--pkg-tar-files+ to the |
---|
392 | +sb-set-builder+ command. This creates a tar file per package built in the |
---|
393 | build set. |
---|
394 | |
---|
395 | ------------------------------------------------------------- |
---|
396 | $ ../source-builder/sb-set-builder --log=l-sparc.txt \ |
---|
397 | --prefix=$HOME/development/rtems/4.11 \ |
---|
398 | --bset-tar-file --pkg-tar-files <1> --no-install 4.11/rtems-sparc |
---|
399 | Source Builder - Set Builder, v0.1 |
---|
400 | Build Set: 4.11/rtems-sparc |
---|
401 | config: expat-2.1.0-1.cfg |
---|
402 | package: expat-2.1.0-x86_64-freebsd9.1-1 |
---|
403 | building: expat-2.1.0-x86_64-freebsd9.1-1 |
---|
404 | config: tools/rtems-binutils-2.22-1.cfg |
---|
405 | package: sparc-rtems4.11-binutils-2.22-1 |
---|
406 | building: sparc-rtems4.11-binutils-2.22-1 |
---|
407 | config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg |
---|
408 | package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 |
---|
409 | building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 |
---|
410 | config: tools/rtems-gdb-7.5.1-1.cfg |
---|
411 | package: sparc-rtems4.11-gdb-7.5.1-1 |
---|
412 | building: sparc-rtems4.11-gdb-7.5.1-1 |
---|
413 | tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 |
---|
414 | cleaning: expat-2.1.0-x86_64-freebsd9.1-1 |
---|
415 | cleaning: sparc-rtems4.11-binutils-2.22-1 |
---|
416 | cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 |
---|
417 | cleaning: sparc-rtems4.11-gdb-7.5.1-1 |
---|
418 | Build Set: Time 0:14:37.658460 |
---|
419 | $ ls tar |
---|
420 | expat-2.1.0-x86_64-freebsd9.1-1.tar.bz2 sparc-rtems4.11-binutils-2.22-1.tar.bz2 |
---|
421 | sparc-rtems4.11-gdb-7.5.1-1.tar.bz2 <2> rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3> |
---|
422 | sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1.tar.bz2 |
---|
423 | ------------------------------------------------------------- |
---|
424 | |
---|
425 | <1> The option to create packages tar files. |
---|
426 | <2> The GDB package tar file. |
---|
427 | <3> The build set tar file. All the others in a single tar file. |
---|
428 | |
---|
429 | Why Build from Source ? |
---|
430 | ----------------------- |
---|
431 | |
---|
432 | The RTEMS Source Builder is not a replacement for the binary install systems |
---|
433 | you have with commercial operating systems or open source operating system |
---|
434 | distributions. Those products and distributions are critically important and |
---|
435 | are the base that allows the Source Builder to work. The RTEMS Source Builder |
---|
436 | sits somewhere between you manually entering the commands to build a tool set |
---|
437 | and a tool such as +yum+ or +apt-get+ to install binary packages made |
---|
438 | specifically for your host operating system. Building manually or installing a |
---|
439 | binary package from a remote repository are valid and real alternatives while |
---|
440 | the Source Builder is attempting to provide a specific service of repeatably |
---|
441 | being able to build tool sets from source code. |
---|
442 | |
---|
443 | If you are developing a system or product that has a long shelf life or is used |
---|
444 | in a critical piece of infrastructure that has a long life cycle being able to |
---|
445 | build from source is important. It insulates the project from the fast ever |
---|
446 | changing world of the host development machines. If your tool set is binary and |
---|
447 | you have lost the ability to build it you have lost a degree of control and |
---|
448 | flexibility open source gives you. Fast moving host environments are |
---|
449 | fantastic. We have powerful multi-core computers with huge amounts of memory |
---|
450 | and state of the art operating systems to run on them how-ever the product or |
---|
451 | project you are part of may need to be maintained well past the life time of |
---|
452 | these host. Being able to build from source an important and critical part of |
---|
453 | this process because you can move to a newer host and create an equivalent tool |
---|
454 | set. |
---|
455 | |
---|
456 | Building from source provides you with control over the configuration of the |
---|
457 | package you are building. If all or the most important dependent parts are |
---|
458 | built from source you limit the exposure to host variations. For example the |
---|
459 | GNU C compiler (gcc) currently uses a number of 3rd party libraries internally |
---|
460 | (gmp, mpfr, etc). If your validated compiler generating code for your target |
---|
461 | processor is dynamically linked against the host's version of these libraries |
---|
462 | any change in the host's configuration may effect you. The changes the host's |
---|
463 | package management system makes may be perfectly reasonable in relation to the |
---|
464 | distribution being managed how-ever this may not extend to you and your |
---|
465 | tools. Building your tools from source and controlling the specific version of |
---|
466 | these dependent parts means you are not exposing yourself to unexpected and |
---|
467 | often difficult to resolve problems. On the other side you need to make sure |
---|
468 | your tools build and work with newer versions of the host operating |
---|
469 | system. Given the stability of standards based libraries like 'libc' and ever |
---|
470 | improving support for standard header file locations this task is becoming |
---|
471 | easier. |
---|
472 | |
---|
473 | The RTEMS Source Builder is designed to be audited and incorporated into a |
---|
474 | project's verification and validation process. If your project is developing |
---|
475 | critical applications that needs to be traced from source to executable code in |
---|
476 | the target, you need to also consider the tools and how to track them. |
---|
477 | |
---|
478 | If your IT department maintains all your computers and you do not have suitable |
---|
479 | rights to install binary packages, building from source lets you create your |
---|
480 | own tool set that you install under your home directory. Avoiding installing |
---|
481 | any extra packages as a super user is always helpful in maintaining a secure |
---|
482 | computing environment. |
---|
483 | |
---|
484 | Configuration |
---|
485 | ------------- |
---|
486 | |
---|
487 | The RTEMS Source Builder has two types of configuration data: |
---|
488 | |
---|
489 | . Build Sets |
---|
490 | . Package Build Configurations |
---|
491 | |
---|
492 | By default these files can be located in two separate directories and |
---|
493 | searched. The first directory is +config+ in your current working directory |
---|
494 | (+_topdir+) and the second is +config+ located in the base directory of the |
---|
495 | RTEMS Source Builder command you run (+_sbdir+). The RTEMS directory +rtems+ |
---|
496 | located at the top of the RTEMS Source Builder source code is an example of a |
---|
497 | specific build configuration directory. You can create custom or private build |
---|
498 | configurations and if you run the RTEMS Source Builder command from that |
---|
499 | directory your configurations will be used. |
---|
500 | |
---|
501 | [[X1]] The configuration search path is a macro variable and is reference as |
---|
502 | +%\{_configdir\}+. It's default is defined as: |
---|
503 | |
---|
504 | ------------------------------------------------------------- |
---|
505 | _configdir : dir optional %{_topdir}/config:%{_sbdir}/config <1> |
---|
506 | ------------------------------------------------------------- |
---|
507 | |
---|
508 | <1> The +_topdir+ is the directory you run the command from and +_sbdir+ is the |
---|
509 | location of the RTEMS Source Builder command. |
---|
510 | |
---|
511 | Build set files have the file extension +.bset+ and the package build |
---|
512 | configuration files have the file extension of +.cfg+. The +sb-set-builder+ |
---|
513 | command will search for _build sets_ and the +sb-builder+ commands works with |
---|
514 | package build configuration files. |
---|
515 | |
---|
516 | Both types of configuration files use the \'#' character as a comment |
---|
517 | character. Anything after this character on the line is ignored. There is no |
---|
518 | block comment. |
---|
519 | |
---|
520 | Macros and Defaults |
---|
521 | ~~~~~~~~~~~~~~~~~~~ |
---|
522 | |
---|
523 | The RTEMS Source Builder uses a table of _macros_ called the _defaults_. The |
---|
524 | values the _defaults_ are initialised to is dependent on your host. This lets |
---|
525 | the Source Builder handle differences in the hosts. Build set and configuration |
---|
526 | files can define new values extending the defaults. For example builds are |
---|
527 | given a release number. This is typically a single number at the end of the |
---|
528 | package name. For RTEMS this is set in the top level build set configuration |
---|
529 | file with: |
---|
530 | |
---|
531 | ------------------------------------------------------------- |
---|
532 | %define release 1 |
---|
533 | ------------------------------------------------------------- |
---|
534 | |
---|
535 | Once defined if can be accessed in a build set or package configuration file |
---|
536 | with: |
---|
537 | |
---|
538 | ------------------------------------------------------------- |
---|
539 | %{release} |
---|
540 | ------------------------------------------------------------- |
---|
541 | |
---|
542 | The +sb-defaults+ command lists the defaults for your host. I will not include |
---|
543 | the output of this command becauses of its size. |
---|
544 | |
---|
545 | ------------------------------------------------------------- |
---|
546 | $ ../source-builder/sb-defaults |
---|
547 | ------------------------------------------------------------- |
---|
548 | |
---|
549 | A nested build set is given a separate copy of the defaults. Changes in one |
---|
550 | change set are not seen in other build sets. That same happens with |
---|
551 | configuration files unless inline includes are used. |
---|
552 | |
---|
553 | Build Set Files |
---|
554 | ~~~~~~~~~~~~~~~ |
---|
555 | |
---|
556 | Build set files lets you list the packages in the build set you are defining |
---|
557 | and have a file extension of +.bset+. Build sets can define macro variables, |
---|
558 | inline include other files and reference other build set or package |
---|
559 | configuration files. |
---|
560 | |
---|
561 | Defining macros is performed with the +%define+ macro: |
---|
562 | |
---|
563 | ------------------------------------------------------------- |
---|
564 | %define _target m32r-rtems4.11 |
---|
565 | ------------------------------------------------------------- |
---|
566 | |
---|
567 | Inline including another file with the +%include+ macro continues processing |
---|
568 | with the specified file returning to carry on from just after the include |
---|
569 | point. |
---|
570 | |
---|
571 | ------------------------------------------------------------- |
---|
572 | %include rtems-4.11-base.bset |
---|
573 | ------------------------------------------------------------- |
---|
574 | |
---|
575 | This includes the RTEMS 4.11 base set of defines and checks. The configuration |
---|
576 | paths as defined by +_configdir+ are scanned. The file extension is optional. |
---|
577 | |
---|
578 | You reference build set or package configuration files by placing the file name |
---|
579 | on a single line. |
---|
580 | |
---|
581 | ------------------------------------------------------------- |
---|
582 | tools/rtems-binutils-2.22-1 |
---|
583 | ------------------------------------------------------------- |
---|
584 | |
---|
585 | The +_configdir+ path is scanned for +tools/rtems-binutils-2.22-1.bset+ or |
---|
586 | +tools/rtems-binutils-2.22-1.cfg+. Build set files take precedent over package |
---|
587 | configuration files. If +tools/rtems-binutils-2.22-1+ is a build set a new |
---|
588 | instance of the build set processor is created and if the file is a package |
---|
589 | configuration the package is built with the package builder. This all happens |
---|
590 | once the build set file has finished being scanned. |
---|
591 | |
---|
592 | Configuration Control |
---|
593 | ~~~~~~~~~~~~~~~~~~~~~ |
---|
594 | |
---|
595 | The RTEMS Souce Builder is designed to fit within most verification and |
---|
596 | validation processes. All of the RTEMS Source Builder is source code. The |
---|
597 | Python code is source and comes with a commercial friendly license. All |
---|
598 | configuration data is text and can be read or parsed with standard text based |
---|
599 | tools. |
---|
600 | |
---|
601 | File naming provides configuration management. A specific version of a package |
---|
602 | is captured in a specific set of configuration files. The top level |
---|
603 | configuration file referenced in a _build set_ or passed to the +sb-builder+ |
---|
604 | command relates to a specific configuration of the package being built. For |
---|
605 | example the RTEMS configuration file +rtems-gcc-4.7.2-newlib-2.0.0-1.cfg+ |
---|
606 | creates an RTEMS GCC and Newlib package where the GCC version is 4.7.2, the |
---|
607 | Newlib version is 2.0.0, plus any RTEMS specific patches that related to this |
---|
608 | version. The configuration defines the version numbers of the various parts |
---|
609 | that make up this package: |
---|
610 | |
---|
611 | ------------------------------------------------------------- |
---|
612 | %define gcc_version 4.7.2 |
---|
613 | %define newlib_version 2.0.0 |
---|
614 | %define mpfr_version 3.0.1 |
---|
615 | %define mpc_version 0.8.2 |
---|
616 | %define gmp_version 5.0.5 |
---|
617 | ------------------------------------------------------------- |
---|
618 | |
---|
619 | The package build options, if there are any are also defined: |
---|
620 | |
---|
621 | ------------------------------------------------------------- |
---|
622 | %define with_threads 1 |
---|
623 | %define with_plugin 0 |
---|
624 | %define with_iconv 1 |
---|
625 | ------------------------------------------------------------- |
---|
626 | |
---|
627 | The generic configuration may provide defaults in case options are not |
---|
628 | specified. The patches this specific version of the package requires can be |
---|
629 | included: |
---|
630 | |
---|
631 | ------------------------------------------------------------- |
---|
632 | Patch0: gcc-4.7.2-rtems4.11-20121026.diff |
---|
633 | ------------------------------------------------------------- |
---|
634 | |
---|
635 | Finally including the GCC 4.7 configuration script: |
---|
636 | |
---|
637 | ------------------------------------------------------------- |
---|
638 | %include %{_configdir}/gcc-4.7-1.cfg |
---|
639 | ------------------------------------------------------------- |
---|
640 | |
---|
641 | The +gcc-4.7-1.cfg+ file is a generic script to build a GCC 4.7 compiler with |
---|
642 | Newlib. It is not specific to RTEMS. A bare no operating system tool set can be |
---|
643 | built with this file. |
---|
644 | |
---|
645 | The +-1+ part of the file names is a revision. The GCC 4.7 script maybe revised |
---|
646 | to fix a problem and if this fix effects an existing script the file is copied |
---|
647 | and given a +-2+ revision number. Any dependent scripts referencing the earlier |
---|
648 | revision number will not be effected by the change. This locks down a specific |
---|
649 | configuration over time. |
---|
650 | |
---|
651 | Scripting |
---|
652 | ~~~~~~~~~ |
---|
653 | |
---|
654 | Configuration files specify how to build a package. Configuration files are |
---|
655 | scripts and have a +.cfg+ file extension. The script format is based loosely on |
---|
656 | the RPM spec file format how-ever the use and purpose in this tool does not |
---|
657 | compare with the functionality and therefore the important features of the spec |
---|
658 | format RPM needs and uses. |
---|
659 | |
---|
660 | The script language is implemented in terms of macros. The built-in list is: |
---|
661 | |
---|
662 | [horizontal] |
---|
663 | +%{}+:: Macro expansion with conditional logic. |
---|
664 | +%()+:: Shell expansion. |
---|
665 | +%prep+:: The source preparation shell commands. |
---|
666 | +%build+:: The build shell commands. |
---|
667 | +%install+:: The package install shell commands. |
---|
668 | +%clean+:: The package clean shell commands. |
---|
669 | +%include+:: Inline include another configuration file. |
---|
670 | +%name+:: The name of the package. |
---|
671 | +%summary+:: A brief package description. Useful when reporting about a build. |
---|
672 | +%release+:: The package release. A number that is the release as built by this tool. |
---|
673 | +%version+:: The package's version string. |
---|
674 | +%buildarch+:: The build architecture. |
---|
675 | +%setup+:: Setup a source package. |
---|
676 | +%source+:: Define a source code package. This macro has a number appended. |
---|
677 | +%patch+:: Define a patch. This macro has a is number appended. |
---|
678 | +%echo+:: Print the following string as a message. |
---|
679 | +%warning+:: Print the following string as a warning and continue. |
---|
680 | +%error+:: Print the following string as an error and exit. |
---|
681 | +%define+:: Define a macro. Macros cannot be redefined, you must first undefine it. |
---|
682 | +%undefine+:: Undefine a macro. |
---|
683 | +%if+:: Start a conditional logic block that ends with a +%endif+. |
---|
684 | +%ifn+:: Inverted start of a conditional logic block. |
---|
685 | +%ifarch+:: Test the architecture against the following string. |
---|
686 | +%ifnarch+:: Inverted test of the architecture |
---|
687 | +%ifos+:: Test the host operating system. |
---|
688 | +%else+:: Start the _else_ conditional logic block. |
---|
689 | +%endfi+:: End the conditional logic block. |
---|
690 | +%bconf_with+:: Test the build condition _with_ setting. This is the +--with-*+ |
---|
691 | command line option. |
---|
692 | +%bconf_without+:: Test the build condition _without_ setting. This is the |
---|
693 | +--without-*+ command line option. |
---|
694 | |
---|
695 | Expanding |
---|
696 | ^^^^^^^^^ |
---|
697 | |
---|
698 | A macro can be `%{string}` or the equivalent of `%string`. The following macro |
---|
699 | expansions supported are: |
---|
700 | |
---|
701 | `%{string}`;; |
---|
702 | Expand the 'string' replacing the entire macro text with the text in the table |
---|
703 | for the entry 'string . For example if 'var' is 'foo' then `${var}` would |
---|
704 | become `foo`. |
---|
705 | |
---|
706 | `%{expand: string}`;; |
---|
707 | Expand the 'string' and then use it as a ``string'' to the macro expanding the |
---|
708 | macro. For example if _foo_ is set to 'bar' and 'bar' is set to 'foovar' then |
---|
709 | `%{expand:foo}` would result in `foobar`. Shell expansion can also be used. |
---|
710 | |
---|
711 | `%{with string}`;; |
---|
712 | Expand the macro to '1' if the macro `with_`'string' is defined else expand to |
---|
713 | _0_. Macros with the name `with_`'string' can be define with command line |
---|
714 | arguments to the RTEMS Source Builder commands. |
---|
715 | |
---|
716 | `%{defined string}`;; |
---|
717 | Expand the macro to '1' if a macro of name 'string' is defined else expand to '0'. |
---|
718 | |
---|
719 | `%{?string: expression}`;; |
---|
720 | Expand the macro to 'expression' if a macro of name 'string' is defined else expand to `%{nil}`. |
---|
721 | |
---|
722 | `%{!?string: expression}`;; |
---|
723 | Expand the macro to 'expression' if a macro of name 'string' is not defined. If |
---|
724 | the macro is define expand to `%{nil}`. |
---|
725 | |
---|
726 | `%(expression)`;; |
---|
727 | Expand the macro to the result of running the 'expression' in a host shell. It |
---|
728 | is assumed this is a Unix type shell. For example `%(whoami)` will return your |
---|
729 | user name and `%(date)` will return the current date string. |
---|
730 | |
---|
731 | %prep |
---|
732 | ^^^^^ |
---|
733 | |
---|
734 | The +%prep+ macro starts a block that continues until the next block macro. The |
---|
735 | _prep_ or preparation block defines the setup of the package's source and is a |
---|
736 | mix of RTEMS Source Builder macros and shell scripting. The sequence is |
---|
737 | typically +%setup+ macros for source, +%patch+ macros to patch the source |
---|
738 | mixed with some shell commands to correct any source issues. A +%prep+ section |
---|
739 | starts with a +%setup+ command. This creates the package source top level |
---|
740 | directory then is followed by the first source file. |
---|
741 | |
---|
742 | ------------------------------------------------------------- |
---|
743 | <1> <2> |
---|
744 | %setup -q -c -T -n %{name}-%{version} |
---|
745 | %setup -q -T -D -n %{name}-%{version} -a0 |
---|
746 | ------------------------------------------------------------- |
---|
747 | |
---|
748 | <1> The package's name. |
---|
749 | <2> The version of the package. |
---|
750 | |
---|
751 | The source for a package is declared with the +%source*+ macro where +*+ is |
---|
752 | a number. For example +%source0+ is the source 0 tar file and is defined with |
---|
753 | something similar to this: |
---|
754 | |
---|
755 | ------------------------------------------------------------- |
---|
756 | Source0: http://ftp.gnu.org/gnu/gdb/gdb-%{gdb_version}.tar.bz2 |
---|
757 | ------------------------------------------------------------- |
---|
758 | |
---|
759 | This URL is the primary location of the GNU GCC source code and the RTEMS |
---|
760 | Source Builder can download the file from this location and by inspecting the |
---|
761 | file extension use +bzip2+ decompression. When the +%prep+ section is processed |
---|
762 | a check of the local +source+ directory is made to see if the file has already |
---|
763 | been downloaded. If not found in the source cache directory the package is |
---|
764 | downloaded from the URL. You can append other base URLs via the command line |
---|
765 | option +--url+. This option accepts a comma delimited list of sites to try. |
---|
766 | |
---|
767 | You can combine the source macro with conditional logic to implement a default |
---|
768 | that can be over-riden in the top level files. This lets you reuse a generic |
---|
769 | build script with different sources. This happens if you have a private source |
---|
770 | package with local modifications. The following example is taken from the |
---|
771 | +gcc-4.8-1.cfg+ build script. |
---|
772 | |
---|
773 | ------------------------------------------------------------- |
---|
774 | %ifn %{defined Source0} |
---|
775 | Source0: ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2 |
---|
776 | VersionContro0: git clone git://gcc.gnu.org/git/gcc.git <1> |
---|
777 | %endif |
---|
778 | ------------------------------------------------------------- |
---|
779 | |
---|
780 | <1> The version control macro is currently not implemented. |
---|
781 | |
---|
782 | You could optionally have a few source files that make up the package. For |
---|
783 | example GNU's GCC was a few tar files for a while and it is now a single tar |
---|
784 | file. Support for multiple source files can be conditionally implemented with |
---|
785 | the following scripting: |
---|
786 | |
---|
787 | ------------------------------------------------------------- |
---|
788 | %{?source1:%setup -q -T -D -n %{name}-%{version} -a1} |
---|
789 | ------------------------------------------------------------- |
---|
790 | |
---|
791 | The +source1+ macro value is checked and if present the command string after |
---|
792 | the +:+ is executed. It is common to see a number of these present allowing top |
---|
793 | level configuration files including a base configuration the ability to define |
---|
794 | a number of source packages. |
---|
795 | |
---|
796 | ------------------------------------------------------------- |
---|
797 | %{?source1:%setup -q -T -D -n %{name}-%{version} -a1} |
---|
798 | %{?source2:%setup -q -T -D -n %{name}-%{version} -a2} |
---|
799 | %{?source3:%setup -q -T -D -n %{name}-%{version} -a3} |
---|
800 | ------------------------------------------------------------- |
---|
801 | |
---|
802 | Patching also occurs during the preparation stage. Patches are handled in a |
---|
803 | similar way to the source packages. Most patches are based around the top of |
---|
804 | the source tree. This is an example of the patch scripting for the GCC 4.8 |
---|
805 | series of compilers: |
---|
806 | |
---|
807 | ------------------------------------------------------------- |
---|
808 | cd gcc-%{gcc_version} <1> |
---|
809 | %{?patch0:%patch0 -p1} <2> |
---|
810 | %{?patch1:%patch1 -p1} |
---|
811 | %{?patch2:%patch2 -p1} |
---|
812 | %{?patch3:%patch3 -p1} |
---|
813 | %{?patch4:%patch4 -p1} |
---|
814 | %{?patch5:%patch5 -p1} |
---|
815 | %{?patch6:%patch6 -p1} |
---|
816 | %{?patch7:%patch7 -p1} |
---|
817 | %{?patch8:%patch8 -p1} |
---|
818 | %{?patch9:%patch9 -p1} |
---|
819 | cd .. <3> |
---|
820 | ------------------------------------------------------------- |
---|
821 | |
---|
822 | <1> Change from the top of the source tree into the package being patched's top |
---|
823 | directory. |
---|
824 | <2> The conditional macro expansion checks if +%patch0+ is defined and if |
---|
825 | defined issues the +%patch0" macro giving +-p1+ to the patch command. |
---|
826 | <3> Return back to the top of the source tree. |
---|
827 | |
---|
828 | %build |
---|
829 | ^^^^^^ |
---|
830 | |
---|
831 | The +%build+ macro starts a block that continues until the next block |
---|
832 | macro. The build block is a series of shell commands that execute to build the |
---|
833 | package. It assumes all source code has been unpacked, patch and adjusted so |
---|
834 | the build will succeed. |
---|
835 | |
---|
836 | The following is an example take from the GutHub STLink project: |
---|
837 | |
---|
838 | NOTE: STLink is a JTAG debugging device for the ST ARM family of processors. |
---|
839 | |
---|
840 | ------------------------------------------------------------- |
---|
841 | %build |
---|
842 | export PATH="%{_bindir}:${PATH}" <1> |
---|
843 | |
---|
844 | cd texane-stlink-%{stlink_version} <2> |
---|
845 | |
---|
846 | ./autogen.sh <3> |
---|
847 | |
---|
848 | %if "%{_build}" != "%{_host}" |
---|
849 | CFLAGS_FOR_BUILD="-g -O2 -Wall" \ <4> |
---|
850 | %endif |
---|
851 | CPPFLAGS="-I $SB_TMPPREFIX/include/libusb-1.0" \ <5> |
---|
852 | CFLAGS="$SB_OPT_FLAGS" \ |
---|
853 | LDFLAGS="-L $SB_TMPPREFIX/lib" \ |
---|
854 | ./configure \ <6> |
---|
855 | --build=%{_build} --host=%{_host} \ |
---|
856 | --verbose \ |
---|
857 | --prefix=%{_prefix} --bindir=%{_bindir} \ |
---|
858 | --exec-prefix=%{_exec_prefix} \ |
---|
859 | --includedir=%{_includedir} --libdir=%{_libdir} \ |
---|
860 | --mandir=%{_mandir} --infodir=%{_infodir} |
---|
861 | |
---|
862 | %{__make} %{?_smp_mflags} all <7> |
---|
863 | |
---|
864 | cd .. |
---|
865 | ------------------------------------------------------------- |
---|
866 | |
---|
867 | <1> Setup the PATH environment variable. This is not always needed. |
---|
868 | <2> This package builds in the source tree so enter it. |
---|
869 | <3> The package is actually checked directly out from the github project and so |
---|
870 | it needs its autoconf and automake files generated. |
---|
871 | <4> Flags for a cross-compiled build. |
---|
872 | <5> Various settings passed to configure to customise the build. In this |
---|
873 | example an include path is being set to the install point of _libusb_. This |
---|
874 | package requires _libusb_ is built before it. |
---|
875 | <6> The +configure+ command. The RTEMS Source Builder provides all the needed |
---|
876 | paths as macro variables. You just need to provide them to +configure+. |
---|
877 | <7> Running make. Do not use +make+ directly, use the RTEMS Source Builder's |
---|
878 | defined value. This value is specific to the host. A large number of |
---|
879 | packages need GNU make and on BSD systems this is +gmake+. You can |
---|
880 | optionally add the SMP flags if the packages build system can handle |
---|
881 | parallel building with multiple jobs. The +_smp_mflags+ value is |
---|
882 | automatically setup for SMP hosts to match the number of cores the host has. |
---|
883 | |
---|
884 | %install |
---|
885 | ^^^^^^^^ |
---|
886 | |
---|
887 | The +%install+ macro starts a block that continues until the next block |
---|
888 | macro. The install block is a series of shell commands that execute to install |
---|
889 | the package. You can assume the package has build correctly when this block |
---|
890 | starts executing. |
---|
891 | |
---|
892 | Never install the package to the actual _prefix_ the package was built |
---|
893 | with. Always install to the RTEMS Source Builder's temporary path defined in |
---|
894 | the macro variable +\__tmpdir+. The RTEMS Source Builder sets up a shell |
---|
895 | environment variable called +SB_BUILD_ROOT+ as the standard install point. Most |
---|
896 | packages support adding +DESTDIR=+ to the _make install_ command. |
---|
897 | |
---|
898 | Looking at the same example as in <<_build, %build>>: |
---|
899 | |
---|
900 | ------------------------------------------------------------- |
---|
901 | %install |
---|
902 | export PATH="%{_bindir}:${PATH}" <1> |
---|
903 | rm -rf $SB_BUILD_ROOT <2> |
---|
904 | |
---|
905 | cd texane-stlink-%{stlink_version} <3> |
---|
906 | %{__make} DESTDIR=$SB_BUILD_ROOT install <4> |
---|
907 | |
---|
908 | cd .. |
---|
909 | ------------------------------------------------------------- |
---|
910 | |
---|
911 | <1> Setup the PATH environment variable. This is not always needed. |
---|
912 | <2> Clean any installed files. This make sure the install is just what |
---|
913 | the package installs and not any left over files from a broken build or |
---|
914 | install. |
---|
915 | <3> Enter the build directory. In this example it just happens to be the source |
---|
916 | directory. |
---|
917 | <4> Run +make install+ to install the package overriding the +DESTDIR+ make |
---|
918 | variable. |
---|
919 | |
---|
920 | %clean |
---|
921 | ^^^^^^ |
---|
922 | |
---|
923 | The +%clean+ macro starts a block that continues until the next block |
---|
924 | macro. The clean block is a series of shell commands that execute to clean up |
---|
925 | after a package has been built and install. This macro is currenly not been |
---|
926 | used because the RTEMS Source Builder automatically cleans up. |
---|
927 | |
---|
928 | %include |
---|
929 | ^^^^^^^^ |
---|
930 | |
---|
931 | The +%include+ macro inline includes the specific file. The +\__confdir+ |
---|
932 | path is searched. Any relative path component of the include file is appended |
---|
933 | to each part of the +\__configdir+. Adding an extension is optional as files |
---|
934 | with +.bset+ and +.cfg+ are automatically searched for. |
---|
935 | |
---|
936 | Inline including means the file is processed as part of the configuration at |
---|
937 | the point it is included. Parsing continues from the next line in the |
---|
938 | configuration file that contains the +%include+ macro. |
---|
939 | |
---|
940 | Including files allow a kind of configuration file reuse. The outer |
---|
941 | configuration files provide specific information such as package version |
---|
942 | numbers and patches and then include a generic configuration script which |
---|
943 | builds the package. |
---|
944 | |
---|
945 | ------------------------------------------------------------- |
---|
946 | %include %{_configdir}/gcc-4.7-1.cfg |
---|
947 | ------------------------------------------------------------- |
---|
948 | |
---|
949 | %name |
---|
950 | ^^^^^ |
---|
951 | |
---|
952 | The name of the package being built. The name typically contains the components |
---|
953 | of the package and their version number plus a revision number. For the GCC |
---|
954 | with Newlib configuration the name is typically: |
---|
955 | |
---|
956 | ------------------------------------------------------------- |
---|
957 | Name: %{_target}-gcc-%{gcc_version}-newlib-%{newlib_version}-%{release} |
---|
958 | ------------------------------------------------------------- |
---|
959 | |
---|
960 | %summary |
---|
961 | ^^^^^^^^ |
---|
962 | |
---|
963 | The +%summary+ is a brief description of the package. It is useful when |
---|
964 | reporting. This information is not capture in the package anywhere. For the GCC |
---|
965 | with Newlib configuration the summary is typically: |
---|
966 | |
---|
967 | ------------------------------------------------------------- |
---|
968 | Summary: GCC v%{gcc_version} and Newlib v%{newlib_version} for target %{_target} on host %{_host} |
---|
969 | ------------------------------------------------------------- |
---|
970 | |
---|
971 | %release |
---|
972 | ^^^^^^^^ |
---|
973 | |
---|
974 | The +%release+ is packaging number that allows revisions of a package to happen |
---|
975 | where none package versions change. This value typically increases when the |
---|
976 | configuration building the package changes. |
---|
977 | |
---|
978 | ------------------------------------------------------------- |
---|
979 | %define release 1 |
---|
980 | ------------------------------------------------------------- |
---|
981 | |
---|
982 | %version |
---|
983 | ^^^^^^^^ |
---|
984 | |
---|
985 | The +%version% macro sets the version the package. If the package is a single |
---|
986 | component it tracks that component's version number. For example in the |
---|
987 | _libusb_ configuration the +%version+ is the same as +%libusb_version+, |
---|
988 | how-ever in a GCC with Newlib configuration there is no single version |
---|
989 | number. In this case the GCC version is used. |
---|
990 | |
---|
991 | ------------------------------------------------------------- |
---|
992 | Version: %{gcc_version} |
---|
993 | ------------------------------------------------------------- |
---|
994 | |
---|
995 | %buildarch |
---|
996 | ^^^^^^^^^^ |
---|
997 | |
---|
998 | The +%buildarch+ macro is set to the architecture the package contains. This is |
---|
999 | currently not used in the RTEMS Source Builder and may go away. This macro is |
---|
1000 | more important in a real packaging system where the package could end up on the |
---|
1001 | wrong architecture. |
---|
1002 | |
---|
1003 | %setup |
---|
1004 | ^^^^^^ |
---|
1005 | |
---|
1006 | The +%setup+ macro sets up the source code tree and is used in the +%prep+ |
---|
1007 | section of the script. The options are: |
---|
1008 | |
---|
1009 | [horizontal] |
---|
1010 | *Switch*:: *Description* |
---|
1011 | +-n+:: The -n option is used to set the name of the software's build |
---|
1012 | directory. This is necessary only when the source archive unpacks into a |
---|
1013 | directory named other than +<name>-<version>+. |
---|
1014 | +-c+:: The -c option is used to direct %setup to create the top-level build |
---|
1015 | directory before unpacking the sources. |
---|
1016 | +-D+:: The -D option is used to direct %setup to not delete the build directory |
---|
1017 | prior to unpacking the sources. This option is used when more than one source |
---|
1018 | archive is to be unpacked into the build directory, normally with the +-b+ or |
---|
1019 | +-a+ options. |
---|
1020 | +-T+:: The -T option is used to direct %setup to not perform the default |
---|
1021 | unpacking of the source archive specified by the first Source: macro. It is used |
---|
1022 | with the +-a+ or +-b+ options. |
---|
1023 | +-b <n>+:: The -b option is used to direct %setup to unpack the source archive |
---|
1024 | specified on the nth Source: macro line before changing directory into the build |
---|
1025 | directory. |
---|
1026 | +-a <n>+:: The -a option is used to direct %setup to unpack the source archive |
---|
1027 | specified on the nth Source: macro line after changing directory into the build |
---|
1028 | directory. |
---|
1029 | |
---|
1030 | %source |
---|
1031 | ^^^^^^^ |
---|
1032 | |
---|
1033 | The +%source+ macro is numbered and defines a source tar file used in the |
---|
1034 | package. The +%setup+ macro references the packages defined here. A macro is |
---|
1035 | defined as: |
---|
1036 | |
---|
1037 | ------------------------------------------------------------- |
---|
1038 | Source0: ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2 |
---|
1039 | ------------------------------------------------------------- |
---|
1040 | |
---|
1041 | The setup script is: |
---|
1042 | |
---|
1043 | ------------------------------------------------------------- |
---|
1044 | %setup -q -T -D -n %{name}-%{version} -a0 |
---|
1045 | ------------------------------------------------------------- |
---|
1046 | |
---|
1047 | The +-a0+ means use +%source0+. |
---|
1048 | |
---|
1049 | %patch |
---|
1050 | ^^^^^^ |
---|
1051 | |
---|
1052 | The +%patch+ macro is numbered and can define a patch and in the +%prep+ |
---|
1053 | section applies the patch. To define a patch append a +:+ followed by the patch |
---|
1054 | filename: |
---|
1055 | |
---|
1056 | ------------------------------------------------------------- |
---|
1057 | Patch0: gcc-4.7.2-rtems4.11-20121026.diff |
---|
1058 | ------------------------------------------------------------- |
---|
1059 | |
---|
1060 | The +__patchdir+ path is search. |
---|
1061 | |
---|
1062 | Placing +%patch+ in the +%prep+ section will apply it with any trailing options |
---|
1063 | passed to the +patch+ command. This allows the +-p+ option to be passed to |
---|
1064 | strip any leading path components from the patch contents. |
---|
1065 | |
---|
1066 | ------------------------------------------------------------- |
---|
1067 | %patch0 -p1 |
---|
1068 | ------------------------------------------------------------- |
---|
1069 | |
---|
1070 | You will typically see the patch conditionally used as: |
---|
1071 | |
---|
1072 | ------------------------------------------------------------- |
---|
1073 | %{patch0:%patch0 -p1} |
---|
1074 | ------------------------------------------------------------- |
---|
1075 | |
---|
1076 | In this case the patch will only be applied if it is defined. |
---|
1077 | |
---|
1078 | %echo |
---|
1079 | ^^^^^ |
---|
1080 | |
---|
1081 | The +%echo+ macro outputs the following string to stdout. This can also be used |
---|
1082 | as `%{echo: message}`. |
---|
1083 | |
---|
1084 | %warning |
---|
1085 | ^^^^^^^^ |
---|
1086 | |
---|
1087 | The +%warning+ macro outputs the following string as a warning. This can also |
---|
1088 | be used as `%{warning: message}`. |
---|
1089 | |
---|
1090 | %error |
---|
1091 | ^^^^^^ |
---|
1092 | |
---|
1093 | The +%error+ macro outputs the follow string as an error and exits the RTEMS |
---|
1094 | Source Builder. This can also be used as `%{error: message}`. |
---|
1095 | |
---|
1096 | %define |
---|
1097 | ^^^^^^^ |
---|
1098 | |
---|
1099 | The +%define+ macro defines a new macro or updates an existing one. If no value |
---|
1100 | is given it is assumed to be 1. |
---|
1101 | |
---|
1102 | ------------------------------------------------------------- |
---|
1103 | %define foo bar |
---|
1104 | %define one_plus_one 2 |
---|
1105 | %define one <1> |
---|
1106 | ------------------------------------------------------------- |
---|
1107 | |
---|
1108 | <1> The macro _one_ is set to 1. |
---|
1109 | |
---|
1110 | %undefine |
---|
1111 | ^^^^^^^^^ |
---|
1112 | |
---|
1113 | The +%undefine+ macro removes a macro if it exists. Any further references to |
---|
1114 | it will result in an undefine macro error. |
---|
1115 | |
---|
1116 | %if |
---|
1117 | ^^^ |
---|
1118 | |
---|
1119 | The +%if+ macro starts a conditional logic block that can optionally have a |
---|
1120 | _else_ section. A test follows this macro and can have the following operators: |
---|
1121 | |
---|
1122 | [horizontal] |
---|
1123 | *Operator*:: *Description* |
---|
1124 | +%{}+:: Check the macro is set or _true_, ie non-zero. |
---|
1125 | + |
---|
1126 | ------------------------------------------------------------- |
---|
1127 | %if ${foo} |
---|
1128 | %warning The test passes, must not be empty or is non-zero |
---|
1129 | %else |
---|
1130 | %error The test fails, must be empty or zero |
---|
1131 | %endif |
---|
1132 | ------------------------------------------------------------- |
---|
1133 | +!+:: The _not_ operator inverts the test of the macro. |
---|
1134 | + |
---|
1135 | ------------------------------------------------------------- |
---|
1136 | %if ! ${foo} |
---|
1137 | %warning The test passes, must be empty or zero |
---|
1138 | %else |
---|
1139 | %error The test fails, must not be empty or is non-zero |
---|
1140 | %endif |
---|
1141 | ------------------------------------------------------------- |
---|
1142 | +==+:: The left hand size must equal the right hand side. For example: |
---|
1143 | + |
---|
1144 | ------------------------------------------------------------- |
---|
1145 | %define one 1 |
---|
1146 | %if ${one} == 1 |
---|
1147 | %warning The test passes |
---|
1148 | %else |
---|
1149 | %error The test fails |
---|
1150 | %endif |
---|
1151 | ------------------------------------------------------------- |
---|
1152 | + |
---|
1153 | You can also check to see if a macro is empty: |
---|
1154 | + |
---|
1155 | ------------------------------------------------------------- |
---|
1156 | %if ${nothing} == %{nil} |
---|
1157 | %warning The test passes |
---|
1158 | %else |
---|
1159 | %error The test fails |
---|
1160 | %endif |
---|
1161 | ------------------------------------------------------------- |
---|
1162 | +!=+:: The left hand size does not equal the right hand side. For example: |
---|
1163 | + |
---|
1164 | ------------------------------------------------------------- |
---|
1165 | %define one 1 |
---|
1166 | %if ${one} != 2 |
---|
1167 | %warning The test passes |
---|
1168 | %else |
---|
1169 | %error The test fails |
---|
1170 | %endif |
---|
1171 | ------------------------------------------------------------- |
---|
1172 | + |
---|
1173 | You can also check to see if something is set: |
---|
1174 | + |
---|
1175 | ------------------------------------------------------------- |
---|
1176 | %if ${something} != %{nil} |
---|
1177 | %warning The test passes |
---|
1178 | %else |
---|
1179 | %error The test fails |
---|
1180 | %endif |
---|
1181 | ------------------------------------------------------------- |
---|
1182 | +>+:: The left hand side is numerically greater than the right hand side. |
---|
1183 | +>=+:: The left hand side is numerically greater than or equal to the right |
---|
1184 | hand side. |
---|
1185 | +<+:: The left hand side is numerically less than the right hand side. |
---|
1186 | +\<=+:: The left hand side is numerically less than or equal to the right hand |
---|
1187 | side. |
---|
1188 | |
---|
1189 | %ifn |
---|
1190 | ^^^^ |
---|
1191 | |
---|
1192 | The +%ifn+ macro inverts the normal +%if+ logic. It avoids needing to provide |
---|
1193 | empty _if_ blocks followed by _else_ blocks. It is useful when checking if a |
---|
1194 | macro is defined: |
---|
1195 | |
---|
1196 | ------------------------------------------------------------- |
---|
1197 | %ifn %{defined foo} |
---|
1198 | %define foo bar |
---|
1199 | %endif |
---|
1200 | ------------------------------------------------------------- |
---|
1201 | |
---|
1202 | %ifarch |
---|
1203 | ^^^^^^^ |
---|
1204 | |
---|
1205 | The +%ifarch+ is a short cut for "+%if %{\_arch} == i386+". Currently not used. |
---|
1206 | |
---|
1207 | %ifnarch |
---|
1208 | ^^^^^^^^ |
---|
1209 | |
---|
1210 | The +%ifnarch+ is a short cut for "+%if %{\_arch} != i386+". Currently not |
---|
1211 | used. |
---|
1212 | |
---|
1213 | %ifos |
---|
1214 | ^^^^^ |
---|
1215 | |
---|
1216 | The +%ifos+ is a short cut for "+%if %{\_os} != mingw32+". It allows |
---|
1217 | conditional support for various operating system differences when building |
---|
1218 | packages. |
---|
1219 | |
---|
1220 | %else |
---|
1221 | ^^^^^ |
---|
1222 | |
---|
1223 | The +%else+ macro starts the conditional _else_ block. |
---|
1224 | |
---|
1225 | %endfi |
---|
1226 | ^^^^^^ |
---|
1227 | |
---|
1228 | The +%endif+ macro ends a conditional logic block. |
---|
1229 | |
---|
1230 | %bconf_with |
---|
1231 | ^^^^^^^^^^^ |
---|
1232 | |
---|
1233 | The +%bconf_with+ macro provides a way to test if the user has passed a |
---|
1234 | specific option on the command line with the +--with-<label>+ option. This |
---|
1235 | option is only available with the +sb-builder+ command. |
---|
1236 | |
---|
1237 | %bconf_without |
---|
1238 | ^^^^^^^^^^^^^^ |
---|
1239 | |
---|
1240 | The +%bconf_without+ macro provides a way to test if the user has passed a |
---|
1241 | specific option on the command line with the +--without-<label>+ option. This |
---|
1242 | option is only available with the +sb-builder+ command. |
---|
1243 | |
---|
1244 | |
---|
1245 | Project Sets |
---|
1246 | ------------ |
---|
1247 | |
---|
1248 | The RTEMS Source Builder supports project configurations. Project |
---|
1249 | configurations can be public or private and can be contained in the RTEMS |
---|
1250 | Source Builder project if suitable, other projects they use the RTEM Source |
---|
1251 | Builder or privately on your local file system. |
---|
1252 | |
---|
1253 | The configuration file loader searches the macro +_configdir+ and by default |
---|
1254 | this is set to +%{\_topdir}/config:%{\_sbdir}/config+ where +_topdir+ is the |
---|
1255 | your current working direct, in other words the directory you invoke the RTEMS |
---|
1256 | Source Builder command in, and +_sbdir+ is the directory where the RTEMS Source |
---|
1257 | Builder command resides. Therefore the +config+ directory under each of these |
---|
1258 | is searched so all you need to do is create a +config+ in your project and add |
---|
1259 | your configuration files. They do not need to be under the RTEMS Source Builder |
---|
1260 | source tree. Public projects are included in the main RTEMS Source Builder such |
---|
1261 | as RTEMS. |
---|
1262 | |
---|
1263 | You can also add your own +patches+ directory next to your +config+ directory |
---|
1264 | as the +%patch+ command searches the +_patchdir+ macro variable and it is |
---|
1265 | by default set to +%{\_topdir}/patches:%{\_sbdir}/patches+. |
---|
1266 | |
---|
1267 | The +source-builder/config+ directory provides generic scripts for building |
---|
1268 | various tools. You can specialise these in your private configurations to make |
---|
1269 | use of them. If you add new generic configurations please contribute them back |
---|
1270 | to the project |
---|
1271 | |
---|
1272 | RTEMS Configurations |
---|
1273 | ~~~~~~~~~~~~~~~~~~~~ |
---|
1274 | |
---|
1275 | The RTEMS Configurations are grouped by RTEMS version. In RTEMS the tools are |
---|
1276 | specific to a specific version because of variations between Newlib and |
---|
1277 | RTEMS. Restructuring in RTEMS and Newlib sometimes moves _libc_ functionality |
---|
1278 | between them and this makes existing tool incompatible with RTEMS. |
---|
1279 | |
---|
1280 | RTEMS allows architectures to have different tool versions and patches. The |
---|
1281 | large number of architectures RTEMS supports can make it difficult to get a |
---|
1282 | common stable version of all the packages. An architecture may require a recent |
---|
1283 | GCC because an existing bug has been fixed, how-ever the more recent version |
---|
1284 | may have a bug in other architecture. Architecture specific patches should be |
---|
1285 | limited to the architecture it relates to. The patch may fix a problem on the |
---|
1286 | effect architecture how-ever it could introduce a problem in another |
---|
1287 | architecture. Limit exposure limits any possible crosstalk between |
---|
1288 | architectures. |
---|
1289 | |
---|
1290 | RTEMS supports _stable_ and _unstable_ configuration of tools. The stable build |
---|
1291 | sets are referenced as +<version>/rtems-<arch>+ and the unstable build sets are |
---|
1292 | references as +<version>/unstable/rtems-<arch>+. |
---|
1293 | |
---|
1294 | Commands |
---|
1295 | -------- |
---|
1296 | |
---|
1297 | Checker (sb-check) |
---|
1298 | ~~~~~~~~~~~~~~~~~~ |
---|
1299 | |
---|
1300 | This commands checks your system is set up correctly. Most options are ignored. |
---|
1301 | |
---|
1302 | ------------------------------------------------------------- |
---|
1303 | $ ../source-builder/sb-check --help |
---|
1304 | sb-check: [options] [args] |
---|
1305 | RTEMS Source Builder, an RTEMS Tools Project (c) 2012-2013 Chris Johns |
---|
1306 | Options and arguments: |
---|
1307 | --force : Create directories that are not present |
---|
1308 | --trace : Trace the execution (not current used) |
---|
1309 | --dry-run : Do everything but actually run the build |
---|
1310 | --warn-all : Generate warnings |
---|
1311 | --no-clean : Do not clean up the build tree |
---|
1312 | --no-smp : Run with 1 job and not as many as CPUs |
---|
1313 | --rebuild : Rebuild (not used) |
---|
1314 | --host : Set the host triplet |
---|
1315 | --build : Set the build triplet |
---|
1316 | --target : Set the target triplet |
---|
1317 | --prefix path : Tools build prefix, ie where they are installed |
---|
1318 | --prefixbase path : |
---|
1319 | --topdir path : Top of the build tree, default is $PWD |
---|
1320 | --configdir path : Path to the configuration directory, default: ./config |
---|
1321 | --builddir path : Path to the build directory, default: ./build |
---|
1322 | --sourcedir path : Path to the source directory, default: ./source |
---|
1323 | --tmppath path : Path to the temp directory, default: ./tmp |
---|
1324 | --log file : Log file where all build out is written too |
---|
1325 | --url url : URL to look for source |
---|
1326 | --targetcflags flags : List of C flags for the target code |
---|
1327 | --targetcxxflags flags : List of C++ flags for the target code |
---|
1328 | --libstdcxxflags flags : List of C++ flags to build the target libstdc++ code |
---|
1329 | --with-<label> : Add the --with-<label> to the build |
---|
1330 | --without-<label> : Add the --without-<label> to the build |
---|
1331 | $ ../source-builder/sb-check |
---|
1332 | RTEMS Source Builder environment is ok |
---|
1333 | ------------------------------------------------------------- |
---|
1334 | |
---|
1335 | Defaults (sb-defaults) |
---|
1336 | ~~~~~~~~~~~~~~~~~~~~~~ |
---|
1337 | |
---|
1338 | This commands outputs and the default macros for your when given no |
---|
1339 | arguments. Most options are ignored. |
---|
1340 | |
---|
1341 | ------------------------------------------------------------- |
---|
1342 | $ ../source-builder/sb-defaults --help |
---|
1343 | sb-defaults: [options] [args] |
---|
1344 | RTEMS Source Builder, an RTEMS Tools Project (c) 2012-2013 Chris Johns |
---|
1345 | Options and arguments: |
---|
1346 | --force : Force the build to proceed |
---|
1347 | --trace : Trace the execution (not current used) |
---|
1348 | --dry-run : Do everything but actually run the build |
---|
1349 | --warn-all : Generate warnings |
---|
1350 | --no-clean : Do not clean up the build tree |
---|
1351 | --no-smp : Run with 1 job and not as many as CPUs |
---|
1352 | --rebuild : Rebuild (not used) |
---|
1353 | --host : Set the host triplet |
---|
1354 | --build : Set the build triplet |
---|
1355 | --target : Set the target triplet |
---|
1356 | --prefix path : Tools build prefix, ie where they are installed |
---|
1357 | --prefixbase path : |
---|
1358 | --topdir path : Top of the build tree, default is $PWD |
---|
1359 | --configdir path : Path to the configuration directory, default: ./config |
---|
1360 | --builddir path : Path to the build directory, default: ./build |
---|
1361 | --sourcedir path : Path to the source directory, default: ./source |
---|
1362 | --tmppath path : Path to the temp directory, default: ./tmp |
---|
1363 | --log file : Log file where all build out is written too |
---|
1364 | --url url : URL to look for source |
---|
1365 | --targetcflags flags : List of C flags for the target code |
---|
1366 | --targetcxxflags flags : List of C++ flags for the target code |
---|
1367 | --libstdcxxflags flags : List of C++ flags to build the target libstdc++ code |
---|
1368 | --with-<label> : Add the --with-<label> to the build |
---|
1369 | --without-<label> : Add the --without-<label> to the build |
---|
1370 | ------------------------------------------------------------- |
---|
1371 | |
---|
1372 | Set Builder (sb-set-builder) |
---|
1373 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
1374 | |
---|
1375 | This command builds a set. |
---|
1376 | |
---|
1377 | ------------------------------------------------------------- |
---|
1378 | $ ../source-builder/sb-set-builder --help |
---|
1379 | sb-set-builder: [options] [args] |
---|
1380 | RTEMS Source Builder, an RTEMS Tools Project (c) 2012-2013 Chris Johns |
---|
1381 | Options and arguments: |
---|
1382 | --force : Force the build to proceed |
---|
1383 | --trace : Trace the execution (not current used) |
---|
1384 | --dry-run : Do everything but actually run the build |
---|
1385 | --warn-all : Generate warnings |
---|
1386 | --no-clean : Do not clean up the build tree |
---|
1387 | --no-smp : Run with 1 job and not as many as CPUs |
---|
1388 | --rebuild : Rebuild (not used) |
---|
1389 | --host : Set the host triplet |
---|
1390 | --build : Set the build triplet |
---|
1391 | --target : Set the target triplet |
---|
1392 | --prefix path : Tools build prefix, ie where they are installed |
---|
1393 | --prefixbase path : |
---|
1394 | --topdir path : Top of the build tree, default is $PWD |
---|
1395 | --configdir path : Path to the configuration directory, default: ./config |
---|
1396 | --builddir path : Path to the build directory, default: ./build |
---|
1397 | --sourcedir path : Path to the source directory, default: ./source |
---|
1398 | --tmppath path : Path to the temp directory, default: ./tmp |
---|
1399 | --log file : Log file where all build out is written too |
---|
1400 | --url url : URL to look for source |
---|
1401 | --targetcflags flags : List of C flags for the target code |
---|
1402 | --targetcxxflags flags : List of C++ flags for the target code |
---|
1403 | --libstdcxxflags flags : List of C++ flags to build the target libstdc++ code |
---|
1404 | --with-<label> : Add the --with-<label> to the build |
---|
1405 | --without-<label> : Add the --without-<label> to the build |
---|
1406 | --list-bsets : List available build sets |
---|
1407 | --keep-going : Do not stop on error. |
---|
1408 | --no-install : Do not install the packages to the prefix. |
---|
1409 | --bset-tar-file : Create a build set tar file |
---|
1410 | --list-configs : List available configurations |
---|
1411 | --pkg-tar-files : Create package tar files |
---|
1412 | ------------------------------------------------------------- |
---|
1413 | |
---|
1414 | .Arguments |
---|
1415 | The +[args]+ are a list build sets to build. |
---|
1416 | |
---|
1417 | .Options |
---|
1418 | +--force+;; |
---|
1419 | Force the build to proceed even if the host check fails. Typically this happens |
---|
1420 | if executable files are found in the path at a different location to the host |
---|
1421 | defaults. |
---|
1422 | +--trace+;; |
---|
1423 | Trace enable printing of debug information to stdout. It is really only of use |
---|
1424 | to RTEMS Source Builder's developers. |
---|
1425 | +--dry-run+;; |
---|
1426 | Do everything but actually run the build commands. This is useful when checking |
---|
1427 | a new configuration parses cleanly. |
---|
1428 | +--warn-all+;; |
---|
1429 | Generate warnings. |
---|
1430 | +--no-clean+;; |
---|
1431 | Do not clean up the build tree during the cleaning phase of the build. This |
---|
1432 | leaves the source and the build output on disk so you can make changes, or |
---|
1433 | amend or generate new patches. It also allows you to review configure type |
---|
1434 | output such as +config.log+. |
---|
1435 | +--no-smp+;; |
---|
1436 | Run +make+ with 1 job and not as many as there are cores. This option can help |
---|
1437 | isolate parallel make type bugs or make the log file output |
---|
1438 | sequential. Parallel jobs can make the output confusing. |
---|
1439 | +--host+;; |
---|
1440 | Set the host triplet value. Becareful with this option. |
---|
1441 | +--build+;; |
---|
1442 | Set the build triplet. Becareful with this option. |
---|
1443 | +--target+;; |
---|
1444 | Set the target triplet. Becareful with this option. This is useful if you have |
---|
1445 | a generic configuration script that can work for a range of architectures. |
---|
1446 | +--prefix path+;; |
---|
1447 | Tools build prefix, ie where they are installed. |
---|
1448 | +--prefixbase path+;; |
---|
1449 | The prefix base is appended to the build root path. |
---|
1450 | +--topdir path+;; |
---|
1451 | Top of the build tree, that is the current directory you are in. |
---|
1452 | +--configdir path+;; |
---|
1453 | Path to the configuration directory. This overrides the built in defaults. |
---|
1454 | +--builddir path+;; |
---|
1455 | Path to the build directory. This overrides the default of +build+. |
---|
1456 | +--sourcedir path+;; |
---|
1457 | Path to the source directory. This overrides the default of +source+. |
---|
1458 | +--tmppath path+;; |
---|
1459 | Path to the temporary directory. This overrides the default of +tmp+. |
---|
1460 | +--log file+;; |
---|
1461 | Log all the output from the build process. The output is directed to +stdout+ |
---|
1462 | if no log file is provided. |
---|
1463 | +--url url+;; |
---|
1464 | URL to look for source when downloading. This is can be comma separate list. |
---|
1465 | +--targetcflags flags+;; |
---|
1466 | List of C flags for the target code. This allows for specific local |
---|
1467 | customisation when testing new variations. |
---|
1468 | +--targetcxxflags flags+;; |
---|
1469 | List of C++ flags for the target code. This allows for specific local |
---|
1470 | customisation when testing new variations. |
---|
1471 | +--libstdcxxflags flags+;; |
---|
1472 | List of C\++ flags to build the target libstdc++ code. This allows for specific |
---|
1473 | local customisation when testing new variations. |
---|
1474 | +--with-<label>+;; |
---|
1475 | Add the --with-<label> to the build. This can be tested for in a script with |
---|
1476 | the +%bconf_with+ macro. |
---|
1477 | +--without-<label>+;; |
---|
1478 | Add the --without-<label> to the build. This can be tested for in a script with |
---|
1479 | the +%bconf_without+ macro. |
---|
1480 | +--list-bsets+;; |
---|
1481 | List available build sets. |
---|
1482 | +--list-configs+;; |
---|
1483 | List available configurations. |
---|
1484 | +--keep-going+;; |
---|
1485 | Do not stop on error. This is useful if your build sets performs a large number |
---|
1486 | of testing related builds and there are errors. |
---|
1487 | +--no-install+;; |
---|
1488 | Do not install the packages to the prefix. Use this if you are only after the |
---|
1489 | tar files. |
---|
1490 | +--bset-tar-file+;; |
---|
1491 | Create a build set tar file. This is a single tar file of all the packages in |
---|
1492 | the build set. |
---|
1493 | +--pkg-tar-files+;; |
---|
1494 | Create package tar files. A tar file will be created for each package built in |
---|
1495 | a build set. |
---|
1496 | |
---|
1497 | Set Builder (sb-builder) |
---|
1498 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
1499 | |
---|
1500 | This command builds a configuration as described in a configuration |
---|
1501 | file. Configuration files have the extension of +.cfg+. |
---|
1502 | |
---|
1503 | ------------------------------------------------------------- |
---|
1504 | $ ./source-builder/sb-builder --help |
---|
1505 | sb-builder: [options] [args] |
---|
1506 | RTEMS Source Builder, an RTEMS Tools Project (c) 2012 Chris Johns |
---|
1507 | Options and arguments: |
---|
1508 | --force : Create directories that are not present |
---|
1509 | --trace : Trace the execution (not current used) |
---|
1510 | --dry-run : Do everything but actually run the build |
---|
1511 | --warn-all : Generate warnings |
---|
1512 | --no-clean : Do not clean up the build tree |
---|
1513 | --no-smp : Run with 1 job and not as many as CPUs |
---|
1514 | --rebuild : Rebuild (not used) |
---|
1515 | --host : Set the host triplet |
---|
1516 | --build : Set the build triplet |
---|
1517 | --target : Set the target triplet |
---|
1518 | --prefix path : Tools build prefix, ie where they are installed |
---|
1519 | --prefixbase path : |
---|
1520 | --topdir path : Top of the build tree, default is $PWD |
---|
1521 | --configdir path : Path to the configuration directory, default: ./config |
---|
1522 | --builddir path : Path to the build directory, default: ./build |
---|
1523 | --sourcedir path : Path to the source directory, default: ./source |
---|
1524 | --tmppath path : Path to the temp directory, default: ./tmp |
---|
1525 | --log file : Log file where all build out is written too |
---|
1526 | --url url : URL to look for source |
---|
1527 | --targetcflags flags : List of C flags for the target code |
---|
1528 | --targetcxxflags flags : List of C++ flags for the target code |
---|
1529 | --libstdcxxflags flags : List of C++ flags to build the target libstdc++ code |
---|
1530 | --with-<label> : Add the --with-<label> to the build |
---|
1531 | --without-<label> : Add the --without-<label> to the build |
---|
1532 | --list-configs : List available configurations |
---|
1533 | ------------------------------------------------------------- |
---|
1534 | |
---|
1535 | Host Setups |
---|
1536 | ----------- |
---|
1537 | |
---|
1538 | MacOS X |
---|
1539 | ~~~~~~~ |
---|
1540 | |
---|
1541 | The RTEMS Source Builder has been tested on Mountain Lion. You will need to |
---|
1542 | install the Xcode app using the _App Store_ tool, run Xcode and install the |
---|
1543 | Developers Tools package within Xcode. |
---|
1544 | |
---|
1545 | Ubuntu |
---|
1546 | ~~~~~~ |
---|
1547 | |
---|
1548 | The latest testing was with 12.10. A minimal installation was used and the |
---|
1549 | following packages installed. |
---|
1550 | |
---|
1551 | ------------------------------------------------------------- |
---|
1552 | $ sudo apt-get build-dep binutils gcc g++ gdb unzip git |
---|
1553 | ------------------------------------------------------------- |
---|
1554 | |
---|
1555 | Raspbian |
---|
1556 | ~~~~~~~~ |
---|
1557 | |
---|
1558 | The is the Debian distribution for the Raspberry Pi. The following packages are |
---|
1559 | required. |
---|
1560 | |
---|
1561 | ------------------------------------------------------------- |
---|
1562 | $ sudo apt-get install autoconf automake bison flex binutils gcc g++ gdb \ |
---|
1563 | texinfo unzip ncurses-dev python-dev git |
---|
1564 | ------------------------------------------------------------- |
---|
1565 | |
---|
1566 | It is recommended you get Model B of the Pi with 512M of memory and to mount a |
---|
1567 | remote disk over the network. The tools can be build with a prefix under your |
---|
1568 | home directory as recommended and end up on the SD card. |
---|
1569 | |
---|
1570 | CentOS 6 |
---|
1571 | ~~~~~~~~ |
---|
1572 | |
---|
1573 | The following packages are required on a minimal CentOS 6.3 installation: |
---|
1574 | |
---|
1575 | ------------------------------------------------------------- |
---|
1576 | # yum install autoconf automake binutils gcc gcc-c++ gdb make patch \ |
---|
1577 | bison flex xz unzip ncurses-devel texinfo zlib-devel python-devel git |
---|
1578 | ------------------------------------------------------------- |
---|
1579 | |
---|
1580 | The minimal CentOS distribution is a specific DVD that installs a minimal |
---|
1581 | system. If you use a full system some of these packages may have been |
---|
1582 | installed. |
---|
1583 | |
---|
1584 | History |
---|
1585 | ------- |
---|
1586 | |
---|
1587 | The RTEMS Source Builder is a stand alone tool based on another tool called the |
---|
1588 | 'SpecBuilder'. The SpecBuilder was written for the RTEMS project to give me a |
---|
1589 | way to build tools on hosts that did not support RPMs. At the time the RTEMS |
---|
1590 | tools maintainer only used spec files to create various packages. This meant I |
---|
1591 | had either spec files, RPM files or SRPM files. The RPM and SPRM files where |
---|
1592 | useless because you needed an 'rpm' type tool to extract and manage them. There |
---|
1593 | are versions of 'rpm' for a number of non-RPM hosts how-ever these proved to be |
---|
1594 | in various broken states and random-ally maintained. The solution I settled on |
---|
1595 | was to use spec files so I wrote a Python based tool that parsed the spec file |
---|
1596 | format and allowed me to create a shell script I could run to build the |
---|
1597 | package. This approach proved successful and I was able to track the RPM |
---|
1598 | version of the RTEMS tools on a non-RPM host over a number of years. How-ever |
---|
1599 | the SpecBuilder tool did not help me build tools or other packages not related |
---|
1600 | to the RTEMS project where there was no spec file I could use so I needed |
---|
1601 | another tool. Rather than start again I decided to take the parsing code for |
---|
1602 | the spec file format and build a new tool called the RTEMS Source Builder. |
---|