source: rtems/doc/FAQ/build45.t @ 537449c

4.104.114.84.95
Last change on this file since 537449c was 537449c, checked in by Ralf Corsepius <ralf.corsepius@…>, on Jan 22, 2003 at 1:47:32 PM

2003-01-22 Ralf Corsepius <corsepiu@…>

  • build45.t: Several fixes and additions.
  • Property mode set to 100644
File size: 14.6 KB
Line 
1@c
2@c  $Id$
3@c
4
5@chapter Building RTEMS
6
7Building any package in a cross-compilation fashion can be difficult,
8but configuring and building a real-time operating system that
9supports many CPU families and target boards can be confusing.  The
10RTEMS development team has made every effort to make this process as
11straight forward as possible but there are going to be questions.
12
13Moreover, between RTEMS 4.0 and 4.5, the configure and Makefile system in RTEMS
14was changed to be more compatible with GNU standards.  This transition
15has lead to a number of subtle differences. 
16
17This section of the FAQ tries to address the more frequently asked
18questions about building RTEMS.  Thanks to Ralf Corsepius for
19compiling this section from excerpts from various postings to the
20rtems-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
40No, you don't.  Or to be more accurate, you won't need them until you
41modify something in RTEMS's Makefile.ams/configure.acs or start to develop
42with RTEMS.
43 
44I.e.  you won't need them to get started, but you will need them when getting
45serious.
46
47@subsection Do I need a native gcc on my host?
48
49No, you should be able to use any native, ansi-compliant C-compiler, but
50using a native gcc is highly recommended.
51
52@subsection Can I use a non-gcc cross-toolchain?
53
54Generally speaking, it should be possible.
55However, most RTEMS development has taken place using gcc, therefore
56getting it working may not be easy.
57
58@subsection Do I need gcc-2.9x for cross compilation?
59
60[FIXME: Partially obsolete]
61
62Not necessarily, but gcc-2.9x is highly recommended, because most development
63has taken place using gcc-2.9x and previous versions of gcc are not actively
64supported in RTEMS anymore (@ref{Can I use a non-gcc cross-toolchain?}).
65
66@subsection Where to get autoconf automake ld gcc etc.?
67
68The sources of all gnutools are available at any
69@uref{ftp://ftp.gnu.org,GNU} mirror.
70Native Linux binaries should come with any Linux distribution.
71Native Cygwin binaries should be available at Cygnus.
72
73GNU-Toolchain binaries (gcc, binutils etc.) for Linux and patches required
74to 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
82You are probably trying to build within the source-tree.
83RTEMS requires a separate build directory.  I.e.  if the
84sources are located at @code{/usr/local/src/rtems-@value{VERSION}},
85use something similar to this to configure RTEMS:
86
87@example
88cd somewhere
89mkdir build
90cd 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
96Many possibile causes: Most likely one of these:
97@itemize @bullet
98@item You are trying to build RTEMS with insufficient or incompatible
99versions of autoconf and automake.
100@item The autotools can't be found because your $PATH might not be set up
101correctly (Cf. @ref{How to set up $PATH?})
102@item You have used configure-script options which interfer with RTEMS
103configuration (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
109While running a configure script, you see a message like this:
110@example
111checking for m68k-rtems-gcc... (cached) m68k-rtems-gcc
112checking for C compiler default output... configure: error: C compiler cannot create executables
113configure: error: /bin/sh '../../../../rtems-ss-@value{VERSION}/c/make/configure'
114failed for c/make
115@end example
116This kind of error message typically indicates a broken toolchain, broken
117toolchain installation or broken user environment.
118
119Examinating the @code{config.long} corresponding to the the failing
120configure script should provide further information of what
121actually 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
125The build-directory hierarchy is setup dynamically at configuration time.
126
127Configuring inside of the source tree would prevent being able to configure
128for multiple targets simultaneously.
129
130Using a separate build-tree simplifies Makefiles and configure scripts
131significantly.
132
133Adaptation to GNU/Cygnus conventions.
134
135@subsection Which environment variables to set?
136
137None.  Unlike for previous releases, it is not recommended anymore to set any
138RTEMS related environment variable (Exception: $PATH, cf.
139@ref{How to set up $PATH?}).
140
141
142@subsection Compiler /Assembler /Linker report errors
143
144If you see a bunch of the error messages related to invalid instructions
145or similar, then probably your @code{$PATH} environment variable is not
146set up correctly (cf.  @ref{How to set up $PATH?}).  Otherwise you might
147have found a bug either in RTEMS or parts of the toolchain.
148
149@subsection How to set up $PATH?
150
151All target tools are supposed to be prefixed with a target-canonicalization
152prefix, eg.  i386-rtems-gcc, m68k-rtems-ld are target tools.
153
154Host tools are supposed not to be prefixed.
155e.g.: cc, ld, gcc, autoconf, automake, aclocal etc.
156
157If 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
162RTEMS >= 4.6.0 configuration is prepared for building RTEMS Canadian Cross,
163however building RTEMS Canadian Cross is known to be in its infancy, so
164your mileage may vary (See @code{README.cdn-X} in the toplevel directory of
165RTEMS's source tree for details.)
166
167@subsection Building RTEMS is slow
168
169RTEMS has become fairly large :).
170
171In comparison to building previous versions, building RTEMS is slow,
172 but that's the tradeoff to pay for simplier and safer configuration.
173
174If 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
180See @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
186These make targets are not supported anymore.  Instead, use:
187
188@example
189make VARIANT=DEBUG install
190make VARIANT=PROFILE install
191@end example
192
193@subsection make debug / make profile
194
195[FIXME:Partially obsolete]
196
197These make targets are not supported anymore.
198Instead, use:
199
200@example
201make VARIANT=DEBUG all
202make VARIANT=PROFILE all
203@end example
204
205
206@subsection Building RTEMS does not honor XXX_FOR_TARGET
207
208RTEMS < 4.6.0 did not support passing flags from the environment.
209If using RTEMS < 4.6.0, editing your BSP's @code{make/custom/mybsp.cfg} and
210setting appropriate flags there is required.
211
212RTEMS >= 4.6.0 honors several XXX_FOR_TARGET environment variables.
213Run @code{<path-to-rtems>/configure --help} for a full list of supported variables.
214
215@subsection Editing Makefile.in Makefile configure
216
217These files are generated by auto* tools, cf.
218@ref{Editing auto* generated files}).
219
220@subsection Editing auto* generated files
221
222RTEMS uses automake, therefore @b{never}, @b{ever}, @b{ever}
223edit Makefile.ins, Makefiles, configure or other auto* generated files.
224Changes to them will be swapped away soon and will get lost.
225
226Instead edit the sources (eg.: Makefile.ams, configure.acs) auto* generated
227files are generated from directly.
228
229If sending patches always send Makefile.ams and configure.acs.
230Sending Makefile.ins, Makefiles and configure scripts is pretty much useless.
231If sending larger patches, consider removing all auto* generated files
232by running @code{bootstrap -c} (cf. See @ref{./bootstrap})
233before running diff to cut a patch.
234
235If you don't understand what this is all about, try start getting familiar
236with auto* tools by reading autoconf.info and automake.info, or feel free
237to 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
245No, plain DOS and plain Win will not work, but Cygwin should.
246Other U*nix emulations, such as Mingw and DJGPP are not supported and very
247likely will not work.
248Cywin / WinNT is known to work, but at the time of writing this, there
249seem to persist non-RTEMS related issues with Cygwin under Win9x which
250seem to prevent success on those systems.
251
252@subsection Do I need Linux?
253
254
255No, 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
260None, any recent U*nix should work, i.e.
261any 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
269The simple answer is that between 4.0 and 4.5.0, RTEMS has moved to automake
270and greater compliance with GNU conventions.
271In 4.0, there was a single configure script at the top of the tree.
272Now RTEMS is configured more like other GNU tools -- as a collection of
273configurable entities.
274
275Each BSP now has its own configure script.
276I highly recommend you look at the Makefile.am's, configure.ac, of a similar
277BSP.  You might even want to consider running "bootstrap -c" from the top of
278the tree and looking at what is left.  bootstrap (cf. @ref{./bootstrap})
279generates/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
285templates when implementing BSPs or porting RTEMS to new CPUs.
286
287@subsection What is the bare-BSP?
288
289At the time being RTEMS is build per BSP, with all support files being build
290separately for each BSP.  This can become unhandy when using several similar
291but not identical boards (e.g.  a PC with different peripherial cards plugged
292in), because this in general requires to implement a BSP for each setup.
293The bare BSP is a general, setup independent BSP which can be used when
294keeping all BSP specific parts external from RTEMS.
295
296At present time the bare BSP is in its infancy.
297It is known that it can be build for most CPUs RTEMS supports.
298It 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
304One major change having been introduced to RTEMS-4.6.0 is the cpukit,
305located below the directory @code{cpukit/} in RTEMS's toplevel directory.
306
307@subsection Multilib vs.  RTEMS CPU-variants
308
309The GNU toolchain applies a specific classification of similar CPUs into
310CPU variants (eg.  SH1, SH2 etc.) to provide better support for each CPU variant.
311
312RTEMS uses a different classification because it internally requires more
313details about a specific CPU than the GNU toolchain's multilib classification
314provides.
315
316@subsection Keeping auto* generated files in CVS
317
318When using CVS to archive source code, problems arise from keeping generated
319files 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
324from 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
333having checked them out from CVS.
334
335@end itemize
336
337RTEMS favors the the latter variant, because it appears to be less error-prone
338and easier to handle (cf. @ref{./bootstrap} for details).
339
340@subsection Importing RTEMS into CVS/RCS
341
342When importing RTEMS into CVS/RCS or similar, we recommend not to import
343auto* generated files (cf. @ref{Keeping auto* generated files in CVS}).
344
345To remove them before importing, run
346
347@example
348./bootstrap -c
349@end example
350
351from 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
357auto* 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,
359automake and further underlying packages installed to apply it.
360
361It typically should be applied when having:
362
363@itemize @bullet
364
365@item checked out RTEMS sources from a CVS repository which does
366not contain generated files.
367
368@item added new automake / autoconf files to the source tree (eg.
369having added a new BSP), and when not being sure about what needs to be
370updated.
371
372@end itemize
373
374Once all autoconf/automake generated files are present, you will rarely
375need to run @code{bootstrap}, because automake automatically updates
376generated 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
381When 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
388This will enable the maintainer-mode in automake generated Makefiles, which
389will let automake take care about dependencies between auto* generated
390files.  I.e.  auto* generated files will get automatically updated.
391
392Configuring RTEMS in maintainer-mode will require to have autoconf, automake
393and underlying tools installed (Cf. @ref{Required Tools}).
394
395@subsection configure --program-[prefix|suffix|transform-name]
396
397These are generic configure script options automatically added by autoconf.
398RTEMS configuration does not support these, worse, they interfer with
399RTEMS's configuration -- i.e. @b{do not use them}.
400
401@subsection configure.ac vs. configure.in
402
403autoconf < 2.50 used the name @code{configure.in} for it's input files.
404autoconf >= 2.50 recommends using the name @code{configure.ac}, instead.
405
406RTEMS > 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
408have been adapted to autoconf >= 2.50 demands.
409
410@subsection Reporting bugs
411
412Several possibilities (In decreasing preference):
413@itemize @bullet
414@item File a bug report at @uref{http://www.oarcorp.com/cgi-bin/gnatweb.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
Note: See TracBrowser for help on using the repository browser.