2001-01-17 Joel Sherrill <joel@OARcorp.com>

	* SUPPORT, LICENSE: New files.
	* Numerous files touched as part of merging the 4.5 branch
	onto the mainline development trunk and ensuring that the
	script that cuts snapshots and releases works on the documentation.

1 files changed, 202 insertions, 65 deletions

diff --git a/doc/started/buildrt.t b/doc/started/buildrt.t
index 0b60bcdfba..0ab4d00287 100644
--- a/doc/started/buildrt.t
+++ b/doc/started/buildrt.t
@@ -1,6 +1,6 @@
 @c
 @c
-@c  COPYRIGHT (c) 1988-1999.
+@c  COPYRIGHT (c) 1988-2002.
 @c  On-Line Applications Research Corporation (OAR).
 @c  All rights reserved.
 @c
@@ -9,40 +9,55 @@
 
 @chapter Building RTEMS
 
-@section Unpack the RTEMS Source
+@section Obtain the RTEMS Source Code
 
-Use the following command sequence to unpack the RTEMS source into the
-tools directory: 
+This section provides pointers to the RTEMS source code and
+Hello World example program.  These files should be
+placed in your @code{archive} directory.  
 
+@subheading @value{RTEMS-VERSION}
 @example
-cd tools
-tar xzf ../archive/@value{RTEMS-TAR}
+    FTP Site:    @value{RTEMS-FTPSITE}
+    Directory:   @value{RTEMS-FTPDIR}
+    File:        @value{RTEMS-TAR}
+@ifset use-html
+@c    URL:         @uref{ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}, Download RTEMS components}
+    URL:         ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}
+@end ifset
 @end example
 
-If you did not build and install the tools from source, then you
-will need to unarchive the build scripts at this point.  In this
-case, you will have to execute the following additional command
-since you did not do it as part of building the tools.
+@subheading RTEMS Hello World
+@example
+    FTP Site:    @value{RTEMS-FTPSITE}
+    Directory:   @value{RTEMS-FTPDIR}
+    File:        hello_world_c.tgz
+@ifset use-html
+@c    URL:         @uref{ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}/hello_world_c.tgz, Download RTEMS Hello World}
+    URL:         ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}/hello_world_c.tgz
+@end ifset
+@end example
+
+@c
+@c  Unarchive the RTEMS Source
+@c
+
+@section Unarchive the RTEMS Source
+
+Use the following command sequence to unpack the RTEMS source into the
+tools directory: 
 
 @example
-tar xzf ../archive/@value{BUILDTOOLS-TAR}
+cd tools
+tar xzf ../archive/@value{RTEMS-TAR}
 @end example
 
-At this point, the following files and directories should
-exist in the current directory in order to build RTEMS:
+This creates the directory @value{RTEMS-UNTAR}.
 
-@itemize @bullet
-@item bit
-@item bit_rtems
-@item common.sh
-@item @value{RTEMS-UNTAR}
-@item user.cfg
-@end itemize
 
 @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
+in your search path.  The following command appends the directory
 where the tools were installed prior to this point:
 
 @example
@@ -58,9 +73,9 @@ derivatives of the C Shell.
 
 In order to insure that the cross-compiler is invoking the correct
 subprograms (like @code{as} and @code{ld}), one can test assemble
-a small program.  When in verbose more, @code{gcc} prints out information 
-showing where it found the subprograms it invokes.  Place the following
-function in a file named @code{f.c}:
+a small program.  When in verbose mode, @code{gcc} prints out information 
+showing where it found the subprograms it invokes.  In a temporary
+working directory, place the following function in a file named @code{f.c}:
 
 @example
 int f( int x )
@@ -81,48 +96,40 @@ a sequence of output showing where the cross-compiler searched for
 and found its subcomponents.  Verify that these paths correspond
 to your <INSTALL_POINT>.
 
-@b{NOTE:} One of the most common installation errors is for the
-cross-compiler not to be able to find the cross assembler and default
-to using the native @code{as}.  This can result in very confusing
-error messages.
+Look at the created file @code{f.s} and verify that it is in fact
+for your target processor.
 
-@section Generate RTEMS for a Specific Target and BSP
-
-@subsection Using the bit_rtems Script
-
-The simplest way to build RTEMS is to use the @code{bit_rtems} script.
-This script interprets the settings in the @code{user.cfg} file to
-enable or disable the various RTEMS options.
-
-This script is invoked as follows:
+Then try to compile the file @code{f.c} directly to object code
+using a command like the following:
 
 @example
-./bit_rtems CPU [BSP]
+m68k-rtems-gcc -v -c f.c
 @end example
 
-Where CPU is one of the RTEMS supported CPU families from the following
-list:
+If this produces messages that indicate the assembly code is
+not valid, then it is likely that you have fallen victim to 
+one of the problems described in
+@ref{Error Message Indicates Invalid Option to Assembler}
+Don't feel bad about this, one of the most common installation errors
+is for the cross-compiler not to be able to find the cross assembler
+and default to using the native @code{as}.  This can result in very confusing
+error messages.
+
+@section Building RTEMS for a Specific Target and BSP
+
+This section describes how to configure and build RTEMS 
+so that it is specifically tailored for your BSP and the
+CPU model it uses.  There are two methods to compile and install RTEMS:
 
 @itemize @bullet
-@item hppa1.1
-@item i386
-@item i386-elf
-@item i386-go32
-@item i960 
-@item m68k
-@item mips64orion
-@item powerpc
-@item sh
-@item sparc
+@item direct invocation of @code{configure} and @code{make}
+@item using the @code{bit} script
 @end itemize
 
-BSP is a supported BSP for the selected CPU family.  The list of
-supported BSPs may be found in the file
-tools/@value{RTEMS-UNTAR}/README.configure
-in the RTEMS source tree.  If the BSP parameter is not specified,
-then all supported BSPs for the selected CPU family will be built.
+Direct invocation of @code{configure} and @code{make} provides more control
+and easier recovery from problems when building.
 
-@b{NOTE:}  The POSIX API must be enabled to use GNAT/RTEMS.
+This section describes how to build RTEMS.
 
 @subsection Using the RTEMS configure Script Directly
 
@@ -130,13 +137,14 @@ Make a build directory under tools and build the RTEMS product in this
 directory. The ../@value{RTEMS-UNTAR}/configure
 command has numerous command line
 arguments. These arguments are discussed in detail in documentation that
-comes with the RTEMS distribution. In the installation described in the
-section "Unpack the RTEMS source", these configuration options can be found
-in the file tools/@value{RTEMS-UNTAR}/README.configure.
+comes with the RTEMS distribution. If you followed the procedure
+described in the section @ref{Unarchive the RTEMS Source}, these
+configuration options can be found in the 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.
+@b{NOTE}: 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, FreeBSD TCP/IP,
@@ -153,11 +161,140 @@ cd build-rtems
 make all install
 @end example
 
-Where the list of currently supported of <TARGET_CONFIGURATION>'s and
+Where the list of currently supported <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. 
+<INSTALL_POINT> is typically the installation point for the 
+tools and is @code{/opt/rtems} when using prebuilt toolset executables.
 
 NOTE: The @code{make} utility used should be GNU make.
+
+@c
+@c Using the bit_rtems Script
+@c
+
+@subsection Using the bit_rtems Script
+
+If you have not previously unarchived the build tools, then you
+will need to unarchive the build scripts at this point if you
+plan to use @code{bit_rtems} to build RTEMS.  If this is the
+case, you will have to execute the following additional command
+since you did not do it as part of building the tools.
+
+@example
+cd tools
+tar xzf ../archive/@value{BUILDTOOLS-TAR}
+@end example
+
+This script interprets the settings in the @code{user.cfg} file to
+enable or disable the various RTEMS options.  The RTEMS
+specific entries described below must be set to
+tailor the RTEMS configuration to meet your application requirements:
+
+@table @code
+
+@item RTEMS
+is the directory under tools that contains @value{RTEMS-UNTAR}.
+
+@item ENABLE_RTEMS_POSIX
+is set to "yes" if you want to enable the RTEMS POSIX API support.
+At this time, this feature is not supported by the UNIX ports of RTEMS
+and is forced to "no" for those targets.  This corresponds to the
+@code{configure} option @code{--enable-posix}.
+
+@item ENABLE_RTEMS_ITRON
+is set to "yes" if you want to enable the RTEMS ITRON API support.
+At this time, this feature is not supported by the UNIX ports of RTEMS
+and is forced to "no" for those targets.  This corresponds to the
+@code{configure} option @code{--enable-itron}.
+
+@item ENABLE_RTEMS_MP
+is set to "yes" if you want to enable the RTEMS multiprocessing
+support.  This feature is not supported by all RTEMS BSPs and
+is automatically forced to "no" for those BSPs.  This corresponds to the
+@code{configure} option @code{--enable-multiprocessing}.
+
+@item ENABLE_RTEMS_CXX
+is set to "yes" if you want to build the RTEMS C++ support including
+the C++ Wrapper for the Classic API.  This corresponds to the
+@code{configure} option @code{--enable-cxx}.
+
+@item ENABLE_RTEMS_TESTS
+is set to "yes" if you want to build the RTEMS Test Suite.  If this
+is set to "no", then only the Sample Tests will be built.  Setting
+this option to "yes" significantly increases the amount of disk
+space required to build RTEMS.
+This corresponds to the @code{configure} option @code{--enable-tests}.
+
+@item ENABLE_RTEMS_TCPIP
+is set to "yes" if you want to build the RTEMS TCP/IP Stack.  If a
+particular BSP does not support TCP/IP, then this feature is automatically
+disabled.  This corresponds to the @code{configure} option
+@code{--enable-tcpip}.
+
+@item ENABLE_RTEMS_NONDEBUG
+is set to "yes" if you want to build RTEMS in a fully optimized
+state.  This corresponds to executing @code{make} after configuring
+the source tree.
+
+@item ENABLE_RTEMS_DEBUG
+is set to "yes" if you want to build RTEMS in a debug version.
+When built for debug, RTEMS will include run-time code to 
+perform consistency checks such as heap consistency checks.
+Although the precise compilation arguments are BSP dependent,
+the debug version of RTEMS is usually built at a lower optimization
+level.  This is usually done to reduce inlining which can make
+tracing code execution difficult.  This corresponds to executing
+@code{make VARIANT=debug} after configuring
+the source tree.
+
+@item INSTALL_RTEMS
+is set to "yes" if you want to install RTEMS after building it.
+This corresponds to executing @code{make install} after configuring
+and building the source tree.
+
+@item ENABLE_RTEMS_MAINTAINER_MODE
+is set to "yes" if you want to enabled maintainer mode functionality
+in the RTEMS Makefile.  This is disabled by default and it is not
+expected that most users will want to enable this.  When this option
+is enabled, the build process may attempt to regenerate files that
+require tools not required when this option is disabled.
+This corresponds to the @code{configure} option
+@code{--enable-maintainer-mode}.
+
+@end table
+
+After tailoring @code{user.cfg} for your application, the @code{bit_rtems}
+script may be invoked as follows:
+
+@example
+./bit_rtems CPU [BSP]
+@end example
+
+Where CPU is one of the RTEMS supported CPU families from the following
+list:
+
+@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
+
+BSP is a supported BSP for the selected CPU family.  The list of
+supported BSPs may be found in the file
+tools/@value{RTEMS-UNTAR}/README.configure
+in the RTEMS source tree.  If the BSP parameter is not specified,
+then all supported BSPs for the selected CPU family will be built.
+
+@b{NOTE:}  The POSIX API must be enabled to use GNAT/RTEMS.
+