RTOS/rtems
1
0
Fork 0
forked from Imagelibrary/rtems
Code Pull Requests Activity

Now a passable Ada manual

Browse Source
This commit is contained in:
Joel Sherrill
1998-04-11 14:54:20 +00:00
parent 5741c943d0
commit 6d3d425dbd
7 changed files with 269 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
doc/started_ada/Makefile
View File

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

135
doc/started_ada/buildada.t
View File

@@ -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 Modify the bit script
@c
@c GNAT patches
@c
@section Modify the bit Script
@section Apply RTEMS Patch to GNAT
Copy the @code{bit} script from arc to the tools directory.
@ifclear GNAT-RTEMSPATCH
No RTEMS specific patches are required for @value{GNAT-VERSION} to
support @value{RTEMS-VERSION}.
@end ifclear
Edit the @code{bit} file to alter the following environmental variables:
@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_ada Script
Copy the @code{bit_ada} script from arc to the tools directory.
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.

29
doc/started_ada/buildrt.t
View File

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

68
doc/started_ada/gdb.t
View File

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

61
doc/started_ada/require.t
View File

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

33
doc/started_ada/sample.t
View File

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

26
doc/started_ada/versions.texi
View File

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