Added information about the new build scripts. The biggest thing was

describing the user.cfg file.

Added a section on Solaris 2.x.

1 files changed, 73 insertions, 59 deletions

diff --git a/doc/started/buildc.t b/doc/started/buildc.t
index e7abcba948..c5cf38973a 100644
--- a/doc/started/buildc.t
+++ b/doc/started/buildc.t
@@ -104,7 +104,7 @@ specific patches.
 @example
     FTP Site:    @value{RTEMS-FTPSITE}
     Directory:   @value{RTEMS-FTPDIR}/c_tools
-    File:        bit
+    File:        @value{BUILDTOOLS-TAR}
 @ifset BINUTILS-RTEMSPATCH
     File:        @value{BINUTILS-RTEMSPATCH}
 @end ifset
@@ -129,6 +129,7 @@ cd tools
 tar xzf ../archive/@value{GCC-TAR}
 tar xzf ../archive/@value{BINUTILS-TAR}
 tar xzf ../archive/@value{NEWLIB-TAR}
+tar xzf ../archive/@value{BUILDTOOLS-TAR}
 @end example
 
 After the compressed tar files have been unpacked, the following
@@ -140,12 +141,16 @@ directories will have been created under tools.
 @item @value{NEWLIB-UNTAR}
 @end itemize
 
-Copy the @code{bit} script from the @code{archive} directory
-to the @code{tools} directory as shown below:
+There will also be a set of scripts in the current directory 
+which aid in building the tools and RTEMS.  They are:
 
-@example
-cp ../archive/bit .
-@end example
+@itemize @bullet
+@item bit
+@item bit_gdb
+@item bit_rtems
+@item common.sh
+@item user.cfg
+@end itemize
 
 When the @code{bit} script is executed later in this process, 
 it will automatically create two other subdirectories:
@@ -155,22 +160,22 @@ it will automatically create two other subdirectories:
 @item build-$@{CPU@}-tools
 @end itemize
 
-@itemize @bullet
-@item src
-@item build-$@{CPU@}-tools
-@end itemize
+Similarly, the @code{bit_gdb} script will create the 
+subdirectory @code{build-$@{CPU@}-gdb} and
+the @code{bit_rtems} script will create the
+subdirectory @code{build-$@{CPU@}-rtems}.
 
 The tree should look something like the following figure:
 
 @example
 @group
 /whatever/prefix/you/choose/
-        bit
         archive/
             @value{GCC-TAR}
             @value{BINUTILS-TAR}
             @value{NEWLIB-TAR}
             @value{RTEMS-TAR}
+            @value{BUILDTOOLS-TAR}
 @ifset GCC-RTEMSPATCH
             @value{GCC-RTEMSPATCH}
 @end ifset
@@ -188,7 +193,10 @@ The tree should look something like the following figure:
             @value{NEWLIB-UNTAR}/
             @value{RTEMS-UNTAR}/
             bit
-
+            bit_gdb
+            bit_rtems
+            common.sh
+            user.cfg
 @end group
 @end example
 
@@ -200,6 +208,20 @@ The tree should look something like the following figure:
 @c @end ifset
 
 @c
+@c  Host Specific Notes
+@c
+
+@section Host Specific Notes
+
+@subsection Solaris 2.x
+
+The build scripts are written in "shell".  The program @code{/bin/sh}
+on Solaris 2.x is not robust enough to execute these scripts.  If you
+are on a Solaris 2.x host, then change the first line of the files
+@code{bit}, @code{bit_gdb}, and @code{bit_rtems} to use the
+@code{/bin/ksh} shell instead.
+
+@c
 @c  Reading the Documentation
 @c
 
@@ -238,7 +260,7 @@ 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.
+This should not happen with a good patch file which is properly applied.
 
 @end ifset
 
@@ -270,7 +292,7 @@ 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. 
+This should not happen with a good patch file which is properly applied. 
 
 @end ifset
 
@@ -303,58 +325,20 @@ 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. 
+This should not happen with a good patch file which is properly applied. 
 
 @end ifset
 
 @c
-@c  Modify the bit script
+@c  Localizing the Configuration
 @c
 
-@section Modify the bit Script
-
-Copy the @code{bit} script from @code{archive} to the tools directory.
-
-Edit the @code{bit} file to alter the following environmental variables:
-
-@itemize @bullet
-@item INSTALL_POINT
-@item BINUTILS
-@item NEWLIB
-@item GCC
-@item BUILD_DOCS
-@item BUILD_OTHER_LANGUAGES
-@end itemize
-
-These variables are located in the script section that resembles the
-extract below: 
-
-
-@example
-# USERCHANGE -- localize these.
-#
-#  INSTALL_POINT: Directory tools are installed into.
-#      Recommended installation point for various OS's:
-#         Linux:    /usr/local/rtems
-#         Solaris:  /opt/gnu/rtems
-#   BINUTILS:     Binutils source directory
-#   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.
-@end example
+@section Localizing the Configuration
 
-Where each of the variables which may be modified is described below:
+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
@@ -408,6 +392,36 @@ For 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.
+
+@item RTEMS
+is the directory under tools that contails @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_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.
+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_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}.
 @end table
 
 @section Running the bit Script