summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJoel Sherrill <joel.sherrill@OARcorp.com>1998-04-11 14:54:20 +0000
committerJoel Sherrill <joel.sherrill@OARcorp.com>1998-04-11 14:54:20 +0000
commit6d3d425dbd239fdb9a65a2a0a9834db8a657346c (patch)
treeff6bfebe2955b0148379fd5e1b2d2dc47ddfe619
parent5741c943d00d515de7dd489ca0fd7807903e25d3 (diff)
downloadrtems-6d3d425dbd239fdb9a65a2a0a9834db8a657346c.tar.bz2
Now a passable Ada manual
-rw-r--r--doc/started_ada/Makefile10
-rw-r--r--doc/started_ada/buildada.t133
-rw-r--r--doc/started_ada/buildrt.t29
-rw-r--r--doc/started_ada/gdb.t68
-rw-r--r--doc/started_ada/require.t61
-rw-r--r--doc/started_ada/sample.t33
-rw-r--r--doc/started_ada/versions.texi26
7 files changed, 268 insertions, 92 deletions
diff --git a/doc/started_ada/Makefile b/doc/started_ada/Makefile
index 74704a686d..1507aaeb4a 100644
--- a/doc/started_ada/Makefile
+++ b/doc/started_ada/Makefile
@@ -50,27 +50,27 @@ intro.texi: intro.t versions.texi
-n "Requirements" ${*}.t
require.texi: require.t versions.texi
- $(BMENU) -c -p "Introduction" \
+ $(BMENU) -c -p "Cross Development" \
-u "Top" \
-n "Building the GNAT Cross Compiler Toolset" ${*}.t
buildada.texi: buildada.t versions.texi
- $(BMENU) -c -p "Requirements" \
+ $(BMENU) -c -p "Insure GCC and GNAT Environment Variables Are Not Set" \
-u "Top" \
-n "Building RTEMS" ${*}.t
buildrt.texi: buildrt.t versions.texi
- $(BMENU) -c -p "Running the bit Script" \
+ $(BMENU) -c -p "Running the bit_ada Script" \
-u "Top" \
-n "Building the Sample Application" ${*}.t
sample.texi: sample.t versions.texi
- $(BMENU) -c -p "Generate RTEMS for a specific target and board support package" \
+ $(BMENU) -c -p "Generate RTEMS for a Specific Target and BSP" \
-u "Top" \
-n "Building the GNU Debugger" ${*}.t
gdb.texi: gdb.t versions.texi
- $(BMENU) -c -p "Application executable" \
+ $(BMENU) -c -p "Application Executable" \
-u "Top" \
-n "" ${*}.t
diff --git a/doc/started_ada/buildada.t b/doc/started_ada/buildada.t
index a078985e0f..9418e3d38c 100644
--- a/doc/started_ada/buildada.t
+++ b/doc/started_ada/buildada.t
@@ -6,20 +6,22 @@
@c $Id$
@c
-@chapter Building the GNU C/C++ Cross Compiler Toolset
+@chapter Building the GNAT Cross Compiler Toolset
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.
-@section Get all the pieces
+@section Directory Organization
The tree structure in the figure below is assumed to be present in the
-following discussions:
+following discussions:
@center @b{XXX directory tree figure goes here}
+@section Get all the Pieces
+
Gather the components that will be required for the installation and place
them in an archive directory. Call this directory arc. Be sure that there
is sufficient space to hold all necessary information. This will amount to
@@ -32,6 +34,13 @@ approximately 20 megabytes.
File: @value{GCC-TAR}
@end example
+@subheading @value{GNAT-VERSION}
+@example
+ FTP Site: @value{GNAT-FTPSITE}
+ Directory: @value{GNAT-FTPDIR}
+ File: @value{GNAT-TAR}
+@end example
+
@subheading @value{BINUTILS-VERSION}
@example
FTP Site: @value{BINUTILS-FTPSITE}
@@ -51,15 +60,24 @@ approximately 20 megabytes.
FTP Site: @value{RTEMS-FTPSITE}
Directory: @value{RTEMS-FTPDIR}
File: @value{RTEMS-TAR}
- File: bit
+ File: bit_ada
+@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}
- File: hello_world_c.tgz
+@end ifset
+@ifset GNAT-RTEMSPATCH
+ File: @value{GNAT-RTEMSPATCH}
+@end ifset
+ File: hello_world_ada.tgz
@end example
-@section Create the tools directory
+@section Create the tools Directory
Create a directory called tools that will serve as a working directory to
perform the build of the cross compiler tools.
@@ -69,6 +87,7 @@ Unpack the compressed tar files using the following command sequence:
@example
cd tools
tar xzf ../arc/@value{GCC-TAR}
+tar xzf ../arc/@value{GNAT-TAR}
tar xzf ../arc/@value{BINUTILS-TAR}
tar xzf ../arc/@value{NEWLIB-TAR}
@end example
@@ -79,14 +98,15 @@ directories will have been created under tools.
@itemize @bullet
@item @value{BINUTILS-UNTAR}
@item @value{GCC-UNTAR}
+@item @value{GNAT-UNTAR}
@item @value{NEWLIB-UNTAR}
@end itemize
@c
-@c EGCS patches
+@c GCC patches
@c
-@section Apply RTEMS Patch to EGCS
+@section Apply RTEMS Patch to GCC
@ifclear GCC-RTEMSPATCH
No RTEMS specific patches are required for @value{GCC-VERSION} to
@@ -207,15 +227,73 @@ The files that are found, have been modified by the patch file.
@end ifset
+@c
+@c GNAT patches
@c
-@c Modify the bit script
+
+@section Apply RTEMS Patch to GNAT
+
+@ifclear GNAT-RTEMSPATCH
+No RTEMS specific patches are required for @value{GNAT-VERSION} to
+support @value{RTEMS-VERSION}.
+@end ifclear
+
+@ifset GNAT-RTEMSPATCH
+
+Apply the patch using the following command sequence:
+
+@example
+cd tools/@value{GNAT-UNTAR}
+zcat arc/@value{GNAT-RTEMSPATCH} | patch -p1
+@end example
+
+Check to see if any of these patches have been rejected using the following
+sequence:
+
+@example
+cd tools/@value{GNAT-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.
+
+To see the files that have been modified use the sequence:
+
+@example
+cd tools/@value{GNAT-UNTAR}
+find . -name "*.orig" -print
+@end example
+
+The files that are found, have been modified by the patch file.
+
+@end ifset
+
+@c
+@c Copy the ada directory
+@c
+
+
+@section Copy the ada Subdirectory to the GCC Source Tree
+
+Copy the ada subtree in the patched subtree of
+tools/@value{GNAT-UNTAR}/src to the
+tools/@value{GCC-UNTAR} directory:
+
+@example
+cd tools/@value{GNAT-UNTAR}/src
+cp -r ada ../../../@value{GCC-UNTAR}
+@end example
+
+@c
+@c Modify the bit_ada script
@c
-@section Modify the bit Script
+@section Modify the bit_ada Script
-Copy the @code{bit} script from arc to the tools directory.
+Copy the @code{bit_ada} script from arc to the tools directory.
-Edit the @code{bit} file to alter the following environmental variables:
+Edit the @code{bit_ada} file to alter the following environmental variables:
@itemize @bullet
@item INSTALL_POINT
@@ -223,7 +301,6 @@ Edit the @code{bit} file to alter the following environmental variables:
@item NEWLIB
@item GCC
@item BUILD_DOCS
-@item BUILD_OTHER_LANGUAGES
@end itemize
These variables are located in the script section that resembles the
@@ -241,14 +318,11 @@ extract below:
# NEWLIB: Newlib source directory
# GCC: Newlib source directory
# BUILD_DOCS: Set to "yes" if you want to install documentation.
-# BUILD_OTHER_LANGUAGES:
-# Set to "yes" if you want to build Fortran and Objective-C
#
BINUTILS=@value{BINUTILS-UNTAR}
GCC=@value{GCC-UNTAR}
NEWLIB=@value{NEWLIB-UNTAR}
BUILD_DOCS=yes
-BUILD_OTHER_LANGUAGES=yes
INSTALL_POINT=/home/joel/$@{GCC@}/$@{target@}
# USERCHANGE - uncomment this if you want to watch the commands.
@@ -295,26 +369,17 @@ For 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, this enables Fortan and Objective-C.
-For example,
-
-@example
-BUILD_OTHER_LANGUAGES=yes
-@end example
-
@end table
-@section Running the bit Script
+@section Running the bit_ada Script
-After the @code{bit} script has been modified to reflect the
-local installation, the modified @code{bit} script is run
+After the @code{bit_ada} script has been modified to reflect the
+local installation, the modified @code{bit_ada} script is run
using the following sequence:
@example
cd tools
-./bit <target configuration>
+./bit_ada <target configuration>
@end example
Where <target configuration> is one of the following:
@@ -332,7 +397,11 @@ Where <target configuration> is one of the following:
@item sparc
@end itemize
-If no errors are encountered, the @code{bit} script will conclude by
+NOTE: The above list of target configurations is the list of RTEMS supported
+targets. Only a subset of these have been tested with GNAT/RTEMS. For more
+information, contact your GNAT/RTEMS representative.
+
+If no errors are encountered, the @code{bit_ada} script will conclude by
printing messages similar to the following:
@example
@@ -343,9 +412,9 @@ 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
+If the @code{bit_ada} script successfully completes, then the
GNU C/C++ cross compilation tools are installed.
-If the @code{bit} script does not successfully complete, then investigation
+If the @code{bit_ada} script does not successfully complete, then investigation
will be required to determine the source of the error.
diff --git a/doc/started_ada/buildrt.t b/doc/started_ada/buildrt.t
index daaf72f88b..2dd76b54fd 100644
--- a/doc/started_ada/buildrt.t
+++ b/doc/started_ada/buildrt.t
@@ -9,7 +9,7 @@
@chapter Building RTEMS
-@section Unpack the RTEMS source
+@section Unpack the RTEMS Source
Use the following command sequence to unpack the RTEMS source into the
tools directory:
@@ -19,7 +19,7 @@ cd tools
tar xzf ../arc/@value{RTEMS-TAR}
@end example
-@section Add the bin directory under the install point to the default PATH
+@section Add <INSTALL_POINT>/bin to Executable PATH
In order to compile RTEMS, you must have the cross compilation toolset
in your search patch. The following command appends the directory
@@ -29,11 +29,11 @@ where the tools were installed in the previous chapter:
export PATH=$PATH:<INSTALL_POINT>/bin
@end example
-NOTE: The above command is in Bourne shell (@code{sh}) syntax and should work with
-the Korn (@code{ksh}) and GNU Bourne Again Shell (@code{bash}). It will not
-work with the C Shell (@code{csh})or derivatives of the C Shell.
+NOTE: The above command is in Bourne shell (@code{sh}) syntax and should
+work with the Korn (@code{ksh}) and GNU Bourne Again Shell (@code{bash}).
+It will not work with the C Shell (@code{csh})or derivatives of the C Shell.
-@section Generate RTEMS for a specific target and board support package
+@section Generate RTEMS for a Specific Target and BSP
Make a build directory under tools and build the RTEMS product in this
directory. The ../@value{RTEMS-UNTAR}/configure
@@ -43,28 +43,29 @@ comes with the RTEMS distribution. In the installation described in the
section "Unpack the RTEMS source", these configuration options can be found
in file tools/@value{RTEMS-UNTAR}/README.configure.
+The GNAT/RTEMS run-time implementation is based on the POSIX API. Thus
+the RTEMS configuration for a GNAT/RTEMS environment MUST include the
+@code{--enable-posix} flag.
+
The following shows the command sequence required to configure,
-compile, and install RTEMS with the POSIX API, KA9Q TCP/IP,
-and C++ support disabled. RTEMS will be built to target
-the @code{BOARD_SUPPORT_PACKAGE} board.
+compile, and install RTEMS with the POSIX API enabled.
+RTEMS will be built to target the @code{BOARD_SUPPORT_PACKAGE} board.
@example
mkdir build-rtems
cd build-rtems
../@value{RTEMS-UNTAR}/configure --target=<TARGET_CONFIGURATION> \
- --disable-posix --disable-ka9q --disable-cxx \
+ --enable-posix \
--enable-rtemsbsp=<BOARD_SUPPORT_PACKAGE>\
--prefix=<INSTALL_POINT>
gmake all install
@end example
-Where:
-
-The list of currently supported of <TARGET_CONFIGURATION>'s and
+Where the list of currently supported of <TARGET_CONFIGURATION>'s and
<BOARD_SUPPORT_PACKAGE>'s can be found in
tools/@value{RTEMS-UNTAR}/README.configure.
<INSTALL_POINT> is the installation point from the previous step
-"Modify the bit script" in the build of the tools.
+"Modify the bit_ada Script" in the build of the tools.
diff --git a/doc/started_ada/gdb.t b/doc/started_ada/gdb.t
index 7ae7c2d9cd..d8820906ac 100644
--- a/doc/started_ada/gdb.t
+++ b/doc/started_ada/gdb.t
@@ -20,7 +20,7 @@ successfully used with RTEMS applications:
Other configurations of gdb have successfully been used by RTEMS users
but are not documented here.
-@section Unarchive the gdb distribution
+@section Unarchive the gdb Distribution
Use the following commands to unarchive the gdb distribution:
@@ -31,8 +31,50 @@ tar xzf ../arc/@value{GDB-TAR}
The directory @value{GDB-UNTAR} is created under the tools directory.
+@c
+@c GDB GNAT Patch
@c
-@c GDB Patch
+
+@section Apply GNAT Patch to GDB
+
+@ifclear GDB-GNATPATCH
+No GNAT specific patches are required for @value{GDB-VERSION} to
+support @value{RTEMS-VERSION} and @value{GNAT-VERSION}.
+@end ifclear
+
+@ifset GDB-GNATPATCH
+
+Apply the patch using the following command sequence:
+
+@example
+cd tools/@value{GDB-UNTAR}
+zcat arc/@value{GDB-GNATPATCH} | 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.
+
+To see the files that have been modified use the sequence:
+
+@example
+cd tools/@value{GDB-UNTAR}
+find . -name "*.orig" -print
+@end example
+
+The files that are found, have been modified by the patch file.
+
+@end ifset
+
+@c
+@c GDB RTEMS Patch
@c
@section Apply RTEMS Patch to GDB
@@ -76,7 +118,7 @@ The files that are found, have been modified by the patch file.
@section GDB with Sparc Instruction Simulation (SIS)
-@subheading Make the build directory
+@subheading Make the Build Directory
Create a build directory for the SIS Debugger
@@ -85,7 +127,7 @@ cd tools
mkdir build-sis
@end example
-@subheading Configure for the build
+@subheading Configure for the Build
Configure the GNU Debugger for the
Sparc Instruction Simulator (SIS):
@@ -102,7 +144,7 @@ cd tools/build-sis
Where <INSTALL_POINT_FOR_SIS> is a unique location where the gdb
with SIS will be created.
-@subheading Make the debugger
+@subheading Make the Debugger
From tools/build-sis execute the following command sequence:
@@ -113,7 +155,7 @@ gmake all install
@section GDB with PowerPC Instruction Simulator
-@subheading Make the build directory
+@subheading Make the Build Directory
Create a build directory for the SIS Debugger
@@ -122,7 +164,7 @@ cd tools
mkdir build-ppc
@end example
-@subheading Configure for the build
+@subheading Configure for the Build
Configure the GNU Debugger for the PowerPC
Instruction Simulator (PSIM):
@@ -144,7 +186,7 @@ Where <INSTALL_POINT_FOR_PPC> is a unique location where the gdb
with PSIM will be created.
-@subheading Make the debugger
+@subheading Make the Debugger
From tools/build-ppc execute the following command sequence:
@@ -155,11 +197,7 @@ gmake all install
@section GDB for DINK32
-@subheading Unarchive the gdb distribution
-
-Use the following commands to unarchive the gdb distribution:
-
-@subheading Make the build directory
+@subheading Make the Build Directory
Create a build directory for the DINK32 Debugger
@@ -168,7 +206,7 @@ cd tools
mkdir build-dink32
@end example
-@subheading Configure for the build
+@subheading Configure for the Build
Configure the GNU Debugger to communicate with
the DINK32 ROM monitor:
@@ -184,7 +222,7 @@ cd tools/build-dink32
Where <INSTALL_POINT_FOR_DINK32> is a unique location where the
gdb Dink32 will be created.
-@subheading Make the debugger
+@subheading Make the Debugger
From tools/build-dink32 execute the following command sequence:
diff --git a/doc/started_ada/require.t b/doc/started_ada/require.t
index e598e088ca..779ea7b3df 100644
--- a/doc/started_ada/require.t
+++ b/doc/started_ada/require.t
@@ -29,8 +29,69 @@ including:
@itemize @bullet
@item GCC
+@item GNAT
@item GNU make
@end itemize
In addition, some native utilities may be deficient for building
the GNU tools.
+
+@section Native GNAT
+
+The native GNAT must be installed in the default location or built
+from source. No GCC or GNAT environment variables should be set during
+the build or use of the cross GNAT/RTEMS toolset as this could result in
+an unpredictable mix of native and cross toolsets.
+
+Binaries for native GNAT installations are available at the primary
+GNAT ftp site (@value{GNAT-FTP}. Installation instructions are
+included with the binary GNAT distributions. The binary installation
+should be installed in the default location or installed in a
+non-default location and used ONLY to build a native GNAT from source.
+This final native GNAT will be used to build the GNAT/RTEMS cross
+development toolset.
+
+@subsection Verifying Correct Operation of Native GNAT
+
+It is imperative that the native GNAT installation work correctly for
+the installation of GNAT/RTEMS to succeed. It is recommended that the
+user verify that the native GNAT is installed correctly by performing
+these tests:
+
+@subsubsection Native Hello World Test
+
+Place the following Ada source code in hello.adb:
+
+@example
+with Text_IO: use Text_IO;
+
+procedure Hello is
+begin
+ Put_Line ( "Hello World");
+end Hello;
+@end example
+
+Use the following command sequence to ompile and execute the above program:
+
+@example
+gnatmake hello
+./hello
+@end example
+
+If the message @code{Hello World} is printed, then the native installation
+of GNAT operates well enough to proceed.
+
+@subsubsection Insure GCC and GNAT Environment Variables Are Not Set
+
+If any of the following commands produce output, then you have
+environment variables overriding the default behavior of the
+native GNAT toolset. These variables will conflict with the cross
+toolset. Please resolve this problem before proceeding further.
+
+@example
+echo $GCC_EXEC_PREFIX
+echo $ADA_INCLUDE_PATH
+echo $ADA_OBJECTS_PATH
+echo $LD_RUN_PATH
+echo $C_INCLUDE_PATH
+@end example
diff --git a/doc/started_ada/sample.t b/doc/started_ada/sample.t
index 2ff35bda63..9f2d8ddc48 100644
--- a/doc/started_ada/sample.t
+++ b/doc/started_ada/sample.t
@@ -8,28 +8,22 @@
@chapter Building the Sample Application
-@section Unpack the sample application
+@section Unpack the Sample Application
Use the following command to unarchive the sample application:
@example
cd tools
-tar xzf ../arc/hello_world_c.tgz
+tar xzf ../arc/hello_world_ada.tgz
@end example
-@section Set the environment variable RTEMS_MAKEFILE_PATH
+@section Create a BSP Specific Makefile
-It must point to the appropriate directory containing RTEMS build for our
-target and board support package combination.
+Provided are example Makefiles for multiple BSPs. Copy one of these to
+the file Makefile.<BOARD_SUPPORT_PACKAGE> and edit it as appropriate for
+your local configuration.
-@example
-export RTEMS_MAKEFILE_PATH = \
-<INSTALLATION_POINT>/rtems/<BOARD_SUPPORT_PACKAGE>
-@end example
-
-Where:
-
-<INSTALLATION_POINT> and <BOARD_SUPPORT_PACKAGE> are those used when
+Use the <INSTALLATION_POINT> and <BOARD_SUPPORT_PACKAGE> specified when
configuring and installing RTEMS.
@section Build the Sample Application
@@ -37,22 +31,23 @@ configuring and installing RTEMS.
Use the following command to start the build of the sample application:
@example
-cd tools/hello_world_c
-gmake
+cd tools/hello_world_ada
+gmake -f Makefile.<BOARD_SUPPORT_PACKAGE>
@end example
-If no errors are detected during the sample application build, it is
-reasonable to assume that the build of the GNU C/C++ Cross Compiler Tools
+If the BSP specific modifications to the Makefile were correct and
+no errors are detected during the sample application build, it is
+reasonable to assume that the build of the GNAT/RTEMS Cross Compiler Tools
for RTEMS and RTEMS itself for the selected host and target
combination was done properly.
-@section Application executable
+@section Application Executable
If the sample application has successfully been build, then the application
executable is placed in the following directory:
@example
-tools/simple_app/o-<BOARD_SUPPORT_PACKAGE>/<filename>.exe
+tools/hello_world_ada/o-<BOARD_SUPPORT_PACKAGE>/<filename>.exe
@end example
How this executable is downloaded to the target board is very dependent
diff --git a/doc/started_ada/versions.texi b/doc/started_ada/versions.texi
index ce84d3633a..24866ae3b0 100644
--- a/doc/started_ada/versions.texi
+++ b/doc/started_ada/versions.texi
@@ -21,12 +21,23 @@
@c GCC/EGCS Version
@c
-@set GCC-VERSION egcs 1.0.2
-@set GCC-TAR egcs-1.0.2.tar.gz
-@set GCC-UNTAR egcs-1.0.2
-@set GCC-FTPSITE egcs.cygnus.com
-@set GCC-FTPDIR /pub/egcs/releases/egcs-1.0.2
-@set GCC-RTEMSPATCH egcs-1.0.2-rtems-diff-980331.gz
+@set GCC-VERSION gcc 2.8.1
+@set GCC-TAR gcc-2.8.1.tar.gz
+@set GCC-UNTAR gcc-2.8.1
+@set GCC-FTPSITE ftp.gnu.oar
+@set GCC-FTPDIR /pub/GNU
+@set GCC-RTEMSPATCH gcc-2.8.1-rtems-diff-980323.gz
+
+@c
+@c GNAT Version
+@c
+
+@set GNAT-VERSION gnat 3.10p
+@set GNAT-TAR gnat-3.10p.tar.gz
+@set GNAT-UNTAR gnat-3.10p-src
+@set GNAT-FTPSITE cs.nyu.edu
+@set GNAT-FTPDIR /pub/gnat
+@set GNAT-RTEMSPATCH gnat-3.10p-rtems-diff.971106.gz
@c
@c BINUTILS Version
@@ -68,7 +79,8 @@
@set GDB-UNTAR gdb-4.16.86
@set GDB-FTPSITE ftp.cygnus.com
@set GDB-FTPDIR /private/gdb
-@set GDB-RTEMSPATCH TBD
+@set GDB-RTEMSPATCH GDB-RTEMS-PATCH-TBD
+@set GDB-GNATPATCH GDB-GNAT-PATCH-TBD
@c
@c RTEMS Version