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}
@@ -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
@@ -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
@@ -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".
 
@@ -956,5 +972,4 @@ Note that the tool source directory is searched before the
 build directory.
 
 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

@@ -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,7 +81,7 @@ 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
 showing where it found the subprograms it invokes.  In a temporary
@@ -114,8 +128,8 @@ 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
+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
@@ -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
@@ -15,31 +15,24 @@ This chapter was originally written by
 @uref{mailto:g_montel@@yahoo.com, Geoffroy Montel <g_montel@@yahoo.com>}
 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
 
-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
 
@@ -79,18 +72,17 @@ shell scripts properly.
 filesystem (e.g. mounted with the @code{-b} option).  Otherwise,
 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
 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
@@ -100,22 +92,27 @@ tar -xzvf archive.tgz
 
 @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/sample.t

@@ -30,11 +30,11 @@ 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
@@ -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