2003-01-22 Ralf Corsepius <corsepiu@faw.uni-ulm.de>

* build45.t: Several fixes and additions.

doc/FAQ/ChangeLog

@@ -1,3 +1,7 @@
+2003-01-22	Ralf Corsepius <corsepiu@faw.uni-ulm.de>
+
+	* build45.t: Several fixes and additions.
+
 2003-01-22	Ralf Corsepius <corsepiu@faw.uni-ulm.de>
 
 	* FAQ.texi: Rename section "Building RTEMS 4.5" into "Building

doc/FAQ/build45.t

@@ -57,6 +57,8 @@ getting it working may not be easy.
 
 @subsection Do I need gcc-2.9x for cross compilation?
 
+[FIXME: Partially obsolete]
+
 Not necessarily, but gcc-2.9x is highly recommended, because most development
 has taken place using gcc-2.9x and previous versions of gcc are not actively
 supported in RTEMS anymore (@ref{Can I use a non-gcc cross-toolchain?}).
@@ -64,13 +66,13 @@ supported in RTEMS anymore (@ref{Can I use a non-gcc cross-toolchain?}).
 @subsection Where to get autoconf automake ld gcc etc.?
 
 The sources of all gnutools are available at any 
-@uref{GNU,ftp://ftp.gnu.org} mirror.
+@uref{ftp://ftp.gnu.org,GNU} mirror.
 Native Linux binaries should come with any Linux distribution.
 Native Cygwin binaries should be available at Cygnus.
 
 GNU-Toolchain binaries (gcc, binutils etc.) for Linux and patches required
 to build them from source are available from 
-@uref{OAR Corporation,ftp://ftp.oarcorp.com}.
+@uref{ftp://ftp.oarcorp.com,OAR Corporation}.
 
 
 @section Issues when building RTEMS
@@ -89,8 +91,36 @@ cd build
 /usr/local/src/rtems-@value{VERSION}/configure [options]
 @end example
 
-@subsection Why can I not build RTEMS inside of the source tree?
+@subsection When running bootstrap weird thing start to happen
 
+Many possibile causes: Most likely one of these:
+@itemize @bullet
+@item You are trying to build RTEMS with insufficient or incompatible
+versions of autoconf and automake.
+@item The autotools can't be found because your $PATH might not be set up 
+correctly (Cf. @ref{How to set up $PATH?})
+@item You have used configure-script options which interfer with RTEMS
+configuration (Cf. @ref{configure --program-[prefix|suffix|transform-name]})
+@item You have tripped over a bug in RTEMS ;)
+@end itemize
+
+@subsection configure xxx cannot create executables
+
+While running a configure script, you see a message like this:
+@example
+checking for m68k-rtems-gcc... (cached) m68k-rtems-gcc
+checking for C compiler default output... configure: error: C compiler cannot create executables
+configure: error: /bin/sh '../../../../rtems-ss-@value{VERSION}/c/make/configure'
+failed for c/make
+@end example
+This kind of error message typically indicates a broken toolchain, broken
+toolchain installation or broken user environment.
+
+Examinating the @code{config.long} corresponding to the the failing
+configure script should provide further information of what
+actually goes wrong (In the example above: @code{<target>/c/<BSP>/make/config.log})
+
+@subsection Why can I not build RTEMS inside of the source tree?
 
 The build-directory hierarchy is setup dynamically at configuration time.
 
@@ -130,7 +160,7 @@ If using OAR Corporation's rpms for the toolchain, simply prepend
 @subsection Can I build RTEMS Canadian Cross?
 
 RTEMS >= 4.6.0 configuration is prepared for building RTEMS Canadian Cross,
-however building RTEMS Canadian Cross is known to be in it's infancy, so
+however building RTEMS Canadian Cross is known to be in its infancy, so
 your mileage may vary (See @code{README.cdn-X} in the toplevel directory of
 RTEMS's source tree for details.)
 
@@ -151,6 +181,8 @@ See @ref{How to merge pre-RTEMS-4.5.0 BSPs into RTEMS-4.5.0?}.
 
 @subsection make debug_install / make profile_install
 
+[FIXME:Partially obsolete]
+
 These make targets are not supported anymore.  Instead, use:
 
 @example
@@ -160,6 +192,8 @@ make VARIANT=PROFILE install
 
 @subsection make debug / make profile
 
+[FIXME:Partially obsolete]
+
 These make targets are not supported anymore.
 Instead, use:
 
@@ -185,7 +219,6 @@ These files are generated by auto* tools, cf.
 
 @subsection Editing auto* generated files
 
-
 RTEMS uses automake, therefore @b{never}, @b{ever}, @b{ever}
 edit Makefile.ins, Makefiles, configure or other auto* generated files.
 Changes to them will be swapped away soon and will get lost.
@@ -231,13 +264,14 @@ any recent Linux distribution should work, too.
 
 @subsection How to merge pre-RTEMS-4.5.0 BSPs into RTEMS-4.5.0?
 
-The simple answer is that between 4.0 and now, RTEMS has moved to automake
+[FIXME:Partially obsolete]
+
+The simple answer is that between 4.0 and 4.5.0, RTEMS has moved to automake
 and greater compliance with GNU conventions.
 In 4.0, there was a single configure script at the top of the tree.
 Now RTEMS is configured more like other GNU tools -- as a collection of
 configurable entities.
 
-
 Each BSP now has its own configure script.
 I highly recommend you look at the Makefile.am's, configure.ac, of a similar
 BSP.  You might even want to consider running "bootstrap -c" from the top of
@@ -263,6 +297,13 @@ At present time the bare BSP is in its infancy.
 It is known that it can be build for most CPUs RTEMS supports.
 It is also known to work in individual cases, but your mileage may vary.
 
+@subsection What is the cpukit?
+
+[FIXME:To be extended]
+
+One major change having been introduced to RTEMS-4.6.0 is the cpukit,
+located below the directory @code{cpukit/} in RTEMS's toplevel directory.
+
 @subsection Multilib vs.  RTEMS CPU-variants
 
 The GNU toolchain applies a specific classification of similar CPUs into
@@ -351,6 +392,12 @@ files.  I.e.  auto* generated files will get automatically updated.
 Configuring RTEMS in maintainer-mode will require to have autoconf, automake
 and underlying tools installed (Cf. @ref{Required Tools}).
 
+@subsection configure --program-[prefix|suffix|transform-name]
+
+These are generic configure script options automatically added by autoconf.
+RTEMS configuration does not support these, worse, they interfer with
+RTEMS's configuration -- i.e. @b{do not use them}.
+
 @subsection configure.ac vs. configure.in
 
 autoconf < 2.50 used the name @code{configure.in} for it's input files. 
@@ -358,4 +405,14 @@ autoconf >= 2.50 recommends using the name @code{configure.ac}, instead.
 
 RTEMS > 4.5.0 applies autoconf >= 2.50, therefore all former RTEMS's
 @code{configure.in}'s have been renamed into @code{configure.ac} and 
-adapted to autoconf >= 2.50 demands.
+have been adapted to autoconf >= 2.50 demands.
+
+@subsection Reporting bugs
+
+Several possibilities (In decreasing preference):
+@itemize @bullet
+@item File a bug report at @uref{http://www.oarcorp.com/cgi-bin/gnatweb.pl,OAR's GNAT}
+@item Send an email to @uref{mailto:rtems-bugs@@OARcorp.com,rtems-bugs@@OARcorp.com}
+@item Report your problem to one of the RTEMS mailing lists 
+(Cf. @ref{Are there any mailing lists?}).
+@end itemize