source: rtems/doc/started/buildc.t @ 4a675a5c

4.104.114.84.95
Last change on this file since 4a675a5c was 4a675a5c, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 13, 2002 at 8:20:29 PM

2002-11-13 Joel Sherrill <joel@…>

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