source: rtems/doc/FAQ/build45.t @ 2f957f19

4.104.114.84.95
Last change on this file since 2f957f19 was 2f957f19, checked in by Joel Sherrill <joel.sherrill@…>, on 05/28/00 at 19:33:59

Merged Ralf Corsepius' 4.5 Build Issues FAQ into this.

  • Property mode set to 100644
File size: 11.6 KB
Line 
1@c
2@c  $Id$
3@c
4
5@chapter Building RTEMS 4.5
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 4.5.  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.ins 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
54
55Generally speaking, it should be possible.
56However, most RTEMS-4.5 development has taken place using gcc-2.9x, therefore
57getting it working may not be easy.
58
59@subsection Do I need gcc-2.9x for cross compilation?
60
61Not necessarily, but gcc-2.9x is highly recommended, because most development
62has taken place using gcc-2.9x and previous versions of gcc are not actively
63supported in RTEMS anymore (@ref{Can I use a non-gcc cross-toolchain?}).
64
65@subsection Where to get autoconf automake ld gcc etc.  ?
66
67The sources of all gnutools are available at any
68@uref{GNU,ftp://ftp.gnu.org} mirror.
69Native Linux binaries should come with any Linux distribution.
70Native Cygwin binaries should be available at Cygnus.
71
72GNU-Toolchain binaries (gcc, binutils etc.) for Linux and patches required
73to build them from source are available from
74@uref{OAR Corporation,ftp://ftp.oarcorp.com}.
75
76
77@section Issues when building RTEMS
78
79@subsection When running ./configure weird thing start to happen
80
81You are probably trying to build within the source-tree.
82RTEMS requires a separate build directory.  I.e.  if the
83sources are located at @code{/usr/local/src/rtems-4.5.0},
84use something similar to this to configure RTEMS:
85
86@example
87cd somewhere
88mkdir build
89cd build
90/usr/local/src/rtems-4.5.0/configure [options]
91@end example
92
93@subsection Why can I not build RTEMS inside of the source tree?
94
95
96The build-directory hierarchy is setup dynamically at configuration time.
97
98Configuring inside of the source tree would prevent being able to configure
99for multiple targets simultaneously.
100
101Using a separate build-tree simplifies Makefiles and configure scripts
102significantly.
103
104Adaptation to GNU/Cygnus conventions.
105
106@subsection Which environment variables to set?
107
108None.  Unlike for previous releases, it is not recommended anymore to set any
109RTEMS related environment variable (Exception: $PATH, cf.
110@ref{How to set up $PATH?}).
111
112
113@subsection Compiler /Assembler /Linker report errors
114
115If you see a bunch of the error messages related to invalid instructions
116or similar, then probably your @code{$PATH} environment variable is not
117set up correctly (cf.  @ref{How to set up $PATH?}).  Otherwise you might
118have found a bug either in RTEMS or parts of the toolchain.
119
120@subsection How to set up $PATH?
121
122All target tools are supposed to be prefixed with a target-canonicalization
123prefix, eg.  i386-rtems-gcc, m68k-rtems-ld are target tools.
124
125Host tools are supposed not to be prefixed.
126e.g.: cc, ld, gcc etc.
127
128If using OARCorp's rpms for the toolchain, simply prepend:
129@code{/opt/rtems/bin} to @code{$PATH}.
130
131@subsection Can I build RTEMS Canadian Cross?
132
133Unfortunately, not (yet).
134
135@subsection Building RTEMS is slow
136
137RTEMS has become fairly large :).
138
139In comparison to building previous versions, building RTEMS-4.5 is slow,
140 but that's the tradeoff to pay for simplier and safer configuration.
141
142If using Cygwin, remember that Cygwin is emulating one OS ontop of another
143 -- this necessarily must be significantly slower than using U*nix on the
144 same hardware.
145
146@subsection Building my pre-4.5.x BSPs does not work anymore
147
148See @ref{How to merge pre-RTEMS-4.5.0 BSPs into RTEMS-4.5.0?}.
149
150@subsection make debug_install / make profile_install
151
152These make targets are not supported anymore.  Instead, use:
153
154@example
155make VARIANT=DEBUG install
156make VARIANT=PROFILE install
157@end example
158
159@subsection make debug / make profile
160
161These make targets are not supported anymore.
162Instead, use:
163
164@example
165make VARIANT=DEBUG all
166make VARIANT=PROFILE all
167@end example
168
169@subsection Building RTEMS does not honor XXX_FOR_TARGET
170
171RTEMS currently does not support passing flags from the environment.
172Instead add a @code{make/custom/mybsp.cfg} for your bsp and set
173appropriate flags there.
174
175@subsection Editing Makefile.in Makefile configure
176
177These files are generated by auto* tools, cf.
178@ref{Editing auto* generated files}).
179
180@subsection Editing auto* generated files
181
182
183RTEMS uses automake, therefore @b{never}, @b{ever}, @b{ever}
184edit Makefile.ins, Makefiles, configure or other auto* generated files.
185Changes to them will be swapped away soon and will get lost.
186
187Instead edit the sources (eg.: Makefile.ams, configure.ins) auto* generated
188files are generated from directly.
189
190If sending patches always send Makefile.ams and configure.ins.
191Sending Makefile.ins, Makefiles and configure scripts is pretty much useless.
192If sending larger patches, consider removing all auto* generated files
193by running @code{bootstrap -c} (cf. See @ref{./bootstrap})
194before running diff to cut a patch.
195
196If you don't understand what this is all about, try start getting familiar
197with auto* tools by reading autoconf.info and automake.info, or feel free
198to ask for assistance on the RTEMS Mailing List (See @ref{RTEMS Mailing List}.
199
200@section Host Operating Systems and RTEMS
201
202@subsection Can I use Windows or DOS?
203
204
205No, plain DOS and plain Win will not work, but Cygwin should.
206Other U*nix emulations, such as Mingw and DJGPP are not supported and very
207likely will not work.
208Cywin / WinNT is known to work, but at the time of writing this, there
209seem to persist non-RTEMS related issues with Cygwin under Win9x which
210seem to prevent success on those systems.
211
212@subsection Do I need Linux?
213
214
215No, you should be able to build RTEMS on any U*ix OS and under Cygwin/NT
216(cf. @ref{Can I use Windows or DOS?}).
217 
218@subsection Which Linux distribution is recommended?
219
220None, any recent U*nix should work, i.e.
221any recent Linux distribution should work, too.
222
223@section Development related questions
224
225@subsection How to merge pre-RTEMS-4.5.0 BSPs into RTEMS-4.5.0?
226
227The simple answer is that between 4.0 and now, RTEMS has moved to automake
228and greater compliance with GNU conventions.
229In 4.0, there was a single configure script at the top of the tree.
230Now RTEMS is configured more like other GNU tools -- as a collection of
231configurable entities.
232 
233
234Each BSP now has its own configure script.
235I highly recommend you look at the Makefile.am's, configure.in, of a similar
236BSP.  You might even want to consider running "bootstrap -c" from the top of
237the tree and looking at what is left.  bootstrap (cf. @ref{./bootstrap})
238generates/removes all automatically generated files.
239
240@subsection What is no_bsp / no_cpu?
241
242@code{no_bsp} is a fictional BSP for a fictional CPU of type
243@code{no_cpu}.  @code{no_cpu/no_bsp} support files in RTEMS can be used as
244templates when implementing BSPs or porting RTEMS to new CPUs.
245
246@subsection What is the bare-BSP?
247
248At the time being RTEMS is build per BSP, with all support files being build
249separately for each BSP.  This can become unhandy when using several similiar
250but not identical boards (e.g.  a PC with different peripherial cards plugged
251in), because this in general requires to implement a BSP for each setup.
252The bare BSP is a general, setup independent BSP which can be used when
253keeping all BSP specific parts external from RTEMS.
254
255At present time the bare BSP is in its infancy.
256It is known that it can be build for most CPUs RTEMS supports.
257It is also known to work in individual cases, but your mileage may vary.
258
259@subsection Multilib vs.  RTEMS CPU-variants
260
261The GNU toolchain applies a specific classification of similar CPUs into
262CPU variants (eg.  SH1, SH2 etc.) to provide better support for each CPU variant.
263
264RTEMS uses a different classification because it internally requires more
265details about a specific CPU than the GNU toolchain's multilib classification
266provides.
267
268@subsection Keeping auto* generated files in CVS
269
270When using CVS to archive source code, problems arise from keeping generated
271files in CVS.  In general, two possible solutions exist:
272
273@itemize @bullet
274
275@item Find a way to get correct timestamps after checking out the sources
276from CVS.  Some people try to achieve this by
277
278@itemize @bullet
279@item carefully checking in files into CVS in appropriate order
280@item applying scripts to fix timestamps accordingling (eg.  by applying
281@code{touch} and @code{find}).
282@end itemize
283
284@item Not keeping generated files in CVS, but regenerate them after
285having checked them out from CVS.
286
287@end itemize
288
289RTEMS favors the the latter variant, because it appears to be less error-prone
290and easier to handle (cf. @ref{./bootstrap} for details).
291
292@subsection Importing RTEMS into CVS/RCS
293
294When importing RTEMS into CVS/RCS or similar, we recommend not to import
295auto* generated files (cf. @ref{Keeping auto* generated files in CVS}).
296
297To remove them before importing, run
298
299@example
300./bootstrap -c
301@end example
302
303from the toplevel directory of the source tree (XXX ref sec-bootstrap).
304 
305@subsection ./bootstrap
306
307
308@code{bootstrap} is a simple shell script which automatically generates all
309auto* generated files within RTEMS's source tree (Other packages use the name
310@code{autogen.sh} for similar scripts).  You will need to have autoconf,
311automake and further underlaying packages installed to apply it.
312
313It typically should be applied when having:
314
315@itemize @bullet
316
317@item checked out RTEMS sources from a CVS repository which does
318not contain generated files.
319
320@item added new automake / autoconf files to the source tree (eg.
321having added a new BSP), and when not being sure about what needs to be
322updated.
323
324@end itemize
325
326Once all autoconf/automake generated files are present, you will rarely
327need to run @code{bootstrap}, because automake automatically updates
328generated files when it detects some files need to be updated (Cf.
329@ref{--enable-maintainer-mode}).
330
331@subsection --enable-maintainer-mode
332
333When working within the source-tree, consider to append
334@code{--enable-maintainer-mode} to the options passed to configure RTEMS.
335
336@example
337<path>/rtems-4.5.0/configure <options> --enable-maintainer-mode
338@end example
339
340This will enable the maintainer-mode in automake generated Makefiles, which
341will let automake take care about dependencies between auto* generated
342files.  I.e.  auto* generated files will get automatically updated.
343
344Configuring RTEMS in maintainer-mode will require to have autoconf, automake
345and underlaying tools installed (Cf. @ref{Required Tools}).
Note: See TracBrowser for help on using the repository browser.