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 | Not necessarily, but gcc-2.9x is highly recommended, because most development |
---|
61 | has taken place using gcc-2.9x and previous versions of gcc are not actively |
---|
62 | supported in RTEMS anymore (@ref{Can I use a non-gcc cross-toolchain?}). |
---|
63 | |
---|
64 | @subsection Where to get autoconf automake ld gcc etc. ? |
---|
65 | |
---|
66 | The sources of all gnutools are available at any |
---|
67 | @uref{GNU,ftp://ftp.gnu.org} mirror. |
---|
68 | Native Linux binaries should come with any Linux distribution. |
---|
69 | Native Cygwin binaries should be available at Cygnus. |
---|
70 | |
---|
71 | GNU-Toolchain binaries (gcc, binutils etc.) for Linux and patches required |
---|
72 | to 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 | |
---|
80 | You are probably trying to build within the source-tree. |
---|
81 | RTEMS requires a separate build directory. I.e. if the |
---|
82 | sources are located at @code{/usr/local/src/rtems-@value{VERSION}}, |
---|
83 | use something similar to this to configure RTEMS: |
---|
84 | |
---|
85 | @example |
---|
86 | cd somewhere |
---|
87 | mkdir build |
---|
88 | cd 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 | |
---|
95 | The build-directory hierarchy is setup dynamically at configuration time. |
---|
96 | |
---|
97 | Configuring inside of the source tree would prevent being able to configure |
---|
98 | for multiple targets simultaneously. |
---|
99 | |
---|
100 | Using a separate build-tree simplifies Makefiles and configure scripts |
---|
101 | significantly. |
---|
102 | |
---|
103 | Adaptation to GNU/Cygnus conventions. |
---|
104 | |
---|
105 | @subsection Which environment variables to set? |
---|
106 | |
---|
107 | None. Unlike for previous releases, it is not recommended anymore to set any |
---|
108 | RTEMS related environment variable (Exception: $PATH, cf. |
---|
109 | @ref{How to set up $PATH?}). |
---|
110 | |
---|
111 | |
---|
112 | @subsection Compiler /Assembler /Linker report errors |
---|
113 | |
---|
114 | If you see a bunch of the error messages related to invalid instructions |
---|
115 | or similar, then probably your @code{$PATH} environment variable is not |
---|
116 | set up correctly (cf. @ref{How to set up $PATH?}). Otherwise you might |
---|
117 | have found a bug either in RTEMS or parts of the toolchain. |
---|
118 | |
---|
119 | @subsection How to set up $PATH? |
---|
120 | |
---|
121 | All target tools are supposed to be prefixed with a target-canonicalization |
---|
122 | prefix, eg. i386-rtems-gcc, m68k-rtems-ld are target tools. |
---|
123 | |
---|
124 | Host tools are supposed not to be prefixed. |
---|
125 | e.g.: cc, ld, gcc, autoconf, automake, aclocal etc. |
---|
126 | |
---|
127 | If 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 | |
---|
132 | RTEMS >= 4.6.0 configuration is prepared for building RTEMS Canadian Cross, |
---|
133 | however building RTEMS Canadian Cross is known to be in it's infancy, so |
---|
134 | your mileage may vary (See @code{README.cdn-X} in the toplevel directory of |
---|
135 | RTEMS's source tree for details.) |
---|
136 | |
---|
137 | @subsection Building RTEMS is slow |
---|
138 | |
---|
139 | RTEMS has become fairly large :). |
---|
140 | |
---|
141 | In comparison to building previous versions, building RTEMS is slow, |
---|
142 | but that's the tradeoff to pay for simplier and safer configuration. |
---|
143 | |
---|
144 | If 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 | |
---|
150 | See @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 | |
---|
154 | These make targets are not supported anymore. Instead, use: |
---|
155 | |
---|
156 | @example |
---|
157 | make VARIANT=DEBUG install |
---|
158 | make VARIANT=PROFILE install |
---|
159 | @end example |
---|
160 | |
---|
161 | @subsection make debug / make profile |
---|
162 | |
---|
163 | These make targets are not supported anymore. |
---|
164 | Instead, use: |
---|
165 | |
---|
166 | @example |
---|
167 | make VARIANT=DEBUG all |
---|
168 | make VARIANT=PROFILE all |
---|
169 | @end example |
---|
170 | |
---|
171 | |
---|
172 | @subsection Building RTEMS does not honor XXX_FOR_TARGET |
---|
173 | |
---|
174 | RTEMS < 4.6.0 did not support passing flags from the environment. |
---|
175 | If using RTEMS < 4.6.0, editing your BSP's @code{make/custom/mybsp.cfg} and |
---|
176 | setting appropriate flags there is required. |
---|
177 | |
---|
178 | RTEMS >= 4.6.0 honors several XXX_FOR_TARGET environment variables. |
---|
179 | Run @code{<path-to-rtems>/configure --help} for a full list of supported variables. |
---|
180 | |
---|
181 | @subsection Editing Makefile.in Makefile configure |
---|
182 | |
---|
183 | These files are generated by auto* tools, cf. |
---|
184 | @ref{Editing auto* generated files}). |
---|
185 | |
---|
186 | @subsection Editing auto* generated files |
---|
187 | |
---|
188 | |
---|
189 | RTEMS uses automake, therefore @b{never}, @b{ever}, @b{ever} |
---|
190 | edit Makefile.ins, Makefiles, configure or other auto* generated files. |
---|
191 | Changes to them will be swapped away soon and will get lost. |
---|
192 | |
---|
193 | Instead edit the sources (eg.: Makefile.ams, configure.acs) auto* generated |
---|
194 | files are generated from directly. |
---|
195 | |
---|
196 | If sending patches always send Makefile.ams and configure.acs. |
---|
197 | Sending Makefile.ins, Makefiles and configure scripts is pretty much useless. |
---|
198 | If sending larger patches, consider removing all auto* generated files |
---|
199 | by running @code{bootstrap -c} (cf. See @ref{./bootstrap}) |
---|
200 | before running diff to cut a patch. |
---|
201 | |
---|
202 | If you don't understand what this is all about, try start getting familiar |
---|
203 | with auto* tools by reading autoconf.info and automake.info, or feel free |
---|
204 | to 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 | |
---|
212 | No, plain DOS and plain Win will not work, but Cygwin should. |
---|
213 | Other U*nix emulations, such as Mingw and DJGPP are not supported and very |
---|
214 | likely will not work. |
---|
215 | Cywin / WinNT is known to work, but at the time of writing this, there |
---|
216 | seem to persist non-RTEMS related issues with Cygwin under Win9x which |
---|
217 | seem to prevent success on those systems. |
---|
218 | |
---|
219 | @subsection Do I need Linux? |
---|
220 | |
---|
221 | |
---|
222 | No, 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 | |
---|
227 | None, any recent U*nix should work, i.e. |
---|
228 | any 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 | |
---|
234 | The simple answer is that between 4.0 and now, RTEMS has moved to automake |
---|
235 | and greater compliance with GNU conventions. |
---|
236 | In 4.0, there was a single configure script at the top of the tree. |
---|
237 | Now RTEMS is configured more like other GNU tools -- as a collection of |
---|
238 | configurable entities. |
---|
239 | |
---|
240 | |
---|
241 | Each BSP now has its own configure script. |
---|
242 | I highly recommend you look at the Makefile.am's, configure.ac, of a similar |
---|
243 | BSP. You might even want to consider running "bootstrap -c" from the top of |
---|
244 | the tree and looking at what is left. bootstrap (cf. @ref{./bootstrap}) |
---|
245 | generates/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 |
---|
251 | templates when implementing BSPs or porting RTEMS to new CPUs. |
---|
252 | |
---|
253 | @subsection What is the bare-BSP? |
---|
254 | |
---|
255 | At the time being RTEMS is build per BSP, with all support files being build |
---|
256 | separately for each BSP. This can become unhandy when using several similar |
---|
257 | but not identical boards (e.g. a PC with different peripherial cards plugged |
---|
258 | in), because this in general requires to implement a BSP for each setup. |
---|
259 | The bare BSP is a general, setup independent BSP which can be used when |
---|
260 | keeping all BSP specific parts external from RTEMS. |
---|
261 | |
---|
262 | At present time the bare BSP is in its infancy. |
---|
263 | It is known that it can be build for most CPUs RTEMS supports. |
---|
264 | It is also known to work in individual cases, but your mileage may vary. |
---|
265 | |
---|
266 | @subsection Multilib vs. RTEMS CPU-variants |
---|
267 | |
---|
268 | The GNU toolchain applies a specific classification of similar CPUs into |
---|
269 | CPU variants (eg. SH1, SH2 etc.) to provide better support for each CPU variant. |
---|
270 | |
---|
271 | RTEMS uses a different classification because it internally requires more |
---|
272 | details about a specific CPU than the GNU toolchain's multilib classification |
---|
273 | provides. |
---|
274 | |
---|
275 | @subsection Keeping auto* generated files in CVS |
---|
276 | |
---|
277 | When using CVS to archive source code, problems arise from keeping generated |
---|
278 | files 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 |
---|
283 | from 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 |
---|
292 | having checked them out from CVS. |
---|
293 | |
---|
294 | @end itemize |
---|
295 | |
---|
296 | RTEMS favors the the latter variant, because it appears to be less error-prone |
---|
297 | and easier to handle (cf. @ref{./bootstrap} for details). |
---|
298 | |
---|
299 | @subsection Importing RTEMS into CVS/RCS |
---|
300 | |
---|
301 | When importing RTEMS into CVS/RCS or similar, we recommend not to import |
---|
302 | auto* generated files (cf. @ref{Keeping auto* generated files in CVS}). |
---|
303 | |
---|
304 | To remove them before importing, run |
---|
305 | |
---|
306 | @example |
---|
307 | ./bootstrap -c |
---|
308 | @end example |
---|
309 | |
---|
310 | from 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 |
---|
316 | auto* 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, |
---|
318 | automake and further underlying packages installed to apply it. |
---|
319 | |
---|
320 | It typically should be applied when having: |
---|
321 | |
---|
322 | @itemize @bullet |
---|
323 | |
---|
324 | @item checked out RTEMS sources from a CVS repository which does |
---|
325 | not contain generated files. |
---|
326 | |
---|
327 | @item added new automake / autoconf files to the source tree (eg. |
---|
328 | having added a new BSP), and when not being sure about what needs to be |
---|
329 | updated. |
---|
330 | |
---|
331 | @end itemize |
---|
332 | |
---|
333 | Once all autoconf/automake generated files are present, you will rarely |
---|
334 | need to run @code{bootstrap}, because automake automatically updates |
---|
335 | generated 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 | |
---|
340 | When 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 | |
---|
347 | This will enable the maintainer-mode in automake generated Makefiles, which |
---|
348 | will let automake take care about dependencies between auto* generated |
---|
349 | files. I.e. auto* generated files will get automatically updated. |
---|
350 | |
---|
351 | Configuring RTEMS in maintainer-mode will require to have autoconf, automake |
---|
352 | and underlying tools installed (Cf. @ref{Required Tools}). |
---|
353 | |
---|
354 | @subsection configure.ac vs. configure.in |
---|
355 | |
---|
356 | autoconf < 2.50 used the name @code{configure.in} for it's input files. |
---|
357 | autoconf >= 2.50 recommends using the name @code{configure.ac}, instead. |
---|
358 | |
---|
359 | RTEMS > 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 |
---|
361 | adapted to autoconf >= 2.50 demands. |
---|