source: rtems/doc/started/buildc.t @ 0ab65474

4.104.114.84.95
Last change on this file since 0ab65474 was 0ab65474, checked in by Joel Sherrill <joel.sherrill@…>, on Jun 10, 2000 at 8:33:47 PM

Purged as many egcs references as possible.

  • Property mode set to 100644
File size: 18.8 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-1999.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Building the GNU C/C++ Cross Compiler Toolset
10
11This chapter describes the steps required to acquire the
12source code for a GNU cross compiler toolset, apply
13any required RTEMS specific patches, compile that
14toolset and install it.
15
16It is recommended that when toolset binaries are available for
17your particular host, that they be used.  Prebuilt binaries
18are much easier to install.
19
20@section Create the Archive and Build Directories
21
22Start by making the @code{archive} directory to contain the downloaded
23source code and the @code{tools} directory to be used as a build
24directory.  The command sequence to do this is shown
25below:
26
27@example
28mkdir archive
29mkdir tools
30@end example
31
32This will result in an initial directory structure similar to the
33one shown in the following figure:
34
35@example
36@group
37/whatever/prefix/you/choose/
38        archive/
39        tools/
40
41@end group
42@end example
43
44@c @ifset use-html
45@c @html
46@c <IMG SRC="sfile12c.jpg" WIDTH=417 HEIGHT=178
47@c      ALT="Starting Directory Organization">
48@c @end html
49@c @end ifset
50
51@section Get All the Pieces
52
53This section lists the components of an RTEMS cross development system. 
54Included are the locations of each component as well as any required RTEMS
55specific patches.
56
57@subheading @value{GCC-VERSION}
58@example
59    FTP Site:    @value{GCC-FTPSITE}
60    Directory:   @value{GCC-FTPDIR}
61    File:        @value{GCC-TAR}
62@ifset use-html
63@c    URL:         @uref{Download @value{GCC-VERSION}, ftp://@value{GCC-FTPSITE}@value{GCC-FTPDIR}}
64    URL:         ftp://@value{GCC-FTPSITE}@value{GCC-FTPDIR}
65@end ifset
66@end example
67
68@subheading @value{BINUTILS-VERSION}
69@example
70    FTP Site:    @value{BINUTILS-FTPSITE}
71    Directory:   @value{BINUTILS-FTPDIR}
72    File:        @value{BINUTILS-TAR}
73@ifset use-html
74@c    URL:         @uref{ftp://@value{BINUTILS-FTPSITE}@value{BINUTILS-FTPDIR}/@value{BINUTILS-TAR},Download @value{BINUTILS-VERSION}}
75    URL:         ftp://@value{BINUTILS-FTPSITE}@value{BINUTILS-FTPDIR}/@value{BINUTILS-TAR}
76@end ifset
77@end example
78
79@subheading @value{NEWLIB-VERSION}
80@example
81    FTP Site:    @value{NEWLIB-FTPSITE}
82    Directory:   @value{NEWLIB-FTPDIR}
83    File:        @value{NEWLIB-TAR}
84@ifset use-html
85@c    URL:         @uref{ftp://@value{NEWLIB-FTPSITE}@value{NEWLIB-FTPDIR}/@value{NEWLIB-TAR}, Download @value{NEWLIB-VERSION}}
86    URL:         ftp://@value{NEWLIB-FTPSITE}@value{NEWLIB-FTPDIR}/@value{NEWLIB-TAR}
87@end ifset
88@end example
89
90@subheading @value{RTEMS-VERSION}
91@example
92    FTP Site:    @value{RTEMS-FTPSITE}
93    Directory:   @value{RTEMS-FTPDIR}
94    File:        @value{RTEMS-TAR}
95@ifset use-html
96@c    URL:         @uref{ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}, Download RTEMS components}
97    URL:         ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}
98@end ifset
99@end example
100
101@subheading RTEMS Hello World
102@example
103    FTP Site:    @value{RTEMS-FTPSITE}
104    Directory:   @value{RTEMS-FTPDIR}
105    File:        hello_world_c.tgz
106@ifset use-html
107@c    URL:         @uref{ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}/hello_world_c.tgz, Download RTEMS Hello World}
108    URL:         ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}/hello_world_c.tgz
109@end ifset
110@end example
111
112@subheading RTEMS Specific Tool Patches and Scripts
113@example
114    FTP Site:    @value{RTEMS-FTPSITE}
115    Directory:   @value{RTEMS-FTPDIR}/c_tools/source
116    File:        @value{BUILDTOOLS-TAR}
117@ifset BINUTILS-RTEMSPATCH
118    File:        @value{BINUTILS-RTEMSPATCH}
119@end ifset
120@ifset NEWLIB-RTEMSPATCH
121    File:        @value{NEWLIB-RTEMSPATCH}
122@end ifset
123@ifset GCC-RTEMSPATCH
124    File:        @value{GCC-RTEMSPATCH}
125@end ifset
126@ifset use-html
127@c    URL:         @uref{ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}/c_tools/source,Download RTEMS Patches and Scripts}
128    URL:         ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}/c_tools/source
129@end ifset
130@end example
131
132@section Unarchiving the Tools
133
134While in the @code{tools} directory, unpack the compressed
135tar files using the following command sequence:
136
137@example
138cd tools
139tar xzf ../archive/@value{GCC-TAR}
140tar xzf ../archive/@value{BINUTILS-TAR}
141tar xzf ../archive/@value{NEWLIB-TAR}
142tar xzf ../archive/@value{BUILDTOOLS-TAR}
143@end example
144
145After the compressed tar files have been unpacked, the following
146directories will have been created under tools.
147
148@itemize @bullet
149@item @value{BINUTILS-UNTAR}
150@item @value{GCC-UNTAR}
151@item @value{NEWLIB-UNTAR}
152@end itemize
153
154There will also be a set of scripts in the current directory
155which aid in building the tools and RTEMS.  They are:
156
157@itemize @bullet
158@item bit
159@item bit_gdb
160@item bit_rtems
161@item common.sh
162@item user.cfg
163@end itemize
164
165When the @code{bit} script is executed later in this process,
166it will automatically create this subdirectory:
167
168@itemize @bullet
169@item build-$@{CPU@}-tools
170@end itemize
171
172Similarly, the @code{bit_gdb} script will create the
173subdirectory @code{build-$@{CPU@}-gdb} and
174the @code{bit_rtems} script will create the
175subdirectory @code{build-$@{CPU@}-rtems}.
176
177The tree should look something like the following figure:
178
179@example
180@group
181/whatever/prefix/you/choose/
182        archive/
183            @value{GCC-TAR}
184            @value{BINUTILS-TAR}
185            @value{NEWLIB-TAR}
186            @value{RTEMS-TAR}
187            @value{BUILDTOOLS-TAR}
188@ifset GCC-RTEMSPATCH
189            @value{GCC-RTEMSPATCH}
190@end ifset
191@ifset BINUTILS-RTEMSPATCH
192            @value{BINUTILS-RTEMSPATCH}
193@end ifset
194@ifset NEWLIB-RTEMSPATCH
195            @value{NEWLIB-RTEMSPATCH}
196@end ifset
197            hello_world_c.tgz
198            bit
199        tools/
200            @value{BINUTILS-UNTAR}/
201            @value{GCC-UNTAR}/
202            @value{NEWLIB-UNTAR}/
203            bit
204            bit_gdb
205            bit_rtems
206            common.sh
207            user.cfg
208@end group
209@end example
210
211
212@c @ifset use-html
213@c @html
214@c <IMG SRC="bit_c.jpg" WIDTH=816 HEIGHT=267 ALT="Directory Organization">
215@c @end html
216@c @end ifset
217
218@c
219@c  Host Specific Notes
220@c
221
222@section Host Specific Notes
223
224@subsection Solaris 2.x
225
226The build scripts are written in "shell".  The program @code{/bin/sh}
227on Solaris 2.x is not robust enough to execute these scripts.  If you
228are on a Solaris 2.x host, then change the first line of the files
229@code{bit}, @code{bit_gdb}, and @code{bit_rtems} to use the
230@code{/bin/ksh} shell instead.
231
232@subsection Linux
233
234@subsubsection Broken install Program
235
236Certain versions of GNU fileutils include a version of @code{install} which
237does not work properly.  Please perform the following test to see if you
238need to upgrade:
239
240@example
241install -c -d /tmp/foo/bar
242@end example
243
244If this does not create the specified directories your install
245program will not install RTEMS properly.   You will need to upgrade
246to at least GNU fileutile version 3.16 to resolve this problem.
247
248@c
249@c  Reading the Documentation
250@c
251
252@section Reading the Tools Documentation
253
254Each of the tools in the GNU development suite comes with documentation.
255It is in the reader's and tool maintainers' interest that one read the
256documentation before posting a problem to a mailing list or news group.
257Much of that documentation is available on-line.  The following is
258a list of URLs where can find HTML versions of the manuals.
259
260@table @b
261GCC Documentation
262http://gcc.gnu.org/onlinedocs
263
264Newlib Documentation
265Not currently online at http://sourceware.cygnus.com/newlib
266
267Binutils Documentation
268Not currently online at http://sourceware.cygnus.com/binutils
269@end table
270
271@c
272@c  GCC patches
273@c
274
275@section Apply RTEMS Patch to GCC
276
277@ifclear GCC-RTEMSPATCH
278No RTEMS specific patches are required for @value{GCC-VERSION} to
279support @value{RTEMS-VERSION}.
280@end ifclear
281
282@ifset GCC-RTEMSPATCH
283
284Apply the patch using the following command sequence:
285
286@example
287cd tools/@value{GCC-UNTAR}
288zcat ../../archive/@value{GCC-RTEMSPATCH} | patch -p1
289@end example
290
291Check to see if any of these patches have been rejected using the following
292sequence:
293
294@example
295cd tools/@value{GCC-UNTAR}
296find . -name "*.rej" -print
297@end example
298
299If any files are found with the .rej extension, a patch has been rejected.
300This should not happen with a good patch file which is properly applied.
301
302@end ifset
303
304@c
305@c  BINUTILS patches
306@c
307
308@section Apply RTEMS Patch to binutils
309
310@ifclear BINUTILS-RTEMSPATCH
311No RTEMS specific patches are required for @value{BINUTILS-VERSION} to
312support @value{RTEMS-VERSION}.
313@end ifclear
314
315@ifset BINUTILS-RTEMSPATCH
316Apply the patch using the following command sequence:
317
318@example
319cd tools/@value{BINUTILS-UNTAR}
320zcat ../../archive/@value{BINUTILS-RTEMSPATCH} | patch -p1
321@end example
322
323Check to see if any of these patches have been rejected using the following
324sequence:
325
326@example
327cd tools/@value{BINUTILS-UNTAR}
328find . -name "*.rej" -print
329@end example
330
331If any files are found with the .rej extension, a patch has been rejected.
332This should not happen with a good patch file which is properly applied.
333
334@end ifset
335
336@c
337@c  Newlib patches
338@c
339
340@section Apply RTEMS Patch to newlib
341
342@ifclear NEWLIB-RTEMSPATCH
343No RTEMS specific patches are required for @value{NEWLIB-VERSION} to
344support @value{RTEMS-VERSION}.
345@end ifclear
346
347@ifset NEWLIB-RTEMSPATCH
348
349Apply the patch using the following command sequence:
350
351@example
352cd tools/@value{NEWLIB-UNTAR}
353zcat ../../archive/@value{NEWLIB-RTEMSPATCH} | patch -p1
354@end example
355
356Check to see if any of these patches have been rejected using the following
357sequence:
358
359@example
360cd tools/@value{NEWLIB-UNTAR}
361find . -name "*.rej" -print
362@end example
363
364If any files are found with the .rej extension, a patch has been rejected.
365This should not happen with a good patch file which is properly applied.
366
367@end ifset
368
369@c
370@c  Localizing the Configuration
371@c
372
373@section Localizing the Configuration
374
375Edit the @code{user.cfg} file to alter the settings of various
376variables which are used to tailor the build process.
377Each of the variables set in @code{user.cfg} may be modified
378as described below:
379
380@table @code
381@item INSTALL_POINT
382is the location where you wish the GNU C/C++ cross compilation tools for
383RTEMS to be built. It is recommended that the directory chosen to receive
384these tools be named so that it is clear from which gcc distribution it
385was generated and for which target system the tools are to produce code for.
386
387@b{WARNING}: The @code{INSTALL_POINT} should not be a subdirectory
388under the build directory.  The build directory will be removed
389automatically upon successful completion of the build procedure.
390
391@item BINUTILS
392is the directory under tools that contains @value{BINUTILS-UNTAR}.
393For example:
394
395@example
396BINUTILS=@value{BINUTILS-UNTAR}
397@end example
398
399@item GCC
400is the directory under tools that contains @value{GCC-UNTAR}.
401For example,
402
403@example
404GCC=@value{GCC-UNTAR}
405@end example
406
407@item NEWLIB
408is the directory under tools that contains @value{NEWLIB-UNTAR}.
409For example:
410
411@example
412NEWLIB=@value{NEWLIB-UNTAR}
413@end example
414
415@item BUILD_DOCS
416is set to "yes" if you want to install documentation.  This requires
417that tools supporting documentation production be installed.  This
418currently is limited to the GNU texinfo package.
419For example:
420
421@example
422BUILD_DOCS=yes
423@end example
424
425@item BUILD_OTHER_LANGUAGES
426is set to "yes" if you want to build languages other than C and C++.  At
427the current time, the set of alternative languages includes Java, Fortran,
428and Objective-C.  These alternative languages do not always build cross.
429Hence this option defaults to "no".
430
431For example:
432
433@example
434BUILD_OTHER_LANGUAGES=yes
435@end example
436
437@b{NOTE:} Based upon the version of the compiler being used, it may not
438be possible to build languages other than C and C++ cross.  In many cases,
439the language run-time support libraries are not "multilib'ed".  Thus the
440executable code in these libraries will be for the default compiler settings
441and not necessarily be correct for your CPU model.
442
443@item RTEMS
444is the directory under tools that contails @value{RTEMS-UNTAR}.
445
446@item ENABLE_RTEMS_POSIX
447is set to "yes" if you want to enable the RTEMS POSIX API support.
448At this time, this feature is not supported by the UNIX ports of RTEMS
449and is forced to "no" for those targets.  This corresponds to the
450@code{configure} option @code{--enable-posix}.
451
452@item ENABLE_RTEMS_ITRON
453is set to "yes" if you want to enable the RTEMS ITRON API support.
454At this time, this feature is not supported by the UNIX ports of RTEMS
455and is forced to "no" for those targets.  This corresponds to the
456@code{configure} option @code{--enable-itron}.
457
458@item ENABLE_RTEMS_MP
459is set to "yes" if you want to enable the RTEMS multiprocessing
460support.  This feature is not supported by all RTEMS BSPs and
461is automatically forced to "no" for those BSPs.  This corresponds to the
462@code{configure} option @code{--enable-multiprocessing}.
463
464@item ENABLE_RTEMS_CXX
465is set to "yes" if you want to build the RTEMS C++ support including
466the C++ Wrapper for the Classic API.  This corresponds to the
467@code{configure} option @code{--enable-cxx}.
468
469@item ENABLE_RTEMS_TESTS
470is set to "yes" if you want to build the RTEMS Test Suite.  If this
471is set to "no", then only the Sample Tests will be built.  Setting
472this option to "yes" significantly increases the amount of disk
473space required to build RTEMS.
474This corresponds to the @code{configure} option @code{--enable-tests}.
475
476@item ENABLE_RTEMS_TCPIP
477is set to "yes" if you want to build the RTEMS TCP/IP Stack.  If a
478particular BSP does not support TCP/IP, then this feature is automatically
479disabled.  This corresponds to the @code{configure} option
480@code{--enable-tcpip}.
481
482@item ENABLE_RTEMS_NONDEBUG
483is set to "yes" if you want to build RTEMS in a fully optimized
484state.  This corresponds to executing @code{make} after configuring
485the source tree.
486
487@item ENABLE_RTEMS_DEBUG
488is set to "yes" if you want to build RTEMS in a debug version.
489When built for debug, RTEMS will include run-time code to
490perform consistency checks such as heap consistency checks.
491Although the precise compilation arguments are BSP dependent,
492the debug version of RTEMS is usually built at a lower optimization
493level.  This is usually done to reduce inlining which can make
494tracing code execution difficult.  This corresponds to executing
495@code{make VARIANT=debug} after configuring
496the source tree.
497
498@item INSTALL_RTEMS
499is set to "yes" if you want to install RTEMS after building it.
500This corresponds to executing @code{make install} after configuring
501and building the source tree.
502
503@item ENABLE_RTEMS_MAINTAINER_MODE
504is set to "yes" if you want to enabled maintainer mode functionality
505in the RTEMS Makefile.  This is disabled by default and it is not
506expected that most users will want to enable this.  When this option
507is enabled, the build process may attempt to regenerate files that
508require tools not required when this option is disabled.
509This corresponds to the @code{configure} option
510@code{--enable-maintainer-mode}.
511
512@end table
513
514@section Running the bit Script
515
516After the @code{bit} script has been modified to reflect the
517local installation, the modified @code{bit} script is run
518using the following sequence:
519
520@example
521cd tools
522./bit <target configuration>
523@end example
524
525Where <target configuration> is one of the following:
526
527@itemize @bullet
528@item hppa1.1
529@item i386
530@item i386-elf
531@item i386-go32
532@item i960
533@item m68k
534@item mips64orion
535@item powerpc
536@item sh
537@item sparc
538@end itemize
539
540The build process can take a while to complete.  Many users find it
541handy to run the build process in the background, capture the output
542in a file, and monitor the output.  This can be done as follows:
543
544@example
545./bit_ada <target configuration> >bit.log 2>&1 &
546tail -f bit.log
547@end example
548
549If no errors are encountered, the @code{bit} script will conclude by
550printing messages similar to the following:
551
552@example
553
554The build-i386-tools subdirectory may now be removed.
555
556Started:  Fri Apr 10 10:14:07 CDT 1998
557Finished: Fri Apr 10 12:01:33 CDT 1998
558@end example
559
560If the @code{bit} script successfully completes, then the
561GNU C/C++ cross compilation tools are installed.
562
563If the @code{bit} script does not successfully complete, then investigation
564will be required to determine the source of the error.
565
566@section Common Problems
567
568@subsection Error Message Indicates Invalid Option to Assembler
569
570If a message like this is printed then the new cross compiler
571is most likely using the native assembler instead of the cross
572assembler or vice-versa (native compiler using new cross assembler).
573This can occur for one of the following reasons:
574
575@itemize @bullet
576
577@item Binutils Patch Improperly Applied
578@item Binutils Not Built
579@item Current Directory is in Your PATH
580
581@end itemize
582
583If you are using binutils 2.9.1 or newer with certain versions of
584gcc, they do not agree on what the name of the newly
585generated cross assembler is.  Older binutils called it @code{as.new}
586which became @code{as.new.exe} under Windows.  This is not a valid
587file name, so @code{as.new} is now called @code{as-new}.  By using the latest
588released tool versions and RTEMS patches, this problem will be avoided.
589
590If binutils did not successfully build the cross assembler, then
591the new cross gcc (@code{xgcc}) used to build the libraries can not
592find it.  Make sure the build of the binutils succeeded.
593
594If you include the current directory in your PATH, then there
595is a chance that the native compiler will accidentally use
596the new cross assembler instead of the native one.  This usually
597indicates that "." is before the standard system directories
598in your PATH.  As a general rule, including "." in your PATH
599is a security risk and should be avoided.  Remove "." from
600your PATH.
601
602NOTE:  In some environments, it may be difficult remove "."
603completely from your PATH.  In this case, make sure that "."
604is after the system directories containing "as" and "ld".
605
606@subsection Error Messages Indicating Configuration Problems
607
608If you see error messages like the following,
609
610@itemize @bullet
611
612@item cannot configure libliberty
613@item coff-emulation not found
614@item etc.
615
616@end itemize
617
618Then it is likely that one or more of your gnu tools is
619already configured locally in its source tree.  You can check
620for this by searching for the @code{config.status} file
621in the various tool source trees.  The following command
622does this for the binutils source:
623
624@example
625find @value{BINUTILS-UNTAR} -name config.status -print
626@end example
627
628The solution for this is to execute the command
629@code{make distclean} in each of the GNU tools
630root source directory.  This should remove all
631generated files including Makefiles.
632
633This situation usually occurs when you have previously
634built the tool source for some non-RTEMS target.  The
635generated configuration specific files are still in
636the source tree and the include path specified during
637the RTEMS build accidentally picks up the previous
638configuration.  The include path used is something like
639this:
640
641@example
642-I../../@value{BINUTILS-UNTAR}/gcc -I/@value{BINUTILS-UNTAR}/gcc/include -I.
643@end example
644
645Note that the tool source directory is searched before the
646build directory.
647
648This situation can be avoided entirely by never using
649the source tree as the build directory -- even for
650native builds.
Note: See TracBrowser for help on using the repository browser.