source: rtems/doc/started/buildc.t @ bf31efd

4.104.114.84.95
Last change on this file since bf31efd was bf31efd, checked in by Joel Sherrill <joel.sherrill@…>, on Sep 19, 2003 at 6:03:32 PM

2003-09-19 Joel Sherrill <joel@…>

  • .cvsignore, binaries.t, buildc.t, buildrt.t, intro.t, nextstep.t, nt.t, started.texi: Merge from branch.
  • tversions.texi.in: New file.
  • Property mode set to 100644
File size: 28.7 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 C/C++ 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{BINUTILSUNTAR} for the
541sparc-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 --prefix=@value{RTEMSPREFIX}
549make all
550make info
551make install
552@end example
553
554After @value{GCCUNTAR} is built and installed the
555build directory @code{b-gcc} may be removed.
556
557For more information on the invocation of @code{configure}, please
558refer to the documentation for @value{GCCUNTAR} or
559invoke the @value{GCCUNTAR} @code{configure} command with the
560@code{--help} option.
561
562@c
563@c Building the GNU Debugger GDB
564@c
565
566@section Building the GNU Debugger GDB
567
568NOTE: This step is NOT required if prebuilt executables for
569the GNU Debugger GDB were installed.
570
571The GNU Debugger GDB supports many configurations but requires some
572means of communicating between the host computer and target board.
573This communication can be via a serial port, Ethernet, BDM, or ROM emulator.
574The communication protocol can be the GDB remote protocol or GDB
575can talk directly to a ROM monitor.  This setup is target board
576specific.  The following configurations have been
577successfully used with RTEMS applications:
578
579@itemize @bullet
580@item Sparc Instruction Simulator (SIS)
581@item PowerPC Instruction Simulator (PSIM)
582@item DINK32
583@item BDM with 68360 and MPC860 CPUs
584@item Motorola Mxxxbug found on M68xxx VME boards
585@item Motorola PPCbug found on PowerPC VME and CompactPCI boards
586@end itemize
587
588GDB is currently RTEMS thread/task aware only if you are using the
589remote debugging support via Ethernet.  These are configured
590using gdb targets of the form CPU-RTEMS.  Note the capital RTEMS.
591
592It is recommended that when toolset binaries are available for
593your particular host, that they be used.  Prebuilt binaries
594are much easier to install but in the case of gdb may or may
595not include support for your particular target board.
596
597@c
598@c  Obtain Source and Patches for GDB
599@c
600
601@subsection Obtain Source and Patches for GDB
602
603NOTE: This step is required for all methods of building GDB.
604
605This section lists the components required to build GDB
606from source to target RTEMS.  These files should be
607placed in your @code{archive} directory.  Included are the locations
608of each component as well as any required RTEMS specific patches.
609
610@need 1000
611@subheading @value{GDBUNTAR}
612@example
613    FTP Site:    @value{GDBFTPSITE}
614    Directory:   @value{GDBFTPDIR}
615    File:        @value{GDBTAR}
616    URL:         @uref{@value{GDBFTPURL},,@value{GDBFTPURL}}
617@end example
618
619@need 1000
620@subheading RTEMS Specific Tool Patches and Scripts
621@example
622    FTP Site:    @value{RTEMSFTPSITE}
623    Directory:   @value{RTEMSFTPDIR}/c_tools/source
624@ifset GDBPATCHVERSION
625    File:        @value{GDBRTEMSPATCH}
626    URL:         @uref{ftp://@value{RTEMSFTPSITE}@value{RTEMSFTPDIR}/c_tools/source/@value{GDBRTEMSPATCH},,ftp://@value{RTEMSFTPSITE}@value{RTEMSFTPDIR}/c_tools/source/@value{GDBRTEMSPATCH}}
627@end ifset
628@end example
629
630@c
631@c  Unarchiving the GDB Distribution
632@c
633@subsection Unarchiving the GDB Distribution
634
635Use the following commands to unarchive the GDB distribution:
636
637@example
638cd tools
639tar xzf ../archive/@value{GDBTAR}
640@end example
641
642The directory @value{GDBUNTAR} is created under the tools directory.
643
644@c
645@c  Applying RTEMS Patch to GDB
646@c
647
648@subsection Applying RTEMS Patch to GDB
649
650@ifclear GDBPATCHVERSION
651No RTEMS specific patches are required for @value{GDBVERSION} to
652support @value{RTEMSVERSION}.
653@end ifclear
654
655@ifset GDBPATCHVERSION
656
657Apply the patch using the following command sequence:
658
659@example
660cd tools/@value{GDBUNTAR}
661cat archive/@value{GDBRTEMSPATCH} | \
662    patch -p1
663@end example
664
665If the patch was compressed with the @code{gzip} program, it will
666have a suffix of @code{.gz} and you should use @code{zcat} instead
667of @code{cat} as shown above.  If the patch was compressed with
668the @code{gzip} program, it will have a suffix of @code{.bz2} and
669you should use @code{bzcat} instead of @code{cat} as shown above.
670
671Check to see if any of these patches have been rejected using the following
672sequence:
673
674@example
675cd tools/@value{GDBUNTAR}
676find . -name "*.rej" -print
677@end example
678
679If any files are found with the .rej extension, a patch has been rejected.
680This should not happen with a good patch file.
681
682@end ifset
683
684@c
685@c  Compiling and Installing the GNU Debugger GDB
686@c
687
688@subsection Compiling and Installing the GNU Debugger GDB
689
690There are three methods of building the GNU Debugger:
691
692@itemize @bullet
693@item RPM
694@item direct invocation of @code{configure} and @code{make}
695@end itemize
696
697Direct invocation of @code{configure} and @code{make} provides more control
698and easier recovery from problems when building.
699
700@c
701@c  Using RPM to Build GDB
702@c
703
704@subsubsection Using RPM to Build GDB
705
706This section describes the process of building binutils, gcc, and
707newlib using RPM.  RPM is a packaging format which can be used to
708distribute binary files as well as to capture the procedure and
709source code used to produce those binary files.  Before
710attempting to build any RPM from source, it is necessary to
711ensure that all required source and patches are in the @code{SOURCES}
712directory under the RPM root (probably @code{/usr/src/redhat} or
713@code{/usr/local/src/redhat}) on your machine.  This procedure
714starts by installing the source RPMs as shown in the following
715example:
716
717@example
718rpm -i i386-rtems-gdb-collection-@value{GDBVERSION}-@value{GDBRPMRELEASE}.nosrc.rpm
719@end example
720
721Because RTEMS tool RPMS are called "nosrc" to indicate that one or
722more source files required to produce the RPMs are not present.
723The RTEMS source GDB RPM does not include the large @code{.tar.gz} or
724@code{.tgz} files for GDB.  This is shared by all RTEMS RPMs
725regardless of target CPU and there was no reason
726to duplicate them.  You will have to get the required source
727archive files by hand and place them in the @code{SOURCES} directory
728before attempting to build.  If you forget to do this, RPM is
729smart -- it will tell you what is missing.  To determine what is
730included or referenced by a particular RPM, use a command like the
731following:
732
733@example
734$ rpm -q -l -p i386-rtems-gdb-collection-@value{GDBVERSION}-@value{GDBRPMRELEASE}.nosrc.rpm
735gdb-@value{GDBVERSION}-rtems-@value{GDBPATCHVERSION}.diff
736gdb-@value{GDBVERSION}.tar.gz
737i386-rtems-gdb-@value{GDBVERSION}.spec
738@end example
739
740Notice that there is a patch file (the @code{.diff} file), a source archive
741file (the @code{.tar.gz}), and a file describing the build procedure and
742files produced (the @code{.spec} file).  The @code{.spec} file is placed
743in the @code{SPECS} directory under the RPM root directory.
744
745@c
746@c  Configuring and Building GDB using RPM
747@c
748
749@subheading Configuring and Building GDB using RPM
750
751The following example illustrates the invocation of RPM to build a new,
752locally compiled, binutils binary RPM that matches the installed source
753RPM.  This example assumes that all of the required source is installed.
754
755@example
756cd <RPM_ROOT_DIRECTORY>/SPECS
757rpm -bb i386-rtems-gdb-@value{GDBVERSION}.spec
758@end example
759
760If the build completes successfully, RPMS like the following will
761be generated in a build-host architecture specific subdirectory
762of the RPMS directory under the RPM root directory.
763
764@example
765rtems-base-gdb-@value{GDBVERSION}-@value{GDBRPMRELEASE}.i386.rpm
766i386-rtems-gdb-@value{GDBVERSION}-@value{GDBRPMRELEASE}.i386.rpm
767@end example
768
769NOTE: It may be necessary to remove the build tree in the
770@code{BUILD} directory under the RPM root directory.
771
772@c
773@c Using the GDB configure Script Directly
774@c
775
776@subsubsection Using the GDB configure Script Directly
777
778This section describes how to configure the GNU debugger for
779RTEMS targets using @code{configure} and @code{make} directly.
780The following example illustrates the invocation of @code{configure}
781and @code{make} to build and install @value{GDBUNTAR} for the
782m68k-rtems target:
783
784@example
785mkdir b-gdb
786cd b-gdb
787../@value{GDBUNTAR}/configure --target=m68k-rtems \
788  --prefix=@value{RTEMSPREFIX}
789make all
790make info
791make install
792@end example
793
794For some configurations, it is necessary to specify extra options
795to @code{configure} to enable and configure option components
796such as a processor simulator.  The following is a list of
797configurations for which there are extra options:
798
799@table @b
800@item i960-rtems
801@code{--enable-sim}
802
803@item powerpc-rtems
804@code{--enable-sim --enable-sim-powerpc --enable-sim-timebase --enable-sim-hardware}
805
806@item sparc-rtems
807@code{--enable-sim}
808
809@end table
810
811After @value{GDBUNTAR} is built and installed the
812build directory @code{b-gdb} may be removed.
813
814For more information on the invocation of @code{configure}, please
815refer to the documentation for @value{GDBUNTAR} or
816invoke the @value{GDBUNTAR} @code{configure} command with the
817@code{--help} option.
818
819@c
820@c Common Problems
821@c
822
823@section Common Problems
824
825@subsection Error Message Indicates Invalid Option to Assembler
826
827If a message like this is printed then the new cross compiler
828is most likely using the native assembler instead of the cross
829assembler or vice-versa (native compiler using new cross assembler).
830This can occur for one of the following reasons:
831
832@itemize @bullet
833
834@item Binutils Patch Improperly Applied
835@item Binutils Not Built
836@item Current Directory is in Your PATH
837
838@end itemize
839
840If you are using binutils 2.9.1 or newer with certain older versions of
841gcc, they do not agree on what the name of the newly
842generated cross assembler is.  Older binutils called it @code{as.new}
843which became @code{as.new.exe} under Windows.  This is not a valid
844file name, so @code{as.new} is now called @code{as-new}.  By using the latest
845released tool versions and RTEMS patches, this problem will be avoided.
846
847If binutils did not successfully build the cross assembler, then
848the new cross gcc (@code{xgcc}) used to build the libraries can not
849find it.  Make sure the build of the binutils succeeded.
850
851If you include the current directory in your PATH, then there
852is a chance that the native compiler will accidentally use
853the new cross assembler instead of the native one.  This usually
854indicates that "." is before the standard system directories
855in your PATH.  As a general rule, including "." in your PATH
856is a security risk and should be avoided.  Remove "." from
857your PATH.
858
859NOTE:  In some environments, it may be difficult to remove "."
860completely from your PATH.  In this case, make sure that "."
861is after the system directories containing "as" and "ld".
862
863@subsection Error Messages Indicating Configuration Problems
864
865If you see error messages like the following,
866
867@itemize @bullet
868
869@item cannot configure libiberty
870@item coff-emulation not found
871@item etc.
872
873@end itemize
874
875Then it is likely that one or more of your gnu tools is
876already configured locally in its source tree.  You can check
877for this by searching for the @code{config.status} file
878in the various tool source trees.  The following command
879does this for the binutils source:
880
881@example
882find @value{BINUTILSUNTAR} -name config.status -print
883@end example
884
885The solution for this is to execute the command
886@code{make distclean} in each of the GNU tools
887root source directory.  This should remove all
888generated files including Makefiles.
889
890This situation usually occurs when you have previously
891built the tool source for some non-RTEMS target.  The
892generated configuration specific files are still in
893the source tree and the include path specified during
894the RTEMS build accidentally picks up the previous
895configuration.  The include path used is something like
896this:
897
898@example
899-I../../@value{BINUTILSUNTAR}/gcc -I/@value{BINUTILSUNTAR}/gcc/include -I.
900@end example
901
902Note that the tool source directory is searched before the
903build directory.
904
905This situation can be avoided entirely by never using
906the source tree as the build directory -- even for
907
Note: See TracBrowser for help on using the repository browser.