[PATCH] doc/started: simplify and fix

Gedare Bloom gedare at rtems.org
Wed Mar 11 17:39:43 UTC 2015


* fix and remove some macros in rtems.texi.in.
* refer to devel mailing list.
* remove reference to Debian packaging in requirements section.
* remove section on prebuilt tools.
* replace toolset build instructions with link to RSB docs.
* Add a note in building RTEMS section about using RSB.
* Fix URLs

Closes #2291.
---
 doc/common/rtems.texi.in |   7 +-
 doc/started/Makefile.am  |  20 +-
 doc/started/binaries.t   | 341 -------------------
 doc/started/buildc.t     | 829 +----------------------------------------------
 doc/started/buildrt.t    |  28 +-
 doc/started/intro.t      |  37 +--
 doc/started/require.t    |   7 -
 doc/started/started.texi |   4 +-
 8 files changed, 47 insertions(+), 1226 deletions(-)
 delete mode 100644 doc/started/binaries.t

diff --git a/doc/common/rtems.texi.in b/doc/common/rtems.texi.in
index 06172cc..063e5e9 100644
--- a/doc/common/rtems.texi.in
+++ b/doc/common/rtems.texi.in
@@ -1,8 +1,5 @@
- at set RTEMSHTTPSITE		www.rtems.org
- at set RTEMSUSERS			rtems-users@@rtems.com
- at set RTEMSUSERSSUBSCRIBE	rtems-users-subscribe@@rtems.com
- at set RTEMSBUGS			http://www.rtems.org/bugzilla
- at set RTEMSFTPURL		ftp://www.rtems.org
+ at set RTEMSUSERS			users@@rtems.org
+ at set RTEMSDEVEL			devel@@rtems.org
 @set RTEMSHTTPURL		http://www.rtems.org
 @set RTEMSPREFIX		@RTEMSPREFIX@
 @set RTEMSAPI			@RTEMSAPI@
diff --git a/doc/started/Makefile.am b/doc/started/Makefile.am
index df74da3..0eef621 100644
--- a/doc/started/Makefile.am
+++ b/doc/started/Makefile.am
@@ -8,7 +8,7 @@ PROJECT = started
 include $(top_srcdir)/project.am
 include $(top_srcdir)/main.am
 
-GENERATED_FILES = binaries.texi buildc.texi buildrt.texi intro.texi nt.texi \
+GENERATED_FILES = buildc.texi buildrt.texi intro.texi nt.texi \
     require.texi nextstep.texi sample.texi
 
 COMMON_FILES += $(top_srcdir)/common/cpright.texi
@@ -24,23 +24,19 @@ intro.texi: intro.t
 	    -n "Requirements" < $< > $@
 
 require.texi: require.t
-	$(BMENU2) -c -p "GCC Mailing Lists" \
+	$(BMENU2) -c -p "RTEMS Mailing Lists" \
 	    -u "Top" \
-	    -n "Prebuilt Toolset Executables" < $< > $@
-
-binaries.texi: binaries.t
-	$(BMENU2) -c \
-	    -p "GNU/Linux Distributions using Debian Packaging Format" \
-	    -u "Top" \
-	    -n "Building the GNU Cross Compiler Toolset" < $< > $@
+	    -n "Building the GNU Cross Compiler Toolset with RSB" < $< > $@
 
 buildc.texi: buildc.t
-	$(BMENU2) -c -p "Removing Zipped Tar Files" \
+	$(BMENU2) -c \
+	    -p "Distribution Independent Potential GNU/Linux Issues" \
 	    -u "Top" \
 	    -n "Building RTEMS" < $< > $@
 
 buildrt.texi: buildrt.t
-	$(BMENU2) -c -p "Error Messages Indicating Configuration Problems" \
+	$(BMENU2) -c \
+	    -p "Building the GNU Cross Compiler Toolset with RSB" \
 	    -u "Top" \
 	    -n "Building the Sample Applications" < $< > $@
 
@@ -59,7 +55,7 @@ nt.texi: nt.t
 	    -u "Top" \
 	    -n "" < $< > $@
 
-EXTRA_DIST = binaries.t buildc.t buildrt.t intro.t nextstep.t nt.t require.t \
+EXTRA_DIST = buildc.t buildrt.t intro.t nextstep.t nt.t require.t \
     sample.t
 
 if USE_HTML
diff --git a/doc/started/binaries.t b/doc/started/binaries.t
deleted file mode 100644
index 7616d87..0000000
--- a/doc/started/binaries.t
+++ /dev/null
@@ -1,341 +0,0 @@
- at c
- at c  COPYRIGHT (c) 1988-2010.
- at c  On-Line Applications Research Corporation (OAR).
- at c  All rights reserved.
-
- at chapter Prebuilt Toolset Executables
-
-Precompiled toolsets are available for GNU/Linux and MS-Windows. 
-Other hosts will need to build from source.  Packaged binaries are
-in the following formats:
-
- at itemize @bullet
- at item GNU/Linux - RPM
- at item Cygwin - tar.bz2
- at item Mingw - tar.bz2
- at end itemize
-
-RPM is an acronym for the RPM Package Manager.  RPM is the native package
-installer for many GNU/Linux distributions including RedHat Enterprise
-Linux, Centos, SuSE, and Fedora.
-
-The RTEMS Project maintains a Yum Repository which makes it quite simple
-to install and update RTEMS toolsets.
-
-The prebuilt binaries are intended to be easy to install and
-the instructions are similar regardless of the host environment.  
-There are a few structural issues with the packaging of the RTEMS
-Cross Toolset binaries that you need to be aware of.
-
- at enumerate
- at item There are dependencies between the various packages.  This requires
-that certain packages be installed before others may be.  Some packaging
-formats enforce this dependency.
-
- at item Some packages are target CPU family independent and shared
-across all target architectures.   These are referred to as 
-"base" packages.
-
- at item Pre-built GNU Binary Utilities (binutils) packages are available
-for all RTEMS targets.  These include tools such as the assembler and
-linker and must be installed.
-
- at item Pre-built C language packages are available which include a C
-compiler as well as the Standard C libraries for the embedded RTEMS
-targets.  These must be installed.
-
- at item Pre-built C++ language packages are available for most target
-architectures which includes a C++ compiler as well as the Standard C++
-libraries for the embedded RTEMS targets.  These are not part of the
-minimum installation and need only be installed if the application is
-using C++.
-
- at end enumerate
-
-NOTE: Installing toolset binaries does not install RTEMS itself, only
-the tools required to build RTEMS.  See @ref{Building RTEMS} for the next
-step in the process.
-
- at section RPMs
-
-This section provides information on installing and removing RPMs.
-
-Note that RTEMS tools for multiple major versions of RTEMS can be
-installed in parallel since they are installed into different host
-directories.  The tools also include the RTEMS Release Series in their
-name.
-
- at subsection Locating the RPMs for your GNU/Linux Distribution
-
-The RTEMS Project maintains a Yum Repository of RPMs for its
-toolsets. Whether you use Yum to install the RPMs or download and install
-them via another procedure, you will need to locate the appropriate
-set of RPMs on the RTEMS Yum Repository.  The following instructions
-are generalized.
-
-If your host operating system uses Yum and RPMs, then you will only have
-to download and install two RPMs by hand
-
- at enumerate
- at item Point your browser at
- at uref{http://www.rtems.org/ftp/pub/rtems/linux,
-http://www.rtems.org/ftp/pub/rtems/linux}.  In this directory, you
-will see a list of RTEMS major versions such as 4.11, 4.10, 4.9, etc..
-Descend into the appropriate directory for the version of RTEMS you
-are using.
-
- at item Now that you are in the directory for a specific RTEMS major
-version, you will be presented with a list of GNU/Linux distributions.
-This will include options like redhat, centos, fedora, and suse.
-Select the appropriate distribution.
-
- at item Now that you are in the directory for your selected distribution,
-you will be presented with a list of distribution versions for which
-RTEMS pre-built RPMs are available.  Select the appropriate distribution
-version.
-
- at item Now that you are in the directory for the proper version of
-your selected distribution, you will be presented with a choice of
-host architecture versions such as i386, i686, and x86_64.  Select the
-appropriate version for your development computer.
-
- at item At this point, you will have a long list of RPMs to select from.
- at end enumerate
-
-The RTEMS Projects supports a wide variety of host OS and target
-combinations.  In addition, these toolsets are specific to a particular
-RTEMS Release Series.  Given the large number of possible combinations,
-the instructions use variables to indicate where versions go in the real
-package names you will use.  These variable are used in the examples of
-RPM version names:
-
- at itemize @bullet
- at item @code{<VERSION>} is the tool version will be found at this location
-in the RPM name. This will be a release number such as @code{2.20}
-or @code{4.4.5}.
-
- at item @code{<DIST>} indicates the GNU/Linux distribution version.
-This will be a string such as @code{fc14} or @code{el6}.
-
- at item @code{<ARCH>} indicates the architecture used for RPMs on your
-GNU/Linux installation.  This will be a string such as @code{i386}
-or @code{x86_64}.
-
- at item @code{<RPM>} indicates the RPM revision level.  This will be a
-single integer.
- at end itemize
-
-The tool VERSION and RPM release may vary within the set of current RPMs for a particular RTEMS Release series based upon the target architecture.  
-
-If you are using Yum, please continue to the next section.  If you are
-downloading the RPMs to install by hand, then go to the @ref{Installing
-RPMs Without Yum} section.
-
- at subsection Managing RPMs Using Yum
-
-This section describes how to install and remove RTEMS Toolsets using Yum.
-
- at subsubsection Installing RPMs Using Yum
-
-If you are on a host operating system that uses Yum, you are fortunate because this is the one of the simplest ways to install the tools.  After locating the appropriate directory on the RTEMS Yum Repository using the instructions in @ref{Locating the RPMs for your GNU/Linux Distribution}, you will need to install the following RPMs:
-
- at itemize @bullet
- at item @value{RTEMSRPMPREFIX}-release-<VERSION>-<RPM>.<DIST>.noarch.rpm
- at item @value{RTEMSRPMPREFIX}-yum-conf-<VERSION>-<RPM>.<DIST>.noarch.rpm
- at end itemize
-
-You can use the search within page feature of your browser to locate
-the RPMs with "release" or "yum" in their names.
-
-You will need to download the RPMs above or RPM can be given the URLs for
-them and it will fetch them for you.  Either way, the commands similar
-to the following will install the common or base RPMs required.
-
- at example
-rpm -U @value{RTEMSRPMPREFIX}-release-<VERSION>-<RPM>.<DIST>.noarch.rpm \
-       @value{RTEMSRPMPREFIX}-yum-conf-<VERSION>-<RPM>.<DIST>.noarch.rpm
- at end example
-
-Once these are installed, Yum knows about the RTEMS Yum repository
-for @value{RTEMSPREFIX}.  This means that you can install and upgrade
-RTEMS Toolsets just like the packages provided by your distribution.
-To install complete C and C++ toolset targeting the SPARC architecture
-for the RTEMS @value{RTEMSAPI} Release series, commands similar to the
-following will be used.
-
- at example
-yum install @value{RTEMSPREFIX}-auto*
-yum install @value{RTEMSPREFIX}-sparc-*
- at end example
-
-The first command installs GNU autoconf and automake which are used
-by all RTEMS targets.  The second command installs the complete
-sparc- at value{RTEMSPREFIX} toolset including all dependencies.
-
- at subsubsection Removing RPMs Using Yum
-
-The following is a sample session illustrating the removal of a C/C++
-toolset targeting the SPARC architecture.
-
- at example
-yum erase @value{RTEMSRPMPREFIX}-sparc-*
- at end example
-
-If this is the last target architecture for which tools are installed, then you can remove the RTEMS GNU autotools and common packages as follows:
-
- at example
-yum erase @value{RTEMSRPMPREFIX}-auto*
-yum erase @value{RTEMSRPMPREFIX}-*common*
- at end example
-
-NOTE:  If you have installed any RTEMS BSPs, then it is likely that RPM
-will complain about not being able to remove everything.  These will
-have to be removed by hand.
-
- at subsection Managing RPMs Without Using Yum
-
-This section describes how to install and remove RTEMS Toolsets without
-using Yum.  This is NOT expected to be the norm for RPM users.
-
- at subsubsection Installing RPMs Without Yum
-
-The following is a sample session illustrating the installation of the
-complete C and C++ toolset targeting the SPARC architecture for the
-RTEMS @value{RTEMSAPI} Release series.
-
-Since you are not using Yum, you will need to download all of the RPMs
-you will install.  Alternatively, RPM can be given a URL for an RPM file
-and it will fetch it for you.  Either way, the commands similar to the
-following will install the common or base RPMs required.
-
- at example
-rpm -U @value{RTEMSRPMPREFIX}binutils-common-<VERSION>-<RPM>.<DIST>.noarch.rpm \
-       @value{RTEMSRPMPREFIX}gcc-common-<VERSION>-<RPM>.<DIST>.noarch.rpm \
-       @value{RTEMSRPMPREFIX}newlib-common-<VERSION>-<RPM>.<DIST>.noarch.rpm \
-       @value{RTEMSRPMPREFIX}gdb-common-<VERSION>-<RPM>.<DIST>.noarch.rpm
- at end example
-
-The above RPMs are shared across all RTEMS targets and include common
-files such as the documentation.  The following illustrates how to install
-the GNU Autoconf and Automake RPMs that match your RTEMS installation.
-RTEMS uses the GNU Autotools for its configure and build infrastructure
-and you will need these if you modify the build infrastructure or check
-out RTEMS from CVS and have to bootstrap the source tree.
-
- at example
-rpm -U @value{RTEMSRPMPREFIX}autoconf-<VERSION>-<RPM>.<DIST>.noarch.rpm \
-       @value{RTEMSRPMPREFIX}automake-<VERSION>-<RPM>.<DIST>.noarch.rpm
- at end example
-
-Now that you have installed all of the RPMs that are independent of the
-target architecture you can install the C toolset for a specific target.
-The following command will install the target architecture specific set
-of the RPMs for a C toolset including GDB.
-
- at example
-rpm -U @value{RTEMSRPMPREFIX}sparc-rtems at value{RTEMSAPI}-binutils-<VERSION>-<RPM>.<ARCH>.rpm \
-       @value{RTEMSRPMPREFIX}sparc-rtems at value{RTEMSAPI}-gcc-<VERSION>-<RPM>.<ARCH>.rpm \
-       @value{RTEMSRPMPREFIX}sparc-rtems at value{RTEMSAPI}-newlib-<VERSION>-<RPM>.<ARCH>.rpm \
-       @value{RTEMSRPMPREFIX}sparc-rtems at value{RTEMSAPI}-libgcc-<VERSION>-<RPM>.<ARCH>.rpm \
-       @value{RTEMSRPMPREFIX}sparc-rtems at value{RTEMSAPI}-gdb-<VERSION>-<RPM>.<ARCH>.rpm
- at end example
-
-The following command illustrates how to install the C++ specific portion of the RPMs.
-
- at example
-rpm -U @value{RTEMSRPMPREFIX}sparc-rtems at value{RTEMSAPI}-gcc-c++-<VERSION>-<RPM>.<ARCH>.rpm \
-       @value{RTEMSRPMPREFIX}sparc-rtems at value{RTEMSAPI}-libstd++-<VERSION>-<RPM>.<ARCH>.rpm
- at end example
-
-Upon successful completion of the above command sequence, a C/C++
-cross development toolset targeting the SPARC is installed in
- at code{@value{RTEMSPREFIX}}.  In order to use this toolset, the directory
- at code{@value{RTEMSPREFIX}/bin} should be at the start of your PATH.
-At this point, the tools are installed for a specific target architecture
-adn you may proceed directly to @ref{Building RTEMS}.
-
-If you want to build RTEMS for multiple target architectures, you will
-need to install the target specific portion of the RPMs for each target.
-
- at subsubsection Removing RPMs Without Using Yum
-
-The following is a sample session illustrating the removal of a C/C++
-toolset targeting the SPARC architecture.
-
- at example
-rpm -e `rpm -qa | grep @value{RTEMSRPMPREFIX}-sparc-`
- at end example
-
-If this is the last target architecture for which tools are installed, then you can remove the RTEMS GNU autotools and common packages as follows:
-
- at example
-rpm -e `rpm -qa | grep @value{RTEMSRPMPREFIX}-auto`
-rpm -e `rpm -qa | grep @value{RTEMSRPMPREFIX} | grep common`
- at end example
-
-NOTE:  If you have installed any RTEMS BSPs, then it is likely that RPM
-will complain about not being able to remove everything.  These will
-have to be removed by hand.
-
- at subsection Determining Which RTEMS RPMs are Installed
-
-The following command will report which RTEMS RPMs are currently
-installed:
-
- at example
-rpm -qa | grep @value{RTEMSAPI}
- at end example
-
- at section Zipped Tar Files
-
-The tool binaries for some hosts are provided as compressed tar files.
-This section provides information on installing and removing Zipped Tar
-Files (e.g .tar.gz or .tar.bz2).
-
- at subsection Installing Zipped Tar Files
-
-The following is a sample session illustrating the installation
-of a C/C++ toolset targeting the SPARC architecture assuming
-that GNU tar is installed as @code{tar} for a set of archive
-files compressed with GNU Zip (gzip):
-
- at example
-cd /
-tar xzf @value{RTEMSRPMPREFIX}binutils-common-<VERSION>-<RPM>.tar.gz
-tar xzf @value{RTEMSRPMPREFIX}sparc-rtems at value{RTEMSAPI}-binutils-<VERSION>-<RPM>.tar.gz
-tar xzf @value{RTEMSRPMPREFIX}gcc-common-<VERSION>-<RPM>.tar.gz
-tar xzf @value{RTEMSRPMPREFIX}sparc-rtems at value{RTEMSAPI}-gcc-<VERSION>-<RPM>.tar.gz
-tar xzf @value{RTEMSRPMPREFIX}sparc-rtems at value{RTEMSAPI}-newlib-<VERSION>-<RPM>.tar.gz
-tar xzf @value{RTEMSRPMPREFIX}gdb-common-<VERSION>-<RPM>.tar.gz
-tar xzf @value{RTEMSRPMPREFIX}sparc-rtems at value{RTEMSAPI}-gdb-<VERSION>-<RPM>.tar.gz
- at end example
-
-The following command set is the equivalent command sequence
-for the same toolset assuming that is was compressed with
-GNU BZip (bzip2):
-
- at example
-cd /
-tar xjf @value{RTEMSRPMPREFIX}binutils-common-<VERSION>-<RPM>.tar.bz2
-tar xjf @value{RTEMSRPMPREFIX}sparc-rtems at value{RTEMSAPI}-binutils-<VERSION>-<RPM>.tar.bz2
-tar xjf @value{RTEMSRPMPREFIX}gcc-common-<VERSION>-<RPM>.tar.bz2
-tar xjf @value{RTEMSRPMPREFIX}sparc-rtems at value{RTEMSAPI}-newlib-<VERSION>-<RPM>.tar.bz2
-tar xjf @value{RTEMSRPMPREFIX}sparc-rtems at value{RTEMSAPI}-gcc-<VERSION>-<RPM>.tar.bz2
-tar xjf @value{RTEMSRPMPREFIX}gdb-common-<VERSION>-<RPM>.tar.bz2
-tar xjf @value{RTEMSRPMPREFIX}sparc-rtems at value{RTEMSAPI}-gdb-<VERSION>-<RPM>.tar.bz2
- at end example
-
-Upon successful completion of the above command sequence, a
-C/C++ cross development toolset targeting the SPARC is
-installed in @code{@value{RTEMSPREFIX}}.  In order to use this toolset,
-the directory @code{@value{RTEMSPREFIX}} must be included in your
-PATH.
-
- at subsection Removing Zipped Tar Files
-
-There is no automatic way to remove the contents of a @code{tar.gz} 
-or @code{tar.bz2} once it is installed.  The contents of the directory
- at code{@value{RTEMSPREFIX}} can be removed but this will likely result
-in other packages being removed as well.
-
-
diff --git a/doc/started/buildc.t b/doc/started/buildc.t
index a16c9f2..b4544ab 100644
--- a/doc/started/buildc.t
+++ b/doc/started/buildc.t
@@ -3,827 +3,14 @@
 @c  On-Line Applications Research Corporation (OAR).
 @c  All rights reserved.
 
- at chapter Building the GNU Cross Compiler Toolset
+ at chapter Building the GNU Cross Compiler Toolset with RSB
 
- at b{NOTE}:  This chapter describes the steps required to build cross-compilation
-toolset on Linux (and possibly Windows using Cygwin) systems.  This chapter
-does @b{NOT} apply if you installed prebuilt toolset executables for BINUTILS,
-GCC, NEWLIB, and GDB.  If you installed prebuilt executables for all of those,
-proceed to @ref{Building RTEMS}.  If you require a GDB with a special
-configuration to connect to your target board, then proceed to
- at ref{Installing GDB Without RPM} for some advice.
+The RTEMS Projects recommends using the RTEMS Source Builder (RSB)
+for building the toolset from source. RSB has evolved over time from
+various instructions and scripts for building the toolset, and it removes
+much of the frustration associated with building the toolset from source.
+Although prebuilt binaries are much easier to install, they are harder
+for the RTEMS Project to support.
 
-This chapter describes the steps required to acquire the source code for
-a GNU cross compiler toolset, apply any required RTEMS specific patches,
-compile that toolset and install it.
+Documentation for RSB is available from @uref{https://docs.rtems.org/rsb/,https://docs.rtems.org/rsb/}.
 
-It is recommended that when toolset binaries are available for your
-particular host, that they be used.  Prebuilt binaries are much easier
-to install.  They are also much easier for the RTEMS Project to support.
-
- at c
- at c  Preparation
- at c
- at section Preparation
-
-Before you can build an RTEMS toolset from source, there are some
-preparatory steps which must be performed.  You will need to determine
-the various tool versions and patches required and download them  You
-will also have to unarchive the source and apply any patches.
-
- at c
- at c  Determining Tool Version and Patch Revision
- at c
- at subsection Determining Tool Version and Patch Revision
-
-The tool versions and patch revisions change on a fairly frequent basis.
-In addition, these may vary based upon the target architecture.  In some
-cases, the RTEMS Project may have to stick with a particular version
-of a tool to provide a working version for a specific architecture.
-Because of this, it is impossible to provide this information in a
-complete and accurate manner in this manual.  You will need to refer
-to the configuration files used by the RTEMS RPM specification files to
-determine the current versions and, if a patch is required, what version.
-This section describes how to locate the appropriate tool versions and
-patches for a particular target architecture.
-
-All patches and RPM specification files are kept under source code
-control.  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://wiki.rtems.org/wiki/index.php/RTEMS_GIT_Repository,
-http://wiki.rtems.org/wiki/index.php/RTEMS_GIT_Repository} and look for
-instructions on accessing the RTEMS Source Code Repository in read-only
-mode.
-
-In the checked out source code, you will need to look in the subdirectory
- at code{contrib/crossrpms/autotools} to determine the versions of AUTOCONF
-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 (AUTOCONF_VERS and AUTOMAKE_VERS respectively).  Then
-examine the following files to determine the master location for the source
-tarballs and to determine if a patch is required for each tool version cited in
-the @code{Makefile.am}.
-
- at example
-autoconf-sources.add
-automake-sources.add
- at end example
-
-If any patches are required, they will be in the
- at 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
- at code{contrib/crossrpms/rtems at value{RTEMSAPI}} to determine the target
-specific tool versions and patches required. In this directory, you
-will find a number of subdirectories with many named after target
-architectures supported by RTEMS.  Descend into the directory for the
-architecture you plan to build tools for.  Again, the @code{Makefile.am}
-defines the tool versions for this architecture and RTEMS Release Series.
-Make a note of the version numbers required for BINUTILS, GCC, NEWLIB,
-and GDB.  Then examine the following files to determine the master
-location for the source tarballs and to determine if a patch is required
-for each tool version cited in the @code{Makefile.am}.
-
- at itemize
- at item binutils-sources.add
- at item gcc-sources.add
- at item gdb-sources.add
- at end itemize
-
-If any patches are required, they will be in the
- at code{contrib/crossrpms/patches} subdirectory of your checked out RTEMS
-source tree.
-
-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.
-
- at c
- at c  Obtain Source and Patches
- at c
- at subsection Obtain Source and Patches
-
-You will need to download the sources for the various packages from
-their master locations as identified in the previous section.
-
-Any patches needed should be in the @code{contrib/crossrpms/patches}
-directory of your RTEMS source.
-
- at c
- at c  Installing the Tools Without RPM
- at c
- at section Installing the Tools Without RPM
-
-This section describes the procedure for building and installing an RTEMS
-cross toolset from source code without using the RPM build infrastructure.
-
-Direct invocation of @code{configure} and @code{make} provides more control
-and easier recovery from problems when building.
-
- at c
- at c Archive and Build Directory Format
- at c
- at subsection Archive and Build Directory Format
-
-When no packaging format requirements are present, the root directory for
-the storage of source archives and patches as well as for building the
-tools is up to the user.  The only concern is that there be enough
-disk space to complete the build.  In this document, the following
-organization will be used.
-
-Make an @code{archive} directory to contain the downloaded source code
-and pataches.  Additionally, a @code{tools} directory to be used as a
-build directory.  The command sequence to do this is shown below:
-
- at example
-mkdir archive
-mkdir tools
- at end example
-
-This will result in an initial directory structure similar to the
-one shown in the following figure:
-
- at example
- at group
-/whatever/prefix/you/choose/
-        archive/
-        tools/
-
- at end group
- at end example
-
-The RTEMS Project tries to submit all of our patches upstream to the
-parent projects.  In the event there are patches, the master copy of them
-is located in the appropriate branch of the RTEMS source module in CVS.
-Patches are in the @code{contrib/crossrpms/patches}.
-
- at c
- at c  Unarchiving the Tools
- at c
- at subsection Unarchiving the Tools
-
- at 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.
-
-GNU source distributions are archived using @code{tar} and
-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.
-
-While in the @code{tools} directory, unpack the compressed tar files
-using the appropriate command based upon the compression program used.
-
- at example
-cd tools
-tar xzf ../archive/TOOLNAME.tar.gz  # for gzip'ed tools
-tar xjf ../archive/TOOLNAME.tar.bz2 # for bzip'ed tools
- at end example
-
-Assuming you are building a complete toolset, after all of the the
-compressed tar files have been unpacked using the appropriate commands,
-the following directories will have been created under @code{tools}.
-
- at itemize @bullet
- at item autoconf-<VERSION>
- at item automake-<VERSION>
- at item binutils-<VERSION>
- at item gcc-<VERSION>
- at item newlib-<VERSION>
- at item gdb-<VERSION>
- at end itemize
-
-The tree should look something like the following figure:
-
- at example
- at group
-/whatever/prefix/you/choose/
-        archive/
-          variable tarballs
-          variable patches
-        tools/
-          various tool source trees
- at end group
- at end example
-
- at c
- at c Applying RTEMS Project Tool Patches
- at c
-
- at subsection Applying RTEMS Project Tool Patches
-
- at 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, it is placed in the
- at code{contrib/crossrpms/patches} directory in the CVS tree.  Make sure the
-patch version is the same as of the tool you are building.  You will perform a
-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.
-
- at example
-cd tools/<TOOL>
-cat ../../archive/<TOOL_PATCH> | patch -p1
- at end example
-
- at 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.
-
-If the patch was compressed with the @code{gzip} program, it will
-have a suffix of @code{.gz} and you should use @code{zcat} instead
-of @code{cat} as shown above.  If the patch was compressed with
-the @code{gzip} program, it will have a suffix of @code{.bz2} and
-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:
-
- at example
-cd tools/<TOOL>
-find . -name "*.rej" -print
- at end example
-
-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.
-
- at c
- at c  Installing AUTOCONF From Source
- at c
-
- at 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.
-
- at 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.
-
- at example
-mkdir b-autoconf
-cd b-autoconf
-../autoconf-<VERSION>/configure --prefix=@value{RTEMSPREFIX}
-make
-make install
- at end example
-
-After autoconf-<VERSION> is built and installed the build directory
- at code{b-autoconf} may be removed.
-
-For more information on the invocation of @code{configure}, please
-refer to the documentation for autoconf-<VERSION> or invoke the
-autoconf-VERSION> @code{configure} command with the @code{--help} option.
-
- at c
- at c  Installing AUTOMAKE From Source
- at c
-
- at 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
-installed as a native utility and is independent of any RTEMS target.
-
- at example
-mkdir b-automake
-cd b-automake
-../automake-<VERSION>/configure --prefix=@value{RTEMSPREFIX}
-make all
-make info
-make install
- at end example
-
-After automake-<VERSION> is built and installed the build directory
- at code{b-automake} may be removed.
-
-For more information on the invocation of @code{configure}, please
-refer to the documentation for automake-<VERSION> or invoke the
-automake-VERSION> @code{configure} command with the @code{--help} option.
-
- at c
- at c  Installing BINUTILS From Source
- at c
- at subsection Installing BINUTILS From Source
-
-The following example illustrates the invocation of @code{configure}
-and @code{make} to build and install binutils-<version>
-sparc-rtems at value{RTEMSAPI} target:
-
- at example
-mkdir b-binutils
-cd b-binutils
-../binutils-<VERSION>/configure --target=sparc-rtems at value{RTEMSAPI} \
-  --prefix=@value{RTEMSPREFIX}
-make all
-make info
-make install
- at end example
-
-After binutils-<VERSION> is built and installed the build directory
- at code{b-binutils} may be removed.
-
-For more information on the invocation of @code{configure}, please
-refer to the documentation for binutils-<VERSION> or invoke the
-binutils-VERSION> @code{configure} command with the @code{--help} option.
-
-NOTE: The shell PATH variable needs to be updated to include the path
-the binutils user executables have  been installed in.  The directory
-containing the executables is the prefix used above with
- at file{bin} post-fixed.
-
- at example
-export PATH=@value{RTEMSPREFIX}/bin:$@{PATH@}
- at end example
-
-As you will need to frequently run various commands in the
- at value{RTEMSPREFIX}/bin, you can update your @code{~/.bashrc} to include this
-line. After doing that, don't forget to run
- at example
-source ~/.bashrc
- at 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:
-
- at example
-sparc-rtems at value{RTEMSAPI}-ar: command not found
- at end example
-
- at c
- at c  Installing GCC and NEWLIB Without RPM
- at c
- at subsection Installing GCC and NEWLIB Without RPM
-
-Before building gcc-<VERSION> and newlib-<VERSION>,
-binutils-<VERSION> must be installed and the directory
-containing those executables must be in your PATH.
-
-The C Library is built as a subordinate component of
-gcc-<VERSION>.  Because of this, the newlib-<VERSION>
-directory source must be available inside the gcc-<VERSION>
-source tree.  This is normally accomplished using a symbolic
-link as shown in this example:
-
- at example
-cd gcc-<VERSION>
-ln -s ../newlib-<VERSION>/newlib .
- at end example
-
-The following example illustrates the invocation of
- at code{configure} and @code{make}
-to build and install gcc-<VERSION> with only
-C and C++ support for the sparc-rtems at value{RTEMSAPI} target:
-
- at example
-mkdir b-gcc
-cd b-gcc
-../gcc-<VERSION>/configure --target=sparc-rtems at value{RTEMSAPI} \
-   --with-gnu-as --with-gnu-ld --with-newlib --verbose \
-   --enable-threads --enable-languages="c,c++" \
-   --prefix=@value{RTEMSPREFIX}
-make all
-make info
-make install
- at end example
-
-After gcc-<VERSION> is built and installed the
-build directory @code{b-gcc} may be removed.
-
-For more information on the invocation of @code{configure}, please
-refer to the documentation for gcc-<VERSION> or
-invoke the gcc-<VERSION> @code{configure} command with the
- at code{--help} option.
-
- at c
- at c Building GCC with Ada Support
- at c
- at subsection Building GCC with Ada Support
-
-If you want a GCC toolset that includes support for Ada
-(e.g. GNAT), there are some additional requirements on
-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
-the same version of GNAT itself.
-
-It is also important to verify whether there is an RTEMS specific
-Ada patch required for GCC.  These can be found in
- at uref{http://www.rtems.org/ftp/pub/rtems/people/joel/ada,
-http://www.rtems.org/ftp/pub/rtems/people/joel/ada}.  The patch is
-often a minor version or two behind GCC but will usually apply cleanly.
-This patch must be applied.
-
-After this, it is critical to perform these steps in the correct order.
-GNAT requires that the C Library and RTEMS itself be installed before
-the language run-time can be built.
-
- at itemize @bullet
- at item install native GCC with GNAT
- at item place new native GNAT at head of PATH
- at item install BINUTILS
- at item place RTEMS prefix at head of PATH
- at item install C toolset (C++ is optional)
- at item install RTEMS built multilib
- at item install RTEMS built for your BSP
- at end itemize
-
-The build procedure is the same until the Ada configure step.  A GCC
-toolset with GNAT enabled requires that @code{ada} be included in the set
-of enabled languages.  The following example illustrates the invocation of
- at code{configure} and @code{make} to build and install gcc-<VERSION> with
-only C, C++, and Ada support for the sparc-rtems at value{RTEMSAPI} target:
-
- at example
-mkdir b-gcc
-cd b-gcc
-../gcc-<VERSION>/configure --target=sparc-rtems at value{RTEMSAPI} \
-   --with-gnu-as --with-gnu-ld --with-newlib --verbose \
-   --enable-threads --enable-languages="c,c++,ada" \
-   --prefix=@value{RTEMSPREFIX}
-make all
-make info
-make install
- at end example
-
-After gcc-<VERSION> is built and installed the build directory
- at code{b-gcc} may be removed.
-
- at c
- at c Installing GDB Without RPM
- at c
- at subsection Installing GDB Without RPM
-
- at b{NOTE}:  This step is NOT required if prebuilt executables for the
-GDB were installed and they meet your target interface
-requirements.
-
-GDB supports many configurations but requires some means of communicating
-between the host computer and target board.  This communication can be via
-a serial port, Ethernet, BDM, or ROM emulator.  The communication protocol
-can be the GDB remote protocol or GDB can talk directly to a ROM monitor.
-This setup is target board specific.  Some of the configurations that have
-been successfully used with RTEMS applications are:
-
- at itemize @bullet
- at item BDM with ColdFire, 683xx, MPC860 CPUs
- at item Motorola Mxxxbug found on M68xxx VME boards
- at item Motorola PPCbug found on PowerPC VME, CompactPCI, and MTX boards
- at item ARM based Cogent EDB7312
- at item PC's using various Intel and AMD CPUs including i386,
-i486, Pentium and above, and Athlon
- at item PowerPC Instruction Simulator in GDB (PSIM)
- at item MIPS Instruction Simulator in GDB (JMR3904)
- at item Sparc Instruction Simulator in GDB (SIS)
- at item Sparc Instruction Simulator (TSIM)
- at end itemize
-
-GDB is currently RTEMS thread/task aware only if you are using the
-remote debugging support via Ethernet.  These are configured
-using gdb targets of the form CPU-RTEMS.  Note the capital RTEMS.
-
-It is recommended that when toolset binaries are available for
-your particular host, that they be used.  Prebuilt binaries
-are much easier to install but in the case of gdb may or may
-not include support for your particular target board.
-
-The following example illustrates the invocation of @code{configure}
-and @code{make} to build and install gdb-<VERSION> for the
-m68k-rtems at value{RTEMSAPI} target:
-
- at example
-mkdir b-gdb
-cd b-gdb
-../gdb-<VERSION>/configure --target=m68k-rtems at value{RTEMSAPI} \
-  --prefix=@value{RTEMSPREFIX}
-make all
-make info
-make install
- at end example
-
-For some configurations, it is necessary to specify extra options
-to @code{configure} to enable and configure option components
-such as a processor simulator.  The following is a list of
-configurations for which there are extra options:
-
- at table @b
- at item powerpc-rtems at value{RTEMSAPI}
- at code{--enable-sim --enable-sim-powerpc --enable-sim-timebase --enable-sim-hardware}
-
- at item sparc-rtems at value{RTEMSAPI}
- at code{--enable-sim}
-
- at end table
-
-After gdb-<VERSION> is built and installed the
-build directory @code{b-gdb} may be removed.
-
-For more information on the invocation of @code{configure}, please
-refer to the documentation for gdb-<VERSION> or
-invoke the gdb-<VERSION> @code{configure} command with the
- at code{--help} option.
-
-
- at c
- at c  Using RPM to Build Tools
- at c
-
- at section Using RPM to Build Tools
-
-RPM is a packaging format which can be used to distribute binary files as
-well as to capture the procedure and source code used to produce those
-binary files.  For RPM, it is assumed that the following subdirectories
-are under a root directory such as @code{/usr/src/redhat} or
- at code{/usr/local/src/redhat}) on your machine.
-
- at example
-BUILD
-RPMS
-SOURCES
-SPECS
-SRPMS
- at end example
-
-For the purposes of this document, the RPM @code{SOURCES} directory is the
-directory into which all tool source and patches are assumed to reside.
-The @code{BUILD} directory is where the actual build is performed when
-building binaries from a source RPM.
-
-RPM automatically unarchives the source and applies any needed patches
-so you do @b{NOT} have to manually perform the procedures described
- at ref{Unarchiving the Tools} and @ref{Applying RTEMS Project Tool Patches}.
-But you are responsible for placing all source tarballs
-and patches in the @code{SOURCES} directory per the instructions in
- at ref{Obtain Source and Patches}
-
-This procedure starts by installing the source (e.g. @code{.src.rpm}
-extension) RPMs.  The RTEMS tool source RPMS are called "nosrc" to
-indicate that one or more source files required to produce the RPMs
-are not present.  The RTEMS source RPMs typically include all required
-patches, but do not include the large @code{.tar.gz} or @code{.tgz} files
-for each component such as BINUTILS, GCC, or NEWLIB.  These are shared
-by all RTEMS RPMs regardless of target CPU and there was no reason to
-duplicate them.  You will have to get the required source archive files
-by hand and place them in the @code{SOURCES} directory before attempting
-to build.  If you forget to do this, RPM is smart -- it will tell you
-what is missing. You can fetch any missing files and try again.
-
- at c
- at c  Building AUTOCONF using RPM
- at c
- at subsection Building AUTOCONF using RPM
-
-This section illustrates the invocation of RPM to build a new, locally
-compiled, AUTOCONF binary RPM that matches the installed source RPM.
-This example assumes that all of the required source is installed.
-
- at example
-rpm -U @value{RTEMSRPMPREFIX}i386-rtems at value{RTEMSAPI}-autoconf-<VERSION>-<RPM_RELEASE>.src.rpm
- at end example
-
- at example
-cd <RPM_ROOT_DIRECTORY>/SPECS
-rpm -bb i386-rtems at value{RTEMSAPI}-autoconf-<VERSION>.spec
- at end example
-
-If the build completes successfully, RPMS like the following will be
-generated in a build-host architecture specific subdirectory of the RPMs
-directory under the RPM root directory.
-
- at example
- at value{RTEMSRPMPREFIX}rtems at value{RTEMSAPI}-autoconf-<VERSION>-<RPM_RELEASE>.<ARCH>.rpm
- at end example
-
- at b{NOTE}:  It may be necessary to remove the build tree in the @code{BUILD}
-directory under the RPM root directory.
-
- at c
- at c  Building AUTOMAKE using RPM
- at c
- at subsection Building AUTOMAKE using RPM
-
-This section illustrates the invocation of RPM to build a new, locally
-compiled, AUTOMAKE binary RPM that matches the installed source RPM.
-This example assumes that all of the required source is installed.
-
- at example
-rpm -U @value{RTEMSRPMPREFIX}i386-rtems at value{RTEMSAPI}-automake-<VERSION>-<RPM_RELEASE>.src.rpm
- at end example
-
- at example
-cd <RPM_ROOT_DIRECTORY>/SPECS
-rpm -bb i386-rtems at value{RTEMSAPI}-automake-<VERSION>.spec
- at end example
-
-If the build completes successfully, RPMS like the following will be
-generated in a build-host architecture specific subdirectory of the RPMs
-directory under the RPM root directory.
-
- at example
- at value{RTEMSRPMPREFIX}rtems at value{RTEMSAPI}-automake-<VERSION>-<RPM_RELEASE>.<ARCH>.rpm
- at end example
-
- at b{NOTE}:  It may be necessary to remove the build tree in the @code{BUILD}
-directory under the RPM root directory.
-
-
- at c
- at c  Building BINUTILS using RPM
- at c
- at subsection Building BINUTILS using RPM
-
-This section illustrates the invocation of RPM to build a new, locally
-compiled, binutils binary RPM that matches the installed source RPM.
-This example assumes that all of the required source is installed.
-
- at example
-rpm -U @value{RTEMSRPMPREFIX}i386-rtems at value{RTEMSAPI}-binutils-<VERSION>-<RPM_RELEASE>.src.rpm
- at end example
-
- at example
-cd <RPM_ROOT_DIRECTORY>/SPECS
-rpm -bb i386-rtems at value{RTEMSAPI}-binutils-<VERSION>.spec
- at end example
-
-If the build completes successfully, RPMS like the following will be
-generated in a build-host architecture specific subdirectory of the RPMS
-directory under the RPM root directory.
-
- at example
- at value{RTEMSRPMPREFIX}binutils-common-<VERSION>-<RPM_RELEASE>.<ARCH>.rpm
- at value{RTEMSRPMPREFIX}i386-rtems at value{RTEMSAPI}-binutils-<VERSION>-<RPM_RELEASE>.<ARCH>.rpm
- at end example
-
-NOTE: It may be necessary to remove the build tree in the @code{BUILD}
-directory under the RPM root directory.
-
- at c
- at c  Building GCC and NEWLIB using RPM
- at c
- at subsection Building GCC and NEWLIB using RPM
-
-This section illustrates the invocation of RPM to build a new,
-locally compiled, set of GCC and NEWLIB binary RPMs that match the
-installed source RPM.  It is also necessary to install the BINUTILS
-RPMs and place them in your PATH.  This example assumes that all of
-the required source is installed.
-
- at example
-cd <RPM_ROOT_DIRECTORY>/SPECS
-rpm -bb i386-rtems at value{RTEMSAPI}-gcc-<VERSION>.spec
- at end example
-
-If the build completes successfully, a set of RPMS like the following will
-be generated in a build-host architecture specific subdirectory
-of the RPMS directory under the RPM root directory.
-
- at example
- at value{RTEMSRPMPREFIX}gcc-common-<VERSION>-<RPM>.<DIST>.noarch.rpm \
- at value{RTEMSRPMPREFIX}newlib-common-<VERSION>-<RPM>.<DIST>.noarch.rpm \
- at value{RTEMSRPMPREFIX}i386-rtems at value{RTEMSAPI}-gcc-<VERSION>-<RPM>.<ARCH>.rpm \
- at value{RTEMSRPMPREFIX}i386-rtems at value{RTEMSAPI}-newlib-<VERSION>-<RPM>.<ARCH>.rpm \
- at value{RTEMSRPMPREFIX}i386-rtems at value{RTEMSAPI}-libgcc-<VERSION>-<RPM>.<ARCH>.rpm \
- at value{RTEMSRPMPREFIX}i386-rtems at value{RTEMSAPI}-gcc-c++-<VERSION>-<RPM>.<ARCH>.rpm \
- at value{RTEMSRPMPREFIX}i386-rtems at value{RTEMSAPI}-libstd++-<VERSION>-<RPM>.<ARCH>.rpm
- at end example
-
- at b{NOTE}: Some targets do not support building all languages.
-
- at b{NOTE}: It may be necessary to remove the build tree in the
- at code{BUILD} directory under the RPM root directory.
-
- at c
- at c Building the GDB using RPM
- at c
- at subsection Building the GDB using RPM
-
-The following example illustrates the invocation of RPM to build a new,
-locally compiled, binutils binary RPM that matches the installed source
-RPM.  This example assumes that all of the required source is installed.
-
-
- at example
-rpm -U @value{RTEMSRPMPREFIX}i386-rtems at value{RTEMSAPI}-gdb-<VERSION>-<RPM_RELEASE>.src.rpm
- at end example
-
- at example
-cd <RPM_ROOT_DIRECTORY>/SPECS
-rpm -bb i386-rtems at value{RTEMSAPI}-gdb-<VERSION>.spec
- at end example
-
-If the build completes successfully, RPMS like the following will
-be generated in a build-host architecture specific subdirectory
-of the RPMS directory under the RPM root directory.
-
- at example
- at value{RTEMSRPMPREFIX}gdb-common-<VERSION>-<RPM_RELEASE>.<ARCH>.rpm
- at value{RTEMSRPMPREFIX}i386-rtems at value{RTEMSAPI}-gdb-<VERSION>-<RPM_RELEASE>.<ARCH>.rpm
- at end example
-
- at b{NOTE}: It may be necessary to remove the build tree in the
- at code{BUILD} directory under the RPM root directory.
-
- at c
- at c Common Problems
- at c
-
- at section Common Problems
-
- at subsection Error Message Indicates Invalid Option to Assembler
-
-If a message like this is printed then the new cross compiler
-is most likely using the native assembler instead of the cross
-assembler or vice-versa (native compiler using new cross assembler).
-This can occur for one of the following reasons:
-
- at itemize @bullet
-
- at item Binutils Patch Improperly Applied
- at item Binutils Not Built
- at item Current Directory is in Your PATH
-
- at 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
-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
-the new cross gcc (@code{xgcc}) used to build the libraries can not
-find it.  Make sure the build of the binutils succeeded.
-
-If you include the current directory in your PATH, then there
-is a chance that the native compiler will accidentally use
-the new cross assembler instead of the native one.  This usually
-indicates that "." is before the standard system directories
-in your PATH.  As a general rule, including "." in your PATH
-is a security risk and should be avoided.  Remove "." from
-your PATH.
-
- at 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".
-
- at subsection Error Messages Indicating Configuration Problems
-
-If you see error messages like the following,
-
- at itemize @bullet
-
- at item cannot configure libiberty
- at item coff-emulation not found
- at item etc.
-
- at end itemize
-
-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
-does this for the binutils source:
-
- at example
-find binutils-<VERSION> -name config.status -print
- at end example
-
-The solution for this is to execute the command
- at code{make distclean} in each of the GNU tools
-root source directory.  This should remove all
-generated files including Makefiles.
-
-This situation usually occurs when you have previously
-built the tool source for some non-RTEMS target.  The
-generated configuration specific files are still in
-the source tree and the include path specified during
-the RTEMS build accidentally picks up the previous
-configuration.  The include path used is something like
-this:
-
- at example
--I../../binutils-<VERSION>/gcc -I/binutils-<VERSION>/gcc/include -I.
- at end example
-
-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.
diff --git a/doc/started/buildrt.t b/doc/started/buildrt.t
index 5adf547..549e309 100644
--- a/doc/started/buildrt.t
+++ b/doc/started/buildrt.t
@@ -5,6 +5,11 @@
 
 @chapter Building RTEMS
 
+ at b{NOTE}: If you built your toolset with RSB, by default the RSB also 
+builds RTEMS while building the compiler toolset. You may already have
+a built and installed RTEMS in this case, and if not you should check
+the RSB documentation at @uref{https://docs.rtems.org/rsb/,https://docs.rtems.org/rsb/}.
+
 @section Obtain the RTEMS Source Code
 
 This section provides pointers to the RTEMS source code and example
@@ -14,8 +19,8 @@ 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
- at item @uref{http://www.rtems.org/ftp/pub/rtems,http://www.rtems.org/ftp/pub/rtems}
- at item @uref{ftp://www.rtems.org/pub/rtems,ftp://www.rtems.org/pub/rtems}
+ at item @uref{http://ftp.rtems.org/pub/rtems,http://ftp.rtems.org/pub/rtems}
+ at item @uref{ftp://ftp.rtems.org/pub/rtems,ftp://ftp.rtems.org/pub/rtems}
 @end itemize
 
 Associated with each RTEMS Release is a set of example programs.
@@ -47,7 +52,7 @@ Instead of downloading release tarballs you may choose to check out the current
 RTEMS source from the project's source code repository. For details on
 accessing the RTEMS source repository consult:
 
- at uref{http://wiki.rtems.org/wiki/index.php/RTEMS_GIT_Repository, http://wiki.rtems.org/wiki/index.php/RTEMS_GIT_Repository}.
+ at uref{https://devel.rtems.org/wiki/Developer/Git,https://devel.rtems.org/wiki/Developer/Git}.
 
 @section Add <INSTALL_POINT>/bin to Executable PATH
 
@@ -56,8 +61,8 @@ in your search path.  It is important to have the RTEMS toolset first
 in your path to ensure that you are using the intended version of all
 tools.  The following command prepends the directory where
 the tools were installed in a previous step.  If you are using
-binaries provided by the RTEMS Project, the <INSTALL_POINT> will be
- at code{/opt/rtems- at value{RTEMSAPI}}
+binaries installed to @code{/opt/rtems- at value{RTEMSAPI}}, then the
+<INSTALL_POINT> will be @code{/opt/rtems- at value{RTEMSAPI}}
 
 @example
 export PATH=<INSTALL_POINT>/bin:$@{PATH@}
@@ -106,11 +111,9 @@ m68k-rtems at code{RTEMSAPI}-gcc -v -c f.c
 @end example
 
 If this produces messages that indicate the assembly code is not valid,
-then it is likely that you have fallen victim to one of the problems
-described in @ref{Error Message Indicates Invalid Option to Assembler}
-Please do not feel bad about this and do not give up, 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}.
+then it is likely that you have fallen victim to one of the most
+common installation errors and the cross-compiler is not able
+to find the cross assembler and defaults to using the native @code{as}.
 This can result in very confusing error messages.
 
 @section Building RTEMS for a Specific Target and BSP
@@ -162,8 +165,9 @@ the @code{BOARD_SUPPORT_PACKAGE} board.
 @example
 mkdir build-rtems
 cd build-rtems
-../rtems- at value{RTEMSAPI}.VERSION/configure --target=<TARGET_CONFIGURATION> \
-    --disable-posix --disable-networking --disable-cxx \
+../rtems- at value{RTEMSAPI}.VERSION/configure \
+    --target=<TARGET_CONFIGURATION> \
+    --disable-networking \
     --enable-rtemsbsp=<BSP>\
     --prefix=<INSTALL_POINT>
 make all
diff --git a/doc/started/intro.t b/doc/started/intro.t
index 3c10152..d9879e1 100644
--- a/doc/started/intro.t
+++ b/doc/started/intro.t
@@ -136,37 +136,24 @@ The RTEMS Project provides formatted documentation for the primary
 tools in the cross development toolset including BINUTILS, GCC,
 NEWLIB, and GDB with the pre-built versions of those tools.
 
-Much of the documentation is available at other sites on the Internet.
-The following is a list of URLs where one can find HTML versions of
-the GNU manuals:
+Much of the documentation is available at other sites on the Internet,
+for example the GNU manuals are hosted by the Free Software Foundation
+at @uref{http://www.gnu.org/manual/manual.html, http://www.gnu.org/manual/manual.html}.
 
- at table @b
-
- at item Free Software Foundation
- at uref{http://www.gnu.org/manual/manual.html,
-http://www.gnu.org/manual/manual.html}
-
- at item Delorie Software
- at uref{http://www.delorie.com/gnu/docs, http://www.delorie.com/gnu/docs}
-
- at end table
-
-
- at subsection RTEMS Mailing List
+ at subsection RTEMS Mailing Lists
 
 @uref{mailto:@value{RTEMSUSERS}, at value{RTEMSUSERS}}
 
-This is the primary  mailing list for the discussion of issues
-related to RTEMS, including GNAT/RTEMS.  If you have questions
-about RTEMS, wish to make suggestions, track development efforts,
-or just want to pick up hints, this is a good list to monitor.
+The users mailing list is for any and all questions about RTEMS, especially
+those focusing on how to use RTEMS.
 If you would like to browse the thousands of messages in the fifteen
 year archive of the mailing list or subscribe to it, please visit
- at uref{http://www.rtems.org/mailman,http://www.rtems.org/mailman} for
+ at uref{https://lists.rtems.org/mailman/listinfo/users,https://lists.rtems.org/mailman/listinfo/users} for
 more information,
 
- at subsection GCC Mailing Lists
+ at uref{mailto:@value{RTEMSDEVEL}, at value{RTEMSDEVEL}}
+
+The devel mailing list is the place to track ongoing RTEMS development
+and to discuss changes to RTEMS. This list is also where patches are
+submitted.
 
-The GCC Project is hosted at @uref{http://gcc.gnu.org,http://gcc.gnu.org}.
-They maintain multiple mailing lists that are described at the web site
-along with subscription information.
diff --git a/doc/started/require.t b/doc/started/require.t
index 6b52ebb..0e0f7d1 100644
--- a/doc/started/require.t
+++ b/doc/started/require.t
@@ -152,10 +152,3 @@ to at least GNU fileutils version 3.16 to resolve this problem.
 
 @end itemize
 
- at subsection GNU/Linux Distributions using Debian Packaging Format
-
-The RTEMS Project does not currently provide prebuilt toolsets in the Debian packaging format used by the Debian and Ubuntu distributions.  If you are using a distribution using this packaging format, then you have two options for installing the RTEMS toolset.
-
-The first option is to build the toolset from source following the instructions in the @ref{Building the GNU Cross Compiler Toolset}.  This is an approach taken by many users.
-
-Alternatively, it is often possible to extract the contents of the RPM files which contain the portions of the toolset you require.  In this case, you will follow the instructions in @ref{Locating the RPMs for your GNU/Linux Distribution} but assume your distribution is the RedHat Enterprise Linux version which is closest to yours from a shared library perspective.  As of December 2010, this is usually RedHat Enterprise Linux version 5.  As time passes, it is expected that version 6 will be appropriate in more cases.  You will extract the contents of these RPM files using either @code{rpm2cpio} and install them or you may be able to use the @code{alien} tool to convert them to Debian packaging.
diff --git a/doc/started/started.texi b/doc/started/started.texi
index c226787..4d453e6 100644
--- a/doc/started/started.texi
+++ b/doc/started/started.texi
@@ -64,8 +64,7 @@ This is the online version of the Getting Started with RTEMS.
 @menu
 * Introduction::
 * Requirements::
-* Prebuilt Toolset Executables::
-* Building the GNU Cross Compiler Toolset::
+* Building the GNU Cross Compiler Toolset with RSB::
 * Building RTEMS::
 * Building the Sample Applications::
 * Where To Go From Here::
@@ -77,7 +76,6 @@ This is the online version of the Getting Started with RTEMS.
 
 @include intro.texi
 @include require.texi
- at include binaries.texi
 @include buildc.texi
 @include buildrt.texi
 @include sample.texi
-- 
1.9.1



More information about the devel mailing list