source: rtems/doc/started/buildc.t @ 48cd0b8e

4.104.114.84.95
Last change on this file since 48cd0b8e was 48cd0b8e, checked in by Joel Sherrill <joel.sherrill@…>, on Oct 2, 2003 at 6:01:48 PM

2003-10-02 Joel Sherrill <joel@…>

  • Makefile.am, binaries.t, buildc.t, intro.t, nextstep.t, require.t, sample.t, started.texi: General improvements and merge enough Ada information to justify dropping the Ada specific manual. There is likely still Ada specific information to merge though.
  • Property mode set to 100644
File size: 30.3 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2002.
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 Cross Compiler Toolset
10
11NOTE:  This chapter does @b{NOT} apply if you installed
12prebuilt toolset executables for BINUTILS, GCC, NEWLIB,
13and GDB.  If you installed prebuilt executables for all
14of those, proceed to @ref{Building RTEMS}.  If you require
15a GDB with a special configuration to connect to your
16target board, then proceed to @ref{Building the GNU Debugger GDB}
17for some advice.
18
19This chapter describes the steps required to acquire the
20source code for a GNU cross compiler toolset, apply
21any required RTEMS specific patches, compile that
22toolset and install it.
23
24It is recommended that when toolset binaries are available for
25your particular host, that they be used.  Prebuilt binaries
26are much easier to install.
27
28@c
29@c  Building BINUTILS GCC and NEWLIB
30@c
31@section Building BINUTILS GCC and NEWLIB
32
33NOTE: This step is NOT required if prebuilt executables for
34BINUTILS, GCC, and NEWLIB were installed.
35
36This section describes the process of building BINUTILS, GCC, and
37NEWLIB using a variety of methods.  Included is information on
38obtaining the source code and patches, applying patches, and
39building and installing the tools using multiple methods.
40
41@c
42@c  Obtain Source and Patches for BINUTILS GCC and NEWLIB
43@c
44
45@subsection Obtain Source and Patches for BINUTILS GCC and NEWLIB
46
47NOTE: This step is required for all methods of building BINUTILS,
48GCC, and NEWLIB.
49
50This section lists the components required to build BINUTILS, GCC,
51and NEWLIB from source to target RTEMS.  These files should be
52placed in your @code{archive} directory.  Included are the locations
53of each component as well as any required RTEMS specific patches.
54
55@need 1000
56@subheading @value{GCCUNTAR}
57@example
58    FTP Site:    @value{GCCFTPSITE}
59    Directory:   @value{GCCFTPDIR}
60    File:        @value{GCCTAR}
61@c @ifset use-html
62    URL:         @uref{ftp://@value{GCCFTPSITE}@value{GCCFTPDIR}/@value{GCCTAR},,ftp://@value{GCCFTPSITE}@value{GCCFTPDIR}/@value{GCCTAR}}
63@c    URL:         ftp://@value{GCCFTPSITE}@value{GCCFTPDIR}
64@c @end ifset
65@end example
66
67@need 1000
68@subheading @value{BINUTILSUNTAR}
69@example
70    FTP Site:    @value{BINUTILSFTPSITE}
71    Directory:   @value{BINUTILSFTPDIR}
72    File:        @value{BINUTILSTAR}
73@c @ifset use-html
74    URL:         @uref{ftp://@value{BINUTILSFTPSITE}@value{BINUTILSFTPDIR}/@value{BINUTILSTAR},,ftp://@value{BINUTILSFTPSITE}@value{BINUTILSFTPDIR}/@value{BINUTILSTAR}}
75@c    URL:         ftp://@value{BINUTILSFTPSITE}@value{BINUTILSFTPDIR}/@value{BINUTILSTAR}
76@c @end ifset
77@end example
78
79@need 1000
80@subheading @value{NEWLIBUNTAR}
81@example
82    FTP Site:    @value{NEWLIBFTPSITE}
83    Directory:   @value{NEWLIBFTPDIR}
84    File:        @value{NEWLIBTAR}
85@c @ifset use-html
86    URL:         @uref{ftp://@value{NEWLIBFTPSITE}@value{NEWLIBFTPDIR}/@value{NEWLIBTAR},,ftp://@value{NEWLIBFTPSITE}@value{NEWLIBFTPDIR}/@value{NEWLIBTAR}}
87@c    URL:         ftp://@value{NEWLIBFTPSITE}@value{NEWLIBFTPDIR}/@value{NEWLIBTAR}
88@c @end ifset
89@end example
90
91@need 1000
92@subheading RTEMS Specific Tool Patches and Scripts
93@example
94    FTP Site:    @value{RTEMSFTPSITE}
95    Directory:   @value{RTEMSFTPDIR}/c_tools/source
96@ifset BINUTILSPATCHVERSION
97    File:        @value{BINUTILSRTEMSPATCH}
98@end ifset
99@ifset NEWLIBPATCHVERSION
100    File:        @value{NEWLIBRTEMSPATCH}
101@end ifset
102@ifset GCCPATCHVERSION
103    File:        @value{GCCRTEMSPATCH}
104@end ifset
105@ifset use-html
106@c    URL:         @uref{ftp://@value{RTEMSFTPSITE}@value{RTEMSFTPDIR}/c_tools/source,Download RTEMS Patches and Scripts}
107    URL:         ftp://@value{RTEMSFTPSITE}@value{RTEMSFTPDIR}/c_tools/source
108@end ifset
109@end example
110
111@c
112@c  Unarchiving the Tools
113@c
114@subsection Unarchiving the Tools
115
116NOTE: This step is required if building BINUTILS, GCC, and NEWLIB
117using the procedure described in @ref{Using configure and make}.
118It is @b{NOT} required if using the procedure
119described in @ref{Using RPM to Build BINUTILS GCC and NEWLIB}.
120
121GNU source distributions are archived using @code{tar} and
122compressed using either @code{gzip} or @code{bzip}. 
123If compressed with @code{gzip}, the extension @code{.gz} is used.
124If compressed with @code{bzip}, the extension @code{.bz2} is used.
125
126While in the @code{tools} directory, unpack the compressed
127tar files for BINUTILS, GCC, and NEWLIB using the appropriate
128command based upon the compression program used.
129
130@example
131cd tools
132tar xzf ../archive/TOOLNAME.tar.gz  # for gzip'ed tools
133tar xIf ../archive/TOOLNAME.tar.bz2 # for bzip'ed tools
134@end example
135
136After the compressed tar files have been unpacked using
137the appropriate commands, the following
138directories will have been created under tools.
139
140@itemize @bullet
141@item @value{BINUTILSUNTAR}
142@item @value{GCCUNTAR}
143@item @value{NEWLIBUNTAR}
144@end itemize
145
146The tree should look something like the following figure:
147
148@example
149@group
150/whatever/prefix/you/choose/
151        archive/
152            @value{GCCTAR}
153            @value{BINUTILSTAR}
154            @value{NEWLIBTAR}
155@ifset GCCPATCHVERSION
156            @value{GCCRTEMSPATCH}
157@end ifset
158@ifset BINUTILSPATCHVERSION
159            @value{BINUTILSRTEMSPATCH}
160@end ifset
161@ifset NEWLIBPATCHVERSION
162            @value{NEWLIBRTEMSPATCH}
163@end ifset
164        tools/
165            @value{BINUTILSUNTAR}/
166            @value{GCCUNTAR}/
167            @value{NEWLIBUNTAR}/
168@end group
169@end example
170
171@c
172@c  Applying RTEMS Patches
173@c
174
175@subsection Applying RTEMS Patches
176
177NOTE: This step is required if building BINUTILS, GCC, and NEWLIB
178using the procedures described in @ref{Using configure and make}.
179It is @b{NOT} required if using the procedure
180described in @ref{Using RPM to Build BINUTILS GCC and NEWLIB}.
181
182This section describes the process of applying the RTEMS patches
183to GCC, NEWLIB, and BINUTILS.
184
185@c
186@c  GCC patches
187@c
188
189@subheading Apply RTEMS Patch to GCC
190
191@ifclear GCCPATCHVERSION
192No RTEMS specific patches are required for @value{GCCUNTAR} to
193support @value{RTEMSVERSION}.
194@end ifclear
195
196@ifset GCCPATCHVERSION
197
198Apply the patch using the following command sequence:
199
200@example
201cd tools/@value{GCCUNTAR}
202cat ../../archive/@value{GCCRTEMSPATCH} | \
203    patch -p1
204@end example
205
206If the patch was compressed with the @code{gzip} program, it will
207have a suffix of @code{.gz} and you should use @code{zcat} instead
208of @code{cat} as shown above.  If the patch was compressed with
209the @code{gzip} program, it will have a suffix of @code{.bz2} and
210you should use @code{bzcat} instead of @code{cat} as shown above.
211
212Check to see if any of these patches have been rejected using the following
213sequence:
214
215@example
216cd tools/@value{GCCUNTAR}
217find . -name "*.rej" -print
218@end example
219
220If any files are found with the .rej extension, a patch has been rejected.
221This should not happen with a good patch file which is properly applied.
222
223@end ifset
224
225@c
226@c  BINUTILS patches
227@c
228
229@subheading Apply RTEMS Patch to binutils
230
231@ifclear BINUTILSPATCHVERSION
232No RTEMS specific patches are required for @value{BINUTILSUNTAR} to
233support @value{RTEMSVERSION}.
234@end ifclear
235
236@ifset BINUTILSPATCHVERSION
237Apply the patch using the following command sequence:
238
239@example
240cd tools/@value{BINUTILSUNTAR}
241cat ../../archive/@value{BINUTILSRTEMSPATCH} | \
242    patch -p1
243@end example
244
245If the patch was compressed with the @code{gzip} program, it will
246have a suffix of @code{.gz} and you should use @code{zcat} instead
247of @code{cat} as shown above.  If the patch was compressed with
248the @code{gzip} program, it will have a suffix of @code{.bz2} and
249you should use @code{bzcat} instead of @code{cat} as shown above.
250
251Check to see if any of these patches have been rejected using the following
252sequence:
253
254@example
255cd tools/@value{BINUTILSUNTAR}
256find . -name "*.rej" -print
257@end example
258
259If any files are found with the .rej extension, a patch has been rejected.
260This should not happen with a good patch file which is properly applied.
261
262@end ifset
263
264@c
265@c  Newlib patches
266@c
267
268@subheading Apply RTEMS Patch to newlib
269
270@ifclear NEWLIBPATCHVERSION
271No RTEMS specific patches are required for @value{NEWLIBUNTAR} to
272support @value{RTEMSVERSION}.
273@end ifclear
274
275@ifset NEWLIBPATCHVERSION
276
277Apply the patch using the following command sequence:
278
279@example
280cd tools/@value{NEWLIBUNTAR}
281cat ../../archive/@value{NEWLIBRTEMSPATCH} | \
282    patch -p1
283@end example
284
285If the patch was compressed with the @code{gzip} program, it will
286have a suffix of @code{.gz} and you should use @code{zcat} instead
287of @code{cat} as shown above.  If the patch was compressed with
288the @code{gzip} program, it will have a suffix of @code{.bz2} and
289you should use @code{bzcat} instead of @code{cat} as shown above.
290
291Check to see if any of these patches have been rejected using the following
292sequence:
293
294@example
295cd tools/@value{NEWLIBUNTAR}
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
305@c
306@c  Compiling and Installing BINUTILS GCC and NEWLIB
307@c
308
309@subsection Compiling and Installing BINUTILS GCC and NEWLIB
310
311There are two supported methods to compile and install BINUTILS, GCC,
312and NEWLIB:
313
314@itemize @bullet
315@item RPM
316@item direct invocation of @code{configure} and @code{make}
317@end itemize
318
319Direct invocation of @code{configure} and @code{make} provides more control
320and easier recovery from problems when building.
321
322@c
323@c  Using RPM to Build BINUTILS GCC and NEWLIB
324@c
325
326@subsubsection Using RPM to Build BINUTILS GCC and NEWLIB
327
328NOTE:  The procedures described in the following sections must
329be completed before this step:
330
331@itemize @bullet
332@item @ref{Obtain Source and Patches for BINUTILS GCC and NEWLIB}
333@end itemize
334
335RPM automatically unarchives the source and applies any needed
336patches so you do @b{NOT} have to manually perform the procedures
337described @ref{Unarchiving the Tools} and
338@ref{Applying RTEMS Patches}.
339
340This section describes the process of building binutils, gcc, and
341newlib using RPM.  RPM is a packaging format which can be used to
342distribute binary files as well as to capture the procedure and
343source code used to produce those binary files.  Before
344attempting to build any RPM from source, it is necessary to
345ensure that all required source and patches are in the @code{SOURCES}
346directory under the RPM root (probably @code{/usr/src/redhat} or
347@code{/usr/local/src/redhat}) on your machine.  This procedure
348starts by installing the source RPMs as shown in the following
349example:
350
351@example
352rpm -i i386-rtems-binutils-collection-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.nosrc.rpm
353rpm -i i386-rtems-gcc-newlib-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.nosrc.rpm
354@end example
355
356The RTEMS tool source RPMS are called "nosrc" to indicate that one or
357more source files required to produce the RPMs are not present. 
358The RTEMS source RPMs typically include all required patches, but do not
359include the large @code{.tar.gz} or @code{.tgz} files for
360each component such as BINUTILS, GCC, or NEWLIB.  These are shared
361by all RTEMS RPMs regardless of target CPU and there was no reason
362to duplicate them.  You will have to get the required source
363archive files by hand and place them in the @code{SOURCES} directory
364before attempting to build.  If you forget to do this, RPM is
365smart -- it will tell you what is missing.  To determine what is
366included or referenced by a particular RPM, use a command like the
367following:
368
369@example
370@c Don't use @value{GCC*} below. This is an example
371$ rpm -q -l -p i386-rtems-gcc-newlib-gcc3.2.3newlib1.11.0-1.nosrc.rpm
372gcc-3.2.3-rtems-20030507a.diff
373i386-rtems-gcc-3.2.3-newlib-1.11.0.spec
374newlib-1.11.0-rtems-20030507.diff
375@end example
376
377Notice that there are patch files (the @code{.diff} files) and a file
378describing the build procedure and files produced (the @code{.spec} file),
379but no source archives (the @code{*tar.*} files).
380When installing this source RPM
381(@code{rpm -U i386-rtems-gcc-newlib-gcc3.2.3newlib1.11.0-1.nosrc.rpm}),
382the @code{.spec} file is placed in the @code{SPECS} directory under the RPM root
383directory, while the @code{*.diff} files are placed into the @code{SOURCES}
384directory.
385
386@c
387@c  Configuring and Building BINUTILS using RPM
388@c
389
390@subheading Configuring and Building BINUTILS using RPM
391
392The following example illustrates the invocation of RPM to build a new,
393locally compiled, binutils binary RPM that matches the installed source
394RPM.  This example assumes that all of the required source is installed.
395
396@example
397cd <RPM_ROOT_DIRECTORY>/SPECS
398rpm -bb i386-rtems-binutils-@value{BINUTILSVERSION}.spec
399@end example
400
401If the build completes successfully, RPMS like the following will
402be generated in a build-host architecture specific subdirectory
403of the RPMS directory under the RPM root directory.
404
405@example
406rtems-base-binutils-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.i386.rpm
407i386-rtems-binutils-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.i386.rpm
408@end example
409
410NOTE: It may be necessary to remove the build tree in the
411@code{BUILD} directory under the RPM root directory.
412
413@c
414@c  Configuring and Building GCC and NEWLIB using RPM
415@c
416
417@subheading Configuring and Building GCC and NEWLIB using RPM
418
419The following example illustrates the invocation of RPM to build a new,
420locally compiled, set of GCC and NEWLIB binary RPMs that match the
421installed source RPM.  It is also necessary to install the BINUTILS
422RPMs and place them in your PATH.  This example assumes that all of
423the required source is installed.
424
425@example
426cd <RPM_ROOT_DIRECTORY>/RPMS/i386
427rpm -i rtems-base-binutils-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.i386.rpm
428rpm -i i386-rtems-binutils-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.i386.rpm
429export PATH=@value{RTEMSPREFIX}/bin:$PATH
430cd <RPM_ROOT_DIRECTORY>/SPECS
431rpm -bb i386-rtems-gcc-@value{GCCVERSION}-newlib-@value{NEWLIBVERSION}.spec
432@end example
433
434If the build completes successfully, a set of RPMS like the following will
435be generated in a build-host architecture specific subdirectory
436of the RPMS directory under the RPM root directory.
437
438@example
439rtems-base-gcc-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
440rtems-base-chill-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
441rtems-base-g77-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
442rtems-base-gcj-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
443i386-rtems-gcc-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
444i386-rtems-chill-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
445i386-rtems-g77-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
446i386-rtems-gcj-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
447i386-rtems-objc-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
448@end example
449
450NOTE: Some targets do not support building all languages.
451
452NOTE: It may be necessary to remove the build tree in the
453@code{BUILD} directory under the RPM root directory.
454
455@c
456@c  Using configure and make
457@c
458
459@subsubsection Using configure and make
460
461NOTE:  The procedures described in the following sections must
462be completed before this step:
463
464@itemize @bullet
465@item @ref{Obtain Source and Patches for BINUTILS GCC and NEWLIB}
466@item @ref{Unarchiving the Tools}
467@item @ref{Applying RTEMS Patches}
468@end itemize
469
470This section describes the process of building binutils, gcc, and
471newlib manually using @code{configure} and @code{make} directly.
472
473@c
474@c  Configuring and Building BINUTILS
475@c
476
477@subheading Configuring and Building BINUTILS
478
479The following example illustrates the invocation of
480@code{configure} and @code{make}
481to build and install @value{BINUTILSUNTAR} for the
482sparc-rtems target:
483
484@example
485mkdir b-binutils
486cd b-binutils
487../@value{BINUTILSUNTAR}/configure --target=sparc-rtems \
488  --prefix=@value{RTEMSPREFIX}
489make all
490make info
491make install
492@end example
493
494After @value{BINUTILSUNTAR} is built and installed the
495build directory @code{b-binutils} may be removed.
496
497For more information on the invocation of @code{configure}, please
498refer to the documentation for @value{BINUTILSUNTAR} or
499invoke the @value{BINUTILSUNTAR} @code{configure} command with the
500@code{--help} option.
501
502NOTE: The shell PATH variable needs to be updated to include the path
503the binutils has been installed in. This the prefix used above with
504@file{bin} post-fixed.
505
506@example
507export PATH=$PATH:@value{RTEMSPREFIX}/bin
508@end example
509
510Failure to have the binutils in the path will cause the GCC and NEWLIB
511build to fail with an error message similar to:
512
513@example
514sparc-rtems-ar: command not found
515@end example
516
517@c
518@c  Configuring and Building GCC and NEWLIB
519@c
520
521@subheading Configuring and Building GCC and NEWLIB
522
523Before building @value{GCCUNTAR} and @value{NEWLIBUNTAR},
524@value{BINUTILSUNTAR} must be installed and the directory
525containing those executables must be in your PATH.
526
527The C Library is built as a subordinate component of
528@value{GCCUNTAR}.  Because of this, the @value{NEWLIBUNTAR}
529directory source must be available inside the @value{GCCUNTAR}
530source tree.  This is normally accomplished using a symbolic
531link as shown in this example:
532
533@example
534cd @value{GCCUNTAR}
535ln -s ../@value{NEWLIBUNTAR}/newlib .
536@end example
537
538The following example illustrates the invocation of
539@code{configure} and @code{make}
540to build and install @value{GCCUNTAR} with only
541C and C++ support for the sparc-rtems target:
542
543@example
544mkdir b-gcc
545cd b-gcc
546../@value{GCCUNTAR}/configure --target=sparc-rtems \
547   --with-gnu-as --with-gnu-ld --with-newlib --verbose \
548   --enable-threads --enable-languages="c,c++" \
549   --prefix=@value{RTEMSPREFIX}
550make all
551make info
552make install
553@end example
554
555After @value{GCCUNTAR} is built and installed the
556build directory @code{b-gcc} may be removed.
557
558For more information on the invocation of @code{configure}, please
559refer to the documentation for @value{GCCUNTAR} or
560invoke the @value{GCCUNTAR} @code{configure} command with the
561@code{--help} option.
562
563@c
564@c Building GCC with Ada Support
565@c
566@subheading Building GCC with Ada Support
567
568If you want a GCC toolset that includes support for Ada
569(e.g. GNAT), there are some additional requirements on
570the host environment and additional build steps to perform.
571It is critical that you use the same version of GCC/GNAT as
572the native compiler.  GNAT must be compiled with an Ada compiler
573and when building a GNAT cross-compiler, it should be
574the same version of GNAT itself.
575
576The build procedure is the same until the configure step.
577A GCC toolset with GNAT enabled requires that @code{ada}
578be included in the set of enabled languages.
579The following example illustrates the invocation of
580@code{configure} and @code{make}
581to build and install @value{GCCUNTAR} with only
582C, C++, and Ada support for the sparc-rtems target:
583
584@example
585mkdir b-gcc
586cd @value{GCCUNTAR}/gcc/ada
587touch treeprs.ads [es]info.h nmake.ad[bs]
588cd ../../../b-gcc
589../@value{GCCUNTAR}/configure --target=sparc-rtems \
590   --with-gnu-as --with-gnu-ld --with-newlib --verbose \
591   --enable-threads --enable-languages="c,c++,ada" \
592   --prefix=@value{RTEMSPREFIX}
593make all
594make info
595make -C gcc cross-gnattools
596make -C gcc ada.all.cross
597make -C gcc GNATLIBCFLAGS="USER_SELECTED_CPU_CFLAGS" gnatlib
598make install
599@end example
600
601After @value{GCCUNTAR} is built and installed the
602build directory @code{b-gcc} may be removed.
603
604@c
605@c Building the GNU Debugger GDB
606@c
607
608@section Building the GNU Debugger GDB
609
610NOTE: This step is NOT required if prebuilt executables for
611the GNU Debugger GDB were installed.
612
613The GNU Debugger GDB supports many configurations but requires some
614means of communicating between the host computer and target board.
615This communication can be via a serial port, Ethernet, BDM, or ROM emulator.
616The communication protocol can be the GDB remote protocol or GDB
617can talk directly to a ROM monitor.  This setup is target board
618specific.  The following configurations have been
619successfully used with RTEMS applications:
620
621@itemize @bullet
622@item BDM with ColdFire, 683xx, MPC860 CPUs
623@item Motorola Mxxxbug found on M68xxx VME boards
624@item Motorola PPCbug found on PowerPC VME, CompactPCI, and MTX boards
625@item ARM based Cogent EDP7312
626@item PC's using various Intel and AMD CPUs including i386,
627i486, Pentium and above, and Athlon
628@item PowerPC Instruction Simulator in GDB (PSIM)
629@item MIPS Instruction Simulator in GDB (JMR3904)
630@item Sparc Instruction Simulator in GDB (SIS)
631@item Sparc Instruction Simulator (TSIM)
632@item DINK32 on various PowerPC boards
633@end itemize
634
635GDB is currently RTEMS thread/task aware only if you are using the
636remote debugging support via Ethernet.  These are configured
637using gdb targets of the form CPU-RTEMS.  Note the capital RTEMS.
638
639It is recommended that when toolset binaries are available for
640your particular host, that they be used.  Prebuilt binaries
641are much easier to install but in the case of gdb may or may
642not include support for your particular target board.
643
644@c
645@c  Obtain Source and Patches for GDB
646@c
647
648@subsection Obtain Source and Patches for GDB
649
650NOTE: This step is required for all methods of building GDB.
651
652This section lists the components required to build GDB
653from source to target RTEMS.  These files should be
654placed in your @code{archive} directory.  Included are the locations
655of each component as well as any required RTEMS specific patches.
656
657@need 1000
658@subheading @value{GDBUNTAR}
659@example
660    FTP Site:    @value{GDBFTPSITE}
661    Directory:   @value{GDBFTPDIR}
662    File:        @value{GDBTAR}
663    URL:         @uref{@value{GDBFTPURL},,@value{GDBFTPURL}}
664@end example
665
666@need 1000
667@subheading RTEMS Specific Tool Patches and Scripts
668@example
669    FTP Site:    @value{RTEMSFTPSITE}
670    Directory:   @value{RTEMSFTPDIR}/c_tools/source
671@ifset GDBPATCHVERSION
672    File:        @value{GDBRTEMSPATCH}
673    URL:         @uref{ftp://@value{RTEMSFTPSITE}@value{RTEMSFTPDIR}/c_tools/source/@value{GDBRTEMSPATCH},,ftp://@value{RTEMSFTPSITE}@value{RTEMSFTPDIR}/c_tools/source/@value{GDBRTEMSPATCH}}
674@end ifset
675@end example
676
677@c
678@c  Unarchiving the GDB Distribution
679@c
680@subsection Unarchiving the GDB Distribution
681
682Use the following commands to unarchive the GDB distribution:
683
684@example
685cd tools
686tar xzf ../archive/@value{GDBTAR}
687@end example
688
689The directory @value{GDBUNTAR} is created under the tools directory.
690
691@c
692@c  Applying RTEMS Patch to GDB
693@c
694
695@subsection Applying RTEMS Patch to GDB
696
697@ifclear GDBPATCHVERSION
698No RTEMS specific patches are required for @value{GDBVERSION} to
699support @value{RTEMSVERSION}.
700@end ifclear
701
702@ifset GDBPATCHVERSION
703
704Apply the patch using the following command sequence:
705
706@example
707cd tools/@value{GDBUNTAR}
708cat archive/@value{GDBRTEMSPATCH} | \
709    patch -p1
710@end example
711
712If the patch was compressed with the @code{gzip} program, it will
713have a suffix of @code{.gz} and you should use @code{zcat} instead
714of @code{cat} as shown above.  If the patch was compressed with
715the @code{gzip} program, it will have a suffix of @code{.bz2} and
716you should use @code{bzcat} instead of @code{cat} as shown above.
717
718Check to see if any of these patches have been rejected using the following
719sequence:
720
721@example
722cd tools/@value{GDBUNTAR}
723find . -name "*.rej" -print
724@end example
725
726If any files are found with the .rej extension, a patch has been rejected.
727This should not happen with a good patch file.
728
729@end ifset
730
731@c
732@c  Compiling and Installing the GNU Debugger GDB
733@c
734
735@subsection Compiling and Installing the GNU Debugger GDB
736
737There are three methods of building the GNU Debugger:
738
739@itemize @bullet
740@item RPM
741@item direct invocation of @code{configure} and @code{make}
742@end itemize
743
744Direct invocation of @code{configure} and @code{make} provides more control
745and easier recovery from problems when building.
746
747@c
748@c  Using RPM to Build GDB
749@c
750
751@subsubsection Using RPM to Build GDB
752
753This section describes the process of building binutils, gcc, and
754newlib using RPM.  RPM is a packaging format which can be used to
755distribute binary files as well as to capture the procedure and
756source code used to produce those binary files.  Before
757attempting to build any RPM from source, it is necessary to
758ensure that all required source and patches are in the @code{SOURCES}
759directory under the RPM root (probably @code{/usr/src/redhat} or
760@code{/usr/local/src/redhat}) on your machine.  This procedure
761starts by installing the source RPMs as shown in the following
762example:
763
764@example
765rpm -i i386-rtems-gdb-collection-@value{GDBVERSION}-@value{GDBRPMRELEASE}.nosrc.rpm
766@end example
767
768Because RTEMS tool RPMS are called "nosrc" to indicate that one or
769more source files required to produce the RPMs are not present.
770The RTEMS source GDB RPM does not include the large @code{.tar.gz} or
771@code{.tgz} files for GDB.  This is shared by all RTEMS RPMs
772regardless of target CPU and there was no reason
773to duplicate them.  You will have to get the required source
774archive files by hand and place them in the @code{SOURCES} directory
775before attempting to build.  If you forget to do this, RPM is
776smart -- it will tell you what is missing.  To determine what is
777included or referenced by a particular RPM, use a command like the
778following:
779
780@example
781$ rpm -q -l -p i386-rtems-gdb-collection-@value{GDBVERSION}-@value{GDBRPMRELEASE}.nosrc.rpm
782gdb-@value{GDBVERSION}-rtems-@value{GDBPATCHVERSION}.diff
783gdb-@value{GDBVERSION}.tar.gz
784i386-rtems-gdb-@value{GDBVERSION}.spec
785@end example
786
787Notice that there is a patch file (the @code{.diff} file), a source archive
788file (the @code{.tar.gz}), and a file describing the build procedure and
789files produced (the @code{.spec} file).  The @code{.spec} file is placed
790in the @code{SPECS} directory under the RPM root directory.
791
792@c
793@c  Configuring and Building GDB using RPM
794@c
795
796@subheading Configuring and Building GDB using RPM
797
798The following example illustrates the invocation of RPM to build a new,
799locally compiled, binutils binary RPM that matches the installed source
800RPM.  This example assumes that all of the required source is installed.
801
802@example
803cd <RPM_ROOT_DIRECTORY>/SPECS
804rpm -bb i386-rtems-gdb-@value{GDBVERSION}.spec
805@end example
806
807If the build completes successfully, RPMS like the following will
808be generated in a build-host architecture specific subdirectory
809of the RPMS directory under the RPM root directory.
810
811@example
812rtems-base-gdb-@value{GDBVERSION}-@value{GDBRPMRELEASE}.i386.rpm
813i386-rtems-gdb-@value{GDBVERSION}-@value{GDBRPMRELEASE}.i386.rpm
814@end example
815
816NOTE: It may be necessary to remove the build tree in the
817@code{BUILD} directory under the RPM root directory.
818
819@c
820@c Using the GDB configure Script Directly
821@c
822
823@subsubsection Using the GDB configure Script Directly
824
825This section describes how to configure the GNU debugger for
826RTEMS targets using @code{configure} and @code{make} directly.
827The following example illustrates the invocation of @code{configure}
828and @code{make} to build and install @value{GDBUNTAR} for the
829m68k-rtems target:
830
831@example
832mkdir b-gdb
833cd b-gdb
834../@value{GDBUNTAR}/configure --target=m68k-rtems \
835  --prefix=@value{RTEMSPREFIX}
836make all
837make info
838make install
839@end example
840
841For some configurations, it is necessary to specify extra options
842to @code{configure} to enable and configure option components
843such as a processor simulator.  The following is a list of
844configurations for which there are extra options:
845
846@table @b
847@item i960-rtems
848@code{--enable-sim}
849
850@item powerpc-rtems
851@code{--enable-sim --enable-sim-powerpc --enable-sim-timebase --enable-sim-hardware}
852
853@item sparc-rtems
854@code{--enable-sim}
855
856@end table
857
858After @value{GDBUNTAR} is built and installed the
859build directory @code{b-gdb} may be removed.
860
861For more information on the invocation of @code{configure}, please
862refer to the documentation for @value{GDBUNTAR} or
863invoke the @value{GDBUNTAR} @code{configure} command with the
864@code{--help} option.
865
866@c
867@c Common Problems
868@c
869
870@section Common Problems
871
872@subsection Error Message Indicates Invalid Option to Assembler
873
874If a message like this is printed then the new cross compiler
875is most likely using the native assembler instead of the cross
876assembler or vice-versa (native compiler using new cross assembler).
877This can occur for one of the following reasons:
878
879@itemize @bullet
880
881@item Binutils Patch Improperly Applied
882@item Binutils Not Built
883@item Current Directory is in Your PATH
884
885@end itemize
886
887If you are using binutils 2.9.1 or newer with certain older versions of
888gcc, they do not agree on what the name of the newly
889generated cross assembler is.  Older binutils called it @code{as.new}
890which became @code{as.new.exe} under Windows.  This is not a valid
891file name, so @code{as.new} is now called @code{as-new}.  By using the latest
892released tool versions and RTEMS patches, this problem will be avoided.
893
894If binutils did not successfully build the cross assembler, then
895the new cross gcc (@code{xgcc}) used to build the libraries can not
896find it.  Make sure the build of the binutils succeeded.
897
898If you include the current directory in your PATH, then there
899is a chance that the native compiler will accidentally use
900the new cross assembler instead of the native one.  This usually
901indicates that "." is before the standard system directories
902in your PATH.  As a general rule, including "." in your PATH
903is a security risk and should be avoided.  Remove "." from
904your PATH.
905
906NOTE:  In some environments, it may be difficult to remove "."
907completely from your PATH.  In this case, make sure that "."
908is after the system directories containing "as" and "ld".
909
910@subsection Error Messages Indicating Configuration Problems
911
912If you see error messages like the following,
913
914@itemize @bullet
915
916@item cannot configure libiberty
917@item coff-emulation not found
918@item etc.
919
920@end itemize
921
922Then it is likely that one or more of your gnu tools is
923already configured locally in its source tree.  You can check
924for this by searching for the @code{config.status} file
925in the various tool source trees.  The following command
926does this for the binutils source:
927
928@example
929find @value{BINUTILSUNTAR} -name config.status -print
930@end example
931
932The solution for this is to execute the command
933@code{make distclean} in each of the GNU tools
934root source directory.  This should remove all
935generated files including Makefiles.
936
937This situation usually occurs when you have previously
938built the tool source for some non-RTEMS target.  The
939generated configuration specific files are still in
940the source tree and the include path specified during
941the RTEMS build accidentally picks up the previous
942configuration.  The include path used is something like
943this:
944
945@example
946-I../../@value{BINUTILSUNTAR}/gcc -I/@value{BINUTILSUNTAR}/gcc/include -I.
947@end example
948
949Note that the tool source directory is searched before the
950build directory.
951
952This situation can be avoided entirely by never using
953the source tree as the build directory -- even for
954
Note: See TracBrowser for help on using the repository browser.