Subversion Repositories or1k

@c

@c  COPYRIGHT (c) 1988-2002.

@c  On-Line Applications Research Corporation (OAR).

@c  All rights reserved.

@c

@c  buildc.t,v 1.30 2002/06/28 19:16:45 joel Exp

@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

    File:        @value{BUILDTOOLS-TAR}

@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 procedures described in @ref{Using configure and make}

or @ref{Using the bit Script}.  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 @ifset use-html

@c @html

@c 

@c @end html

@c @end ifset

@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}

or @ref{Using the bit Script}.  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}

zcat ../../archive/@value{GCC-RTEMSPATCH} | \

    patch -p1

@end example

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}

zcat ../../archive/@value{BINUTILS-RTEMSPATCH} | \

    patch -p1

@end example

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}

zcat ../../archive/@value{NEWLIB-RTEMSPATCH} | \

    patch -p1

@end example

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 three methods to compile and install BINUTILS, GCC, and NEWLIB:

@itemize @bullet

@item RPM

@item direct invocation of @code{configure} and @code{make}

@item using the @code{bit} script

@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 /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 /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 /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  Using the bit Script

@c

@subsubsection Using the bit Script

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 using the

@code{bit} script.  This script hides many of the details

of building the tools but can be a hindrance if you

encounter problems building the tools.

@c

@c  Unarchiving the Build Scripts

@c

@subheading Unarchiving the Build Scripts

While in the @code{tools} directory, unpack the compressed

tar file for the build tools using the following command sequence:

@example

cd tools

tar xzf ../archive/@value{BUILDTOOLS-TAR}

@end example

After the compressed tar file @value{BUILDTOOLS-TAR} has been unpacked, there

will be a set of scripts in the tools directory along with

any source code you have previously unarchived.

These scripts are intended to aid in building the tools and RTEMS.

These scripts may be used to automate the tool building process and hide

the invocation of @code{configure} and @code{make} from you.  They are:

@itemize @bullet

@item bit

@item bit_gdb

@item bit_rtems

@item common.sh

@item user.cfg

@end itemize

If @code{bit} is executed later in this process,

it will automatically create this subdirectory:

@itemize @bullet

@item build-$@{CPU@}-tools

@end itemize

At this point, 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}

            @value{BUILDTOOLS-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}/

            bit

            bit_gdb

            bit_rtems

            common.sh

            user.cfg

@end group

@end example

@c @ifset use-html

@c @html

@c 

@c @end html

@c @end ifset

@c

@c  Localizing the Configuration

@c

@subheading Localizing the Configuration

Edit the @code{user.cfg} file to alter the settings of various

variables which are used to tailor the build process.

Each of the variables set in @code{user.cfg} may be modified

as described below:

@table @code

@item INSTALL_POINT

is the location where you wish the GNU C/C++ cross compilation tools for

RTEMS to be built. It is recommended that the directory chosen to receive

these tools be named so that it is clear from which gcc distribution it

was generated and for which target system the tools are to produce code for.

@b{WARNING}: The @code{INSTALL_POINT} should not be a subdirectory

under the build directory.  The build directory will be removed

automatically upon successful completion of the build procedure.

@item BINUTILS

is the directory under tools that contains @value{BINUTILS-UNTAR}.

For example:

@example

BINUTILS=@value{BINUTILS-UNTAR}

@end example

@item GCC

is the directory under tools that contains @value{GCC-UNTAR}.

For example,

@example

GCC=@value{GCC-UNTAR}

@end example

@item GDB

is the directory under tools that contains @value{GDB-UNTAR}.

For example,

@example

GDB=@value{GDB-UNTAR}

@end example

@item NEWLIB

is the directory under tools that contains @value{NEWLIB-UNTAR}.

For example:

@example

NEWLIB=@value{NEWLIB-UNTAR}

@end example

@item BUILD_DOCS

is set to "yes" if you want to install documentation.  This requires

that tools supporting documentation production be installed.  This

currently is limited to the GNU texinfo package.

For example:

@example

BUILD_DOCS=yes

@end example

@item BUILD_OTHER_LANGUAGES

is set to "yes" if you want to build languages other than C and C++.  At

the current time, the set of alternative languages includes Java, Fortran,

and Objective-C.  These alternative languages do not always build cross.

Hence this option defaults to "no".

For example:

@example

BUILD_OTHER_LANGUAGES=yes

@end example

@b{NOTE:} Based upon the version of the compiler being used, it may not

be possible to build languages other than C and C++ cross.  In many cases,

the language run-time support libraries are not "multilib'ed".  Thus the

executable code in these libraries will be for the default compiler settings

and not necessarily be correct for your CPU model.

@end table

The other variables in @code{user.cfg} are RTEMS specific and are

not technically required to be set unless you build RTEMS using

the @code{bit_rtems} script as described in

@ref{Using the bit_rtems Script}.  They are described in detail

in that section.

@c

@c   Running the bit Script

@c

@subheading Running the bit Script

After the @code{bit} script has been modified to reflect the

local installation, the modified @code{bit} script is run

using the following sequence:

@example

cd tools

./bit 

@end example

Where  is one of the following:

@itemize @bullet

@item hppa1.1

@item i386

@item i386-coff

@item i386-elf

@item i960

@item m68k

@item m68k-coff

@item mips64orion

@item powerpc

@item sh

@item sh-elf

@item sparc

@end itemize

The build process can take a while to complete.  Many users find it

handy to run the build process in the background, capture the output

in a file, and monitor the output.  This can be done as follows:

@example

./bit  >bit.log 2>&1 &

tail -f bit.log

@end example

If no errors are encountered, the @code{bit} script will conclude by

printing messages similar to the following:

@example

The build-i386-tools subdirectory may now be removed.

Started:  Fri Apr 10 10:14:07 CDT 1998

Finished: Fri Apr 10 12:01:33 CDT 1998

@end example

If the @code{bit} script successfully completes, then the

GNU C/C++ cross compilation tools are installed.

If the @code{bit} script does not successfully complete, then investigation

will be required to determine the source of the error.

@c -------------------

@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

    File:        @value{BUILDTOOLS-TAR}

@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}

zcat archive/@value{GDB-RTEMSPATCH} | \

    patch -p1

@end example

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}

@item using the @code{bit_gdb} script

@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