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

4.104.114.84.95
Last change on this file since da8c85d was da8c85d, checked in by Joel Sherrill <joel.sherrill@…>, on 09/02/05 at 16:25:51

2005-09-02 Joel Sherrill <joel@…>

  • FAQ/basic.texi, FAQ/bsp.texi, FAQ/build45.texi, FAQ/concepts.texi, FAQ/debug.texi, FAQ/endoftime.texi, FAQ/freesw.texi, FAQ/hwdebugaids.texi, FAQ/projects.texi, FAQ/stamp-vti, FAQ/tools.texi, FAQ/version.texi, bsp_howto/rtc.t, started/buildc.t, started/buildrt.t, user/Makefile.am, user/region.t: Fix typos and regenerate.
  • Property mode set to 100644
File size: 30.6 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}/@value{VERSION}
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}/SOURCES,Download RTEMS Patches and Scripts}
107    URL:         ftp://@value{RTEMSFTPSITE}@value{RTEMSFTPDIR}/SOURCES
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 xjf ../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 @value{RTEMSRPMPREFIX}i386-rtems-binutils-collection-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.nosrc.rpm
353rpm -i @value{RTEMSRPMPREFIX}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 @value{RTEMSRPMPREFIX}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 @value{RTEMSRPMPREFIX}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
406@value{RTEMSRPMPREFIX}rtems-base-binutils-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.i386.rpm
407@value{RTEMSRPMPREFIX}i386-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 @value{RTEMSRPMPREFIX}rtems-base-binutils-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.i386.rpm
428rpm -i @value{RTEMSRPMPREFIX}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
439@value{RTEMSRPMPREFIX}rtems-base-gcc-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
440@value{RTEMSRPMPREFIX}rtems-base-g77-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
441@value{RTEMSRPMPREFIX}rtems-base-gcj-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
442@value{RTEMSRPMPREFIX}i386-rtems-gcc-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
443@value{RTEMSRPMPREFIX}i386-rtems-g77-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
444@value{RTEMSRPMPREFIX}i386-rtems-gcj-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
445@value{RTEMSRPMPREFIX}i386-rtems-objc-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
446@end example
447
448NOTE: Some targets do not support building all languages.
449
450NOTE: It may be necessary to remove the build tree in the
451@code{BUILD} directory under the RPM root directory.
452
453@c
454@c  Using configure and make
455@c
456
457@subsubsection Using configure and make
458
459NOTE:  The procedures described in the following sections must
460be completed before this step:
461
462@itemize @bullet
463@item @ref{Obtain Source and Patches for BINUTILS GCC and NEWLIB}
464@item @ref{Unarchiving the Tools}
465@item @ref{Applying RTEMS Patches}
466@end itemize
467
468This section describes the process of building binutils, gcc, and
469newlib manually using @code{configure} and @code{make} directly.
470
471@c
472@c  Configuring and Building BINUTILS
473@c
474
475@subheading Configuring and Building BINUTILS
476
477The following example illustrates the invocation of
478@code{configure} and @code{make}
479to build and install @value{BINUTILSUNTAR} for the
480sparc-rtems target:
481
482@example
483mkdir b-binutils
484cd b-binutils
485../@value{BINUTILSUNTAR}/configure --target=sparc-rtems \
486  --prefix=@value{RTEMSPREFIX}
487make all
488make info
489make install
490@end example
491
492After @value{BINUTILSUNTAR} is built and installed the
493build directory @code{b-binutils} may be removed.
494
495For more information on the invocation of @code{configure}, please
496refer to the documentation for @value{BINUTILSUNTAR} or
497invoke the @value{BINUTILSUNTAR} @code{configure} command with the
498@code{--help} option.
499
500NOTE: The shell PATH variable needs to be updated to include the path
501the binutils user executables have  been installed in.  The directory
502containing the executables is the prefix used above with
503@file{bin} post-fixed.
504
505@example
506export PATH=@value{RTEMSPREFIX}/bin:$@{PATH@}
507@end example
508
509Failure to have the binutils in the path will cause the GCC and NEWLIB
510build to fail with an error message similar to:
511
512@example
513sparc-rtems-ar: command not found
514@end example
515
516@c
517@c  Configuring and Building GCC and NEWLIB
518@c
519
520@subheading Configuring and Building GCC and NEWLIB
521
522Before building @value{GCCUNTAR} and @value{NEWLIBUNTAR},
523@value{BINUTILSUNTAR} must be installed and the directory
524containing those executables must be in your PATH.
525
526The C Library is built as a subordinate component of
527@value{GCCUNTAR}.  Because of this, the @value{NEWLIBUNTAR}
528directory source must be available inside the @value{GCCUNTAR}
529source tree.  This is normally accomplished using a symbolic
530link as shown in this example:
531
532@example
533cd @value{GCCUNTAR}
534ln -s ../@value{NEWLIBUNTAR}/newlib .
535@end example
536
537The following example illustrates the invocation of
538@code{configure} and @code{make}
539to build and install @value{GCCUNTAR} with only
540C and C++ support for the sparc-rtems target:
541
542@example
543mkdir b-gcc
544cd b-gcc
545../@value{GCCUNTAR}/configure --target=sparc-rtems \
546   --with-gnu-as --with-gnu-ld --with-newlib --verbose \
547   --enable-threads --enable-languages="c,c++" \
548   --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 GCC with Ada Support
564@c
565@subheading Building GCC with Ada Support
566
567If you want a GCC toolset that includes support for Ada
568(e.g. GNAT), there are some additional requirements on
569the host environment and additional build steps to perform.
570It is critical that you use the same version of GCC/GNAT as
571the native compiler.  GNAT must be compiled with an Ada compiler
572and when building a GNAT cross-compiler, it should be
573the same version of GNAT itself.
574
575The build procedure is the same until the configure step.
576A GCC toolset with GNAT enabled requires that @code{ada}
577be included in the set of enabled languages.
578The following example illustrates the invocation of
579@code{configure} and @code{make}
580to build and install @value{GCCUNTAR} with only
581C, C++, and Ada support for the sparc-rtems target:
582
583@example
584mkdir b-gcc
585cd @value{GCCUNTAR}/gcc/ada
586touch treeprs.ads [es]info.h nmake.ad[bs]
587cd ../../../b-gcc
588../@value{GCCUNTAR}/configure --target=sparc-rtems \
589   --with-gnu-as --with-gnu-ld --with-newlib --verbose \
590   --enable-threads --enable-languages="c,c++,ada" \
591   --prefix=@value{RTEMSPREFIX}
592make all
593make info
594make -C gcc cross-gnattools
595make -C gcc ada.all.cross
596make -C gcc GNATLIBCFLAGS="USER_SELECTED_CPU_CFLAGS" gnatlib
597make install
598@end example
599
600After @value{GCCUNTAR} is built and installed the
601build directory @code{b-gcc} may be removed.
602
603@c
604@c Building the GNU Debugger GDB
605@c
606
607@section Building the GNU Debugger GDB
608
609NOTE: This step is NOT required if prebuilt executables for
610the GNU Debugger GDB were installed.
611
612The GNU Debugger GDB supports many configurations but requires some
613means of communicating between the host computer and target board.
614This communication can be via a serial port, Ethernet, BDM, or ROM emulator.
615The communication protocol can be the GDB remote protocol or GDB
616can talk directly to a ROM monitor.  This setup is target board
617specific.  The following configurations have been
618successfully used with RTEMS applications:
619
620@itemize @bullet
621@item BDM with ColdFire, 683xx, MPC860 CPUs
622@item Motorola Mxxxbug found on M68xxx VME boards
623@item Motorola PPCbug found on PowerPC VME, CompactPCI, and MTX boards
624@item ARM based Cogent EDP7312
625@item PC's using various Intel and AMD CPUs including i386,
626i486, Pentium and above, and Athlon
627@item PowerPC Instruction Simulator in GDB (PSIM)
628@item MIPS Instruction Simulator in GDB (JMR3904)
629@item Sparc Instruction Simulator in GDB (SIS)
630@item Sparc Instruction Simulator (TSIM)
631@item DINK32 on various PowerPC boards
632@end itemize
633
634GDB is currently RTEMS thread/task aware only if you are using the
635remote debugging support via Ethernet.  These are configured
636using gdb targets of the form CPU-RTEMS.  Note the capital RTEMS.
637
638It is recommended that when toolset binaries are available for
639your particular host, that they be used.  Prebuilt binaries
640are much easier to install but in the case of gdb may or may
641not include support for your particular target board.
642
643@c
644@c  Obtain Source and Patches for GDB
645@c
646
647@subsection Obtain Source and Patches for GDB
648
649NOTE: This step is required for all methods of building GDB.
650
651This section lists the components required to build GDB
652from source to target RTEMS.  These files should be
653placed in your @code{archive} directory.  Included are the locations
654of each component as well as any required RTEMS specific patches.
655
656@need 1000
657@subheading @value{GDBUNTAR}
658@example
659    FTP Site:    @value{GDBFTPSITE}
660    Directory:   @value{GDBFTPDIR}
661    File:        @value{GDBTAR}
662    URL:         @uref{@value{GDBFTPURL},,@value{GDBFTPURL}}
663@end example
664
665@need 1000
666@subheading RTEMS Specific Tool Patches and Scripts
667@example
668    FTP Site:    @value{RTEMSFTPSITE}
669    Directory:   @value{RTEMSFTPDIR}/SOURCES
670@ifset GDBPATCHVERSION
671    File:        @value{GDBRTEMSPATCH}
672    URL:         @uref{ftp://@value{RTEMSFTPSITE}@value{RTEMSFTPDIR}/SOURCES/@value{GDBRTEMSPATCH},,ftp://@value{RTEMSFTPSITE}@value{RTEMSFTPDIR}/SOURCES/@value{GDBRTEMSPATCH}}
673@end ifset
674@end example
675
676@c
677@c  Unarchiving the GDB Distribution
678@c
679@subsection Unarchiving the GDB Distribution
680
681Use the following commands to unarchive the GDB distribution:
682
683@example
684cd tools
685tar xzf ../archive/@value{GDBTAR}
686@end example
687
688The directory @value{GDBUNTAR} is created under the tools directory.
689
690@c
691@c  Applying RTEMS Patch to GDB
692@c
693
694@subsection Applying RTEMS Patch to GDB
695
696@ifclear GDBPATCHVERSION
697No RTEMS specific patches are required for @value{GDBVERSION} to
698support @value{RTEMSVERSION}.
699@end ifclear
700
701@ifset GDBPATCHVERSION
702
703Apply the patch using the following command sequence:
704
705@example
706cd tools/@value{GDBUNTAR}
707cat archive/@value{GDBRTEMSPATCH} | \
708    patch -p1
709@end example
710
711If the patch was compressed with the @code{gzip} program, it will
712have a suffix of @code{.gz} and you should use @code{zcat} instead
713of @code{cat} as shown above.  If the patch was compressed with
714the @code{gzip} program, it will have a suffix of @code{.bz2} and
715you should use @code{bzcat} instead of @code{cat} as shown above.
716
717Check to see if any of these patches have been rejected using the following
718sequence:
719
720@example
721cd tools/@value{GDBUNTAR}
722find . -name "*.rej" -print
723@end example
724
725If any files are found with the .rej extension, a patch has been rejected.
726This should not happen with a good patch file.
727
728@end ifset
729
730@c
731@c  Compiling and Installing the GNU Debugger GDB
732@c
733
734@subsection Compiling and Installing the GNU Debugger GDB
735
736There are three methods of building the GNU Debugger:
737
738@itemize @bullet
739@item RPM
740@item direct invocation of @code{configure} and @code{make}
741@end itemize
742
743Direct invocation of @code{configure} and @code{make} provides more control
744and easier recovery from problems when building.
745
746@c
747@c  Using RPM to Build GDB
748@c
749
750@subsubsection Using RPM to Build GDB
751
752This section describes the process of building binutils, gcc, and
753newlib using RPM.  RPM is a packaging format which can be used to
754distribute binary files as well as to capture the procedure and
755source code used to produce those binary files.  Before
756attempting to build any RPM from source, it is necessary to
757ensure that all required source and patches are in the @code{SOURCES}
758directory under the RPM root (probably @code{/usr/src/redhat} or
759@code{/usr/local/src/redhat}) on your machine.  This procedure
760starts by installing the source RPMs as shown in the following
761example:
762
763@example
764rpm -i @value{RTEMSRPMPREFIX}i386-rtems-gdb-collection-@value{GDBVERSION}-@value{GDBRPMRELEASE}.nosrc.rpm
765@end example
766
767Because RTEMS tool RPMS are called "nosrc" to indicate that one or
768more source files required to produce the RPMs are not present.
769The RTEMS source GDB RPM does not include the large @code{.tar.gz} or
770@code{.tgz} files for GDB.  This is shared by all RTEMS RPMs
771regardless of target CPU and there was no reason
772to duplicate them.  You will have to get the required source
773archive files by hand and place them in the @code{SOURCES} directory
774before attempting to build.  If you forget to do this, RPM is
775smart -- it will tell you what is missing.  To determine what is
776included or referenced by a particular RPM, use a command like the
777following:
778
779@example
780$ rpm -q -l -p @value{RTEMSRPMPREFIX}i386-rtems-gdb-collection-@value{GDBVERSION}-@value{GDBRPMRELEASE}.nosrc.rpm
781gdb-@value{GDBVERSION}-rtems-@value{GDBPATCHVERSION}.diff
782gdb-@value{GDBVERSION}.tar.gz
783i386-rtems-gdb-@value{GDBVERSION}.spec
784@end example
785
786Notice that there is a patch file (the @code{.diff} file), a source archive
787file (the @code{.tar.gz}), and a file describing the build procedure and
788files produced (the @code{.spec} file).  The @code{.spec} file is placed
789in the @code{SPECS} directory under the RPM root directory.
790
791@c
792@c  Configuring and Building GDB using RPM
793@c
794
795@subheading Configuring and Building GDB using RPM
796
797The following example illustrates the invocation of RPM to build a new,
798locally compiled, binutils binary RPM that matches the installed source
799RPM.  This example assumes that all of the required source is installed.
800
801@example
802cd <RPM_ROOT_DIRECTORY>/SPECS
803rpm -bb i386-rtems-gdb-@value{GDBVERSION}.spec
804@end example
805
806If the build completes successfully, RPMS like the following will
807be generated in a build-host architecture specific subdirectory
808of the RPMS directory under the RPM root directory.
809
810@example
811@value{RTEMSRPMPREFIX}rtems-base-gdb-@value{GDBVERSION}-@value{GDBRPMRELEASE}.i386.rpm
812@value{RTEMSRPMPREFIX}i386-rtems-gdb-@value{GDBVERSION}-@value{GDBRPMRELEASE}.i386.rpm
813@end example
814
815NOTE: It may be necessary to remove the build tree in the
816@code{BUILD} directory under the RPM root directory.
817
818@c
819@c Using the GDB configure Script Directly
820@c
821
822@subsubsection Using the GDB configure Script Directly
823
824This section describes how to configure the GNU debugger for
825RTEMS targets using @code{configure} and @code{make} directly.
826The following example illustrates the invocation of @code{configure}
827and @code{make} to build and install @value{GDBUNTAR} for the
828m68k-rtems target:
829
830@example
831mkdir b-gdb
832cd b-gdb
833../@value{GDBUNTAR}/configure --target=m68k-rtems \
834  --prefix=@value{RTEMSPREFIX}
835make all
836make info
837make install
838@end example
839
840For some configurations, it is necessary to specify extra options
841to @code{configure} to enable and configure option components
842such as a processor simulator.  The following is a list of
843configurations for which there are extra options:
844
845@table @b
846@item powerpc-rtems
847@code{--enable-sim --enable-sim-powerpc --enable-sim-timebase --enable-sim-hardware}
848
849@item sparc-rtems
850@code{--enable-sim}
851
852@end table
853
854After @value{GDBUNTAR} is built and installed the
855build directory @code{b-gdb} may be removed.
856
857For more information on the invocation of @code{configure}, please
858refer to the documentation for @value{GDBUNTAR} or
859invoke the @value{GDBUNTAR} @code{configure} command with the
860@code{--help} option.
861
862@c
863@c Common Problems
864@c
865
866@section Common Problems
867
868@subsection Error Message Indicates Invalid Option to Assembler
869
870If a message like this is printed then the new cross compiler
871is most likely using the native assembler instead of the cross
872assembler or vice-versa (native compiler using new cross assembler).
873This can occur for one of the following reasons:
874
875@itemize @bullet
876
877@item Binutils Patch Improperly Applied
878@item Binutils Not Built
879@item Current Directory is in Your PATH
880
881@end itemize
882
883If you are using binutils 2.9.1 or newer with certain older versions of
884gcc, they do not agree on what the name of the newly
885generated cross assembler is.  Older binutils called it @code{as.new}
886which became @code{as.new.exe} under Windows.  This is not a valid
887file name, so @code{as.new} is now called @code{as-new}.  By using the latest
888released tool versions and RTEMS patches, this problem will be avoided.
889
890If binutils did not successfully build the cross assembler, then
891the new cross gcc (@code{xgcc}) used to build the libraries can not
892find it.  Make sure the build of the binutils succeeded.
893
894If you include the current directory in your PATH, then there
895is a chance that the native compiler will accidentally use
896the new cross assembler instead of the native one.  This usually
897indicates that "." is before the standard system directories
898in your PATH.  As a general rule, including "." in your PATH
899is a security risk and should be avoided.  Remove "." from
900your PATH.
901
902NOTE:  In some environments, it may be difficult to remove "."
903completely from your PATH.  In this case, make sure that "."
904is after the system directories containing "as" and "ld".
905
906@subsection Error Messages Indicating Configuration Problems
907
908If you see error messages like the following,
909
910@itemize @bullet
911
912@item cannot configure libiberty
913@item coff-emulation not found
914@item etc.
915
916@end itemize
917
918Then it is likely that one or more of your gnu tools is
919already configured locally in its source tree.  You can check
920for this by searching for the @code{config.status} file
921in the various tool source trees.  The following command
922does this for the binutils source:
923
924@example
925find @value{BINUTILSUNTAR} -name config.status -print
926@end example
927
928The solution for this is to execute the command
929@code{make distclean} in each of the GNU tools
930root source directory.  This should remove all
931generated files including Makefiles.
932
933This situation usually occurs when you have previously
934built the tool source for some non-RTEMS target.  The
935generated configuration specific files are still in
936the source tree and the include path specified during
937the RTEMS build accidentally picks up the previous
938configuration.  The include path used is something like
939this:
940
941@example
942-I../../@value{BINUTILSUNTAR}/gcc -I/@value{BINUTILSUNTAR}/gcc/include -I.
943@end example
944
945Note that the tool source directory is searched before the
946build directory.
947
948This situation can be avoided entirely by never using
949the source tree as the build directory -- even for
950
Note: See TracBrowser for help on using the repository browser.