source: rtems/doc/started/buildc.t @ 397b1df8

4.104.114.84.9
Last change on this file since 397b1df8 was 397b1df8, checked in by Ralf Corsepius <ralf.corsepius@…>, on Jan 15, 2007 at 9:51:17 AM

Replace nosrc.rpm with src.rpm

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