source: rtems/doc/FAQ/build45.t @ dc5623bb

4.104.114.84.95
Last change on this file since dc5623bb was dc5623bb, checked in by Ralf Corsepius <ralf.corsepius@…>, on 01/22/03 at 12:25:57

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

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