1 | @c |
---|
2 | @c $Id$ |
---|
3 | @c |
---|
4 | |
---|
5 | @chapter Building RTEMS |
---|
6 | |
---|
7 | Building any package in a cross-compilation fashion can be difficult, |
---|
8 | but configuring and building a real-time operating system that |
---|
9 | supports many CPU families and target boards can be confusing. The |
---|
10 | RTEMS development team has made every effort to make this process as |
---|
11 | straight forward as possible but there are going to be questions. |
---|
12 | |
---|
13 | Moreover, between RTEMS 4.0 and 4.5, the configure and Makefile system in RTEMS |
---|
14 | was changed to be more compatible with GNU standards. This transition |
---|
15 | has lead to a number of subtle differences. |
---|
16 | |
---|
17 | This section of the FAQ tries to address the more frequently asked |
---|
18 | questions about building RTEMS. Thanks to Ralf Corsepius for |
---|
19 | compiling this section from excerpts from various postings to the |
---|
20 | rtems-users mailing list. |
---|
21 | |
---|
22 | @section Required Tools |
---|
23 | |
---|
24 | @subsection Which tools are required to build RTEMS? |
---|
25 | |
---|
26 | @itemize @bullet |
---|
27 | |
---|
28 | @item A native C-Toolchain, gcc prefered |
---|
29 | @item GNU-Bash and shell utils |
---|
30 | @item GNU-make. |
---|
31 | @item A target (typically cross) C- and (optional) C++-Toolchain. |
---|
32 | @item autoconf/automake (optional, recommended) |
---|
33 | @item Perl (optional, recommended, needed by automake and some tools within RTEMS) |
---|
34 | @item m4 (optional, recommended, needed by autoconf, GNU-m4 preferred) |
---|
35 | |
---|
36 | @end itemize |
---|
37 | |
---|
38 | @subsection Do I need autoconf and automake to build RTEMS? |
---|
39 | |
---|
40 | No, you don't. Or to be more accurate, you won't need them until you |
---|
41 | modify something in RTEMS's Makefile.ams/configure.acs or start to develop |
---|
42 | with RTEMS. |
---|
43 | |
---|
44 | I.e. you won't need them to get started, but you will need them when getting |
---|
45 | serious. |
---|
46 | |
---|
47 | @subsection Do I need a native gcc on my host? |
---|
48 | |
---|
49 | No, you should be able to use any native, ansi-compliant C-compiler, but |
---|
50 | using a native gcc is highly recommended. |
---|
51 | |
---|
52 | @subsection Can I use a non-gcc cross-toolchain? |
---|
53 | |
---|
54 | Generally speaking, it should be possible. |
---|
55 | However, most RTEMS development has taken place using gcc, therefore |
---|
56 | getting it working may not be easy. |
---|
57 | |
---|
58 | @subsection Do I need gcc-2.9x for cross compilation? |
---|
59 | |
---|
60 | [FIXME: Partially obsolete] |
---|
61 | |
---|
62 | Not necessarily, but gcc-2.9x is highly recommended, because most development |
---|
63 | has taken place using gcc-2.9x and previous versions of gcc are not actively |
---|
64 | supported in RTEMS anymore (@ref{Can I use a non-gcc cross-toolchain?}). |
---|
65 | |
---|
66 | @subsection Where to get autoconf automake ld gcc etc.? |
---|
67 | |
---|
68 | The sources of all gnutools are available at any |
---|
69 | @uref{ftp://ftp.gnu.org,GNU} mirror. |
---|
70 | Native Linux binaries should come with any Linux distribution. |
---|
71 | Native Cygwin binaries should be available at Cygnus. |
---|
72 | |
---|
73 | GNU-Toolchain binaries (gcc, binutils etc.) for Linux and patches required |
---|
74 | to build them from source are available from |
---|
75 | @uref{ftp://ftp.oarcorp.com,OAR Corporation}. |
---|
76 | |
---|
77 | |
---|
78 | @section Issues when building RTEMS |
---|
79 | |
---|
80 | @subsection When running ./configure weird thing start to happen |
---|
81 | |
---|
82 | You are probably trying to build within the source-tree. |
---|
83 | RTEMS requires a separate build directory. I.e. if the |
---|
84 | sources are located at @code{/usr/local/src/rtems-@value{VERSION}}, |
---|
85 | use something similar to this to configure RTEMS: |
---|
86 | |
---|
87 | @example |
---|
88 | cd somewhere |
---|
89 | mkdir build |
---|
90 | cd build |
---|
91 | /usr/local/src/rtems-@value{VERSION}/configure [options] |
---|
92 | @end example |
---|
93 | |
---|
94 | @subsection When running bootstrap weird thing start to happen |
---|
95 | |
---|
96 | Many possibile causes: Most likely one of these: |
---|
97 | @itemize @bullet |
---|
98 | @item You are trying to build RTEMS with insufficient or incompatible |
---|
99 | versions of autoconf and automake. |
---|
100 | @item The autotools can't be found because your $PATH might not be set up |
---|
101 | correctly (Cf. @ref{How to set up $PATH?}) |
---|
102 | @item You have used configure-script options which interfer with RTEMS |
---|
103 | configuration (Cf. @ref{configure --program-[prefix|suffix|transform-name]}) |
---|
104 | @item You have tripped over a bug in RTEMS ;) |
---|
105 | @end itemize |
---|
106 | |
---|
107 | @subsection configure xxx cannot create executables |
---|
108 | |
---|
109 | While running a configure script, you see a message like this: |
---|
110 | @example |
---|
111 | checking for m68k-rtems-gcc... (cached) m68k-rtems-gcc |
---|
112 | checking for C compiler default output... configure: error: C compiler cannot create executables |
---|
113 | configure: error: /bin/sh '../../../../rtems-ss-@value{VERSION}/c/make/configure' |
---|
114 | failed for c/make |
---|
115 | @end example |
---|
116 | This kind of error message typically indicates a broken toolchain, broken |
---|
117 | toolchain installation or broken user environment. |
---|
118 | |
---|
119 | Examinating the @code{config.long} corresponding to the the failing |
---|
120 | configure script should provide further information of what |
---|
121 | actually goes wrong (In the example above: @code{<target>/c/<BSP>/make/config.log}) |
---|
122 | |
---|
123 | @subsection Why can I not build RTEMS inside of the source tree? |
---|
124 | |
---|
125 | The build-directory hierarchy is setup dynamically at configuration time. |
---|
126 | |
---|
127 | Configuring inside of the source tree would prevent being able to configure |
---|
128 | for multiple targets simultaneously. |
---|
129 | |
---|
130 | Using a separate build-tree simplifies Makefiles and configure scripts |
---|
131 | significantly. |
---|
132 | |
---|
133 | Adaptation to GNU/Cygnus conventions. |
---|
134 | |
---|
135 | @subsection Which environment variables to set? |
---|
136 | |
---|
137 | None. Unlike for previous releases, it is not recommended anymore to set any |
---|
138 | RTEMS related environment variable (Exception: $PATH, cf. |
---|
139 | @ref{How to set up $PATH?}). |
---|
140 | |
---|
141 | |
---|
142 | @subsection Compiler /Assembler /Linker report errors |
---|
143 | |
---|
144 | If you see a bunch of the error messages related to invalid instructions |
---|
145 | or similar, then probably your @code{$PATH} environment variable is not |
---|
146 | set up correctly (cf. @ref{How to set up $PATH?}). Otherwise you might |
---|
147 | have found a bug either in RTEMS or parts of the toolchain. |
---|
148 | |
---|
149 | @subsection How to set up $PATH? |
---|
150 | |
---|
151 | All target tools are supposed to be prefixed with a target-canonicalization |
---|
152 | prefix, eg. i386-rtems-gcc, m68k-rtems-ld are target tools. |
---|
153 | |
---|
154 | Host tools are supposed not to be prefixed. |
---|
155 | e.g.: cc, ld, gcc, autoconf, automake, aclocal etc. |
---|
156 | |
---|
157 | If using OAR Corporation's rpms for the toolchain, simply prepend |
---|
158 | @code{/opt/rtems/bin} to @code{$PATH}. |
---|
159 | |
---|
160 | @subsection Can I build RTEMS Canadian Cross? |
---|
161 | |
---|
162 | RTEMS >= 4.6.0 configuration is prepared for building RTEMS Canadian Cross, |
---|
163 | however building RTEMS Canadian Cross is known to be in its infancy, so |
---|
164 | your mileage may vary (See @code{README.cdn-X} in the toplevel directory of |
---|
165 | RTEMS's source tree for details.) |
---|
166 | |
---|
167 | @subsection Building RTEMS is slow |
---|
168 | |
---|
169 | RTEMS has become fairly large :). |
---|
170 | |
---|
171 | In comparison to building previous versions, building RTEMS is slow, |
---|
172 | but that's the tradeoff to pay for simplier and safer configuration. |
---|
173 | |
---|
174 | If using Cygwin, remember that Cygwin is emulating one OS ontop of another |
---|
175 | -- this necessarily must be significantly slower than using U*nix on the |
---|
176 | same hardware. |
---|
177 | |
---|
178 | @subsection Building my pre-4.5.x BSPs does not work anymore |
---|
179 | |
---|
180 | See @ref{How to merge pre-RTEMS-4.5.0 BSPs into RTEMS-4.5.0?}. |
---|
181 | |
---|
182 | @subsection make debug_install / make profile_install |
---|
183 | |
---|
184 | [FIXME:Partially obsolete] |
---|
185 | |
---|
186 | These make targets are not supported anymore. Instead, use: |
---|
187 | |
---|
188 | @example |
---|
189 | make VARIANT=DEBUG install |
---|
190 | make VARIANT=PROFILE install |
---|
191 | @end example |
---|
192 | |
---|
193 | @subsection make debug / make profile |
---|
194 | |
---|
195 | [FIXME:Partially obsolete] |
---|
196 | |
---|
197 | These make targets are not supported anymore. |
---|
198 | Instead, use: |
---|
199 | |
---|
200 | @example |
---|
201 | make VARIANT=DEBUG all |
---|
202 | make VARIANT=PROFILE all |
---|
203 | @end example |
---|
204 | |
---|
205 | |
---|
206 | @subsection Building RTEMS does not honor XXX_FOR_TARGET |
---|
207 | |
---|
208 | RTEMS < 4.6.0 did not support passing flags from the environment. |
---|
209 | If using RTEMS < 4.6.0, editing your BSP's @code{make/custom/mybsp.cfg} and |
---|
210 | setting appropriate flags there is required. |
---|
211 | |
---|
212 | RTEMS >= 4.6.0 honors several XXX_FOR_TARGET environment variables. |
---|
213 | Run @code{<path-to-rtems>/configure --help} for a full list of supported variables. |
---|
214 | |
---|
215 | @subsection Editing Makefile.in Makefile configure |
---|
216 | |
---|
217 | These files are generated by auto* tools, cf. |
---|
218 | @ref{Editing auto* generated files}). |
---|
219 | |
---|
220 | @subsection Editing auto* generated files |
---|
221 | |
---|
222 | RTEMS uses automake, therefore @b{never}, @b{ever}, @b{ever} |
---|
223 | edit Makefile.ins, Makefiles, configure or other auto* generated files. |
---|
224 | Changes to them will be swapped away soon and will get lost. |
---|
225 | |
---|
226 | Instead edit the sources (eg.: Makefile.ams, configure.acs) auto* generated |
---|
227 | files are generated from directly. |
---|
228 | |
---|
229 | If sending patches always send Makefile.ams and configure.acs. |
---|
230 | Sending Makefile.ins, Makefiles and configure scripts is pretty much useless. |
---|
231 | If sending larger patches, consider removing all auto* generated files |
---|
232 | by running @code{bootstrap -c} (cf. See @ref{./bootstrap}) |
---|
233 | before running diff to cut a patch. |
---|
234 | |
---|
235 | If you don't understand what this is all about, try start getting familiar |
---|
236 | with auto* tools by reading autoconf.info and automake.info, or feel free |
---|
237 | to ask for assistance on the RTEMS Mailing List |
---|
238 | (See @ref{Are there any mailing lists?}. |
---|
239 | |
---|
240 | @section Host Operating Systems and RTEMS |
---|
241 | |
---|
242 | @subsection Can I use Windows or DOS? |
---|
243 | |
---|
244 | |
---|
245 | No, plain DOS and plain Win will not work, but Cygwin should. |
---|
246 | Other U*nix emulations, such as Mingw and DJGPP are not supported and very |
---|
247 | likely will not work. |
---|
248 | Cywin / WinNT is known to work, but at the time of writing this, there |
---|
249 | seem to persist non-RTEMS related issues with Cygwin under Win9x which |
---|
250 | seem to prevent success on those systems. |
---|
251 | |
---|
252 | @subsection Do I need Linux? |
---|
253 | |
---|
254 | |
---|
255 | No, you should be able to build RTEMS on any U*ix OS and under Cygwin/NT |
---|
256 | (cf. @ref{Can I use Windows or DOS?}). |
---|
257 | |
---|
258 | @subsection Which Linux distribution is recommended? |
---|
259 | |
---|
260 | None, any recent U*nix should work, i.e. |
---|
261 | any recent Linux distribution should work, too. |
---|
262 | |
---|
263 | @section Development related questions |
---|
264 | |
---|
265 | @subsection How to merge pre-RTEMS-4.5.0 BSPs into RTEMS-4.5.0? |
---|
266 | |
---|
267 | [FIXME:Partially obsolete] |
---|
268 | |
---|
269 | The simple answer is that between 4.0 and 4.5.0, RTEMS has moved to automake |
---|
270 | and greater compliance with GNU conventions. |
---|
271 | In 4.0, there was a single configure script at the top of the tree. |
---|
272 | Now RTEMS is configured more like other GNU tools -- as a collection of |
---|
273 | configurable entities. |
---|
274 | |
---|
275 | Each BSP now has its own configure script. |
---|
276 | I highly recommend you look at the Makefile.am's, configure.ac, of a similar |
---|
277 | BSP. You might even want to consider running "bootstrap -c" from the top of |
---|
278 | the tree and looking at what is left. bootstrap (cf. @ref{./bootstrap}) |
---|
279 | generates/removes all automatically generated files. |
---|
280 | |
---|
281 | @subsection What is no_bsp / no_cpu? |
---|
282 | |
---|
283 | @code{no_bsp} is a fictional BSP for a fictional CPU of type |
---|
284 | @code{no_cpu}. @code{no_cpu/no_bsp} support files in RTEMS can be used as |
---|
285 | templates when implementing BSPs or porting RTEMS to new CPUs. |
---|
286 | |
---|
287 | @subsection What is the bare-BSP? |
---|
288 | |
---|
289 | At the time being RTEMS is build per BSP, with all support files being build |
---|
290 | separately for each BSP. This can become unhandy when using several similar |
---|
291 | but not identical boards (e.g. a PC with different peripherial cards plugged |
---|
292 | in), because this in general requires to implement a BSP for each setup. |
---|
293 | The bare BSP is a general, setup independent BSP which can be used when |
---|
294 | keeping all BSP specific parts external from RTEMS. |
---|
295 | |
---|
296 | At present time the bare BSP is in its infancy. |
---|
297 | It is known that it can be build for most CPUs RTEMS supports. |
---|
298 | It is also known to work in individual cases, but your mileage may vary. |
---|
299 | |
---|
300 | @subsection What is the cpukit? |
---|
301 | |
---|
302 | [FIXME:To be extended] |
---|
303 | |
---|
304 | One major change having been introduced to RTEMS-4.6.0 is the cpukit, |
---|
305 | located below the directory @code{cpukit/} in RTEMS's toplevel directory. |
---|
306 | |
---|
307 | @subsection Multilib vs. RTEMS CPU-variants |
---|
308 | |
---|
309 | The GNU toolchain applies a specific classification of similar CPUs into |
---|
310 | CPU variants (eg. SH1, SH2 etc.) to provide better support for each CPU variant. |
---|
311 | |
---|
312 | RTEMS uses a different classification because it internally requires more |
---|
313 | details about a specific CPU than the GNU toolchain's multilib classification |
---|
314 | provides. |
---|
315 | |
---|
316 | @subsection Keeping auto* generated files in CVS |
---|
317 | |
---|
318 | When using CVS to archive source code, problems arise from keeping generated |
---|
319 | files in CVS. In general, two possible solutions exist: |
---|
320 | |
---|
321 | @itemize @bullet |
---|
322 | |
---|
323 | @item Find a way to get correct timestamps after checking out the sources |
---|
324 | from CVS. Some people try to achieve this by |
---|
325 | |
---|
326 | @itemize @bullet |
---|
327 | @item carefully checking in files into CVS in appropriate order |
---|
328 | @item applying scripts to fix timestamps accordingling (eg. by applying |
---|
329 | @code{touch} and @code{find}). |
---|
330 | @end itemize |
---|
331 | |
---|
332 | @item Not keeping generated files in CVS, but regenerate them after |
---|
333 | having checked them out from CVS. |
---|
334 | |
---|
335 | @end itemize |
---|
336 | |
---|
337 | RTEMS favors the the latter variant, because it appears to be less error-prone |
---|
338 | and easier to handle (cf. @ref{./bootstrap} for details). |
---|
339 | |
---|
340 | @subsection Importing RTEMS into CVS/RCS |
---|
341 | |
---|
342 | When importing RTEMS into CVS/RCS or similar, we recommend not to import |
---|
343 | auto* generated files (cf. @ref{Keeping auto* generated files in CVS}). |
---|
344 | |
---|
345 | To remove them before importing, run |
---|
346 | |
---|
347 | @example |
---|
348 | ./bootstrap -c |
---|
349 | @end example |
---|
350 | |
---|
351 | from the toplevel directory of the source tree (cf. @ref{./bootstrap}). |
---|
352 | |
---|
353 | @subsection ./bootstrap |
---|
354 | |
---|
355 | |
---|
356 | @code{bootstrap} is a simple shell script which automatically generates all |
---|
357 | auto* generated files within RTEMS's source tree (Other packages use the name |
---|
358 | @code{autogen.sh} for similar scripts). You will need to have autoconf, |
---|
359 | automake and further underlying packages installed to apply it. |
---|
360 | |
---|
361 | It typically should be applied when having: |
---|
362 | |
---|
363 | @itemize @bullet |
---|
364 | |
---|
365 | @item checked out RTEMS sources from a CVS repository which does |
---|
366 | not contain generated files. |
---|
367 | |
---|
368 | @item added new automake / autoconf files to the source tree (eg. |
---|
369 | having added a new BSP), and when not being sure about what needs to be |
---|
370 | updated. |
---|
371 | |
---|
372 | @end itemize |
---|
373 | |
---|
374 | Once all autoconf/automake generated files are present, you will rarely |
---|
375 | need to run @code{bootstrap}, because automake automatically updates |
---|
376 | generated files when it detects some files need to be updated (Cf. |
---|
377 | @ref{configure --enable-maintainer-mode}). |
---|
378 | |
---|
379 | @subsection configure --enable-maintainer-mode |
---|
380 | |
---|
381 | When working within the source-tree, consider to append |
---|
382 | @code{--enable-maintainer-mode} to the options passed to configure RTEMS. |
---|
383 | |
---|
384 | @example |
---|
385 | <path>/rtems-@value{VERSION}/configure <options> --enable-maintainer-mode |
---|
386 | @end example |
---|
387 | |
---|
388 | This will enable the maintainer-mode in automake generated Makefiles, which |
---|
389 | will let automake take care about dependencies between auto* generated |
---|
390 | files. I.e. auto* generated files will get automatically updated. |
---|
391 | |
---|
392 | Configuring RTEMS in maintainer-mode will require to have autoconf, automake |
---|
393 | and underlying tools installed (Cf. @ref{Required Tools}). |
---|
394 | |
---|
395 | @subsection configure --program-[prefix|suffix|transform-name] |
---|
396 | |
---|
397 | These are generic configure script options automatically added by autoconf. |
---|
398 | RTEMS configuration does not support these, worse, they interfer with |
---|
399 | RTEMS's configuration -- i.e. @b{do not use them}. |
---|
400 | |
---|
401 | @subsection configure.ac vs. configure.in |
---|
402 | |
---|
403 | autoconf < 2.50 used the name @code{configure.in} for it's input files. |
---|
404 | autoconf >= 2.50 recommends using the name @code{configure.ac}, instead. |
---|
405 | |
---|
406 | RTEMS > 4.5.0 applies autoconf >= 2.50, therefore all former RTEMS's |
---|
407 | @code{configure.in}'s have been renamed into @code{configure.ac} and |
---|
408 | have been adapted to autoconf >= 2.50 demands. |
---|
409 | |
---|
410 | @subsection Reporting bugs |
---|
411 | |
---|
412 | Several possibilities (In decreasing preference): |
---|
413 | @itemize @bullet |
---|
414 | @item File a bug report at @uref{http://www.oarcorp.com/cgi-bin/gnatsweb.pl,OAR's GNAT} |
---|
415 | @item Send an email to @uref{mailto:rtems-bugs@@OARcorp.com,rtems-bugs@@OARcorp.com} |
---|
416 | @item Report your problem to one of the RTEMS mailing lists |
---|
417 | (Cf. @ref{Are there any mailing lists?}). |
---|
418 | @end itemize |
---|