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

4.104.114.84.95
Last change on this file since b2e3795 was b2e3795, checked in by Joel Sherrill <joel.sherrill@…>, on 06/28/02 at 19:16:49

2001-06-28 Joel Sherrill <joel@…>

  • buildc.t, gdb.t: Per PR54, updated to reflect multiple compression schemes including bzip2.
  • Property mode set to 100644
File size: 33.6 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2002.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Building the GNU 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 procedures described in @ref{Using configure and make}
119or @ref{Using the bit Script}.  It 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 @ifset use-html
173@c @html
174@c <IMG SRC="bit_c.jpg" WIDTH=816 HEIGHT=267 ALT="Directory Organization">
175@c @end html
176@c @end ifset
177
178@c
179@c  Applying RTEMS Patches
180@c
181
182@subsection Applying RTEMS Patches
183
184NOTE: This step is required if building BINUTILS, GCC, and NEWLIB
185using the procedures described in @ref{Using configure and make}
186or @ref{Using the bit Script}.  It is @b{NOT} required if using the procedure
187described in @ref{Using RPM to Build BINUTILS GCC and NEWLIB}.
188
189This section describes the process of applying the RTEMS patches
190to GCC, NEWLIB, and BINUTILS.
191
192@c
193@c  GCC patches
194@c
195
196@subheading Apply RTEMS Patch to GCC
197
198@ifclear GCC-RTEMSPATCH
199No RTEMS specific patches are required for @value{GCC-VERSION} to
200support @value{RTEMS-VERSION}.
201@end ifclear
202
203@ifset GCC-RTEMSPATCH
204
205Apply the patch using the following command sequence:
206
207@example
208cd tools/@value{GCC-UNTAR}
209zcat ../../archive/@value{GCC-RTEMSPATCH} | \
210    patch -p1
211@end example
212
213Check to see if any of these patches have been rejected using the following
214sequence:
215
216@example
217cd tools/@value{GCC-UNTAR}
218find . -name "*.rej" -print
219@end example
220
221If any files are found with the .rej extension, a patch has been rejected.
222This should not happen with a good patch file which is properly applied.
223
224@end ifset
225
226@c
227@c  BINUTILS patches
228@c
229
230@subheading Apply RTEMS Patch to binutils
231
232@ifclear BINUTILS-RTEMSPATCH
233No RTEMS specific patches are required for @value{BINUTILS-VERSION} to
234support @value{RTEMS-VERSION}.
235@end ifclear
236
237@ifset BINUTILS-RTEMSPATCH
238Apply the patch using the following command sequence:
239
240@example
241cd tools/@value{BINUTILS-UNTAR}
242zcat ../../archive/@value{BINUTILS-RTEMSPATCH} | \
243    patch -p1
244@end example
245
246Check to see if any of these patches have been rejected using the following
247sequence:
248
249@example
250cd tools/@value{BINUTILS-UNTAR}
251find . -name "*.rej" -print
252@end example
253
254If any files are found with the .rej extension, a patch has been rejected.
255This should not happen with a good patch file which is properly applied.
256
257@end ifset
258
259@c
260@c  Newlib patches
261@c
262
263@subheading Apply RTEMS Patch to newlib
264
265@ifclear NEWLIB-RTEMSPATCH
266No RTEMS specific patches are required for @value{NEWLIB-VERSION} to
267support @value{RTEMS-VERSION}.
268@end ifclear
269
270@ifset NEWLIB-RTEMSPATCH
271
272Apply the patch using the following command sequence:
273
274@example
275cd tools/@value{NEWLIB-UNTAR}
276zcat ../../archive/@value{NEWLIB-RTEMSPATCH} | \
277    patch -p1
278@end example
279
280Check to see if any of these patches have been rejected using the following
281sequence:
282
283@example
284cd tools/@value{NEWLIB-UNTAR}
285find . -name "*.rej" -print
286@end example
287
288If any files are found with the .rej extension, a patch has been rejected.
289This should not happen with a good patch file which is properly applied.
290
291@end ifset
292
293
294@c
295@c  Compiling and Installing BINUTILS GCC and NEWLIB
296@c
297
298@subsection Compiling and Installing BINUTILS GCC and NEWLIB
299
300There are three methods to compile and install BINUTILS, GCC, and NEWLIB:
301
302@itemize @bullet
303@item RPM
304@item direct invocation of @code{configure} and @code{make}
305@item using the @code{bit} script
306@end itemize
307
308Direct invocation of @code{configure} and @code{make} provides more control
309and easier recovery from problems when building.
310
311@c
312@c  Using RPM to Build BINUTILS GCC and NEWLIB
313@c
314
315@subsubsection Using RPM to Build BINUTILS GCC and NEWLIB
316
317NOTE:  The procedures described in the following sections must
318be completed before this step:
319
320@itemize @bullet
321@item @ref{Obtain Source and Patches for BINUTILS GCC and NEWLIB}
322@end itemize
323
324RPM automatically unarchives the source and applies any needed
325patches so you do @b{NOT} have to manually perform the procedures
326described @ref{Unarchiving the Tools} and
327@ref{Applying RTEMS Patches}.
328
329This section describes the process of building binutils, gcc, and
330newlib using RPM.  RPM is a packaging format which can be used to
331distribute binary files as well as to capture the procedure and
332source code used to produce those binary files.  Before
333attempting to build any RPM from source, it is necessary to
334ensure that all required source and patches are in the @code{SOURCES}
335directory under the RPM root (probably @code{/usr/src/redhat} or
336@code{/usr/local/src/redhat}) on your machine.  This procedure
337starts by installing the source RPMs as shown in the following
338example:
339
340@example
341rpm -i i386-rtems-binutils-collection-2.9.5.0.24-1.nosrc.rpm
342rpm -i i386-rtems-gcc-newlib-gcc2.95.2newlib1.8.2-7.nosrc.rpm
343@end example
344
345Because RTEMS tool RPMS are called "nosrc" to indicate that one or
346more source files required to produce the RPMs are not present. 
347The RTEMS source RPMs do not include the large @code{.tar.gz} or
348@code{.tgz} files for
349each component such as BINUTILS, GCC, or NEWLIB.  These are shared
350by all RTEMS RPMs regardless of target CPU and there was no reason
351to duplicate them.  You will have to get the required source
352archive files by hand and place them in the @code{SOURCES} directory
353before attempting to build.  If you forget to do this, RPM is
354smart -- it will tell you what is missing.  To determine what is
355included or referenced by a particular RPM, use a command like the
356following:
357
358@example
359$ rpm -q -l -p i386-rtems-binutils-collection-2.9.5.0.24-1.nosrc.rpm
360binutils-2.9.5.0.24-rtems-20000207.diff
361binutils-2.9.5.0.24.tar.gz
362i386-rtems-binutils-2.9.5.0.24.spec
363@end example
364
365Notice that there is a patch file (the @code{.diff} file), a source archive
366file (the @code{.tar.gz}), and a file describing the build procedure and
367files produced (the @code{.spec} file).  The @code{.spec} file is placed
368in the @code{SPECS} directory under the RPM root directory.
369
370@c
371@c  Configuring and Building BINUTILS using RPM
372@c
373
374@subheading Configuring and Building BINUTILS using RPM
375
376The following example illustrates the invocation of RPM to build a new,
377locally compiled, binutils binary RPM that matches the installed source
378RPM.  This example assumes that all of the required source is installed.
379
380@example
381cd <RPM_ROOT_DIRECTORY>/SPECS
382rpm -bb i386-rtems-binutils-2.9.5.0.24.spec
383@end example
384
385If the build completes successfully, RPMS like the following will
386be generated in a build-host architecture specific subdirectory
387of the RPMS directory under the RPM root directory.
388
389@example
390rtems-base-binutils-2.9.5.0.24-1.i386.rpm
391i386-rtems-binutils-2.9.5.0.24-1.i386.rpm
392@end example
393
394NOTE: It may be necessary to remove the build tree in the
395@code{BUILD} directory under the RPM root directory.
396
397@c
398@c  Configuring and Building GCC and NEWLIB using RPM
399@c
400
401@subheading Configuring and Building GCC and NEWLIB using RPM
402
403The following example illustrates the invocation of RPM to build a new,
404locally compiled, set of GCC and NEWLIB binary RPMs that match the
405installed source RPM.  It is also necessary to install the BINUTILS
406RPMs and place them in your PATH.  This example assumes that all of
407the required source is installed.
408
409@example
410cd <RPM_ROOT_DIRECTORY>/RPMS/i386
411rpm -i rtems-base-binutils-2.9.5.0.24-1.i386.rpm
412rpm -i i386-rtems-binutils-2.9.5.0.24-1.i386.rpm
413export PATH=/opt/rtems/bin:$PATH
414cd <RPM_ROOT_DIRECTORY>/SPECS
415rpm -bb i386-rtems-gcc-2.95.2-newlib-1.8.2.spec
416@end example
417
418If the build completes successfully, a set of RPMS like the following will
419be generated in a build-host architecture specific subdirectory
420of the RPMS directory under the RPM root directory.
421
422@example
423rtems-base-gcc-gcc2.95.2newlib1.8.2-7.i386.rpm
424rtems-base-chill-gcc2.95.2newlib1.8.2-7.i386.rpm
425rtems-base-g77-gcc2.95.2newlib1.8.2-7.i386.rpm
426rtems-base-gcj-gcc2.95.2newlib1.8.2-7.i386.rpm
427i386-rtems-gcc-gcc2.95.2newlib1.8.2-7.i386.rpm
428i386-rtems-chill-gcc2.95.2newlib1.8.2-7.i386.rpm
429i386-rtems-g77-gcc2.95.2newlib1.8.2-7.i386.rpm
430i386-rtems-gcj-gcc2.95.2newlib1.8.2-7.i386.rpm
431i386-rtems-objc-gcc2.95.2newlib1.8.2-7.i386.rpm
432@end example
433
434NOTE: Some targets do not support building all languages.
435
436NOTE: It may be necessary to remove the build tree in the
437@code{BUILD} directory under the RPM root directory.
438
439@c
440@c  Using configure and make
441@c
442
443@subsubsection Using configure and make
444
445NOTE:  The procedures described in the following sections must
446be completed before this step:
447
448@itemize @bullet
449@item @ref{Obtain Source and Patches for BINUTILS GCC and NEWLIB}
450@item @ref{Unarchiving the Tools}
451@item @ref{Applying RTEMS Patches}
452@end itemize
453
454This section describes the process of building binutils, gcc, and
455newlib manually using @code{configure} and @code{make} directly.
456
457@c
458@c  Configuring and Building BINUTILS
459@c
460
461@subheading Configuring and Building BINUTILS
462
463The following example illustrates the invocation of
464@code{configure} and @code{make}
465to build and install @value{BINUTILS-UNTAR} for the
466sparc-rtems target:
467
468@example
469mkdir b-binutils
470cd b-binutils
471../@value{BINUTILS-UNTAR}/configure --target=sparc-rtems \
472  --prefix=/opt/rtems
473make all
474make info
475make install
476@end example
477
478After @value{BINUTILS-UNTAR} is built and installed the
479build directory @code{b-binutils} may be removed.
480
481For more information on the invocation of @code{configure}, please
482refer to the documentation for @value{BINUTILS-UNTAR} or
483invoke the @value{BINUTILS-UNTAR} @code{configure} command with the
484@code{--help} option.
485
486NOTE: The shell PATH variable needs to be updated to include the path
487the binutils has been installed in. This the prefix used above with
488@file{bin} post-fixed.
489
490@example
491export PATH=$PATH:/opt/rtems/bin
492@end example
493
494Failure to have the binutils in the path will cause the GCC and NEWLIB
495build to fail with an error message similar to:
496
497@example
498sparc-rtems-ar: command not found
499@end example
500
501@c
502@c  Configuring and Building GCC and NEWLIB
503@c
504
505@subheading Configuring and Building GCC and NEWLIB
506
507Before building @value{GCC-UNTAR} and @value{NEWLIB-UNTAR},
508@value{BINUTILS-UNTAR} must be installed and the directory
509containing those executables must be in your PATH.
510
511The C Library is built as a subordinate component of
512@value{GCC-UNTAR}.  Because of this, the @value{NEWLIB-UNTAR}
513directory source must be available inside the @value{GCC-UNTAR}
514source tree.  This is normally accomplished using a symbolic
515link as shown in this example:
516
517@example
518cd @value{GCC-UNTAR}
519ln -s ../@value{NEWLIB-UNTAR}/newlib .
520@end example
521
522The following example illustrates the invocation of
523@code{configure} and @code{make}
524to build and install @value{BINUTILS-UNTAR} for the
525sparc-rtems target:
526
527@example
528mkdir b-gcc
529cd b-gcc
530../@value{GCC-UNTAR}/configure --target=sparc-rtems \
531   --with-gnu-as --with-gnu-ld --with-newlib --verbose \
532   --enable-threads --prefix=/opt/rtems
533make all
534make info
535make install
536@end example
537
538After @value{GCC-UNTAR} is built and installed the
539build directory @code{b-gcc} may be removed.
540
541For more information on the invocation of @code{configure}, please
542refer to the documentation for @value{GCC-UNTAR} or
543invoke the @value{GCC-UNTAR} @code{configure} command with the
544@code{--help} option.
545
546@c
547@c  Using the bit Script
548@c
549
550@subsubsection Using the bit Script
551
552NOTE:  The procedures described in the following sections must
553be completed before this step:
554
555@itemize @bullet
556@item @ref{Obtain Source and Patches for BINUTILS GCC and NEWLIB}
557@item @ref{Unarchiving the Tools}
558@item @ref{Applying RTEMS Patches}
559@end itemize
560
561This section describes the process of building using the
562@code{bit} script.  This script hides many of the details
563of building the tools but can be a hindrance if you
564encounter problems building the tools.
565
566@c
567@c  Unarchiving the Build Scripts
568@c
569
570@subheading Unarchiving the Build Scripts
571
572While in the @code{tools} directory, unpack the compressed
573tar file for the build tools using the following command sequence:
574
575@example
576cd tools
577tar xzf ../archive/@value{BUILDTOOLS-TAR}
578@end example
579
580After the compressed tar file @value{BUILDTOOLS-TAR} has been unpacked, there
581will be a set of scripts in the tools directory along with
582any source code you have previously unarchived.
583These scripts are intended to aid in building the tools and RTEMS.
584These scripts may be used to automate the tool building process and hide
585the invocation of @code{configure} and @code{make} from you.  They are:
586
587@itemize @bullet
588@item bit
589@item bit_gdb
590@item bit_rtems
591@item common.sh
592@item user.cfg
593@end itemize
594
595If @code{bit} is executed later in this process,
596it will automatically create this subdirectory:
597
598@itemize @bullet
599@item build-$@{CPU@}-tools
600@end itemize
601
602At this point, the tree should look something like the following figure:
603
604@example
605@group
606/whatever/prefix/you/choose/
607        archive/
608            @value{GCC-TAR}
609            @value{BINUTILS-TAR}
610            @value{NEWLIB-TAR}
611            @value{BUILDTOOLS-TAR}
612@ifset GCC-RTEMSPATCH
613            @value{GCC-RTEMSPATCH}
614@end ifset
615@ifset BINUTILS-RTEMSPATCH
616            @value{BINUTILS-RTEMSPATCH}
617@end ifset
618@ifset NEWLIB-RTEMSPATCH
619            @value{NEWLIB-RTEMSPATCH}
620@end ifset
621        tools/
622            @value{BINUTILS-UNTAR}/
623            @value{GCC-UNTAR}/
624            @value{NEWLIB-UNTAR}/
625            bit
626            bit_gdb
627            bit_rtems
628            common.sh
629            user.cfg
630@end group
631@end example
632
633@c @ifset use-html
634@c @html
635@c <IMG SRC="bit_c.jpg" WIDTH=816 HEIGHT=267 ALT="Directory Organization">
636@c @end html
637@c @end ifset
638
639@c
640@c  Localizing the Configuration
641@c
642
643@subheading Localizing the Configuration
644
645Edit the @code{user.cfg} file to alter the settings of various
646variables which are used to tailor the build process.
647Each of the variables set in @code{user.cfg} may be modified
648as described below:
649
650@table @code
651@item INSTALL_POINT
652is the location where you wish the GNU C/C++ cross compilation tools for
653RTEMS to be built. It is recommended that the directory chosen to receive
654these tools be named so that it is clear from which gcc distribution it
655was generated and for which target system the tools are to produce code for.
656
657@b{WARNING}: The @code{INSTALL_POINT} should not be a subdirectory
658under the build directory.  The build directory will be removed
659automatically upon successful completion of the build procedure.
660
661@item BINUTILS
662is the directory under tools that contains @value{BINUTILS-UNTAR}.
663For example:
664
665@example
666BINUTILS=@value{BINUTILS-UNTAR}
667@end example
668
669@item GCC
670is the directory under tools that contains @value{GCC-UNTAR}.
671For example,
672
673@example
674GCC=@value{GCC-UNTAR}
675@end example
676
677@item GDB
678is the directory under tools that contains @value{GDB-UNTAR}.
679For example,
680
681@example
682GDB=@value{GDB-UNTAR}
683@end example
684
685@item NEWLIB
686is the directory under tools that contains @value{NEWLIB-UNTAR}.
687For example:
688
689@example
690NEWLIB=@value{NEWLIB-UNTAR}
691@end example
692
693@item BUILD_DOCS
694is set to "yes" if you want to install documentation.  This requires
695that tools supporting documentation production be installed.  This
696currently is limited to the GNU texinfo package.
697For example:
698
699@example
700BUILD_DOCS=yes
701@end example
702
703@item BUILD_OTHER_LANGUAGES
704is set to "yes" if you want to build languages other than C and C++.  At
705the current time, the set of alternative languages includes Java, Fortran,
706and Objective-C.  These alternative languages do not always build cross.
707Hence this option defaults to "no".
708
709For example:
710
711@example
712BUILD_OTHER_LANGUAGES=yes
713@end example
714
715@b{NOTE:} Based upon the version of the compiler being used, it may not
716be possible to build languages other than C and C++ cross.  In many cases,
717the language run-time support libraries are not "multilib'ed".  Thus the
718executable code in these libraries will be for the default compiler settings
719and not necessarily be correct for your CPU model.
720
721@end table
722
723The other variables in @code{user.cfg} are RTEMS specific and are
724not technically required to be set unless you build RTEMS using
725the @code{bit_rtems} script as described in
726@ref{Using the bit_rtems Script}.  They are described in detail
727in that section.
728
729@c
730@c   Running the bit Script
731@c
732@subheading Running the bit Script
733
734After the @code{bit} script has been modified to reflect the
735local installation, the modified @code{bit} script is run
736using the following sequence:
737
738@example
739cd tools
740./bit <target configuration>
741@end example
742
743Where <target configuration> is one of the following:
744
745@itemize @bullet
746@item hppa1.1
747@item i386
748@item i386-coff
749@item i386-elf
750@item i960
751@item m68k
752@item m68k-coff
753@item mips64orion
754@item powerpc
755@item sh
756@item sh-elf
757@item sparc
758@end itemize
759
760The build process can take a while to complete.  Many users find it
761handy to run the build process in the background, capture the output
762in a file, and monitor the output.  This can be done as follows:
763
764@example
765./bit <target configuration> >bit.log 2>&1 &
766tail -f bit.log
767@end example
768
769If no errors are encountered, the @code{bit} script will conclude by
770printing messages similar to the following:
771
772@example
773
774The build-i386-tools subdirectory may now be removed.
775
776Started:  Fri Apr 10 10:14:07 CDT 1998
777Finished: Fri Apr 10 12:01:33 CDT 1998
778@end example
779
780If the @code{bit} script successfully completes, then the
781GNU C/C++ cross compilation tools are installed.
782
783If the @code{bit} script does not successfully complete, then investigation
784will be required to determine the source of the error.
785
786@c -------------------
787
788@c
789@c Building the GNU Debugger GDB
790@c
791
792@section Building the GNU Debugger GDB
793
794NOTE: This step is NOT required if prebuilt executables for
795the GNU Debugger GDB were installed.
796
797The GNU Debugger GDB supports many configurations but requires some
798means of communicating between the host computer and target board.
799This communication can be via a serial port, Ethernet, BDM, or ROM emulator.
800The communication protocol can be the GDB remote protocol or GDB
801can talk directly to a ROM monitor.  This setup is target board
802specific.  The following configurations have been
803successfully used with RTEMS applications:
804
805@itemize @bullet
806@item Sparc Instruction Simulator (SIS)
807@item PowerPC Instruction Simulator (PSIM)
808@item DINK32
809@item BDM with 68360 and MPC860 CPUs
810@item Motorola Mxxxbug found on M68xxx VME boards
811@item Motorola PPCbug found on PowerPC VME and CompactPCI boards
812@end itemize
813
814GDB is currently RTEMS thread/task aware only if you are using the
815remote debugging support via Ethernet.  These are configured
816using gdb targets of the form CPU-RTEMS.  Note the capital RTEMS.
817
818It is recommended that when toolset binaries are available for
819your particular host, that they be used.  Prebuilt binaries
820are much easier to install but in the case of gdb may or may
821not include support for your particular target board.
822
823@c
824@c  Obtain Source and Patches for GDB
825@c
826
827@subsection Obtain Source and Patches for GDB
828
829NOTE: This step is required for all methods of building GDB.
830
831This section lists the components required to build GDB
832from source to target RTEMS.  These files should be
833placed in your @code{archive} directory.  Included are the locations
834of each component as well as any required RTEMS specific patches.
835
836@need 1000
837@subheading @value{GDB-VERSION}
838@example
839    FTP Site:    @value{GDB-FTPSITE}
840    Directory:   @value{GDB-FTPDIR}
841    File:        @value{GDB-TAR}
842@ifset use-html
843@c    URL:         @uref{Download @value{GDB-VERSION}, ftp://@value{GDB-FTPSITE}@value{GDB-FTPDIR}}
844    URL:         ftp://@value{GDB-FTPSITE}@value{GDB-FTPDIR}
845@end ifset
846@end example
847
848@need 1000
849@subheading RTEMS Specific Tool Patches and Scripts
850@example
851    FTP Site:    @value{RTEMS-FTPSITE}
852    Directory:   @value{RTEMS-FTPDIR}/c_tools/source
853    File:        @value{BUILDTOOLS-TAR}
854@ifset GDB-RTEMSPATCH
855    File:        @value{GDB-RTEMSPATCH}
856@end ifset
857@ifset use-html
858@c    URL:         @uref{ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}/c_tools/source,Download RTEMS Patches and Scripts}
859    URL:         ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}/c_tools/source
860@end ifset
861@end example
862
863@c
864@c  Unarchiving the GDB Distribution
865@c
866@subsection Unarchiving the GDB Distribution
867
868Use the following commands to unarchive the GDB distribution:
869
870@example
871cd tools
872tar xzf ../archive/@value{GDB-TAR}
873@end example
874
875The directory @value{GDB-UNTAR} is created under the tools directory.
876
877@c
878@c  Applying RTEMS Patch to GDB
879@c
880
881@subsection Applying RTEMS Patch to GDB
882
883@ifclear GDB-RTEMSPATCH
884No RTEMS specific patches are required for @value{GDB-VERSION} to
885support @value{RTEMS-VERSION}.
886@end ifclear
887
888@ifset GDB-RTEMSPATCH
889
890Apply the patch using the following command sequence:
891
892@example
893cd tools/@value{GDB-UNTAR}
894zcat archive/@value{GDB-RTEMSPATCH} | \
895    patch -p1
896@end example
897
898Check to see if any of these patches have been rejected using the following
899sequence:
900
901@example
902cd tools/@value{GDB-UNTAR}
903find . -name "*.rej" -print
904@end example
905
906If any files are found with the .rej extension, a patch has been rejected.
907This should not happen with a good patch file.
908
909@end ifset
910
911@c
912@c  Compiling and Installing the GNU Debugger GDB
913@c
914
915@subsection Compiling and Installing the GNU Debugger GDB
916
917There are three methods of building the GNU Debugger:
918
919@itemize @bullet
920@item RPM
921@item direct invocation of @code{configure} and @code{make}
922@item using the @code{bit_gdb} script
923@end itemize
924
925Direct invocation of @code{configure} and @code{make} provides more control
926and easier recovery from problems when building.
927
928@c
929@c  Using RPM to Build GDB
930@c
931
932@subsubsection Using RPM to Build GDB
933
934This section describes the process of building binutils, gcc, and
935newlib using RPM.  RPM is a packaging format which can be used to
936distribute binary files as well as to capture the procedure and
937source code used to produce those binary files.  Before
938attempting to build any RPM from source, it is necessary to
939ensure that all required source and patches are in the @code{SOURCES}
940directory under the RPM root (probably @code{/usr/src/redhat} or
941@code{/usr/local/src/redhat}) on your machine.  This procedure
942starts by installing the source RPMs as shown in the following
943example:
944
945@example
946rpm -i i386-rtems-gdb-collection-4.18-4.nosrc.rpm
947@end example
948
949Because RTEMS tool RPMS are called "nosrc" to indicate that one or
950more source files required to produce the RPMs are not present.
951The RTEMS source GDB RPM does not include the large @code{.tar.gz} or
952@code{.tgz} files for GDB.  This is shared by all RTEMS RPMs
953regardless of target CPU and there was no reason
954to duplicate them.  You will have to get the required source
955archive files by hand and place them in the @code{SOURCES} directory
956before attempting to build.  If you forget to do this, RPM is
957smart -- it will tell you what is missing.  To determine what is
958included or referenced by a particular RPM, use a command like the
959following:
960
961@example
962$ rpm -q -l -p i386-rtems-gdb-collection-4.18-4.nosrc.rpm
963gdb-4.18-rtems-20000524.diff
964gdb-4.18.tar.gz
965i386-rtems-gdb-4.18.spec
966@end example
967
968Notice that there is a patch file (the @code{.diff} file), a source archive
969file (the @code{.tar.gz}), and a file describing the build procedure and
970files produced (the @code{.spec} file).  The @code{.spec} file is placed
971in the @code{SPECS} directory under the RPM root directory.
972
973@c
974@c  Configuring and Building GDB using RPM
975@c
976
977@subheading Configuring and Building GDB using RPM
978
979The following example illustrates the invocation of RPM to build a new,
980locally compiled, binutils binary RPM that matches the installed source
981RPM.  This example assumes that all of the required source is installed.
982
983@example
984cd <RPM_ROOT_DIRECTORY>/SPECS
985rpm -bb i386-rtems-gdb-4.18.spec
986@end example
987
988If the build completes successfully, RPMS like the following will
989be generated in a build-host architecture specific subdirectory
990of the RPMS directory under the RPM root directory.
991
992@example
993rtems-base-gdb-4.18-4.i386.rpm
994i386-rtems-gdb-4.18-4.i386.rpm
995@end example
996
997NOTE: It may be necessary to remove the build tree in the
998@code{BUILD} directory under the RPM root directory.
999
1000@c
1001@c Using the GDB configure Script Directly
1002@c
1003
1004@subsubsection Using the GDB configure Script Directly
1005
1006This section describes how to configure the GNU debugger for
1007RTEMS targets using @code{configure} and @code{make} directly.
1008The following example illustrates the invocation of @code{configure}
1009and @code{make} to build and install @value{GDB-UNTAR} for the
1010m68k-rtems target:
1011
1012@example
1013mkdir b-gdb
1014cd b-gdb
1015../@value{GDB-UNTAR}/configure --target=m68k-rtems \
1016  --prefix=/opt/rtems
1017make all
1018make info
1019make install
1020@end example
1021
1022For some configurations, it is necessary to specify extra options
1023to @code{configure} to enable and configure option components
1024such as a processor simulator.  The following is a list of
1025configurations for which there are extra options:
1026
1027@table @b
1028@item i960-rtems
1029@code{--enable-sim}
1030
1031@item powerpc-rtems
1032@code{--enable-sim --enable-sim-powerpc --enable-sim-timebase --enable-sim-hardware}
1033
1034@item sparc-rtems
1035@code{--enable-sim}
1036
1037@end table
1038
1039After @value{GDB-UNTAR} is built and installed the
1040build directory @code{b-gdb} may be removed.
1041
1042For more information on the invocation of @code{configure}, please
1043refer to the documentation for @value{GDB-UNTAR} or
1044invoke the @value{GDB-UNTAR} @code{configure} command with the
1045@code{--help} option.
1046
1047@subsubsection Using the bit_gdb Script
1048
1049The simplest way to build gdb for RTEMS is to use the @code{bit_gdb} script.
1050This script interprets the settings in the @code{user.cfg} file to
1051produce the GDB configuration most appropriate for the target CPU.
1052The variables in @code{user.cfg} were described in @ref{Using the bit Script}
1053but only the @code{GDB} variable setting is used by @code{bit_gdb}.
1054
1055The @code{bit_gdb} script is invoked as follows:
1056
1057@example
1058./bit_gdb CPU
1059@end example
1060
1061Where CPU is one of the RTEMS supported CPU families from the following
1062list:
1063
1064@itemize @bullet
1065@item hppa1.1
1066@item i386
1067@item i386-coff
1068@item i386-elf
1069@item i960
1070@item m68k
1071@item m68k-coff
1072@item mips64orion
1073@item powerpc
1074@item sh
1075@item sh-elf
1076@item sparc
1077@end itemize
1078
1079If gdb supports a CPU instruction simulator for this configuration, then
1080it is included in the build.
1081
1082@c -------------------
1083
1084@c
1085@c Common Problems
1086@c
1087
1088@section Common Problems
1089
1090@subsection Error Message Indicates Invalid Option to Assembler
1091
1092If a message like this is printed then the new cross compiler
1093is most likely using the native assembler instead of the cross
1094assembler or vice-versa (native compiler using new cross assembler).
1095This can occur for one of the following reasons:
1096
1097@itemize @bullet
1098
1099@item Binutils Patch Improperly Applied
1100@item Binutils Not Built
1101@item Current Directory is in Your PATH
1102
1103@end itemize
1104
1105If you are using binutils 2.9.1 or newer with certain older versions of
1106gcc, they do not agree on what the name of the newly
1107generated cross assembler is.  Older binutils called it @code{as.new}
1108which became @code{as.new.exe} under Windows.  This is not a valid
1109file name, so @code{as.new} is now called @code{as-new}.  By using the latest
1110released tool versions and RTEMS patches, this problem will be avoided.
1111
1112If binutils did not successfully build the cross assembler, then
1113the new cross gcc (@code{xgcc}) used to build the libraries can not
1114find it.  Make sure the build of the binutils succeeded.
1115
1116If you include the current directory in your PATH, then there
1117is a chance that the native compiler will accidentally use
1118the new cross assembler instead of the native one.  This usually
1119indicates that "." is before the standard system directories
1120in your PATH.  As a general rule, including "." in your PATH
1121is a security risk and should be avoided.  Remove "." from
1122your PATH.
1123
1124NOTE:  In some environments, it may be difficult to remove "."
1125completely from your PATH.  In this case, make sure that "."
1126is after the system directories containing "as" and "ld".
1127
1128@subsection Error Messages Indicating Configuration Problems
1129
1130If you see error messages like the following,
1131
1132@itemize @bullet
1133
1134@item cannot configure libiberty
1135@item coff-emulation not found
1136@item etc.
1137
1138@end itemize
1139
1140Then it is likely that one or more of your gnu tools is
1141already configured locally in its source tree.  You can check
1142for this by searching for the @code{config.status} file
1143in the various tool source trees.  The following command
1144does this for the binutils source:
1145
1146@example
1147find @value{BINUTILS-UNTAR} -name config.status -print
1148@end example
1149
1150The solution for this is to execute the command
1151@code{make distclean} in each of the GNU tools
1152root source directory.  This should remove all
1153generated files including Makefiles.
1154
1155This situation usually occurs when you have previously
1156built the tool source for some non-RTEMS target.  The
1157generated configuration specific files are still in
1158the source tree and the include path specified during
1159the RTEMS build accidentally picks up the previous
1160configuration.  The include path used is something like
1161this:
1162
1163@example
1164-I../../@value{BINUTILS-UNTAR}/gcc -I/@value{BINUTILS-UNTAR}/gcc/include -I.
1165@end example
1166
1167Note that the tool source directory is searched before the
1168build directory.
1169
1170This situation can be avoided entirely by never using
1171the source tree as the build directory -- even for
1172
Note: See TracBrowser for help on using the repository browser.