2011-01-02 Danila Bespalov <danila DOT bespalov AT gmail DOT com>

* started/buildc.t, started/buildrt.t, started/nt.t, started/require.t,
	started/sample.t: Review and improve.

doc/ChangeLog

@@ -1,3 +1,8 @@
+2011-01-02	Danila Bespalov <danila DOT bespalov AT gmail DOT com>
+
+	* started/buildc.t, started/buildrt.t, started/nt.t, started/require.t,
+	started/sample.t: Review and improve.
+
 2010-11-24	Joel Sherrill <joel.sherrilL@OARcorp.com>
 
 	PR 1674/doc

doc/started/buildc.t

@@ -75,6 +75,10 @@ of each component as well as any required RTEMS specific patches.
 @c    URL:         ftp://@value{BINUTILSFTPSITE}@value{BINUTILSFTPDIR}/@value{BINUTILSTAR}
 @c @end ifset
 @end example
+If no patches are required, you can use a package manager provided by your
+Linux distribution to install AUTOMAKE and AUTOCONF to avoid building them from
+source.
+
 
 @need 1000
 @subheading @value{NEWLIBUNTAR}
@@ -132,7 +136,7 @@ It is @b{NOT} required if using the procedure
 described in @ref{Using RPM to Build BINUTILS GCC and NEWLIB}.
 
 GNU source distributions are archived using @code{tar} and
-compressed using either @code{gzip} or @code{bzip}.  
+compressed using either @code{gzip} or @code{bzip}.
 If compressed with @code{gzip}, the extension @code{.gz} is used.
 If compressed with @code{bzip}, the extension @code{.bz2} is used.
 
@@ -224,6 +228,11 @@ you should use @code{bzcat} instead of @code{cat} as shown above.
 
 Check to see if any of these patches have been rejected using the following
 sequence:
+@b{NOTE}: If no patch is required for Autoconf and Automake, you can use the
+standard package manager provided by your Linux distribution to install them.
+Of course, the versions provided by your package manager should be the same
+that specified in Makefile.am or better.
+
 
 @example
 cd tools/@value{GCCUNTAR}
@@ -494,8 +503,7 @@ mkdir b-binutils
 cd b-binutils
 ../@value{BINUTILSUNTAR}/configure --target=sparc-rtems@value{RTEMSAPI} \
   --prefix=@value{RTEMSPREFIX}
-make all
+make
-make info
 make install
 @end example
 
@@ -567,6 +575,14 @@ build directory @code{b-gcc} may be removed.
 For more information on the invocation of @code{configure}, please
 refer to the documentation for @value{GCCUNTAR} or
 invoke the @value{GCCUNTAR} @code{configure} command with the
+As you will need to frequently run various commands in the
+@value{RTEMSPREFIX}/bin, you can update your @code{~/.bashrc} to include this
+line. After doing that, don't forget to run
+@example
+source ~/.bashrc
+@end example
+for the changes to take place.
+
 @code{--help} option.
 
 @c
@@ -579,8 +595,8 @@ If you want a GCC toolset that includes support for Ada
 the host environment and additional build steps to perform.
 It is critical that you use the same version of GCC/GNAT as
 the native compiler.  GNAT must be compiled with an Ada compiler
-and when building a GNAT cross-compiler, it should be 
+and when building a GNAT cross-compiler, it should be
-the same version of GNAT itself. 
+the same version of GNAT itself.
 
 The build procedure is the same until the configure step. 
 A GCC toolset with GNAT enabled requires that @code{ada}
@@ -822,7 +838,7 @@ of the RPMS directory under the RPM root directory.
 @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-gdb-@value{GDBVERSION}-@value{GDBRPMRELEASE}.i386.rpm
 @end example
 
-NOTE: It may be necessary to remove the build tree in the
+@b{NOTE}: It may be necessary to remove the build tree in the
 @code{BUILD} directory under the RPM root directory.
 
 @c
@@ -891,13 +907,13 @@ This can occur for one of the following reasons:
 @end itemize
 
 If you are using binutils 2.9.1 or newer with certain older versions of
-gcc, they do not agree on what the name of the newly 
+gcc, they do not agree on what the name of the newly
 generated cross assembler is.  Older binutils called it @code{as.new}
 which became @code{as.new.exe} under Windows.  This is not a valid
 file name, so @code{as.new} is now called @code{as-new}.  By using the latest
 released tool versions and RTEMS patches, this problem will be avoided.
 
-If binutils did not successfully build the cross assembler, then 
+If binutils did not successfully build the cross assembler, then
 the new cross gcc (@code{xgcc}) used to build the libraries can not
 find it.  Make sure the build of the binutils succeeded.
 
@@ -909,7 +925,7 @@ in your PATH.  As a general rule, including "." in your PATH
 is a security risk and should be avoided.  Remove "." from
 your PATH.
 
-NOTE:  In some environments, it may be difficult to remove "."
+@b{NOTE}:  In some environments, it may be difficult to remove "."
 completely from your PATH.  In this case, make sure that "."
 is after the system directories containing "as" and "ld".
 
@@ -925,7 +941,7 @@ If you see error messages like the following,
 
 @end itemize
 
-Then it is likely that one or more of your gnu tools is 
+Then it is likely that one or more of your gnu tools is
 already configured locally in its source tree.  You can check
 for this by searching for the @code{config.status} file
 in the various tool source trees.  The following command
@@ -935,7 +951,7 @@ does this for the binutils source:
 find @value{BINUTILSUNTAR} -name config.status -print
 @end example
 
-The solution for this is to execute the command 
+The solution for this is to execute the command
 @code{make distclean} in each of the GNU tools
 root source directory.  This should remove all
 generated files including Makefiles.
@@ -952,9 +968,8 @@ this:
 -I../../@value{BINUTILSUNTAR}/gcc -I/@value{BINUTILSUNTAR}/gcc/include -I.
 @end example
 
-Note that the tool source directory is searched before the 
+Note that the tool source directory is searched before the
 build directory.
 
-This situation can be avoided entirely by never using 
+This situation can be avoided entirely by never using
-the source tree as the build directory -- even for
+the source tree as the build directory.
-

doc/started/buildrt.t

@@ -38,7 +38,7 @@ placed in your @code{archive} directory.
 @section Unarchive the RTEMS Source
 
 Use the following command sequence to unpack the RTEMS source into the
-tools directory: 
+tools directory:
 
 @example
 cd tools
@@ -47,6 +47,20 @@ tar xjf ../archive/@value{RTEMSTAR}
 
 This creates the directory @value{RTEMSUNTAR}.
 
+@section Obtaining the RTEMS Source from CVS
+
+Instead of downloading release tarballs you may choose to check out the current
+RTEMS source from CVS. For details on accessing RTEMS CVS repository consult
+@uref{http://www.rtems.org/wiki/index.php/RTEMS_CVS_Repository, http://www.rtems.org/wiki/index.php/RTEMS_CVS_Repository}.  The steps required
+to obtain the source code from CVS are usually like the following:
+@example
+$ cvs -d :pserver:anoncvs@@www.rtems.com:/usr1/CVS login
+Logging in to :pserver:anoncvs@@www.rtems.com:2401/usr1/CVS
+CVS password:
+$ cvs -d :pserver:anoncvs@@www.rtems.com:/usr1/CVS -z 9 co -P rtems  # for the main RTEMS source
+$ cvs -d :pserver:anoncvs@@www.rtems.com:/usr1/CVS -z 9 co -P examples-v2  # for examples
+@end example
+
 
 @section Add <INSTALL_POINT>/bin to Executable PATH
 
@@ -67,9 +81,9 @@ 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
+In order to ensure 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 mode, @code{gcc} prints out information 
+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}:
 
@@ -113,9 +127,9 @@ error messages.
 
 @section Building RTEMS for a Specific Target and BSP
 
-This section describes how to configure and build RTEMS 
+This section describes how to configure and build RTEMS
-so that it is specifically tailored for your BSP and the
+so that it is specifically tailored for your BSP (Board Support Package)
-CPU model it uses.  There is currently only one supported
+and the CPU model it uses.  There is currently only one supported
 method to compile and install RTEMS:
 
 @itemize @bullet
@@ -123,7 +137,7 @@ method to compile and install RTEMS:
 @end itemize
 
 Direct invocation of @code{configure} and @code{make} provides more control
-and easier recovery from problems when building. 
+and easier recovery from problems when building.
 
 This section describes how to build RTEMS.
 
@@ -146,7 +160,7 @@ 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,
-and C++ support disabled.  RTEMS will be built to target 
+and C++ support disabled.  RTEMS will be built to target
 the @code{BOARD_SUPPORT_PACKAGE} board.
 
 @example
@@ -156,7 +170,8 @@ cd build-rtems
     --disable-posix --disable-networking --disable-cxx \
     --enable-rtemsbsp=<BOARD_SUPPORT_PACKAGE>\
     --prefix=<INSTALL_POINT>
-make all install
+make all
+make install
 @end example
 
 Where the list of currently supported <TARGET_CONFIGURATION>'s and

doc/started/nt.t

@@ -1,5 +1,5 @@
 @c
-@c  COPYRIGHT (c) 1988-2002.
+@c  COPYRIGHT (c) 1988-2010.
 @c  On-Line Applications Research Corporation (OAR).
 @c  All rights reserved.
 @c
@@ -11,35 +11,28 @@
 This chapter discusses the installation of the GNU tool chain
 on a computer running the Microsoft Windows operating system.
 
-This chapter was originally written by 
+This chapter was originally written by
-@uref{mailto:g_montel@@yahoo.com, Geoffroy Montel <g_montel@@yahoo.com>} 
+@uref{mailto:g_montel@@yahoo.com, Geoffroy Montel <g_montel@@yahoo.com>}
-with input from 
+with input from
 @uref{mailto:<D.J@@fiddes.surfaid.org>, David Fiddes <D.J@@fiddes.surfaid.org>}.
-It was based upon his successful but unnecessarily
+It was based upon his successful but unnecessarily painful efforts with
-painful efforts with Cygwin beta versions.
+Cygwin beta versions.  Cygwin and this chapter have been updated multiple
-Cygwin and this chapter have been updated multiple times since
+times since those early days although their pioneering efforts and input
-those early days although their pioneering efforts
+is still greatly appreciated.
-and input is still greatly appreciated.
 
 @section Microsoft Windows Version Requirements
 
-RTEMS users report fewer problems when using Microsoft
+RTEMS users report fewer problems when using Microsoft Windows XP or newer.
-Windows NT, 2000, or XP.  Although, the open source tools
-that are used in RTEMS development do execute on Windows 95,
-98, or ME, they tend to be more stable when used with
-the modern Windows variants.
 
-@section Cygwin 
+@section Cygwin
 
-For RTEMS development, the recommended approach is to use
+For RTEMS development, the recommended approach is to use Cygwin. Cygwin
-Cygwin 1.0 or later. Cygwin is  available from
+is  available from @uref{http://www.cygwin.com, http://www.cygwin.com} .
-@uref{http://sources.redhat.com/cygwin, http://sources.redhat.com/cygwin} 
+The primary issues reported by users of Cygwin is that it is slower
-Recent versions of Cygwin are vastly improved over the beta
+on the same hardware than a native GNU/Linux installation and strange
-versions.  Most of the oddities, instabilities, and performance
+issues over carriage return/line feed inconsistencies between UNIX and
-problems have been resolved.  The installation procedure
+Windows environments.  However, there are a handful of other issues that
-is much simpler.  However, there are a handful of issues
+may turn up when using Cygwin as an RTEMS development environment.
-that remain to successfully use Cygwin as an RTEMS development
-environment.
 
 @itemize @bullet
 
@@ -62,7 +55,7 @@ GNU bash, version 2.04.5(12)-release (i686-pc-cygwin)
 Copyright 1999 Free Software Foundation, Inc.
 @end example
 
-If you get an error or it claims to be any other shell, you need 
+If you get an error or it claims to be any other shell, you need
 to copy it to a fake name and copy
 @code{/bin/bash.exe} to @code{/bin/sh.exe}:
 
@@ -77,45 +70,49 @@ shell scripts properly.
 
 @item Make sure you unarchive and build in a binary mounted
 filesystem (e.g. mounted with the @code{-b} option).  Otherwise,
-many confusing errors will result.  
+many confusing errors will result.
 
-@item A user has reported that they needed 
+@item A user has reported that they needed to set @code{CYGWIN=ntsec}
-to set CYGWIN=ntsec for chmod to work correctly, but had to set 
+for chmod to work correctly, but had to set @code{CYGWIN=nontsec}
-CYGWIN=nontsec for compile to work properly (otherwise there were
+for compile to work properly (otherwise there were complaints about
-complaints about permissions on a temporary file).
+permissions on a temporary file).
 
-@item If you want to build the tools from source, you have the 
+@item If you want to build the tools from source, you have the
 same options as UNIX users.
 
-@item You may have to uncompress archives during this
+@item You may have to uncompress archives during this process.  You must
-process.  You must @b{NOT} use @code{WinZip} or
+@b{NOT} use @code{WinZip} or @code{PKZip}.  Instead the un-archiving
-@code{PKZip}.  Instead the un-archiving process uses
+process uses the GNU @code{zip} and @code{tar} programs as shown below:
-the GNU @code{zip} and @code{tar} programs as shown below:
 
 @example
-tar -xzvf archive.tgz 
+tar -xzvf archive.tgz
 @end example
 
 @code{tar} is provided with Cygwin.
 
 @end itemize
 
+@section MingGW
+
+You might consider choosing MinGW since it provides better perfomance. There is a wiki entry on a MinGW RTEMS toolset installer available at @uref{http://www.rtems.org/wiki/index.php/MinGW_Tools_for_Windows,http://www.rtems.org/wiki/index.php/MinGW_Tools_for_Windows}. Also, there are prebuilt tools for different architectures available for download at @uref{http://www.rtems.org/ftp/pub/rtems/mingw32,http://www.rtems.org/ftp/pub/rtems/mingw32}.
+
 @section Text Editor
 
-You absolutely have to use a text editor which can 
+You absolutely have to use a text editor which can save files with Unix format.
-save files with Unix format. So do @b{NOT} use Notepad 
+So do @b{NOT} use Notepad or Wordpad!  Basically, any more or less advanced
-or Wordpad!  There are a number of editors
+text editor is usually able to do that.  There is a number of editors freely
-freely available that can be used.  
+available that can be used.
 
 @itemize @bullet
+@item @b{Notepad++} has an interface familiar to Windows users and can be downloaded from @uref{http://notepad-plus-plus.org/,http://notepad-plus-plus.org/}.
+
 @item @b{VIM} (@b{Vi IMproved}) is available from
-@uref{http://www.vim.org/,http://www.vim.org/}.  
+@uref{http://www.vim.org/,http://www.vim.org/}.  This editor has the very
-This editor has the very handy ability to easily
+handy ability to easily read and write files in either DOS or UNIX style.
-read and write files in either DOS or UNIX style.
 
 @item @b{GNU Emacs} is available for many platforms
-including MS-Windows.  The official homepage 
+including MS-Windows.  The official homepage is
-is @uref{http://www.gnu.org/software/emacs/emacs.html,
+@uref{http://www.gnu.org/software/emacs/emacs.html,
 http://www.gnu.org/software/emacs/emacs.html}.
 The GNU Emacs on Windows NT and Windows 95/98 FAQ is at
 @uref{http://www.gnu.org/software/emacs/windows/ntemacs.html,
@@ -123,11 +120,10 @@ http://www.gnu.org/software/emacs/windows/ntemacs.html}.
 
 @end itemize
 
-If you do accidentally end up with files 
+If you do accidentally end up with files having MS-DOS style line
-having MS-DOS style line termination, then you
+termination, then you may have to convert them to Unix format for some
-may have to convert them to Unix format for some
+Cygwin programs to operate on them properly. The program @code{dos2unix}
-Cygwin programs to operate on them properly. The 
+can be used to put them
-program @code{dos2unix} can be used to put them
 back into Unix format as shown below:
 
 @example
@@ -137,22 +133,16 @@ Dos2Unix: Cleaning file XYZ ...
 
 @section System Requirements
 
-Although the finished cross-compiler is fairly easy on resources,
+Although the finished cross-compiler is fairly easy on resources, building
-building it can take a significant amount of processing power and 
+it can take a significant amount of processing power and disk space.
-disk space.  
+Luckily, desktop computers have progressed very far since this guide
-
+was originally written so it is unlikely you will have any problems.
-@itemize @bullet
+Just do not use an old cast-off machine with < 1 GB RAM and a 1 Ghz CPU.
-
+Unless, of course, you enjoy waiting for things to complete.
-@item The faster the CPU, the better. The tools and Cygwin can be
-@b{very} CPU hungry.
-
-@item The more RAM, the better.  Reports are that when building GCC
-and GDB, peak memory usage can exceed 256 megabytes.
-
-@item The more disk space, the better. You need more if you are building
-the GNU tools and the amount of disk space for binaries is obviously
-directly dependent upon the number of CPUs you have cross toolsets
-installed for.
-
-@end itemize
 
+The more disk space, the better. You need more if you are building the
+GNU tools and the amount of disk space for binaries is obviously directly
+dependent upon the number of CPUs you have cross toolsets installed for.
+In addition to the disk space requirements documented earlier for tool
+building, you will also have to have enough space to install the Cygwin
+environment.

doc/started/require.t

@@ -8,14 +8,14 @@
 
 @chapter Requirements
 
-This chapter describes the build-host system requirements and initial steps 
+This chapter describes the build-host system requirements and initial steps
 in installing the GNU Cross Compiler Tools and RTEMS on a build-host.
 
 @section Disk Space
 
 A fairly large amount of disk space is required to perform the build of the
 GNU C/C++ Cross Compiler Tools for RTEMS. The following table may help in
-assessing the amount of disk space required for your installation: 
+assessing the amount of disk space required for your installation:
 
 @example
 +------------------------------------+--------------------------+
@@ -82,7 +82,7 @@ compiler.
 Both NEWLIB and RTEMS use GNU make specific features and can only be built
 using GNU make.  Many systems include a make utility that is not GNU make.
 The safest way to meet this requirement is to ensure that when you invoke
-the command @code{make}, it is GNU make.  This can be verified by 
+the command @code{make}, it is GNU make.  This can be verified by
 attempting to print the GNU make version information:
 
 @example
@@ -90,7 +90,7 @@ make --version
 @end example
 
 If you have GNU make and another make on your system, it is common to put
-the directory containing GNU make before the directory containing other 
+the directory containing GNU make before the directory containing other
 implementations of make.
 
 @subsection GNU makeinfo Version Requirements

doc/started/sample.t

@@ -8,20 +8,20 @@
 
 @chapter Building the Sample Applications
 
-The RTEMS distribution includes a number of sample C, C++, 
+The RTEMS distribution includes a number of sample C, C++,
 Ada, and networking applications.  This chapter will provide
 an overview of those sample applications.
 
 @c
-@c Set the Environment Variable RTEMS_MAKEFILE_PATH 
+@c Set the Environment Variable RTEMS_MAKEFILE_PATH
-@c 
+@c
-@section Set the Environment Variable RTEMS_MAKEFILE_PATH 
+@section Set the Environment Variable RTEMS_MAKEFILE_PATH
 
 The sample application sets use the RTEMS Application Makefiles.
-This requires that the environment variable 
+This requires that the environment variable
 @code{RTEMS_MAKEFILE_PATH} point to the appropriate directory containing
 the installed RTEMS image built to target your particular CPU and
-board support package combination. 
+board support package combination.
 
 @example
 export RTEMS_MAKEFILE_PATH=<INSTALLATION_POINT>/<CPU>-rtems/<BOARD_SUPPORT_PACKAGE>
@@ -30,17 +30,17 @@ export RTEMS_MAKEFILE_PATH=<INSTALLATION_POINT>/<CPU>-rtems/<BOARD_SUPPORT_PACKA
 Where <INSTALLATION_POINT> and <BOARD_SUPPORT_PACKAGE> are those used when
 configuring and installing RTEMS.
 
-NOTE:  In release 4.0, BSPs were installed at
+@b{NOTE}:  In release 4.0, BSPs were installed at
 @code{<INSTALLATION_POINT>/rtems/<BOARD_SUPPORT_PACKAGE>}.  This
 was changed to be more in compliance with GNU standards.
 
-NOTE: GNU make is the preferred @code{make} utility.  Other @code{make}
+@b{NOTE}: GNU make is the preferred @code{make} utility.  Other @code{make}
 implementations may work but all testing is done with GNU make.
 
 If no errors are detected during the sample application build, it is
 reasonable to assume that the build of the GNU Cross Compiler Tools
 for RTEMS and RTEMS itself for the selected host and target
-combination was done properly. 
+combination was done properly.
 
 @c
 @c Executing the Sample Applications
@@ -97,7 +97,7 @@ The TX3904 is a MIPS R3000 class CPU with serial ports and timers
 integrated with the processor.  This BSP can be used with
 either real  hardware or with the simulator included with
 @code{mipstx39-rtems-gdb}.  An application can be run on the simulator
-by executing the following commands upon entering @code{mipstx39-rtems-gdb}: 
+by executing the following commands upon entering @code{mipstx39-rtems-gdb}:
 
 @example
 target sim --board=jmr3904
@@ -117,10 +117,11 @@ The simulator is complicated to initialize by hand.  The user is referred
 to the script @code{powerpc/psim/tools/psim}.
 
 @item sparc/erc32
-The ERC32 is a radiation hardened SPARC V7.  This BSP can be used with
+The ERC32 is a radiation hardened SPARC V7.  This BSP can be used with either
-either real ERC32 hardware or with the simulator included with
+real ERC32 hardware or with the simulator included with @code{sparc-rtems-gdb}
-@code{sparc-rtems-gdb}.  An application can be run on the simulator
+(for this, you should configure RTEMS to use @code{sis} BSP).  An application
-by executing the following commands upon entering @code{sparc-rtems-gdb}: 
+can be run on the simulator by executing the following commands upon entering
+@code{sparc-rtems-gdb}:
 
 @example
 target sim
@@ -128,6 +129,10 @@ load
 run
 @end example
 
+In case that you don't need a debugger, an application can be run by
+@code{spart-rtems-run}.
+
+
 @end table
 
 RTEMS has many more BSPs and new BSPs for commercial boards and CPUs
@@ -141,7 +146,7 @@ with on-CPU peripherals are generally welcomed.
 The C/C++ sample application set includes a number of simple applications.
 Some demonstrate some basic functionality in RTEMS such as writing
 a file, closing it, and reading it back while others can serve as
-starting points for RTEMS applications or libraries.  Start by 
+starting points for RTEMS applications or libraries.  Start by
 unarchiving them so you can peruse them.  Use a command similar to
 the following to unarchive the sample applications:
 
@@ -179,8 +184,8 @@ as an example.
 @c
 @subheading Build the C Hello World Application
 
-Use the following command to start the build of the sample hello 
+Use the following command to start the build of the sample hello
-world application: 
+world application:
 
 @example
 cd hello_world_c
@@ -189,7 +194,7 @@ make
 
 
 If the sample application has successfully been built, then the application
-executable is placed in the following directory: 
+executable is placed in the following directory:
 
 @example
 hello_world_c/o-optimize/<filename>.exe
@@ -230,7 +235,7 @@ configuring and installing RTEMS.
 
 @section Build the Sample Application
 
-Use the following command to start the build of the sample application: 
+Use the following command to start the build of the sample application:
 
 @example
 cd tools/hello_world_ada
@@ -246,10 +251,10 @@ 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: 
+executable is placed in the following directory:
 
 @example
 tools/hello_world_ada/o-optimize/<filename>.exe