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

4.104.114.84.95
Last change on this file since 6449498 was 6449498, checked in by Joel Sherrill <joel.sherrill@…>, on Jan 17, 2002 at 9:47:47 PM

2001-01-17 Joel Sherrill <joel@…>

  • SUPPORT, LICENSE: New files.
  • Numerous files touched as part of merging the 4.5 branch onto the mainline development trunk and ensuring that the script that cuts snapshots and releases works on the documentation.
  • 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 OAR Corporation'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
199(See @ref{Are there any mailing lists?}.
200
201@section Host Operating Systems and RTEMS
202
203@subsection Can I use Windows or DOS?
204
205
206No, plain DOS and plain Win will not work, but Cygwin should.
207Other U*nix emulations, such as Mingw and DJGPP are not supported and very
208likely will not work.
209Cywin / WinNT is known to work, but at the time of writing this, there
210seem to persist non-RTEMS related issues with Cygwin under Win9x which
211seem to prevent success on those systems.
212
213@subsection Do I need Linux?
214
215
216No, you should be able to build RTEMS on any U*ix OS and under Cygwin/NT
217(cf. @ref{Can I use Windows or DOS?}).
218 
219@subsection Which Linux distribution is recommended?
220
221None, any recent U*nix should work, i.e.
222any recent Linux distribution should work, too.
223
224@section Development related questions
225
226@subsection How to merge pre-RTEMS-4.5.0 BSPs into RTEMS-4.5.0?
227
228The simple answer is that between 4.0 and now, RTEMS has moved to automake
229and greater compliance with GNU conventions.
230In 4.0, there was a single configure script at the top of the tree.
231Now RTEMS is configured more like other GNU tools -- as a collection of
232configurable entities.
233 
234
235Each BSP now has its own configure script.
236I highly recommend you look at the Makefile.am's, configure.in, of a similar
237BSP.  You might even want to consider running "bootstrap -c" from the top of
238the tree and looking at what is left.  bootstrap (cf. @ref{./bootstrap})
239generates/removes all automatically generated files.
240
241@subsection What is no_bsp / no_cpu?
242
243@code{no_bsp} is a fictional BSP for a fictional CPU of type
244@code{no_cpu}.  @code{no_cpu/no_bsp} support files in RTEMS can be used as
245templates when implementing BSPs or porting RTEMS to new CPUs.
246
247@subsection What is the bare-BSP?
248
249At the time being RTEMS is build per BSP, with all support files being build
250separately for each BSP.  This can become unhandy when using several similar
251but not identical boards (e.g.  a PC with different peripherial cards plugged
252in), because this in general requires to implement a BSP for each setup.
253The bare BSP is a general, setup independent BSP which can be used when
254keeping all BSP specific parts external from RTEMS.
255
256At present time the bare BSP is in its infancy.
257It is known that it can be build for most CPUs RTEMS supports.
258It is also known to work in individual cases, but your mileage may vary.
259
260@subsection Multilib vs.  RTEMS CPU-variants
261
262The GNU toolchain applies a specific classification of similar CPUs into
263CPU variants (eg.  SH1, SH2 etc.) to provide better support for each CPU variant.
264
265RTEMS uses a different classification because it internally requires more
266details about a specific CPU than the GNU toolchain's multilib classification
267provides.
268
269@subsection Keeping auto* generated files in CVS
270
271When using CVS to archive source code, problems arise from keeping generated
272files in CVS.  In general, two possible solutions exist:
273
274@itemize @bullet
275
276@item Find a way to get correct timestamps after checking out the sources
277from CVS.  Some people try to achieve this by
278
279@itemize @bullet
280@item carefully checking in files into CVS in appropriate order
281@item applying scripts to fix timestamps accordingling (eg.  by applying
282@code{touch} and @code{find}).
283@end itemize
284
285@item Not keeping generated files in CVS, but regenerate them after
286having checked them out from CVS.
287
288@end itemize
289
290RTEMS favors the the latter variant, because it appears to be less error-prone
291and easier to handle (cf. @ref{./bootstrap} for details).
292
293@subsection Importing RTEMS into CVS/RCS
294
295When importing RTEMS into CVS/RCS or similar, we recommend not to import
296auto* generated files (cf. @ref{Keeping auto* generated files in CVS}).
297
298To remove them before importing, run
299
300@example
301./bootstrap -c
302@end example
303
304from the toplevel directory of the source tree (cf. @ref{./bootstrap}).
305 
306@subsection ./bootstrap
307
308
309@code{bootstrap} is a simple shell script which automatically generates all
310auto* generated files within RTEMS's source tree (Other packages use the name
311@code{autogen.sh} for similar scripts).  You will need to have autoconf,
312automake and further underlying packages installed to apply it.
313
314It typically should be applied when having:
315
316@itemize @bullet
317
318@item checked out RTEMS sources from a CVS repository which does
319not contain generated files.
320
321@item added new automake / autoconf files to the source tree (eg.
322having added a new BSP), and when not being sure about what needs to be
323updated.
324
325@end itemize
326
327Once all autoconf/automake generated files are present, you will rarely
328need to run @code{bootstrap}, because automake automatically updates
329generated files when it detects some files need to be updated (Cf.
330@ref{--enable-maintainer-mode}).
331
332@subsection --enable-maintainer-mode
333
334When working within the source-tree, consider to append
335@code{--enable-maintainer-mode} to the options passed to configure RTEMS.
336
337@example
338<path>/rtems-4.5.0/configure <options> --enable-maintainer-mode
339@end example
340
341This will enable the maintainer-mode in automake generated Makefiles, which
342will let automake take care about dependencies between auto* generated
343files.  I.e.  auto* generated files will get automatically updated.
344
345Configuring RTEMS in maintainer-mode will require to have autoconf, automake
346and underlying tools installed (Cf. @ref{Required Tools}).
Note: See TracBrowser for help on using the repository browser.