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-12-16	Joel Sherrill <joel.sherrilL@OARcorp.com>
 
 	* develenv/direct.t: Remove Getting Started with GNAT/RTEMS.

doc/started/buildc.t

@@ -8,12 +8,13 @@
 
 @chapter Building the GNU Cross Compiler Toolset
 
-NOTE:  This chapter does @b{NOT} apply if you installed prebuilt toolset
+@b{NOTE}:  This chapter describes the steps required to build cross-compilation
-executables for BINUTILS, GCC, NEWLIB, and GDB.  If you installed
+toolset on Linux (and possibly Windows using Cygwin) systems.  This chapter
-prebuilt executables for all of those, proceed to @ref{Building RTEMS}.
+does @b{NOT} apply if you installed prebuilt toolset executables for BINUTILS,
-If you require a GDB with a special configuration to connect to your
+GCC, NEWLIB, and GDB.  If you installed prebuilt executables for all of those,
-target board, then proceed to @ref{Installing GDB Without RPM}
+proceed to @ref{Building RTEMS}.  If you require a GDB with a special
-for some advice.
+configuration to connect to your target board, then proceed to
+@ref{Installing GDB Without RPM} for some advice.
 
 This chapter describes the steps required to acquire the source code for
 a GNU cross compiler toolset, apply any required RTEMS specific patches,
@@ -52,9 +53,14 @@ patches for a particular target architecture.
 All patches and RPM specification files are kept in CVS.  They are
 not included in release tarballs.  You will have to access the
 CVS branch for RTEMS @value{RTEMSAPI}.  For details on this,
-visit @uref{http://www.rtems.org, http://www.rtems.org} and look for
+visit @uref{http://www.rtems.org/wiki/index.php/RTEMS_CVS_Repository, http://www.rtems.org/wiki/index.php/RTEMS_CVS_Repository} and look for
-instructions on accessing the RTEMS Source Code Repository in read-only
+instructions on accessing the RTEMS Source Code Repository in read-only mode.
-mode.
+You can either do a complete checkout of the source tree or use a web
+interface.  A typical checkout command would look like this:
+@c TODO: pointing the user to the wiki entry might be enough.
+@example
+cvs -d :pserver:anoncvs@@www.rtems.com:/usr1/CVS -z 9 co -P rtems
+@end example
 
 In the checked out source code, you will need to look in the subdirectory
 @code{contrib/crossrpms/autotools} to determine the versions of AUTOCONF
@@ -62,9 +68,10 @@ and AUTOMAKE as well as any patches required.  In this directory are
 a few files you will need to look at.  The first is @code{Makefile.am}
 which defines the versions of AUTOCONF and AUTOMAKE required for this
 RTEMS Release Series.  Make a note of the version numbers required for
-AUTOCONF and AUTOMAKE.  Then examine the following files to determine
+AUTOCONF and AUTOMAKE (AUTOCONF_VERS and AUTOMAKE_VERS respectively).  Then
-the master location for the source tarballs and to determine if a patch
+examine the following files to determine the master location for the source
-is required for each tool version cited in the @code{Makefile.am}.
+tarballs and to determine if a patch is required for each tool version cited in
+the @code{Makefile.am}.
 
 @example
 autoconf-sources.add
@@ -75,6 +82,10 @@ If any patches are required, they will be in the
 @code{contrib/crossrpms/patches} subdirectory of your checked out RTEMS
 source tree.
 
+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.
+
 In the checked out source code, you will need to look in the subdirectory
 @code{contrib/crossrpms/rtems@value{RTEMSAPI}} to determine the target
 specific tool versions and patches required. In this directory, you
@@ -101,12 +112,6 @@ This is the entire set of source tarballs and patches required for a
 toolset targeting the selected architecture.  In many cases, this will be
 the same versions required by other targets on this RTEMS Release Series.
 
-Depending on the build method chosen, you may have to download source
-and patches or only patches.  Also the destination directory for the
-downloaded source is dependent on the build method followed.  But the
-versions required are the same.  Specific information on what to download
-and where to place it is in subsequent sections.
-
 @c
 @c  Obtain Source and Patches
 @c
@@ -171,7 +176,7 @@ Patches are in the @code{contrib/crossrpms/patches}.
 @c
 @subsection Unarchiving the Tools
 
-NOTE: This step is required if building any of the tools without using RPM.
+@b{NOTE}:  This step is required if building any of the tools without using RPM.
 It is @b{NOT} required if using the procedure described in @ref{Using RPM
 to Build Tools}.  This section describes the process of unarchiving the
 tools that comprise an RTEMS toolset.
@@ -199,7 +204,7 @@ the following directories will have been created under @code{tools}.
 @item automake-<VERSION>
 @item binutils-<VERSION>
 @item gcc-<VERSION>
-@item binutils-<VERSION>
+@item newlib-<VERSION>
 @item gdb-<VERSION>
 @end itemize
 
@@ -222,23 +227,25 @@ The tree should look something like the following figure:
 
 @subsection Applying RTEMS Project Tool Patches
 
-NOTE: This step is required if building any of the tools IF they have a
+@b{NOTE}:  This step is required if building any of the tools IF they have a
 patch currently required and you are building the tools without using RPM.
 is @b{NOT} required if using the procedure described in @ref{Using RPM
 to Build Tools}.  This section describes the process of applying the
 RTEMS patches to any of the tools.
 
-If a patch is required for a particular tool source tree, then you will
+If a patch is required for a particular tool source tree, it is placed in the
-perform a command similar to the following to apply the patch.  In this
+@code{contrib/crossrpms/patches} directory in the CVS tree.  Make sure the
-example, <TOOL> should be replaced by the appropriate tool directory
+patch version is the same as of the tool you are building.  You will perform a
-and <TOOL_PATCH> with the appropriate patch file.
+command similar to the following to apply the patch.  In this example, <TOOL>
+should be replaced by the appropriate tool directory and <TOOL_PATCH> with the
+appropriate patch file.
 
 @example
 cd tools/<TOOL>
 cat ../../archive/<TOOL_PATCH> | patch -p1
 @end example
 
-NOTE: If you add the @code{--dry-run} option to the @code{patch} command
+@b{NOTE}: If you add the @code{--dry-run} option to the @code{patch} command
 in the above commands, it will attempt to apply the patch and report
 any issues without actually modifying any files.
 
@@ -260,21 +267,25 @@ If any files are found with the .rej extension, a patch has been rejected.
 This should not happen with a good patch file which is properly applied.
 
 @c
-@c  Installing AUTOCONF Without RPM
+@c  Installing AUTOCONF From Source
 @c
 
-@subsection Installing AUTOCONF Without RPM
+@subsection Installing AUTOCONF From Source
 
 The following example illustrates the invocation of @code{configure}
 and @code{make} to build and install autoconf-<version>.  This tool is
 installed as a native utility and is independent of any RTEMS target.
 
+@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
 mkdir b-autoconf
 cd b-autoconf
 ../autoconf-<VERSION>/configure --prefix=@value{RTEMSPREFIX}
-make all
+make
-make info
 make install
 @end example
 
@@ -286,10 +297,10 @@ refer to the documentation for autoconf-<VERSION> or invoke the
 autoconf-VERSION> @code{configure} command with the @code{--help} option.
 
 @c
-@c  Installing AUTOMAKE Without RPM
+@c  Installing AUTOMAKE From Source
 @c
 
-@subsection Installing AUTOMAKE Without RPM
+@subsection Installing AUTOMAKE From Source
 
 The following example illustrates the invocation of @code{configure}
 and @code{make} to build and install automake-<version>.  This tool is
@@ -312,9 +323,9 @@ refer to the documentation for automake-<VERSION> or invoke the
 automake-VERSION> @code{configure} command with the @code{--help} option.
 
 @c
-@c  Installing BINUTILS Without RPM
+@c  Installing BINUTILS From Source
 @c
-@subsection Installing BINUTILS Without RPM
+@subsection Installing BINUTILS From Source
 
 The following example illustrates the invocation of @code{configure}
 and @code{make} to build and install binutils-<version>
@@ -346,6 +357,14 @@ containing the executables is the prefix used above with
 export PATH=@value{RTEMSPREFIX}/bin:$@{PATH@}
 @end example
 
+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.
+
 Failure to have the binutils in the path will cause the GCC and NEWLIB
 build to fail with an error message similar to:
 
@@ -458,7 +477,7 @@ After gcc-<VERSION> is built and installed the build directory
 @c
 @subsection Installing GDB Without RPM
 
-NOTE: This step is NOT required if prebuilt executables for the
+@b{NOTE}:  This step is NOT required if prebuilt executables for the
 GDB were installed and they meet your target interface
 requirements.
 
@@ -598,7 +617,7 @@ directory under the RPM root directory.
 @value{RTEMSRPMPREFIX}rtems@value{RTEMSAPI}-autoconf-<VERSION>-<RPM_RELEASE>.<ARCH>.rpm
 @end example
 
-NOTE: It may be necessary to remove the build tree in the @code{BUILD}
+@b{NOTE}:  It may be necessary to remove the build tree in the @code{BUILD}
 directory under the RPM root directory.
 
 @c
@@ -627,7 +646,7 @@ directory under the RPM root directory.
 @value{RTEMSRPMPREFIX}rtems@value{RTEMSAPI}-automake-<VERSION>-<RPM_RELEASE>.<ARCH>.rpm
 @end example
 
-NOTE: It may be necessary to remove the build tree in the @code{BUILD}
+@b{NOTE}:  It may be necessary to remove the build tree in the @code{BUILD}
 directory under the RPM root directory.
 
 
@@ -691,9 +710,9 @@ of the RPMS directory under the RPM root directory.
 @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-libstd++-<VERSION>-<RPM>.<ARCH>.rpm
 @end example
 
-NOTE: Some targets do not support building all languages.
+@b{NOTE}: Some targets do not support building all languages.
 
-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
@@ -724,7 +743,7 @@ of the RPMS directory under the RPM root directory.
 @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-gdb-<VERSION>-<RPM_RELEASE>.<ARCH>.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
@@ -767,7 +786,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".
 
@@ -814,5 +833,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

@@ -13,7 +13,7 @@
 This section provides pointers to the RTEMS source code and example
 programs.  These files should be placed in your @code{archive} directory.
 The set of tarballs which comprise an RTEMS release is placed in a
-directory whose name if the release on the ftp site.  The RTEMS ftp site
+directory whose name is the release on the ftp site.  The RTEMS ftp site
 is accessible via both the ftp and http protocols at the following URLs:
 
 @itemize @bullet
@@ -44,6 +44,20 @@ tar xjf ../archive/rtems-@value{RTEMSAPI}.<VERSION>.tar.bz2
 
 This creates the directory rtems-@value{RTEMSAPI}.<VERSION>
 
+@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
 
 In order to compile RTEMS, you must have the cross compilation toolset
@@ -65,7 +79,7 @@ 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
@@ -111,8 +125,8 @@ This can result in very confusing 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
@@ -133,8 +147,8 @@ discussed in detail in documentation that comes with the RTEMS
 distribution. A full list of these arguments can be obtained by running
 @code{../rtems-@value{RTEMSAPI}.<VERSION>/configure --help} If you
 followed the procedure described in the section @ref{Unarchive the
-RTEMS Source}, these configuration options can be found in the file
+RTEMS Source} or @ref{Obtaining the RTEMS Source from CVS}, these configuration options can be found in the file
-tools/rtems-@value{RTEMSAPI}.<VERSION>/README.configure.
+rtems-@value{RTEMSAPI}.<VERSION>/README.configure.
 
 @b{NOTE}: The GNAT/RTEMS run-time implementation is based on the POSIX
 API and the GNAT/RTEMS run-time cannot be compiled with networking
@@ -154,7 +168,8 @@ cd build-rtems
     --disable-posix --disable-networking --disable-cxx \
     --enable-rtemsbsp=<BSP>\
     --prefix=<INSTALL_POINT>
-make all install
+make all
+make install
 @end example
 
 <TARGET> is of the form <CPU>-rtems@value{RTEMSAPI} and the list of

doc/started/nt.t

@@ -92,13 +92,20 @@ 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 save files with Unix
+You absolutely have to use a text editor which can save files with Unix format.
-format. So do @b{NOT} use Notepad or Wordpad!  There are a number of
+So do @b{NOT} use Notepad or Wordpad!  Basically, any more or less advanced
-editors freely available that can be used.
+text editor is usually able to do that.  There is a number of editors freely
+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/}.  This editor has the very
 handy ability to easily read and write files in either DOS or UNIX style.

doc/started/require.t

@@ -45,7 +45,7 @@ will tend to be in the 40-60 Mbyte range.
 There are a number of factors which must be taken into
 account in order to estimate the amount of disk space required
 to build RTEMS itself.  Attempting to build multiple BSPs in
-a single step increases the disk space requirements.  One some
+a single step increases the disk space requirements.  On some
 target architectures, this can lead to disk usage during the build
 of over one gigabyte.
 

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