summaryrefslogtreecommitdiffstats
path: root/doc/started/buildc.t
blob: c0042b0b2588e5ee4ceaf63fcb577cd5ca6b4b94 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
@c
@c  COPYRIGHT (c) 1988-2002.
@c  On-Line Applications Research Corporation (OAR).
@c  All rights reserved.
@c
@c  $Id$
@c

@chapter Building the GNU C/C++ Cross Compiler Toolset

NOTE:  This chapter does @b{NOT} apply if you installed
prebuilt toolset executables for BINUTILS, GCC, NEWLIB,
and GDB.  If you installed prebuilt executables for all
of those, proceed to @ref{Building RTEMS}.  If you require
a GDB with a special configuration to connect to your
target board, then proceed to @ref{Building the GNU Debugger GDB}
for some advice.

This chapter describes the steps required to acquire the
source code for a GNU cross compiler toolset, apply 
any required RTEMS specific patches, compile that 
toolset and install it.

It is recommended that when toolset binaries are available for
your particular host, that they be used.  Prebuilt binaries
are much easier to install.

@c
@c  Building BINUTILS GCC and NEWLIB
@c
@section Building BINUTILS GCC and NEWLIB

NOTE: This step is NOT required if prebuilt executables for
BINUTILS, GCC, and NEWLIB were installed.

This section describes the process of building BINUTILS, GCC, and
NEWLIB using a variety of methods.  Included is information on
obtaining the source code and patches, applying patches, and
building and installing the tools using multiple methods.

@c
@c  Obtain Source and Patches for BINUTILS GCC and NEWLIB
@c

@subsection Obtain Source and Patches for BINUTILS GCC and NEWLIB

NOTE: This step is required for all methods of building BINUTILS,
GCC, and NEWLIB.

This section lists the components required to build BINUTILS, GCC,
and NEWLIB from source to target RTEMS.  These files should be
placed in your @code{archive} directory.  Included are the locations
of each component as well as any required RTEMS specific patches.

@need 1000
@subheading @value{GCC-VERSION}
@example
    FTP Site:    @value{GCC-FTPSITE}
    Directory:   @value{GCC-FTPDIR}
    File:        @value{GCC-TAR}
@ifset use-html
@c    URL:         @uref{Download @value{GCC-VERSION}, ftp://@value{GCC-FTPSITE}@value{GCC-FTPDIR}}
    URL:         ftp://@value{GCC-FTPSITE}@value{GCC-FTPDIR}
@end ifset
@end example

@need 1000
@subheading @value{BINUTILS-VERSION}
@example
    FTP Site:    @value{BINUTILS-FTPSITE}
    Directory:   @value{BINUTILS-FTPDIR}
    File:        @value{BINUTILS-TAR}
@ifset use-html
@c    URL:         @uref{ftp://@value{BINUTILS-FTPSITE}@value{BINUTILS-FTPDIR}/@value{BINUTILS-TAR},Download @value{BINUTILS-VERSION}}
    URL:         ftp://@value{BINUTILS-FTPSITE}@value{BINUTILS-FTPDIR}/@value{BINUTILS-TAR}
@end ifset
@end example

@need 1000
@subheading @value{NEWLIB-VERSION}
@example
    FTP Site:    @value{NEWLIB-FTPSITE}
    Directory:   @value{NEWLIB-FTPDIR}
    File:        @value{NEWLIB-TAR}
@ifset use-html
@c    URL:         @uref{ftp://@value{NEWLIB-FTPSITE}@value{NEWLIB-FTPDIR}/@value{NEWLIB-TAR}, Download @value{NEWLIB-VERSION}}
    URL:         ftp://@value{NEWLIB-FTPSITE}@value{NEWLIB-FTPDIR}/@value{NEWLIB-TAR}
@end ifset
@end example

@need 1000
@subheading RTEMS Specific Tool Patches and Scripts
@example
    FTP Site:    @value{RTEMS-FTPSITE}
    Directory:   @value{RTEMS-FTPDIR}/c_tools/source
@ifset BUILDTOOLS-TAR
    File:        @value{BUILDTOOLS-TAR}
@end ifset
@ifset BINUTILS-RTEMSPATCH
    File:        @value{BINUTILS-RTEMSPATCH}
@end ifset
@ifset NEWLIB-RTEMSPATCH
    File:        @value{NEWLIB-RTEMSPATCH}
@end ifset
@ifset GCC-RTEMSPATCH
    File:        @value{GCC-RTEMSPATCH}
@end ifset
@ifset use-html
@c    URL:         @uref{ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}/c_tools/source,Download RTEMS Patches and Scripts}
    URL:         ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}/c_tools/source
@end ifset
@end example

@c
@c  Unarchiving the Tools
@c
@subsection Unarchiving the Tools

NOTE: This step is required if building BINUTILS, GCC, and NEWLIB
using the procedure described in @ref{Using configure and make}.
It is @b{NOT} required if using the procedure
described in @ref{Using RPM to Build BINUTILS GCC and NEWLIB}.

GNU source distributions are archived using @code{tar} and
compressed using either @code{gzip} or @code{bzip}.  
If compressed with @code{gzip}, the extension @code{.gz} is used.
If compressed with @code{bzip}, the extension @code{.bz2} is used.

While in the @code{tools} directory, unpack the compressed
tar files for BINUTILS, GCC, and NEWLIB using the appropriate
command based upon the compression program used.

@example
cd tools
tar xzf ../archive/TOOLNAME.tar.gz  # for gzip'ed tools
tar xIf ../archive/TOOLNAME.tar.bz2 # for bzip'ed tools
@end example

After the compressed tar files have been unpacked using
the appropriate commands, the following
directories will have been created under tools. 

@itemize @bullet
@item @value{BINUTILS-UNTAR}
@item @value{GCC-UNTAR}
@item @value{NEWLIB-UNTAR}
@end itemize

The tree should look something like the following figure:

@example
@group
/whatever/prefix/you/choose/
        archive/
            @value{GCC-TAR}
            @value{BINUTILS-TAR}
            @value{NEWLIB-TAR}
@ifset GCC-RTEMSPATCH
            @value{GCC-RTEMSPATCH}
@end ifset
@ifset BINUTILS-RTEMSPATCH
            @value{BINUTILS-RTEMSPATCH}
@end ifset
@ifset NEWLIB-RTEMSPATCH
            @value{NEWLIB-RTEMSPATCH}
@end ifset
        tools/
            @value{BINUTILS-UNTAR}/
            @value{GCC-UNTAR}/
            @value{NEWLIB-UNTAR}/
@end group
@end example

@c
@c  Applying RTEMS Patches
@c

@subsection Applying RTEMS Patches

NOTE: This step is required if building BINUTILS, GCC, and NEWLIB
using the procedures described in @ref{Using configure and make}.
It is @b{NOT} required if using the procedure
described in @ref{Using RPM to Build BINUTILS GCC and NEWLIB}.

This section describes the process of applying the RTEMS patches
to GCC, NEWLIB, and BINUTILS.

@c
@c  GCC patches
@c

@subheading Apply RTEMS Patch to GCC

@ifclear GCC-RTEMSPATCH
No RTEMS specific patches are required for @value{GCC-VERSION} to
support @value{RTEMS-VERSION}.
@end ifclear

@ifset GCC-RTEMSPATCH

Apply the patch using the following command sequence:

@example
cd tools/@value{GCC-UNTAR}
cat ../../archive/@value{GCC-RTEMSPATCH} | \
    patch -p1
@end example

If the patch was compressed with the @code{gzip} program, it will
have a suffix of @code{.gz} and you should use @code{zcat} instead
of @code{cat} as shown above.  If the patch was compressed with
the @code{gzip} program, it will have a suffix of @code{.bz2} and
you should use @code{bzcat} instead of @code{cat} as shown above.

Check to see if any of these patches have been rejected using the following
sequence:

@example
cd tools/@value{GCC-UNTAR}
find . -name "*.rej" -print
@end example

If any files are found with the .rej extension, a patch has been rejected.
This should not happen with a good patch file which is properly applied.

@end ifset

@c
@c  BINUTILS patches
@c

@subheading Apply RTEMS Patch to binutils

@ifclear BINUTILS-RTEMSPATCH
No RTEMS specific patches are required for @value{BINUTILS-VERSION} to
support @value{RTEMS-VERSION}.
@end ifclear

@ifset BINUTILS-RTEMSPATCH
Apply the patch using the following command sequence:

@example
cd tools/@value{BINUTILS-UNTAR}
cat ../../archive/@value{BINUTILS-RTEMSPATCH} | \
    patch -p1
@end example

If the patch was compressed with the @code{gzip} program, it will
have a suffix of @code{.gz} and you should use @code{zcat} instead
of @code{cat} as shown above.  If the patch was compressed with
the @code{gzip} program, it will have a suffix of @code{.bz2} and
you should use @code{bzcat} instead of @code{cat} as shown above.

Check to see if any of these patches have been rejected using the following
sequence: 

@example
cd tools/@value{BINUTILS-UNTAR}
find . -name "*.rej" -print
@end example

If any files are found with the .rej extension, a patch has been rejected.
This should not happen with a good patch file which is properly applied. 

@end ifset

@c
@c  Newlib patches
@c

@subheading Apply RTEMS Patch to newlib

@ifclear NEWLIB-RTEMSPATCH
No RTEMS specific patches are required for @value{NEWLIB-VERSION} to
support @value{RTEMS-VERSION}.
@end ifclear

@ifset NEWLIB-RTEMSPATCH

Apply the patch using the following command sequence:

@example
cd tools/@value{NEWLIB-UNTAR}
cat ../../archive/@value{NEWLIB-RTEMSPATCH} | \
    patch -p1
@end example

If the patch was compressed with the @code{gzip} program, it will
have a suffix of @code{.gz} and you should use @code{zcat} instead
of @code{cat} as shown above.  If the patch was compressed with
the @code{gzip} program, it will have a suffix of @code{.bz2} and
you should use @code{bzcat} instead of @code{cat} as shown above.

Check to see if any of these patches have been rejected using the following
sequence: 

@example
cd tools/@value{NEWLIB-UNTAR}
find . -name "*.rej" -print
@end example

If any files are found with the .rej extension, a patch has been rejected.
This should not happen with a good patch file which is properly applied. 

@end ifset


@c
@c  Compiling and Installing BINUTILS GCC and NEWLIB
@c

@subsection Compiling and Installing BINUTILS GCC and NEWLIB

There are two supported methods to compile and install BINUTILS, GCC,
and NEWLIB:

@itemize @bullet
@item RPM
@item direct invocation of @code{configure} and @code{make}
@end itemize

Direct invocation of @code{configure} and @code{make} provides more control
and easier recovery from problems when building.

@c
@c  Using RPM to Build BINUTILS GCC and NEWLIB
@c

@subsubsection Using RPM to Build BINUTILS GCC and NEWLIB

NOTE:  The procedures described in the following sections must
be completed before this step:

@itemize @bullet
@item @ref{Obtain Source and Patches for BINUTILS GCC and NEWLIB}
@end itemize

RPM automatically unarchives the source and applies any needed
patches so you do @b{NOT} have to manually perform the procedures
described @ref{Unarchiving the Tools} and 
@ref{Applying RTEMS Patches}.

This section describes the process of building binutils, gcc, and
newlib using RPM.  RPM is a packaging format which can be used to
distribute binary files as well as to capture the procedure and
source code used to produce those binary files.  Before
attempting to build any RPM from source, it is necessary to
ensure that all required source and patches are in the @code{SOURCES}
directory under the RPM root (probably @code{/usr/src/redhat} or
@code{/usr/local/src/redhat}) on your machine.  This procedure
starts by installing the source RPMs as shown in the following 
example:

@example 
rpm -i i386-rtems-binutils-collection-2.9.5.0.24-1.nosrc.rpm
rpm -i i386-rtems-gcc-newlib-gcc2.95.2newlib1.8.2-7.nosrc.rpm
@end example

Because RTEMS tool RPMS are called "nosrc" to indicate that one or
more source files required to produce the RPMs are not present.  
The RTEMS source RPMs do not include the large @code{.tar.gz} or
@code{.tgz} files for
each component such as BINUTILS, GCC, or NEWLIB.  These are shared
by all RTEMS RPMs regardless of target CPU and there was no reason
to duplicate them.  You will have to get the required source
archive files by hand and place them in the @code{SOURCES} directory
before attempting to build.  If you forget to do this, RPM is
smart -- it will tell you what is missing.  To determine what is
included or referenced by a particular RPM, use a command like the
following:

@example
$ rpm -q -l -p i386-rtems-binutils-collection-2.9.5.0.24-1.nosrc.rpm
binutils-2.9.5.0.24-rtems-20000207.diff
binutils-2.9.5.0.24.tar.gz
i386-rtems-binutils-2.9.5.0.24.spec
@end example

Notice that there is a patch file (the @code{.diff} file), a source archive
file (the @code{.tar.gz}), and a file describing the build procedure and
files produced (the @code{.spec} file).  The @code{.spec} file is placed
in the @code{SPECS} directory under the RPM root directory.

@c
@c  Configuring and Building BINUTILS using RPM
@c

@subheading Configuring and Building BINUTILS using RPM

The following example illustrates the invocation of RPM to build a new,
locally compiled, binutils binary RPM that matches the installed source 
RPM.  This example assumes that all of the required source is installed.

@example
cd <RPM_ROOT_DIRECTORY>/SPECS
rpm -bb i386-rtems-binutils-2.9.5.0.24.spec
@end example

If the build completes successfully, RPMS like the following will
be generated in a build-host architecture specific subdirectory
of the RPMS directory under the RPM root directory.

@example
rtems-base-binutils-2.9.5.0.24-1.i386.rpm
i386-rtems-binutils-2.9.5.0.24-1.i386.rpm
@end example

NOTE: It may be necessary to remove the build tree in the
@code{BUILD} directory under the RPM root directory.

@c
@c  Configuring and Building GCC and NEWLIB using RPM
@c

@subheading Configuring and Building GCC and NEWLIB using RPM

The following example illustrates the invocation of RPM to build a new,
locally compiled, set of GCC and NEWLIB binary RPMs that match the
installed source RPM.  It is also necessary to install the BINUTILS
RPMs and place them in your PATH.  This example assumes that all of
the required source is installed.

@example
cd <RPM_ROOT_DIRECTORY>/RPMS/i386
rpm -i rtems-base-binutils-2.9.5.0.24-1.i386.rpm
rpm -i i386-rtems-binutils-2.9.5.0.24-1.i386.rpm
export PATH=/opt/rtems/bin:$PATH
cd <RPM_ROOT_DIRECTORY>/SPECS
rpm -bb i386-rtems-gcc-2.95.2-newlib-1.8.2.spec
@end example

If the build completes successfully, a set of RPMS like the following will
be generated in a build-host architecture specific subdirectory
of the RPMS directory under the RPM root directory.

@example
rtems-base-gcc-gcc2.95.2newlib1.8.2-7.i386.rpm
rtems-base-chill-gcc2.95.2newlib1.8.2-7.i386.rpm
rtems-base-g77-gcc2.95.2newlib1.8.2-7.i386.rpm
rtems-base-gcj-gcc2.95.2newlib1.8.2-7.i386.rpm
i386-rtems-gcc-gcc2.95.2newlib1.8.2-7.i386.rpm
i386-rtems-chill-gcc2.95.2newlib1.8.2-7.i386.rpm
i386-rtems-g77-gcc2.95.2newlib1.8.2-7.i386.rpm
i386-rtems-gcj-gcc2.95.2newlib1.8.2-7.i386.rpm
i386-rtems-objc-gcc2.95.2newlib1.8.2-7.i386.rpm
@end example

NOTE: Some targets do not support building all languages.

NOTE: It may be necessary to remove the build tree in the
@code{BUILD} directory under the RPM root directory.

@c
@c  Using configure and make
@c

@subsubsection Using configure and make

NOTE:  The procedures described in the following sections must
be completed before this step:

@itemize @bullet
@item @ref{Obtain Source and Patches for BINUTILS GCC and NEWLIB}
@item @ref{Unarchiving the Tools}
@item @ref{Applying RTEMS Patches}
@end itemize

This section describes the process of building binutils, gcc, and
newlib manually using @code{configure} and @code{make} directly.

@c
@c  Configuring and Building BINUTILS
@c

@subheading Configuring and Building BINUTILS

The following example illustrates the invocation of
@code{configure} and @code{make}
to build and install @value{BINUTILS-UNTAR} for the
sparc-rtems target:

@example
mkdir b-binutils
cd b-binutils
../@value{BINUTILS-UNTAR}/configure --target=sparc-rtems \
  --prefix=/opt/rtems
make all
make info
make install
@end example

After @value{BINUTILS-UNTAR} is built and installed the 
build directory @code{b-binutils} may be removed.

For more information on the invocation of @code{configure}, please
refer to the documentation for @value{BINUTILS-UNTAR} or 
invoke the @value{BINUTILS-UNTAR} @code{configure} command with the
@code{--help} option.

NOTE: The shell PATH variable needs to be updated to include the path
the binutils has been installed in. This the prefix used above with
@file{bin} post-fixed.

@example
export PATH=$PATH:/opt/rtems/bin
@end example

Failure to have the binutils in the path will cause the GCC and NEWLIB
build to fail with an error message similar to:

@example
sparc-rtems-ar: command not found
@end example

@c
@c  Configuring and Building GCC and NEWLIB
@c

@subheading Configuring and Building GCC and NEWLIB

Before building @value{GCC-UNTAR} and @value{NEWLIB-UNTAR}, 
@value{BINUTILS-UNTAR} must be installed and the directory
containing those executables must be in your PATH.

The C Library is built as a subordinate component of 
@value{GCC-UNTAR}.  Because of this, the @value{NEWLIB-UNTAR}
directory source must be available inside the @value{GCC-UNTAR}
source tree.  This is normally accomplished using a symbolic
link as shown in this example:

@example
cd @value{GCC-UNTAR}
ln -s ../@value{NEWLIB-UNTAR}/newlib .
@end example

The following example illustrates the invocation of
@code{configure} and @code{make}
to build and install @value{BINUTILS-UNTAR} for the
sparc-rtems target:

@example
mkdir b-gcc
cd b-gcc
../@value{GCC-UNTAR}/configure --target=sparc-rtems \
   --with-gnu-as --with-gnu-ld --with-newlib --verbose \
   --enable-threads --prefix=/opt/rtems
make all
make info
make install
@end example

After @value{GCC-UNTAR} is built and installed the 
build directory @code{b-gcc} may be removed.

For more information on the invocation of @code{configure}, please
refer to the documentation for @value{GCC-UNTAR} or
invoke the @value{GCC-UNTAR} @code{configure} command with the
@code{--help} option.

@c
@c Building the GNU Debugger GDB
@c

@section Building the GNU Debugger GDB

NOTE: This step is NOT required if prebuilt executables for
the GNU Debugger GDB were installed.

The GNU Debugger GDB supports many configurations but requires some
means of communicating between the host computer and target board.
This communication can be via a serial port, Ethernet, BDM, or ROM emulator.
The communication protocol can be the GDB remote protocol or GDB
can talk directly to a ROM monitor.  This setup is target board 
specific.  The following configurations have been
successfully used with RTEMS applications:

@itemize @bullet
@item Sparc Instruction Simulator (SIS)
@item PowerPC Instruction Simulator (PSIM)
@item DINK32
@item BDM with 68360 and MPC860 CPUs
@item Motorola Mxxxbug found on M68xxx VME boards
@item Motorola PPCbug found on PowerPC VME and CompactPCI boards
@end itemize

GDB is currently RTEMS thread/task aware only if you are using the
remote debugging support via Ethernet.  These are configured
using gdb targets of the form CPU-RTEMS.  Note the capital RTEMS.

It is recommended that when toolset binaries are available for
your particular host, that they be used.  Prebuilt binaries
are much easier to install but in the case of gdb may or may
not include support for your particular target board.

@c
@c  Obtain Source and Patches for GDB
@c

@subsection Obtain Source and Patches for GDB

NOTE: This step is required for all methods of building GDB.

This section lists the components required to build GDB
from source to target RTEMS.  These files should be
placed in your @code{archive} directory.  Included are the locations
of each component as well as any required RTEMS specific patches.

@need 1000
@subheading @value{GDB-VERSION}
@example
    FTP Site:    @value{GDB-FTPSITE}
    Directory:   @value{GDB-FTPDIR}
    File:        @value{GDB-TAR}
@ifset use-html
@c    URL:         @uref{Download @value{GDB-VERSION}, ftp://@value{GDB-FTPSITE}@value{GDB-FTPDIR}}
    URL:         ftp://@value{GDB-FTPSITE}@value{GDB-FTPDIR}
@end ifset
@end example

@need 1000
@subheading RTEMS Specific Tool Patches and Scripts
@example
    FTP Site:    @value{RTEMS-FTPSITE}
    Directory:   @value{RTEMS-FTPDIR}/c_tools/source
@ifset BUILDTOOLS-TAR
    File:        @value{BUILDTOOLS-TAR}
@end ifset
@ifset GDB-RTEMSPATCH
    File:        @value{GDB-RTEMSPATCH}
@end ifset
@ifset use-html
@c    URL:         @uref{ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}/c_tools/source,Download RTEMS Patches and Scripts}
    URL:         ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}/c_tools/source
@end ifset
@end example

@c
@c  Unarchiving the GDB Distribution
@c
@subsection Unarchiving the GDB Distribution

Use the following commands to unarchive the GDB distribution:

@example
cd tools
tar xzf ../archive/@value{GDB-TAR}
@end example

The directory @value{GDB-UNTAR} is created under the tools directory.

@c
@c  Applying RTEMS Patch to GDB
@c

@subsection Applying RTEMS Patch to GDB

@ifclear GDB-RTEMSPATCH
No RTEMS specific patches are required for @value{GDB-VERSION} to
support @value{RTEMS-VERSION}.
@end ifclear

@ifset GDB-RTEMSPATCH

Apply the patch using the following command sequence:

@example
cd tools/@value{GDB-UNTAR}
cat archive/@value{GDB-RTEMSPATCH} | \
    patch -p1
@end example

If the patch was compressed with the @code{gzip} program, it will
have a suffix of @code{.gz} and you should use @code{zcat} instead
of @code{cat} as shown above.  If the patch was compressed with
the @code{gzip} program, it will have a suffix of @code{.bz2} and
you should use @code{bzcat} instead of @code{cat} as shown above.

Check to see if any of these patches have been rejected using the following
sequence:

@example
cd tools/@value{GDB-UNTAR}
find . -name "*.rej" -print
@end example

If any files are found with the .rej extension, a patch has been rejected.
This should not happen with a good patch file.

@end ifset

@c
@c  Compiling and Installing the GNU Debugger GDB
@c

@subsection Compiling and Installing the GNU Debugger GDB

There are three methods of building the GNU Debugger:

@itemize @bullet
@item RPM
@item direct invocation of @code{configure} and @code{make}
@end itemize

Direct invocation of @code{configure} and @code{make} provides more control
and easier recovery from problems when building.

@c
@c  Using RPM to Build GDB
@c

@subsubsection Using RPM to Build GDB

This section describes the process of building binutils, gcc, and
newlib using RPM.  RPM is a packaging format which can be used to
distribute binary files as well as to capture the procedure and
source code used to produce those binary files.  Before
attempting to build any RPM from source, it is necessary to
ensure that all required source and patches are in the @code{SOURCES}
directory under the RPM root (probably @code{/usr/src/redhat} or
@code{/usr/local/src/redhat}) on your machine.  This procedure
starts by installing the source RPMs as shown in the following
example:

@example
rpm -i i386-rtems-gdb-collection-4.18-4.nosrc.rpm
@end example

Because RTEMS tool RPMS are called "nosrc" to indicate that one or
more source files required to produce the RPMs are not present.
The RTEMS source GDB RPM does not include the large @code{.tar.gz} or
@code{.tgz} files for GDB.  This is shared by all RTEMS RPMs
regardless of target CPU and there was no reason
to duplicate them.  You will have to get the required source
archive files by hand and place them in the @code{SOURCES} directory
before attempting to build.  If you forget to do this, RPM is
smart -- it will tell you what is missing.  To determine what is
included or referenced by a particular RPM, use a command like the
following:

@example
$ rpm -q -l -p i386-rtems-gdb-collection-4.18-4.nosrc.rpm
gdb-4.18-rtems-20000524.diff
gdb-4.18.tar.gz
i386-rtems-gdb-4.18.spec
@end example

Notice that there is a patch file (the @code{.diff} file), a source archive
file (the @code{.tar.gz}), and a file describing the build procedure and
files produced (the @code{.spec} file).  The @code{.spec} file is placed
in the @code{SPECS} directory under the RPM root directory.

@c
@c  Configuring and Building GDB using RPM
@c

@subheading Configuring and Building GDB using RPM

The following example illustrates the invocation of RPM to build a new,
locally compiled, binutils binary RPM that matches the installed source
RPM.  This example assumes that all of the required source is installed.

@example
cd <RPM_ROOT_DIRECTORY>/SPECS
rpm -bb i386-rtems-gdb-4.18.spec
@end example

If the build completes successfully, RPMS like the following will
be generated in a build-host architecture specific subdirectory
of the RPMS directory under the RPM root directory.

@example
rtems-base-gdb-4.18-4.i386.rpm
i386-rtems-gdb-4.18-4.i386.rpm
@end example

NOTE: It may be necessary to remove the build tree in the
@code{BUILD} directory under the RPM root directory.

@c
@c Using the GDB configure Script Directly
@c 

@subsubsection Using the GDB configure Script Directly

This section describes how to configure the GNU debugger for
RTEMS targets using @code{configure} and @code{make} directly.
The following example illustrates the invocation of @code{configure}
and @code{make} to build and install @value{GDB-UNTAR} for the
m68k-rtems target:

@example
mkdir b-gdb
cd b-gdb
../@value{GDB-UNTAR}/configure --target=m68k-rtems \
  --prefix=/opt/rtems
make all
make info
make install
@end example

For some configurations, it is necessary to specify extra options
to @code{configure} to enable and configure option components
such as a processor simulator.  The following is a list of
configurations for which there are extra options:

@table @b
@item i960-rtems
@code{--enable-sim}

@item powerpc-rtems
@code{--enable-sim --enable-sim-powerpc --enable-sim-timebase --enable-sim-hardware}

@item sparc-rtems
@code{--enable-sim}

@end table

After @value{GDB-UNTAR} is built and installed the
build directory @code{b-gdb} may be removed.

For more information on the invocation of @code{configure}, please
refer to the documentation for @value{GDB-UNTAR} or
invoke the @value{GDB-UNTAR} @code{configure} command with the
@code{--help} option.

@c
@c Common Problems
@c

@section Common Problems

@subsection Error Message Indicates Invalid Option to Assembler

If a message like this is printed then the new cross compiler
is most likely using the native assembler instead of the cross
assembler or vice-versa (native compiler using new cross assembler).
This can occur for one of the following reasons:

@itemize @bullet

@item Binutils Patch Improperly Applied
@item Binutils Not Built
@item Current Directory is in Your PATH

@end itemize

If you are using binutils 2.9.1 or newer with certain older versions of
gcc, they do not agree on what the name of the newly 
generated cross assembler is.  Older binutils called it @code{as.new}
which became @code{as.new.exe} under Windows.  This is not a valid
file name, so @code{as.new} is now called @code{as-new}.  By using the latest
released tool versions and RTEMS patches, this problem will be avoided.

If binutils did not successfully build the cross assembler, then 
the new cross gcc (@code{xgcc}) used to build the libraries can not
find it.  Make sure the build of the binutils succeeded.

If you include the current directory in your PATH, then there
is a chance that the native compiler will accidentally use
the new cross assembler instead of the native one.  This usually
indicates that "." is before the standard system directories
in your PATH.  As a general rule, including "." in your PATH
is a security risk and should be avoided.  Remove "." from
your PATH.

NOTE:  In some environments, it may be difficult to remove "."
completely from your PATH.  In this case, make sure that "."
is after the system directories containing "as" and "ld".

@subsection Error Messages Indicating Configuration Problems

If you see error messages like the following,

@itemize @bullet

@item cannot configure libiberty
@item coff-emulation not found
@item etc.

@end itemize

Then it is likely that one or more of your gnu tools is 
already configured locally in its source tree.  You can check
for this by searching for the @code{config.status} file
in the various tool source trees.  The following command
does this for the binutils source:

@example
find @value{BINUTILS-UNTAR} -name config.status -print
@end example

The solution for this is to execute the command 
@code{make distclean} in each of the GNU tools
root source directory.  This should remove all
generated files including Makefiles.

This situation usually occurs when you have previously
built the tool source for some non-RTEMS target.  The
generated configuration specific files are still in
the source tree and the include path specified during
the RTEMS build accidentally picks up the previous
configuration.  The include path used is something like
this:

@example
-I../../@value{BINUTILS-UNTAR}/gcc -I/@value{BINUTILS-UNTAR}/gcc/include -I.
@end example

Note that the tool source directory is searched before the 
build directory.

This situation can be avoided entirely by never using 
the source tree as the build directory -- even for