Comments from Chris Johns

4 files changed, 70 insertions, 5 deletions

diff --git a/doc/started/buildrt.t b/doc/started/buildrt.t
index 766da50886..edfc0c4911 100644
--- a/doc/started/buildrt.t
+++ b/doc/started/buildrt.t
@@ -29,9 +29,42 @@ 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 Verifying the Operation of the Cross Toolset
+
+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}:
+
+@example
+int f( int x )
+{
+  return x + 1;
+}
+@end example
+
+Then assemble the file using a command similar to the following:
+
+@example
+m68k-rtems-gcc -v -S f.c
+@end example
+
+Where @code{m68k-rtems-gcc} should be changed to match the installed
+name of your cross compiler.  The result of this command will be
+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.
 
 @section Generate RTEMS for a Specific Target and BSP
 
diff --git a/doc/started/intro.t b/doc/started/intro.t
index 2de7d458a8..a88fa189ef 100644
--- a/doc/started/intro.t
+++ b/doc/started/intro.t
@@ -130,7 +130,7 @@ use to RTEMS users.
 rtems-list@@OARcorp.com
 
 This mailing list is dedicated to discussion of issues related
-to RTEMS.  If you have questions about RTEMS, which to make
+to RTEMS.  If you have questions about RTEMS, wish to make
 suggestions, or just want to pick up hints, this is a good
 list to subscribe to.  Subscribe by sending a message with
 the one line "subscribe" to rtems-list-request@@OARcorp.com.
diff --git a/doc/started_ada/buildrt.t b/doc/started_ada/buildrt.t
index 2dd76b54fd..2724c0466e 100644
--- a/doc/started_ada/buildrt.t
+++ b/doc/started_ada/buildrt.t
@@ -33,6 +33,38 @@ 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 Verifying the Operation of the Cross Toolset
+
+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}:
+
+@example
+int f( int x )
+{
+  return x + 1; 
+}
+@end example
+
+Then assemble the file using a command similar to the following:
+
+@example 
+m68k-rtems-gcc -v -S f.c
+@end example
+
+Where @code{m68k-rtems-gcc} should be changed to match the installed
+name of your cross compiler.  The result of this command will be
+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.
+
 @section Generate RTEMS for a Specific Target and BSP
 
 Make a build directory under tools and build the RTEMS product in this
diff --git a/doc/started_ada/intro.t b/doc/started_ada/intro.t
index edf6019143..f0a0b0d9d1 100644
--- a/doc/started_ada/intro.t
+++ b/doc/started_ada/intro.t
@@ -130,7 +130,7 @@ use to GNAT/RTEMS users.
 rtems-list@@OARcorp.com
 
 This mailing list is dedicated to discussion of issues related
-to RTEMS.  If you have questions about RTEMS, which to make
+to RTEMS.  If you have questions about RTEMS, wish to make
 suggestions, or just want to pick up hints, this is a good
 list to subscribe to.  Subscribe by sending a message with
 the one line "subscribe" to rtems-list-request@@OARcorp.com.