Changeset 9aff0a7 in rtems


Ignore:
Timestamp:
Dec 16, 2010, 8:54:34 PM (9 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.9
Children:
3547ed6
Parents:
84d6744
Message:

2010-12-16 Joel Sherrill <joel.sherrilL@…>

  • Makefile.am, configure.ac, common/cpright.texi, common/rtems.texi.in, cpu_supplement/.cvsignore, started/Makefile.am, started/binaries.t, started/buildc.t, started/buildrt.t, started/intro.t, started/nextstep.t, started/nt.t, started/require.t, started/sample.t, started/started.texi: Major update which includes removal of references to specific tool versions and patches.
  • started/tversions.texi.in: Removed.
Location:
doc
Files:
1 deleted
16 edited

Legend:

Unmodified
Added
Removed
  • doc/ChangeLog

    r84d6744 r9aff0a7  
     12010-12-16      Joel Sherrill <joel.sherrilL@OARcorp.com>
     2
     3        * Makefile.am, configure.ac, common/cpright.texi, common/rtems.texi.in,
     4        cpu_supplement/.cvsignore, started/Makefile.am, started/binaries.t,
     5        started/buildc.t, started/buildrt.t, started/intro.t,
     6        started/nextstep.t, started/nt.t, started/require.t,
     7        started/sample.t, started/started.texi: Major update which includes
     8        removal of references to specific tool versions and patches.
     9        * started/tversions.texi.in: Removed.
     10
    1112010-12-16      Joel Sherrill <joel.sherrilL@OARcorp.com>
    212
  • doc/Makefile.am

    r84d6744 r9aff0a7  
    99
    1010SUBDIRS = tools started user bsp_howto porting develenv posix_users \
    11     posix1003.1 filesystem itron3.0 networking ada_user \
     11    posix1003.1 filesystem networking ada_user \
    1212    new_chapters relnotes cpu_supplement shell
    1313
     
    2121    common/treedef.tex common/rtems.texi.in
    2222
     23if USE_HTML
    2324html_imagesdir = $(htmldir)/images
     25endif
    2426
    2527HTML_IMAGES = images/dir-arrow.gif images/dvi.gif images/missing-arrow.gif \
  • doc/common/cpright.texi

    r84d6744 r9aff0a7  
    11@c
    2 @c  COPYRIGHT (c) 1988-2008.
     2@c  COPYRIGHT (c) 1988-2010.
    33@c  On-Line Applications Research Corporation (OAR).
    44@c  All rights reserved.
     
    1818
    1919@vskip 0pt plus 1filll
    20 COPYRIGHT @copyright{} 1988 - 2008.@*
     20COPYRIGHT @copyright{} 1988 - 2010.@*
    2121On-Line Applications Research Corporation (OAR).@*
    2222
     
    3737for RTEMS should be directed to the contacts listed on
    3838that site.  A current list of RTEMS Support Providers
    39 is at @uref{http://www.rtems.com/support.html}.
     39is at @uref{http://www.rtems.com/oarsupport}.
    4040
  • doc/common/rtems.texi.in

    r84d6744 r9aff0a7  
    1212@set RTEMSAPI                   @RTEMSAPI@
    1313@set RTEMSRPMPREFIX             @RTEMSRPMPREFIX@
    14 @set RTEMSRPMGROUP              @RTEMSRPMGROUP@
  • doc/configure.ac

    r84d6744 r9aff0a7  
    138138dnl Checks for library functions.
    139139
    140 AC_MSG_CHECKING([for ./setup.def])
    141 AS_IF([test -f ${srcdir}/setup.def],[
    142 . ${srcdir}/setup.def
    143 AC_MSG_RESULT([done])
    144 ],[
    145 AC_MSG_ERROR([missing])
    146 ])
    147 
    148 AS_IF([test -z "$binutils_patch_version"],
    149 [set_binutils_patch="@clear BINUTILSPATCHVERSION"],
    150 [set_binutils_patch="@set BINUTILSPATCHVERSION $binutils_patch_version"])
    151 
    152 AS_IF([test -z "$newlib_patch_version"],
    153 [set_newlib_patch="@clear NEWLIBPATCHVERSION"],
    154 [set_newlib_patch="@set NEWLIBPATCHVERSION $newlib_patch_version"])
    155 
    156 AS_IF([test -z "$gcc_patch_version"],
    157 [set_gcc_patch="@clear GCCPATCHVERSION"],
    158 [set_gcc_patch="@set GCCPATCHVERSION $gcc_patch_version"])
    159 
    160 AS_IF([test -z "$gdb_patch_version"],
    161 [set_gdb_patch="@clear GDBPATCHVERSION"],
    162 [set_gdb_patch="@set GDBPATCHVERSION $gdb_patch_version"])
    163 
    164140AC_CONFIG_SUBDIRS(tools)
    165141
     
    171147s,@RTEMSPREFIX@,$prefix,;t t
    172148s,@RTEMSRPMPREFIX@,$rpmprefix,;t t
    173 s,@RTEMSRPMGROUP@,RTEMS/]RTEMS_API[,;t t
    174149EOF
    175150_RTEMS_UPDATE_CONDITIONAL([common/rtems.sed],[common/rtems.sed~])
     
    182157bsp_howto/Makefile])
    183158
    184 AC_CONFIG_FILES([started/Makefile],[],[
    185 test -d started || mkdir started
    186 cat << EOF > started/tversions.sed~
    187 :t
    188 s/@GCCVERSION@/$gcc_version/;t t
    189 s/@BINUTILSVERSION@/$binutils_version/;t t
    190 s/@NEWLIBVERSION@/$newlib_version/;t t
    191 s/@GDBVERSION@/$gdb_version/;t t
    192 s/@SETBINUTILSPATCHVERSION@/$set_binutils_patch/;t t
    193 s/@SETGCCPATCHVERSION@/$set_gcc_patch/;t t
    194 s/@SETNEWLIBPATCHVERSION@/$set_newlib_patch/;t t
    195 s/@SETGDBPATCHVERSION@/$set_gdb_patch/;t t
    196 s/@GCCRPMRELEASE@/$gccnewlib_rpm_release/;t t
    197 s/@BINUTILSRPMRELEASE@/$binutils_rpm_release/;t t
    198 s/@GDBRPMRELEASE@/$gdb_rpm_release/;t t
    199 EOF
    200 _RTEMS_UPDATE_CONDITIONAL([started/tversions.sed],[started/tversions.sed~])
    201 ])
    202 
    203159AC_CONFIG_FILES([
    204160porting/Makefile
     
    207163posix1003.1/Makefile
    208164filesystem/Makefile
    209 itron3.0/Makefile
    210165ada_user/Makefile
     166started/Makefile
    211167relnotes/Makefile
    212168new_chapters/Makefile
  • doc/cpu_supplement/.cvsignore

    r84d6744 r9aff0a7  
    11arm.texi
     2avr.texi
    23bfin.texi
    34cpu_supplement
     
    2526i386.texi
    2627index.html
     28lm32.texi
    2729m68k.texi
    2830Makefile
     
    3638sh.texi
    3739sparc.texi
     40sparc64.texi
    3841stamp-vti
    3942states.pdf
     43tic4x.texi
    4044version.texi
  • doc/started/Makefile.am

    r84d6744 r9aff0a7  
    11#
    2 #  COPYRIGHT (c) 1988-2002.
     2#  COPYRIGHT (c) 1988-2010.
    33#  On-Line Applications Research Corporation (OAR).
    44#  All rights reserved.
     
    88
    99PROJECT = started
    10 EDITION = 1
    1110
    1211include $(top_srcdir)/project.am
     
    2322started_TEXINFOS = $(FILES) $(COMMON_FILES) $(GENERATED_FILES)
    2423
    25 intro.texi: intro.t tversions.texi
     24intro.texi: intro.t
    2625        $(BMENU2) -c -p "Top" \
    2726            -u "Top" \
    2827            -n "Requirements" < $< > $@
    2928
    30 require.texi: require.t tversions.texi
     29require.texi: require.t
    3130        $(BMENU2) -c -p "GCC Mailing Lists" \
    3231            -u "Top" \
    3332            -n "Prebuilt Toolset Executables" < $< > $@
    3433
    35 binaries.texi: binaries.t tversions.texi
    36         $(BMENU2) -c -p "Archive and Build Directory Format" \
     34binaries.texi: binaries.t
     35        $(BMENU2) -c \
     36            -p "GNU/Linux Distrobutions using Debian Packaging Format" \
    3737            -u "Top" \
    3838            -n "Building the GNU Cross Compiler Toolset" < $< > $@
    3939
    40 buildc.texi: buildc.t tversions.texi
     40buildc.texi: buildc.t
    4141        $(BMENU2) -c -p "Removing Zipped Tar Files" \
    4242            -u "Top" \
    4343            -n "Building RTEMS" < $< > $@
    4444
    45 buildrt.texi: buildrt.t tversions.texi
     45buildrt.texi: buildrt.t
    4646        $(BMENU2) -c -p "Error Messages Indicating Configuration Problems" \
    4747            -u "Top" \
    4848            -n "Building the Sample Applications" < $< > $@
    4949
    50 sample.texi: sample.t tversions.texi
     50sample.texi: sample.t
    5151        $(BMENU2) -c -p "Using the RTEMS configure Script Directly" \
    5252            -u "Top" \
    5353            -n "Where To Go From Here" < $< > $@
    5454
    55 nextstep.texi: nextstep.t tversions.texi
     55nextstep.texi: nextstep.t
    5656        $(BMENU2) -c -p "More Information on RTEMS Application Makefiles" \
    5757            -u "Top" \
    5858            -n "Using MS-Windows as a Development Host" < $< > $@
    5959
    60 nt.texi: nt.t tversions.texi
     60nt.texi: nt.t
    6161        $(BMENU2) -c -p "Writing an Application" \
    6262            -u "Top" \
     
    8484EXTRA_DIST += $(PICTURES)
    8585
    86 tversions.texi: tversions.texi.in tversions.sed
    87         sed -f tversions.sed $(srcdir)/tversions.texi.in > tversions.texi
    88 CLEANFILES += tversions.texi
    89 
    90 EXTRA_DIST += tversions.texi.in
    91 DISTCLEANFILES = tversions.sed
    92 
    9386CLEANFILES += started.info started.info-?
  • doc/started/binaries.t

    r84d6744 r9aff0a7  
    11@c
    2 @c  COPYRIGHT (c) 1988-2002.
     2@c  COPYRIGHT (c) 1988-2010.
    33@c  On-Line Applications Research Corporation (OAR).
    44@c  All rights reserved.
     
    99@chapter Prebuilt Toolset Executables
    1010
    11 Precompiled toolsets are available for Linux, Cygwin, FreeBSD,
    12 and Solaris.  These are packaged in the following formats:
     11Precompiled toolsets are available for GNU/Linux and MS-Windows.
     12Other hosts will need to build from source.  Packaged binaries are
     13in the following formats:
    1314
    1415@itemize @bullet
    15 @item Linux - RPM
     16@item GNU/Linux - RPM
    1617@item Cygwin - tar.bz2
    17 @item Solaris - tar.bz2
     18@item Mingw - tar.bz2
    1819@end itemize
    1920
    20 RPM is an acronym for the RPM Package Manager.  RPM is the
    21 native package installer for many Linux distributions including
    22 RedHat, SuSE, and Fedora.
     21RPM is an acronym for the RPM Package Manager.  RPM is the native package
     22installer for many GNU/Linux distributions including RedHat Enterprise
     23Linux, Centos, SuSE, and Fedora.
     24
     25The RTEMS Project maintains a Yum Repository which makes it quite simple
     26to install and update RTEMS toolsets.
    2327
    2428The prebuilt binaries are intended to be easy to install and
     
    2832
    2933@enumerate
    30 @item There are dependencies between the various packages.
    31 This requires that certain packages be installed before others may be.
    32 Some packaging formats enforce this dependency.
     34@item There are dependencies between the various packages.  This requires
     35that certain packages be installed before others may be.  Some packaging
     36formats enforce this dependency.
    3337
    3438@item Some packages are target CPU family independent and shared
     
    3640"base" packages.
    3741
    38 @item Depending upon the version of GCC as well as the development
    39 host and target CPU combination, pre-built supplemental packages may
    40 be provided for Ada (gnat), Chill, Java (gcj), Fortran (g77), and
    41 Objective-C (objc).  These binaries are strictly optional.
     42@item Pre-built GNU Binary Utilities (binutils) packages are available
     43for all RTEMS targets.  These include tools such as the assembler and
     44linker and must be installed.
     45
     46@item Pre-built C language packages are available which include a C
     47compiler as well as the Standard C libraries for the embedded RTEMS
     48targets.  These must be installed.
     49
     50@item Pre-built C++ language packages are available for most target
     51architectures which includes a C++ compiler as well as the Standard C++
     52libraries for the embedded RTEMS targets.  These are not part of the
     53minimum installation and need only be installed if the application is
     54using C++.
    4255
    4356@end enumerate
     
    5164This section provides information on installing and removing RPMs.
    5265
    53 @subsection Installing RPMs
    54 
    55 The following is a sample session illustrating the installation
    56 of a C/C++ toolset targeting the SPARC architecture. 
    57 
    58 @example
    59 rpm -U @value{RTEMSRPMPREFIX}binutils-common-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.i386.rpm
    60 rpm -U @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-binutils-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.i386.rpm
    61 rpm -U @value{RTEMSRPMPREFIX}gcc-common-@value{GCCVERSION}-@value{GCCRPMRELEASE}.i386.rpm
    62 rpm -U @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-newlib-@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
    63 rpm -U @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gcc-@value{GCCVERSION}-@value{GCCRPMRELEASE}.i386.rpm
    64 rpm -U @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gcc-c++-@value{GCCVERSION}-@value{GCCRPMRELEASE}.i386.rpm
    65 rpm -U @value{RTEMSRPMPREFIX}gdb-common-@value{GDBVERSION}-@value{GDBRPMRELEASE}.i386.rpm
    66 rpm -U @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gdb-@value{GDBVERSION}-@value{GDBRPMRELEASE}.i386.rpm
    67 @end example
    68 
    69 Upon successful completion of the above command sequence, a
    70 C/C++ cross development toolset targeting the SPARC is
    71 installed in @code{@value{RTEMSPREFIX}}.  In order to use this toolset,
    72 the directory @code{@value{RTEMSPREFIX}/bin} must be included in your
    73 PATH.
    74 
    75 Once you have successfully installed the RPMs for BINUTILS, GCC,
    76 NEWLIB, and GDB, then you may proceed directly to @ref{Building RTEMS}. 
     66Note that RTEMS tools for multiple major versions of RTEMS can be
     67installed in parallel since they are installed into different host
     68directories.  The tools also include the RTEMS Release Series in their
     69name.
     70
     71@subsection Locating the RPMs for your GNU/Linux Distribution
     72
     73The RTEMS Project maintains a Yum Repository of RPMs for its
     74toolsets. Whether you use Yum to install the RPMs or download and install
     75them via another procedure, you will need to locate the appropriate
     76set of RPMs on the RTEMS Yum Repository.  The following instructions
     77are generalized.
     78
     79If your host operating system uses Yum and RPMs, then you will only have
     80to download and install two RPMs by hand
     81
     82@enumerate
     83@item Point your browser at
     84@uref{http://www.rtems.org/ftp/pub/rtems/linux,
     85http://www.rtems.org/ftp/pub/rtems/linux}.  In this directory, you
     86will see a list of RTEMS major versions such as 4.11, 4.10, 4.9, etc..
     87Descend into the appropriate directory for the version of RTEMS you
     88are using.
     89
     90@item Now that you are in the directory for a specific RTEMS major
     91version, you will be presented with a list of GNU/Linux distributions.
     92This will include options like redhat, centos, fedora, and suse.
     93Select the appropriate distribution.
     94
     95@item Now that you are in the directory for your selected distribution,
     96you will be presented with a list of distribution versions for which
     97RTEMS pre-built RPMs are available.  Select the appropriate distribution
     98version.
     99
     100@item Now that you are in the directory for the proper version of
     101your selected distribution, you will be presented with a choice of
     102host architecture versions such as i386, i686, and x86_64.  Select the
     103appropriate version for your development computer.
     104
     105@item At this point, you will have a long list of RPMs to select from.
     106@end enumerate
     107
     108The RTEMS Projects supports a wide variety of host OS and target
     109combinations.  In addition, these toolsets are specific to a particular
     110RTEMS Release Series.  Given the large number of possible combinations,
     111the instructions use variables to indicate where versions go in the real
     112package names you will use.  These variable are used in the examples of
     113RPM version names:
     114
     115@itemize @bullet
     116@item @code{<VERSION>} is the tool version will be found at this location
     117in the RPM name. This will be a release number such as @code{2.20}
     118or @code{4.4.5}.
     119
     120@item @code{<DIST>} indicates the GNU/Linux distribution version.
     121This will be a string such as @code{fc14} or @code{el6}.
     122
     123@item @code{<ARCH>} indicates the architecture used for RPMs on your
     124GNU/Linux installation.  This will be a string such as @code{i386}
     125or @code{x86_64}.
     126
     127@item @code{<RPM>} indicates the RPM revision level.  This will be a
     128single integer.
     129@end itemize
     130
     131The tool VERSION and RPM release may vary within the set of current RPMs for a particular RTEMS Release series based upon the target architecture. 
     132
     133If you are using Yum, please continue to the next section.  If you are
     134downloading the RPMs to install by hand, then go to the @ref{Installing
     135RPMs Without Yum} section.
     136
     137@subsection Managing RPMs Using Yum
     138
     139This section describes how to install and remove RTEMS Toolsets using Yum.
     140
     141@subsubsection Installing RPMs Using Yum
     142
     143If 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:
     144
     145@itemize @bullet
     146@item @value{RTEMSRPMPREFIX}-release-<VERSION>-<RPM>.<DIST>.noarch.rpm
     147@item @value{RTEMSRPMPREFIX}-yum-conf-<VERSION>-<RPM>.<DIST>.noarch.rpm
     148@end itemize
     149
     150You can use the search within page feature of your browser to locate
     151the RPMs with "release" or "yum" in their names.
     152
     153You will need to download the RPMs above or RPM can be given the URLs for
     154them and it will fetch them for you.  Either way, the commands similar
     155to the following will install the common or base RPMs required.
     156
     157@example
     158rpm -U @value{RTEMSRPMPREFIX}-release-<VERSION>-<RPM>.<DIST>.noarch.rpm \
     159       @value{RTEMSRPMPREFIX}-yum-conf-<VERSION>-<RPM>.<DIST>.noarch.rpm
     160@end example
     161
     162Once these are installed, Yum knows about the RTEMS Yum repository
     163for @value{RTEMSPREFIX}.  This means that you can install and upgrade
     164RTEMS Toolsets just like the packages provided by your distribution.
     165To install complete C and C++ toolset targeting the SPARC architecture
     166for the RTEMS @value{RTEMSAPI} Release series, commands similar to the
     167following will be used.
     168
     169@example
     170yum install @value{RTEMSPREFIX}-auto*
     171yum install @value{RTEMSPREFIX}-sparc-*
     172@end example
     173
     174The first command installs GNU autoconf and automake which are used
     175by all RTEMS targets.  The second command installs the complete
     176sparc-@value{RTEMSPREFIX} toolset including all dependencies.
     177
     178@subsubsection Removing RPMs Using Yum
     179
     180The following is a sample session illustrating the removal of a C/C++
     181toolset targeting the SPARC architecture.
     182
     183@example
     184yum erase @value{RTEMSRPMPREFIX}-sparc-*
     185@end example
     186
     187If this is the last target architecture for which tools are installed, then you can remove the RTEMS GNU autotools and common packages as follows:
     188
     189@example
     190yum erase @value{RTEMSRPMPREFIX}-auto*
     191yum erase @value{RTEMSRPMPREFIX}-*common*
     192@end example
     193
     194NOTE:  If you have installed any RTEMS BSPs, then it is likely that RPM
     195will complain about not being able to remove everything.  These will
     196have to be removed by hand.
     197
     198@subsection Managing RPMs Without Using Yum
     199
     200This section describes how to install and remove RTEMS Toolsets without
     201using Yum.  This is NOT expected to be the norm for RPM users.
     202
     203@subsubsection Installing RPMs Without Yum
     204
     205The following is a sample session illustrating the installation of the
     206complete C and C++ toolset targeting the SPARC architecture for the
     207RTEMS @value{RTEMSAPI} Release series.
     208
     209Since you are not using Yum, you will need to download all of the RPMs
     210you will install.  Alternatively, RPM can be given a URL for an RPM file
     211and it will fetch it for you.  Either way, the commands similar to the
     212following will install the common or base RPMs required.
     213
     214@example
     215rpm -U @value{RTEMSRPMPREFIX}binutils-common-<VERSION>-<RPM>.<DIST>.noarch.rpm \
     216       @value{RTEMSRPMPREFIX}gcc-common-<VERSION>-<RPM>.<DIST>.noarch.rpm \
     217       @value{RTEMSRPMPREFIX}newlib-common-<VERSION>-<RPM>.<DIST>.noarch.rpm \
     218       @value{RTEMSRPMPREFIX}gdb-common-<VERSION>-<RPM>.<DIST>.noarch.rpm
     219@end example
     220
     221The above RPMs are shared across all RTEMS targets and include common
     222files such as the documentation.  The following illustrates how to install
     223the GNU Autoconf and Automake RPMs that match your RTEMS installation.
     224RTEMS uses the GNU Autotools for its configure and build infrastructure
     225and you will need these if you modify the build infrastructure or check
     226out RTEMS from CVS and have to bootstrap the source tree.
     227
     228@example
     229rpm -U @value{RTEMSRPMPREFIX}autoconf-<VERSION>-<RPM>.<DIST>.noarch.rpm \
     230       @value{RTEMSRPMPREFIX}automake-<VERSION>-<RPM>.<DIST>.noarch.rpm
     231@end example
     232
     233Now that you have installed all of the RPMs that are independent of the
     234target architecture you can install the C toolset for a specific target.
     235The following command will install the target architecture specific set
     236of the RPMs for a C toolset including GDB.
     237
     238@example
     239rpm -U @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-binutils-<VERSION>-<RPM>.<ARCH>.rpm \
     240       @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gcc-<VERSION>-<RPM>.<ARCH>.rpm \
     241       @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-newlib-<VERSION>-<RPM>.<ARCH>.rpm \
     242       @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-libgcc-<VERSION>-<RPM>.<ARCH>.rpm \
     243       @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gdb-<VERSION>-<RPM>.<ARCH>.rpm
     244@end example
     245
     246The following command illustrates how to install the C++ specific portion of the RPMs.
     247
     248@example
     249rpm -U @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gcc-c++-<VERSION>-<RPM>.<ARCH>.rpm \
     250       @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-libstd++-<VERSION>-<RPM>.<ARCH>.rpm
     251@end example
     252
     253Upon successful completion of the above command sequence, a C/C++
     254cross development toolset targeting the SPARC is installed in
     255@code{@value{RTEMSPREFIX}}.  In order to use this toolset, the directory
     256@code{@value{RTEMSPREFIX}/bin} should be at the start of your PATH.
     257At this point, the tools are installed for a specific target architecture
     258adn you may proceed directly to @ref{Building RTEMS}.
     259
     260If you want to build RTEMS for multiple target architectures, you will
     261need to install the target specific portion of the RPMs for each target.
     262
     263@subsubsection Removing RPMs Without Using Yum
     264
     265The following is a sample session illustrating the removal of a C/C++
     266toolset targeting the SPARC architecture.
     267
     268@example
     269rpm -e `rpm -qa | grep @value{RTEMSRPMPREFIX}-sparc-`
     270@end example
     271
     272If this is the last target architecture for which tools are installed, then you can remove the RTEMS GNU autotools and common packages as follows:
     273
     274@example
     275rpm -e `rpm -qa | grep @value{RTEMSRPMPREFIX}-auto`
     276rpm -e `rpm -qa | grep @value{RTEMSRPMPREFIX} | grep common`
     277@end example
     278
     279NOTE:  If you have installed any RTEMS BSPs, then it is likely that RPM
     280will complain about not being able to remove everything.  These will
     281have to be removed by hand.
    77282
    78283@subsection Determining Which RTEMS RPMs are Installed
     
    82287
    83288@example
    84 rpm -q -g @value{RTEMSRPMGROUP}
    85 @end example
    86 
    87 @subsection Removing RPMs
    88 
    89 The following is a sample session illustrating the removal
    90 of a C/C++ toolset targeting the SPARC architecture.
    91 
    92 @example
    93 rpm -e @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gdb
    94 rpm -e @value{RTEMSRPMPREFIX}gdb-common
    95 rpm -e @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gcc-c++
    96 rpm -e @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gcc
    97 rpm -e @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-newlib
    98 rpm -e @value{RTEMSRPMPREFIX}gcc-common
    99 rpm -e @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-binutils
    100 rpm -e @value{RTEMSRPMPREFIX}binutils-common
    101 @end example
    102 
    103 NOTE:  If you have installed any RTEMS BSPs, then it is likely that
    104 RPM will complain about not being able to remove everything.
     289rpm -qa | grep @value{RTEMSAPI}
     290@end example
    105291
    106292@section Zipped Tar Files
    107293
    108 This section provides information on installing and removing
    109 Zipped Tar Files (e.g .tar.gz or .tar.bz2).
     294The tool binaries for some hosts are provided as compressed tar files.
     295This section provides information on installing and removing Zipped Tar
     296Files (e.g .tar.gz or .tar.bz2).
    110297
    111298@subsection Installing Zipped Tar Files
     
    118305@example
    119306cd /
    120 tar xzf @value{RTEMSRPMPREFIX}binutils-common-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.tar.gz
    121 tar xzf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-binutils-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.tar.gz
    122 tar xzf @value{RTEMSRPMPREFIX}gcc-common-@value{GCCVERSION}-@value{GCCRPMRELEASE}.tar.gz
    123 tar xzf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gcc-@value{GCCVERSION}-@value{GCCRPMRELEASE}.tar.gz
    124 tar xzf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-newlib-@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.tar.gz
    125 tar xzf @value{RTEMSRPMPREFIX}gdb-common-@value{GDBVERSION}-@value{GDBRPMRELEASE}.tar.gz
    126 tar xzf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gdb-@value{GDBVERSION}-@value{GDBRPMRELEASE}.tar.gz
     307tar xzf @value{RTEMSRPMPREFIX}binutils-common-<VERSION>-<RPM>.tar.gz
     308tar xzf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-binutils-<VERSION>-<RPM>.tar.gz
     309tar xzf @value{RTEMSRPMPREFIX}gcc-common-<VERSION>-<RPM>.tar.gz
     310tar xzf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gcc-<VERSION>-<RPM>.tar.gz
     311tar xzf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-newlib-<VERSION>-<RPM>.tar.gz
     312tar xzf @value{RTEMSRPMPREFIX}gdb-common-<VERSION>-<RPM>.tar.gz
     313tar xzf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gdb-<VERSION>-<RPM>.tar.gz
    127314@end example
    128315
     
    133320@example
    134321cd /
    135 tar xjf @value{RTEMSRPMPREFIX}binutils-common-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.tar.bz2
    136 tar xjf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-binutils-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.tar.bz2
    137 tar xjf @value{RTEMSRPMPREFIX}gcc-common-@value{GCCVERSION}-@value{GCCRPMRELEASE}.tar.bz2
    138 tar xjf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-newlib-@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.tar.bz2
    139 tar xjf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gcc-@value{GCCVERSION}-@value{GCCRPMRELEASE}.tar.bz2
    140 tar xjf @value{RTEMSRPMPREFIX}gdb-common-@value{GDBVERSION}-@value{GDBRPMRELEASE}.tar.bz2
    141 tar xjf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gdb-@value{GDBVERSION}-@value{GDBRPMRELEASE}.tar.bz2
     322tar xjf @value{RTEMSRPMPREFIX}binutils-common-<VERSION>-<RPM>.tar.bz2
     323tar xjf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-binutils-<VERSION>-<RPM>.tar.bz2
     324tar xjf @value{RTEMSRPMPREFIX}gcc-common-<VERSION>-<RPM>.tar.bz2
     325tar xjf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-newlib-<VERSION>-<RPM>.tar.bz2
     326tar xjf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gcc-<VERSION>-<RPM>.tar.bz2
     327tar xjf @value{RTEMSRPMPREFIX}gdb-common-<VERSION>-<RPM>.tar.bz2
     328tar xjf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gdb-<VERSION>-<RPM>.tar.bz2
    142329@end example
    143330
  • doc/started/buildc.t

    r84d6744 r9aff0a7  
    11@c
    2 @c  COPYRIGHT (c) 1988-2002.
     2@c  COPYRIGHT (c) 1988-2010.
    33@c  On-Line Applications Research Corporation (OAR).
    44@c  All rights reserved.
     
    99@chapter Building the GNU Cross Compiler Toolset
    1010
    11 NOTE:  This chapter does @b{NOT} apply if you installed
    12 prebuilt toolset executables for BINUTILS, GCC, NEWLIB,
    13 and GDB.  If you installed prebuilt executables for all
    14 of those, proceed to @ref{Building RTEMS}.  If you require
    15 a GDB with a special configuration to connect to your
    16 target board, then proceed to @ref{Building the GNU Debugger GDB}
     11NOTE:  This chapter does @b{NOT} apply if you installed prebuilt toolset
     12executables for BINUTILS, GCC, NEWLIB, and GDB.  If you installed
     13prebuilt executables for all of those, proceed to @ref{Building RTEMS}.
     14If you require a GDB with a special configuration to connect to your
     15target board, then proceed to @ref{Installing GDB Without RPM}
    1716for some advice.
    1817
    19 This chapter describes the steps required to acquire the
    20 source code for a GNU cross compiler toolset, apply
    21 any required RTEMS specific patches, compile that
    22 toolset and install it.
    23 
    24 It is recommended that when toolset binaries are available for
    25 your particular host, that they be used.  Prebuilt binaries
    26 are much easier to install.
    27 
    28 @c
    29 @c  Building BINUTILS GCC and NEWLIB
    30 @c
    31 @section Building BINUTILS GCC and NEWLIB
    32 
    33 NOTE: This step is NOT required if prebuilt executables for
    34 BINUTILS, GCC, and NEWLIB were installed.
    35 
    36 This section describes the process of building BINUTILS, GCC, and
    37 NEWLIB using a variety of methods.  Included is information on
    38 obtaining the source code and patches, applying patches, and
    39 building and installing the tools using multiple methods.
    40 
    41 @c
    42 @c  Obtain Source and Patches for BINUTILS GCC and NEWLIB
    43 @c
    44 
    45 @subsection Obtain Source and Patches for BINUTILS GCC and NEWLIB
    46 
    47 NOTE: This step is required for all methods of building BINUTILS,
    48 GCC, and NEWLIB.
    49 
    50 This section lists the components required to build BINUTILS, GCC,
    51 and NEWLIB from source to target RTEMS.  These files should be
    52 placed in your @code{archive} directory.  Included are the locations
    53 of each component as well as any required RTEMS specific patches.
    54 
    55 @need 1000
    56 @subheading @value{GCCUNTAR}
    57 @example
    58     FTP Site:    @value{GCCFTPSITE}
    59     Directory:   @value{GCCFTPDIR}
    60     File:        @value{GCCTAR}
    61 @c @ifset use-html
    62     URL:         @uref{ftp://@value{GCCFTPSITE}@value{GCCFTPDIR}/@value{GCCTAR},,ftp://@value{GCCFTPSITE}@value{GCCFTPDIR}/@value{GCCTAR}}
    63 @c    URL:         ftp://@value{GCCFTPSITE}@value{GCCFTPDIR}
    64 @c @end ifset
    65 @end example
    66 
    67 @need 1000
    68 @subheading @value{BINUTILSUNTAR}
    69 @example
    70     FTP Site:    @value{BINUTILSFTPSITE}
    71     Directory:   @value{BINUTILSFTPDIR}
    72     File:        @value{BINUTILSTAR}
    73 @c @ifset use-html
    74     URL:         @uref{ftp://@value{BINUTILSFTPSITE}@value{BINUTILSFTPDIR}/@value{BINUTILSTAR},,ftp://@value{BINUTILSFTPSITE}@value{BINUTILSFTPDIR}/@value{BINUTILSTAR}}
    75 @c    URL:         ftp://@value{BINUTILSFTPSITE}@value{BINUTILSFTPDIR}/@value{BINUTILSTAR}
    76 @c @end ifset
    77 @end example
    78 
    79 @need 1000
    80 @subheading @value{NEWLIBUNTAR}
    81 @example
    82     FTP Site:    @value{NEWLIBFTPSITE}
    83     Directory:   @value{NEWLIBFTPDIR}
    84     File:        @value{NEWLIBTAR}
    85 @c @ifset use-html
    86     URL:         @uref{ftp://@value{NEWLIBFTPSITE}@value{NEWLIBFTPDIR}/@value{NEWLIBTAR},,ftp://@value{NEWLIBFTPSITE}@value{NEWLIBFTPDIR}/@value{NEWLIBTAR}}
    87 @c    URL:         ftp://@value{NEWLIBFTPSITE}@value{NEWLIBFTPDIR}/@value{NEWLIBTAR}
    88 @c @end ifset
    89 @end example
    90 
    91 @need 1000
    92 @subheading RTEMS Specific Tool Patches and Scripts
    93 @example
    94     FTP Site:    @value{RTEMSFTPSITE}
    95     Directory:   @value{RTEMSFTPDIR}/SOURCES/@value{RTEMSAPI}
    96 @ifset BINUTILSPATCHVERSION
    97     File:        @value{BINUTILSRTEMSPATCH}
    98 @end ifset
    99 @ifset NEWLIBPATCHVERSION
    100     File:        @value{NEWLIBRTEMSPATCH}
    101 @end ifset
    102 @ifset GCCPATCHVERSION
    103     File:        @value{GCCRTEMSPATCH}
    104 @end ifset
    105 @ifset use-html
    106     URL:         @uref{ftp://@value{RTEMSFTPSITE}@value{RTEMSFTPDIR}/SOURCES/@value{RTEMSAPI},,ftp://@value{RTEMSFTPSITE}@value{RTEMSFTPDIR}/SOURCES/@value{RTEMSAPI}}
    107 @c    URL:         ftp://@value{RTEMSFTPSITE}@value{RTEMSFTPDIR}/SOURCES/@value{RTEMSAPI}
    108 @end ifset
    109 @end example
    110 
    111 The individual components in the RTEMS Development Toolset are
    112 updated independently of one another by their respective
    113 maintainers.  In addition, the patches which the RTEMS Project
    114 has determined are necessary are subject to change as users
    115 report issues on individual host and target platforms.  As
    116 a result, it is possible that the versions listed in this
    117 document are @b{NOT} the latest ones available.  The latest
    118 patches for each tool are always available from RTEMS CVS
    119 on the respective branch and should always be mirrored on the
    120 RTEMS ftp site.  It is recommended that before building a
    121 toolset from source, you verify you are using the
    122 latest patches.
     18This chapter describes the steps required to acquire the source code for
     19a GNU cross compiler toolset, apply any required RTEMS specific patches,
     20compile that toolset and install it.
     21
     22It is recommended that when toolset binaries are available for your
     23particular host, that they be used.  Prebuilt binaries are much easier
     24to install.  They are also much easier for the RTEMS Project to support.
     25
     26@c
     27@c  Preparation
     28@c
     29@section Preparation
     30
     31Before you can build an RTEMS toolset from source, there are some
     32preparatory steps which must be performed.  You will need to determine
     33the various tool versions and patches required and download them  You
     34will also have to unarchive the source and apply any patches.
     35
     36@c
     37@c  Determining Tool Version and Patch Revision
     38@c
     39@subsection Determining Tool Version and Patch Revision
     40
     41The tool versions and patch revisions change on a fairly frequent basis.
     42In addition, these may vary based upon the target architecture.  In some
     43cases, the RTEMS Project may have to stick with a particular version
     44of a tool to provide a working version for a specific architecture.
     45Because of this, it is impossible to provide this information in a
     46complete and accurate manner in this manual.  You will need to refer
     47to the configuration files used by the RTEMS RPM specification files to
     48determine the current versions and, if a patch is required, what version.
     49This section describes how to locate the appropriate tool versions and
     50patches for a particular target architecture.
     51
     52All patches and RPM specification files are kept in CVS.  They are
     53not included in release tarballs.  You will have to access the
     54CVS branch for RTEMS @value{RTEMSAPI}.  For details on this,
     55visit @uref{http://www.rtems.org, http://www.rtems.org} and look for
     56instructions on accessing the RTEMS Source Code Repository in read-only
     57mode.
     58
     59In the checked out source code, you will need to look in the subdirectory
     60@code{contrib/crossrpms/autotools} to determine the versions of AUTOCONF
     61and AUTOMAKE as well as any patches required.  In this directory are
     62a few files you will need to look at.  The first is @code{Makefile.am}
     63which defines the versions of AUTOCONF and AUTOMAKE required for this
     64RTEMS Release Series.  Make a note of the version numbers required for
     65AUTOCONF and AUTOMAKE.  Then examine the following files to determine
     66the master location for the source tarballs and to determine if a patch
     67is required for each tool version cited in the @code{Makefile.am}.
     68
     69@example
     70autoconf-sources.add
     71automake-sources.add
     72@end example
     73
     74If any patches are required, they will be in the
     75@code{contrib/crossrpms/patches} subdirectory of your checked out RTEMS
     76source tree.
     77
     78In the checked out source code, you will need to look in the subdirectory
     79@code{contrib/crossrpms/rtems@value{RTEMSAPI}} to determine the target
     80specific tool versions and patches required. In this directory, you
     81will find a number of subdirectories with many named after target
     82architectures supported by RTEMS.  Descend into the directory for the
     83architecture you plan to build tools for.  Again, the @code{Makefile.am}
     84defines the tool versions for this architecture and RTEMS Release Series.
     85Make a note of the version numbers required for BINUTILS, GCC, NEWLIB,
     86and GDB.  Then examine the following files to determine the master
     87location for the source tarballs and to determine if a patch is required
     88for each tool version cited in the @code{Makefile.am}.
     89
     90@itemize
     91binutils-sources.add
     92gcc-sources.add
     93gdb-sources.add
     94@end itemize
     95
     96If any patches are required, they will be in the
     97@code{contrib/crossrpms/patches} subdirectory of your checked out RTEMS
     98source tree.
     99
     100This is the entire set of source tarballs and patches required for a
     101toolset targeting the selected architecture.  In many cases, this will be
     102the same versions required by other targets on this RTEMS Release Series.
     103
     104Depending on the build method chosen, you may have to download source
     105and patches or only patches.  Also the destination directory for the
     106downloaded source is dependent on the build method followed.  But the
     107versions required are the same.  Specific information on what to download
     108and where to place it is in subsequent sections.
     109
     110@c
     111@c  Obtain Source and Patches
     112@c
     113@subsection Obtain Source and Patches
     114
     115You will need to download the sources for the various packages from
     116their master locations as identified in the previous section.
     117
     118Any patches needed should be in the @code{contrib/crossrpms/patches}
     119directory of your RTEMS source.
     120
     121@c
     122@c  Installing the Tools Without RPM
     123@c
     124@section Installing the Tools Without RPM
     125
     126This section describes the procedure for building and installing an RTEMS
     127cross toolset from source code without using the RPM build infrastructure.
     128
     129Direct invocation of @code{configure} and @code{make} provides more control
     130and easier recovery from problems when building.
     131
     132@c
     133@c Archive and Build Directory Format
     134@c
     135@subsection Archive and Build Directory Format
     136
     137When no packaging format requirements are present, the root directory for
     138the storage of source archives and patches as well as for building the
     139tools is up to the user.  The only concern is that there be enough
     140disk space to complete the build.  In this document, the following
     141organization will be used.
     142
     143Make an @code{archive} directory to contain the downloaded source code
     144and pataches.  Additionally, a @code{tools} directory to be used as a
     145build directory.  The command sequence to do this is shown below:
     146
     147@example
     148mkdir archive
     149mkdir tools
     150@end example
     151
     152This will result in an initial directory structure similar to the
     153one shown in the following figure:
     154
     155@example
     156@group
     157/whatever/prefix/you/choose/
     158        archive/
     159        tools/
     160
     161@end group
     162@end example
     163
     164The RTEMS Project tries to submit all of our patches upstream to the
     165parent projects.  In the event there are patches, the master copy of them
     166is located in the appropriate branch of the RTEMS source module in CVS.
     167Patches are in the @code{contrib/crossrpms/patches}.
    123168
    124169@c
     
    127172@subsection Unarchiving the Tools
    128173
    129 NOTE: This step is required if building BINUTILS, GCC, and NEWLIB
    130 using the procedure described in @ref{Using configure and make}.
    131 It is @b{NOT} required if using the procedure
    132 described in @ref{Using RPM to Build BINUTILS GCC and NEWLIB}.
     174NOTE: This step is required if building any of the tools without using RPM.
     175It is @b{NOT} required if using the procedure described in @ref{Using RPM
     176to Build Tools}.  This section describes the process of unarchiving the
     177tools that comprise an RTEMS toolset.
    133178
    134179GNU source distributions are archived using @code{tar} and
     
    137182If compressed with @code{bzip}, the extension @code{.bz2} is used.
    138183
    139 While in the @code{tools} directory, unpack the compressed
    140 tar files for BINUTILS, GCC, and NEWLIB using the appropriate
    141 command based upon the compression program used.
     184While in the @code{tools} directory, unpack the compressed tar files
     185using the appropriate command based upon the compression program used.
    142186
    143187@example
     
    147191@end example
    148192
    149 After the compressed tar files have been unpacked using
    150 the appropriate commands, the following
    151 directories will have been created under tools.
     193Assuming you are building a complete toolset, after all of the the
     194compressed tar files have been unpacked using the appropriate commands,
     195the following directories will have been created under @code{tools}.
    152196
    153197@itemize @bullet
    154 @item @value{BINUTILSUNTAR}
    155 @item @value{GCCUNTAR}
    156 @item @value{NEWLIBUNTAR}
     198@item autoconf-<VERSION>
     199@item automake-<VERSION>
     200@item binutils-<VERSION>
     201@item gcc-<VERSION>
     202@item binutils-<VERSION>
     203@item gdb-<VERSION>
    157204@end itemize
    158205
     
    163210/whatever/prefix/you/choose/
    164211        archive/
    165             @value{GCCTAR}
    166             @value{BINUTILSTAR}
    167             @value{NEWLIBTAR}
    168 @ifset GCCPATCHVERSION
    169             @value{GCCRTEMSPATCH}
    170 @end ifset
    171 @ifset BINUTILSPATCHVERSION
    172             @value{BINUTILSRTEMSPATCH}
    173 @end ifset
    174 @ifset NEWLIBPATCHVERSION
    175             @value{NEWLIBRTEMSPATCH}
    176 @end ifset
     212          variable tarballs
     213          variable patches
    177214        tools/
    178             @value{BINUTILSUNTAR}/
    179             @value{GCCUNTAR}/
    180             @value{NEWLIBUNTAR}/
     215          various tool source trees
    181216@end group
    182217@end example
    183218
    184219@c
    185 @c  Applying RTEMS Patches
    186 @c
    187 
    188 @subsection Applying RTEMS Patches
    189 
    190 NOTE: This step is required if building BINUTILS, GCC, and NEWLIB
    191 using the procedures described in @ref{Using configure and make}.
    192 It is @b{NOT} required if using the procedure
    193 described in @ref{Using RPM to Build BINUTILS GCC and NEWLIB}.
    194 
    195 This section describes the process of applying the RTEMS patches
    196 to GCC, NEWLIB, and BINUTILS.
    197 
    198 @c
    199 @c  GCC patches
    200 @c
    201 
    202 @subheading Apply RTEMS Patch to GCC
    203 
    204 @ifclear GCCPATCHVERSION
    205 No RTEMS specific patches are required for @value{GCCUNTAR} to
    206 support @value{RTEMSVERSION}.
    207 @end ifclear
    208 
    209 @ifset GCCPATCHVERSION
    210 
    211 Apply the patch using the following command sequence:
    212 
    213 @example
    214 cd tools/@value{GCCUNTAR}
    215 cat ../../archive/@value{GCCRTEMSPATCH} | \
    216     patch -p1
    217 @end example
     220@c Applying RTEMS Project Tool Patches
     221@c
     222
     223@subsection Applying RTEMS Project Tool Patches
     224
     225NOTE: This step is required if building any of the tools IF they have a
     226patch currently required and you are building the tools without using RPM.
     227is @b{NOT} required if using the procedure described in @ref{Using RPM
     228to Build Tools}.  This section describes the process of applying the
     229RTEMS patches to any of the tools.
     230
     231If a patch is required for a particular tool source tree, then you will
     232perform a command similar to the following to apply the patch.  In this
     233example, <TOOL> should be replaced by the appropriate tool directory
     234and <TOOL_PATCH> with the appropriate patch file.
     235
     236@example
     237cd tools/<TOOL>
     238cat ../../archive/<TOOL_PATCH> | patch -p1
     239@end example
     240
     241NOTE: If you add the @code{--dry-run} option to the @code{patch} command
     242in the above commands, it will attempt to apply the patch and report
     243any issues without actually modifying any files.
    218244
    219245If the patch was compressed with the @code{gzip} program, it will
     
    227253
    228254@example
    229 cd tools/@value{GCCUNTAR}
     255cd tools/<TOOL>
    230256find . -name "*.rej" -print
    231257@end example
     
    234260This should not happen with a good patch file which is properly applied.
    235261
    236 @end ifset
    237 
    238 @c
    239 @c  BINUTILS patches
    240 @c
    241 
    242 @subheading Apply RTEMS Patch to binutils
    243 
    244 @ifclear BINUTILSPATCHVERSION
    245 No RTEMS specific patches are required for @value{BINUTILSUNTAR} to
    246 support @value{RTEMSVERSION}.
    247 @end ifclear
    248 
    249 @ifset BINUTILSPATCHVERSION
    250 Apply the patch using the following command sequence:
    251 
    252 @example
    253 cd tools/@value{BINUTILSUNTAR}
    254 cat ../../archive/@value{BINUTILSRTEMSPATCH} | \
    255     patch -p1
    256 @end example
    257 
    258 If the patch was compressed with the @code{gzip} program, it will
    259 have a suffix of @code{.gz} and you should use @code{zcat} instead
    260 of @code{cat} as shown above.  If the patch was compressed with
    261 the @code{gzip} program, it will have a suffix of @code{.bz2} and
    262 you should use @code{bzcat} instead of @code{cat} as shown above.
    263 
    264 Check to see if any of these patches have been rejected using the following
    265 sequence:
    266 
    267 @example
    268 cd tools/@value{BINUTILSUNTAR}
    269 find . -name "*.rej" -print
    270 @end example
    271 
    272 If any files are found with the .rej extension, a patch has been rejected.
    273 This should not happen with a good patch file which is properly applied.
    274 
    275 @end ifset
    276 
    277 @c
    278 @c  Newlib patches
    279 @c
    280 
    281 @subheading Apply RTEMS Patch to newlib
    282 
    283 @ifclear NEWLIBPATCHVERSION
    284 No RTEMS specific patches are required for @value{NEWLIBUNTAR} to
    285 support @value{RTEMSVERSION}.
    286 @end ifclear
    287 
    288 @ifset NEWLIBPATCHVERSION
    289 
    290 Apply the patch using the following command sequence:
    291 
    292 @example
    293 cd tools/@value{NEWLIBUNTAR}
    294 cat ../../archive/@value{NEWLIBRTEMSPATCH} | \
    295     patch -p1
    296 @end example
    297 
    298 If the patch was compressed with the @code{gzip} program, it will
    299 have a suffix of @code{.gz} and you should use @code{zcat} instead
    300 of @code{cat} as shown above.  If the patch was compressed with
    301 the @code{gzip} program, it will have a suffix of @code{.bz2} and
    302 you should use @code{bzcat} instead of @code{cat} as shown above.
    303 
    304 Check to see if any of these patches have been rejected using the following
    305 sequence:
    306 
    307 @example
    308 cd tools/@value{NEWLIBUNTAR}
    309 find . -name "*.rej" -print
    310 @end example
    311 
    312 If any files are found with the .rej extension, a patch has been rejected.
    313 This should not happen with a good patch file which is properly applied.
    314 
    315 @end ifset
    316 
    317 
    318 @c
    319 @c  Compiling and Installing BINUTILS GCC and NEWLIB
    320 @c
    321 
    322 @subsection Compiling and Installing BINUTILS GCC and NEWLIB
    323 
    324 There are two supported methods to compile and install BINUTILS, GCC,
    325 and NEWLIB:
    326 
    327 @itemize @bullet
    328 @item RPM
    329 @item direct invocation of @code{configure} and @code{make}
    330 @end itemize
    331 
    332 Direct invocation of @code{configure} and @code{make} provides more control
    333 and easier recovery from problems when building.
    334 
    335 @c
    336 @c  Using RPM to Build BINUTILS GCC and NEWLIB
    337 @c
    338 
    339 @subsubsection Using RPM to Build BINUTILS GCC and NEWLIB
    340 
    341 NOTE:  The procedures described in the following sections must
    342 be completed before this step:
    343 
    344 @itemize @bullet
    345 @item @ref{Obtain Source and Patches for BINUTILS GCC and NEWLIB}
    346 @end itemize
    347 
    348 RPM automatically unarchives the source and applies any needed
    349 patches so you do @b{NOT} have to manually perform the procedures
    350 described @ref{Unarchiving the Tools} and
    351 @ref{Applying RTEMS Patches}.
    352 
    353 This section describes the process of building binutils, gcc, and
    354 newlib using RPM.  RPM is a packaging format which can be used to
    355 distribute binary files as well as to capture the procedure and
    356 source code used to produce those binary files.  Before
    357 attempting to build any RPM from source, it is necessary to
    358 ensure that all required source and patches are in the @code{SOURCES}
    359 directory under the RPM root (probably @code{/usr/src/redhat} or
    360 @code{/usr/local/src/redhat}) on your machine.  This procedure
    361 starts by installing the source RPMs as shown in the following
    362 example:
    363 
    364 @example
    365 rpm -U @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-binutils-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.src.rpm
    366 rpm -U @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-gcc-@value{GCCVERSION}-@value{GCCRPMRELEASE}.src.rpm
    367 @end example
    368 
    369 The RTEMS tool source RPMS are called "nosrc" to indicate that one or
    370 more source files required to produce the RPMs are not present. 
    371 The RTEMS source RPMs typically include all required patches, but do not
    372 include the large @code{.tar.gz} or @code{.tgz} files for
    373 each component such as BINUTILS, GCC, or NEWLIB.  These are shared
    374 by all RTEMS RPMs regardless of target CPU and there was no reason
    375 to duplicate them.  You will have to get the required source
    376 archive files by hand and place them in the @code{SOURCES} directory
    377 before attempting to build.  If you forget to do this, RPM is
    378 smart -- it will tell you what is missing.  To determine what is
    379 included or referenced by a particular RPM, use a command like the
    380 following:
    381 
    382 @example
    383 @c Don't use @value{GCC*} below. This is an example
    384 $ rpm -q -l -p @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-gcc-3.2.3-1.src.rpm
    385 gcc-3.2.3-rtems@value{RTEMSAPI}-20030507a.diff
    386 @value{RTEMSRPMPREFIX}i386-rtems4.7-gcc.spec
    387 newlib-1.11.0-rtems@value{RTEMSAPI}-20030507.diff
    388 @end example
    389 
    390 Notice that there are patch files (the @code{.diff} files) and a file
    391 describing the build procedure and files produced (the @code{.spec} file),
    392 but no source archives (the @code{*tar.*} files).
    393 When installing this source RPM
    394 (@code{rpm -U @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-gcc-newlib-gcc3.2.3newlib1.11.0-1.src.rpm}),
    395 the @code{.spec} file is placed in the @code{SPECS} directory under the RPM root
    396 directory, while the @code{*.diff} files are placed into the @code{SOURCES}
    397 directory.
    398 
    399 @c
    400 @c  Configuring and Building BINUTILS using RPM
    401 @c
    402 
    403 @subheading Configuring and Building BINUTILS using RPM
    404 
    405 The following example illustrates the invocation of RPM to build a new,
    406 locally compiled, binutils binary RPM that matches the installed source
    407 RPM.  This example assumes that all of the required source is installed.
    408 
    409 @example
    410 cd <RPM_ROOT_DIRECTORY>/SPECS
    411 rpm -bb i386-rtems@value{RTEMSAPI}-binutils-@value{BINUTILSVERSION}.spec
    412 @end example
    413 
    414 If the build completes successfully, RPMS like the following will
    415 be generated in a build-host architecture specific subdirectory
    416 of the RPMS directory under the RPM root directory.
    417 
    418 @example
    419 @value{RTEMSRPMPREFIX}binutils-common-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.i386.rpm
    420 @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-binutils-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.i386.rpm
    421 @end example
    422 
    423 NOTE: It may be necessary to remove the build tree in the
    424 @code{BUILD} directory under the RPM root directory.
    425 
    426 @c
    427 @c  Configuring and Building GCC and NEWLIB using RPM
    428 @c
    429 
    430 @subheading Configuring and Building GCC and NEWLIB using RPM
    431 
    432 The following example illustrates the invocation of RPM to build a new,
    433 locally compiled, set of GCC and NEWLIB binary RPMs that match the
    434 installed source RPM.  It is also necessary to install the BINUTILS
    435 RPMs and place them in your PATH.  This example assumes that all of
    436 the required source is installed.
    437 
    438 @example
    439 cd <RPM_ROOT_DIRECTORY>/RPMS/i386
    440 rpm -U @value{RTEMSRPMPREFIX}binutils-common-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.i386.rpm
    441 rpm -U @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-binutils-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.i386.rpm
    442 export PATH=@value{RTEMSPREFIX}/bin:$PATH
    443 cd <RPM_ROOT_DIRECTORY>/SPECS
    444 rpm -bb i386-rtems@value{RTEMSAPI}-gcc-@value{GCCVERSION}-newlib-@value{NEWLIBVERSION}.spec
    445 @end example
    446 
    447 If the build completes successfully, a set of RPMS like the following will
    448 be generated in a build-host architecture specific subdirectory
    449 of the RPMS directory under the RPM root directory.
    450 
    451 @example
    452 @value{RTEMSRPMPREFIX}gcc-common-@value{GCCVERSION}-@value{GCCRPMRELEASE}.i386.rpm
    453 @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-newlib-@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
    454 @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-gcc-@value{GCCVERSION}-@value{GCCRPMRELEASE}.i386.rpm
    455 @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-gcc-c++-@value{GCCVERSION}-@value{GCCRPMRELEASE}.i386.rpm
    456 @end example
    457 
    458 NOTE: Some targets do not support building all languages.
    459 
    460 NOTE: It may be necessary to remove the build tree in the
    461 @code{BUILD} directory under the RPM root directory.
    462 
    463 @c
    464 @c  Using configure and make
    465 @c
    466 
    467 @subsubsection Using configure and make
    468 
    469 NOTE:  The procedures described in the following sections must
    470 be completed before this step:
    471 
    472 @itemize @bullet
    473 @item @ref{Obtain Source and Patches for BINUTILS GCC and NEWLIB}
    474 @item @ref{Unarchiving the Tools}
    475 @item @ref{Applying RTEMS Patches}
    476 @end itemize
    477 
    478 This section describes the process of building binutils, gcc, and
    479 newlib manually using @code{configure} and @code{make} directly.
    480 
    481 @c
    482 @c  Configuring and Building BINUTILS
    483 @c
    484 
    485 @subheading Configuring and Building BINUTILS
    486 
    487 The following example illustrates the invocation of
    488 @code{configure} and @code{make}
    489 to build and install @value{BINUTILSUNTAR} for the
     262@c
     263@c  Installing AUTOCONF Without RPM
     264@c
     265
     266@subsection Installing AUTOCONF Without RPM
     267
     268The following example illustrates the invocation of @code{configure}
     269and @code{make} to build and install autoconf-<version>.  This tool is
     270installed as a native utility and is independent of any RTEMS target.
     271
     272@example
     273mkdir b-autoconf
     274cd b-autoconf
     275../autoconf-<VERSION>/configure --prefix=@value{RTEMSPREFIX}
     276make all
     277make info
     278make install
     279@end example
     280
     281After autoconf-<VERSION> is built and installed the build directory
     282@code{b-autoconf} may be removed.
     283
     284For more information on the invocation of @code{configure}, please
     285refer to the documentation for autoconf-<VERSION> or invoke the
     286autoconf-VERSION> @code{configure} command with the @code{--help} option.
     287
     288@c
     289@c  Installing AUTOMAKE Without RPM
     290@c
     291
     292@subsection Installing AUTOMAKE Without RPM
     293
     294The following example illustrates the invocation of @code{configure}
     295and @code{make} to build and install automake-<version>.  This tool is
     296installed as a native utility and is independent of any RTEMS target.
     297
     298@example
     299mkdir b-automake
     300cd b-automake
     301../automake-<VERSION>/configure --prefix=@value{RTEMSPREFIX}
     302make all
     303make info
     304make install
     305@end example
     306
     307After automake-<VERSION> is built and installed the build directory
     308@code{b-automake} may be removed.
     309
     310For more information on the invocation of @code{configure}, please
     311refer to the documentation for automake-<VERSION> or invoke the
     312automake-VERSION> @code{configure} command with the @code{--help} option.
     313
     314@c
     315@c  Installing BINUTILS Without RPM
     316@c
     317@subsection Installing BINUTILS Without RPM
     318
     319The following example illustrates the invocation of @code{configure}
     320and @code{make} to build and install binutils-<version>
    490321sparc-rtems@value{RTEMSAPI} target:
    491322
     
    493324mkdir b-binutils
    494325cd b-binutils
    495 ../@value{BINUTILSUNTAR}/configure --target=sparc-rtems@value{RTEMSAPI} \
     326../binutils-<VERSION>/configure --target=sparc-rtems@value{RTEMSAPI} \
    496327  --prefix=@value{RTEMSPREFIX}
    497328make all
     
    500331@end example
    501332
    502 After @value{BINUTILSUNTAR} is built and installed the
    503 build directory @code{b-binutils} may be removed.
     333After binutils-<VERSION> is built and installed the build directory
     334@code{b-binutils} may be removed.
    504335
    505336For more information on the invocation of @code{configure}, please
    506 refer to the documentation for @value{BINUTILSUNTAR} or
    507 invoke the @value{BINUTILSUNTAR} @code{configure} command with the
    508 @code{--help} option.
     337refer to the documentation for binutils-<VERSION> or invoke the
     338binutils-VERSION> @code{configure} command with the @code{--help} option.
    509339
    510340NOTE: The shell PATH variable needs to be updated to include the path
     
    525355
    526356@c
    527 @c  Configuring and Building GCC and NEWLIB
    528 @c
    529 
    530 @subheading Configuring and Building GCC and NEWLIB
    531 
    532 Before building @value{GCCUNTAR} and @value{NEWLIBUNTAR},
    533 @value{BINUTILSUNTAR} must be installed and the directory
     357@c  Installing GCC and NEWLIB Without RPM
     358@c
     359@subsection Installing GCC and NEWLIB Without RPM
     360
     361Before building gcc-<VERSION> and newlib-<VERSION>,
     362binutils-<VERSION> must be installed and the directory
    534363containing those executables must be in your PATH.
    535364
    536365The C Library is built as a subordinate component of
    537 @value{GCCUNTAR}.  Because of this, the @value{NEWLIBUNTAR}
    538 directory source must be available inside the @value{GCCUNTAR}
     366gcc-<VERSION>.  Because of this, the newlib-<VERSION>
     367directory source must be available inside the gcc-<VERSION>
    539368source tree.  This is normally accomplished using a symbolic
    540369link as shown in this example:
    541370
    542371@example
    543 cd @value{GCCUNTAR}
    544 ln -s ../@value{NEWLIBUNTAR}/newlib .
     372cd gcc-<VERSION>
     373ln -s ../newlib-<VERSION>/newlib .
    545374@end example
    546375
    547376The following example illustrates the invocation of
    548377@code{configure} and @code{make}
    549 to build and install @value{GCCUNTAR} with only
     378to build and install gcc-<VERSION> with only
    550379C and C++ support for the sparc-rtems@value{RTEMSAPI} target:
    551380
     
    553382mkdir b-gcc
    554383cd b-gcc
    555 ../@value{GCCUNTAR}/configure --target=sparc-rtems@value{RTEMSAPI} \
     384../gcc-<VERSION>/configure --target=sparc-rtems@value{RTEMSAPI} \
    556385   --with-gnu-as --with-gnu-ld --with-newlib --verbose \
    557386   --enable-threads --enable-languages="c,c++" \
     
    562391@end example
    563392
    564 After @value{GCCUNTAR} is built and installed the
     393After gcc-<VERSION> is built and installed the
    565394build directory @code{b-gcc} may be removed.
    566395
    567396For more information on the invocation of @code{configure}, please
    568 refer to the documentation for @value{GCCUNTAR} or
    569 invoke the @value{GCCUNTAR} @code{configure} command with the
     397refer to the documentation for gcc-<VERSION> or
     398invoke the gcc-<VERSION> @code{configure} command with the
    570399@code{--help} option.
    571400
     
    573402@c Building GCC with Ada Support
    574403@c
    575 @subheading Building GCC with Ada Support
     404@subsection Building GCC with Ada Support
    576405
    577406If you want a GCC toolset that includes support for Ada
     
    583412the same version of GNAT itself.
    584413
    585 The build procedure is the same until the configure step.
    586 A GCC toolset with GNAT enabled requires that @code{ada}
    587 be included in the set of enabled languages.
    588 The following example illustrates the invocation of
    589 @code{configure} and @code{make}
    590 to build and install @value{GCCUNTAR} with only
    591 C, C++, and Ada support for the sparc-rtems@value{RTEMSAPI} target:
     414It is also important to verify whether there is an RTEMS specific
     415Ada patch required for GCC.  These can be found in
     416@uref{http://www.rtems.org/ftp/pub/rtems/people/joel/ada,
     417http://www.rtems.org/ftp/pub/rtems/people/joel/ada}.  The patch is
     418often a minor version or two behind GCC but will usually apply cleanly.
     419This patch must be applied.
     420
     421After this, it is critical to perform these steps in the correct order.
     422GNAT requires that the C Library and RTEMS itself be installed before
     423the language run-time can be built.
     424
     425@itemize @bullet
     426@item install native GCC with GNAT
     427@item place new native GNAT at head of PATH
     428@item install BINUTILS
     429@item place RTEMS prefix at head of PATH
     430@item install C toolset (C++ is optional)
     431@item install RTEMS built multilib
     432@item install RTEMS built for your BSP
     433@end itemize
     434
     435The build procedure is the same until the Ada configure step.  A GCC
     436toolset with GNAT enabled requires that @code{ada} be included in the set
     437of enabled languages.  The following example illustrates the invocation of
     438@code{configure} and @code{make} to build and install gcc-<VERSION> with
     439only C, C++, and Ada support for the sparc-rtems@value{RTEMSAPI} target:
    592440
    593441@example
    594442mkdir b-gcc
    595 cd @value{GCCUNTAR}/gcc/ada
    596 touch treeprs.ads [es]info.h nmake.ad[bs]
    597 cd ../../../b-gcc
    598 ../@value{GCCUNTAR}/configure --target=sparc-rtems@value{RTEMSAPI} \
     443cd b-gcc
     444../gcc-<VERSION>/configure --target=sparc-rtems@value{RTEMSAPI} \
    599445   --with-gnu-as --with-gnu-ld --with-newlib --verbose \
    600446   --enable-threads --enable-languages="c,c++,ada" \
     
    602448make all
    603449make info
    604 make -C gcc cross-gnattools
    605 make -C gcc ada.all.cross
    606 make -C gcc GNATLIBCFLAGS="USER_SELECTED_CPU_CFLAGS" gnatlib
    607450make install
    608451@end example
    609452
    610 After @value{GCCUNTAR} is built and installed the
    611 build directory @code{b-gcc} may be removed.
    612 
    613 @c
    614 @c Building the GNU Debugger GDB
    615 @c
    616 
    617 @section Building the GNU Debugger GDB
    618 
    619 NOTE: This step is NOT required if prebuilt executables for
    620 the GNU Debugger GDB were installed.
    621 
    622 The GNU Debugger GDB supports many configurations but requires some
    623 means of communicating between the host computer and target board.
    624 This communication can be via a serial port, Ethernet, BDM, or ROM emulator.
    625 The communication protocol can be the GDB remote protocol or GDB
    626 can talk directly to a ROM monitor.  This setup is target board
    627 specific.  The following configurations have been
    628 successfully used with RTEMS applications:
     453After gcc-<VERSION> is built and installed the build directory
     454@code{b-gcc} may be removed.
     455
     456@c
     457@c Installing GDB Without RPM
     458@c
     459@subsection Installing GDB Without RPM
     460
     461NOTE: This step is NOT required if prebuilt executables for the
     462GDB were installed and they meet your target interface
     463requirements.
     464
     465GDB supports many configurations but requires some means of communicating
     466between the host computer and target board.  This communication can be via
     467a serial port, Ethernet, BDM, or ROM emulator.  The communication protocol
     468can be the GDB remote protocol or GDB can talk directly to a ROM monitor.
     469This setup is target board specific.  Some of the configurations that have
     470been successfully used with RTEMS applications are:
    629471
    630472@itemize @bullet
     
    632474@item Motorola Mxxxbug found on M68xxx VME boards
    633475@item Motorola PPCbug found on PowerPC VME, CompactPCI, and MTX boards
    634 @item ARM based Cogent EDP7312
     476@item ARM based Cogent EDB7312
    635477@item PC's using various Intel and AMD CPUs including i386,
    636478i486, Pentium and above, and Athlon
     
    639481@item Sparc Instruction Simulator in GDB (SIS)
    640482@item Sparc Instruction Simulator (TSIM)
    641 @item DINK32 on various PowerPC boards
    642483@end itemize
    643484
     
    651492not include support for your particular target board.
    652493
    653 @c
    654 @c  Obtain Source and Patches for GDB
    655 @c
    656 
    657 @subsection Obtain Source and Patches for GDB
    658 
    659 NOTE: This step is required for all methods of building GDB.
    660 
    661 This section lists the components required to build GDB
    662 from source to target RTEMS.  These files should be
    663 placed in your @code{archive} directory.  Included are the locations
    664 of each component as well as any required RTEMS specific patches.
    665 
    666 @need 1000
    667 @subheading @value{GDBUNTAR}
    668 @example
    669     FTP Site:    @value{GDBFTPSITE}
    670     Directory:   @value{GDBFTPDIR}
    671     File:        @value{GDBTAR}
    672     URL:         @uref{@value{GDBFTPURL},,@value{GDBFTPURL}}
    673 @end example
    674 
    675 @need 1000
    676 @subheading RTEMS Specific Tool Patches and Scripts
    677 @example
    678     FTP Site:    @value{RTEMSFTPSITE}
    679     Directory:   @value{RTEMSFTPDIR}/SOURCES/@value{RTEMSAPI}
    680 @ifset GDBPATCHVERSION
    681     File:        @value{GDBRTEMSPATCH}
    682     URL:         @uref{ftp://@value{RTEMSFTPSITE}@value{RTEMSFTPDIR}/SOURCES/@value{GDBRTEMSPATCH},,ftp://@value{RTEMSFTPSITE}@value{RTEMSFTPDIR}/SOURCES/@value{GDBRTEMSPATCH}}
    683 @end ifset
    684 @end example
    685 
    686 @c
    687 @c  Unarchiving the GDB Distribution
    688 @c
    689 @subsection Unarchiving the GDB Distribution
    690 
    691 Use the following commands to unarchive the GDB distribution:
    692 
    693 @example
    694 cd tools
    695 tar xzf ../archive/@value{GDBTAR}
    696 @end example
    697 
    698 The directory @value{GDBUNTAR} is created under the tools directory.
    699 
    700 @c
    701 @c  Applying RTEMS Patch to GDB
    702 @c
    703 
    704 @subsection Applying RTEMS Patch to GDB
    705 
    706 @ifclear GDBPATCHVERSION
    707 No RTEMS specific patches are required for @value{GDBVERSION} to
    708 support @value{RTEMSVERSION}.
    709 @end ifclear
    710 
    711 @ifset GDBPATCHVERSION
    712 
    713 Apply the patch using the following command sequence:
    714 
    715 @example
    716 cd tools/@value{GDBUNTAR}
    717 cat archive/@value{GDBRTEMSPATCH} | \
    718     patch -p1
    719 @end example
    720 
    721 If the patch was compressed with the @code{gzip} program, it will
    722 have a suffix of @code{.gz} and you should use @code{zcat} instead
    723 of @code{cat} as shown above.  If the patch was compressed with
    724 the @code{gzip} program, it will have a suffix of @code{.bz2} and
    725 you should use @code{bzcat} instead of @code{cat} as shown above.
    726 
    727 Check to see if any of these patches have been rejected using the following
    728 sequence:
    729 
    730 @example
    731 cd tools/@value{GDBUNTAR}
    732 find . -name "*.rej" -print
    733 @end example
    734 
    735 If any files are found with the .rej extension, a patch has been rejected.
    736 This should not happen with a good patch file.
    737 
    738 @end ifset
    739 
    740 @c
    741 @c  Compiling and Installing the GNU Debugger GDB
    742 @c
    743 
    744 @subsection Compiling and Installing the GNU Debugger GDB
    745 
    746 There are three methods of building the GNU Debugger:
    747 
    748 @itemize @bullet
    749 @item RPM
    750 @item direct invocation of @code{configure} and @code{make}
    751 @end itemize
    752 
    753 Direct invocation of @code{configure} and @code{make} provides more control
    754 and easier recovery from problems when building.
    755 
    756 @c
    757 @c  Using RPM to Build GDB
    758 @c
    759 
    760 @subsubsection Using RPM to Build GDB
    761 
    762 This section describes the process of building binutils, gcc, and
    763 newlib using RPM.  RPM is a packaging format which can be used to
    764 distribute binary files as well as to capture the procedure and
    765 source code used to produce those binary files.  Before
    766 attempting to build any RPM from source, it is necessary to
    767 ensure that all required source and patches are in the @code{SOURCES}
    768 directory under the RPM root (probably @code{/usr/src/redhat} or
    769 @code{/usr/local/src/redhat}) on your machine.  This procedure
    770 starts by installing the source RPMs as shown in the following
    771 example:
    772 
    773 @example
    774 rpm -U @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-gdb-@value{GDBVERSION}-@value{GDBRPMRELEASE}.src.rpm
    775 @end example
    776 
    777 Because RTEMS tool RPMS are called "nosrc" to indicate that one or
    778 more source files required to produce the RPMs are not present.
    779 The RTEMS source GDB RPM does not include the large @code{.tar.gz} or
    780 @code{.tgz} files for GDB.  This is shared by all RTEMS RPMs
    781 regardless of target CPU and there was no reason
    782 to duplicate them.  You will have to get the required source
    783 archive files by hand and place them in the @code{SOURCES} directory
    784 before attempting to build.  If you forget to do this, RPM is
    785 smart -- it will tell you what is missing.  To determine what is
    786 included or referenced by a particular RPM, use a command like the
    787 following:
    788 
    789 @example
    790 $ rpm -q -l -p @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-gdb-@value{GDBVERSION}-@value{GDBRPMRELEASE}.src.rpm
    791 gdb-@value{GDBVERSION}-rtems@value{RTEMSAPI}-@value{GDBPATCHVERSION}.diff
    792 gdb-@value{GDBVERSION}.tar.gz
    793 i386-rtems@value{RTEMSAPI}-gdb-@value{GDBVERSION}.spec
    794 @end example
    795 
    796 Notice that there is a patch file (the @code{.diff} file), a source archive
    797 file (the @code{.tar.gz}), and a file describing the build procedure and
    798 files produced (the @code{.spec} file).  The @code{.spec} file is placed
    799 in the @code{SPECS} directory under the RPM root directory.
    800 
    801 @c
    802 @c  Configuring and Building GDB using RPM
    803 @c
    804 
    805 @subheading Configuring and Building GDB using RPM
    806 
    807 The following example illustrates the invocation of RPM to build a new,
    808 locally compiled, binutils binary RPM that matches the installed source
    809 RPM.  This example assumes that all of the required source is installed.
    810 
    811 @example
    812 cd <RPM_ROOT_DIRECTORY>/SPECS
    813 rpm -bb i386-rtems@value{RTEMSAPI}-gdb-@value{GDBVERSION}.spec
    814 @end example
    815 
    816 If the build completes successfully, RPMS like the following will
    817 be generated in a build-host architecture specific subdirectory
    818 of the RPMS directory under the RPM root directory.
    819 
    820 @example
    821 @value{RTEMSRPMPREFIX}gdb-common-@value{GDBVERSION}-@value{GDBRPMRELEASE}.i386.rpm
    822 @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-gdb-@value{GDBVERSION}-@value{GDBRPMRELEASE}.i386.rpm
    823 @end example
    824 
    825 NOTE: It may be necessary to remove the build tree in the
    826 @code{BUILD} directory under the RPM root directory.
    827 
    828 @c
    829 @c Using the GDB configure Script Directly
    830 @c
    831 
    832 @subsubsection Using the GDB configure Script Directly
    833 
    834 This section describes how to configure the GNU debugger for
    835 RTEMS targets using @code{configure} and @code{make} directly.
    836494The following example illustrates the invocation of @code{configure}
    837 and @code{make} to build and install @value{GDBUNTAR} for the
     495and @code{make} to build and install gdb-<VERSION> for the
    838496m68k-rtems@value{RTEMSAPI} target:
    839497
     
    841499mkdir b-gdb
    842500cd b-gdb
    843 ../@value{GDBUNTAR}/configure --target=m68k-rtems@value{RTEMSAPI} \
     501../gdb-<VERSION>/configure --target=m68k-rtems@value{RTEMSAPI} \
    844502  --prefix=@value{RTEMSPREFIX}
    845503make all
     
    862520@end table
    863521
    864 After @value{GDBUNTAR} is built and installed the
     522After gdb-<VERSION> is built and installed the
    865523build directory @code{b-gdb} may be removed.
    866524
    867525For more information on the invocation of @code{configure}, please
    868 refer to the documentation for @value{GDBUNTAR} or
    869 invoke the @value{GDBUNTAR} @code{configure} command with the
     526refer to the documentation for gdb-<VERSION> or
     527invoke the gdb-<VERSION> @code{configure} command with the
    870528@code{--help} option.
     529
     530
     531@c
     532@c  Using RPM to Build Tools
     533@c
     534
     535@section Using RPM to Build Tools
     536
     537RPM is a packaging format which can be used to distribute binary files as
     538well as to capture the procedure and source code used to produce those
     539binary files.  For RPM, it is assumed that the following subdirectories
     540are under a root directory such as @code{/usr/src/redhat} or
     541@code{/usr/local/src/redhat}) on your machine. 
     542
     543@example
     544BUILD
     545RPMS
     546SOURCES
     547SPECS
     548SRPMS
     549@end example
     550
     551For the purposes of this document, the RPM @code{SOURCES} directory is the
     552directory into which all tool source and patches are assumed to reside.
     553The @code{BUILD} directory is where the actual build is performed when
     554building binaries from a source RPM. 
     555
     556RPM automatically unarchives the source and applies any needed patches
     557so you do @b{NOT} have to manually perform the procedures described
     558@ref{Unarchiving the Tools} and @ref{Applying RTEMS Project Tool Patches}.
     559But you are responsible for placing all source tarballs
     560and patches in the @code{SOURCES} directory per the instructions in
     561@ref{Obtain Source and Patches}
     562
     563This procedure starts by installing the source (e.g. @code{.src.rpm}
     564extension) RPMs.  The RTEMS tool source RPMS are called "nosrc" to
     565indicate that one or more source files required to produce the RPMs
     566are not present.  The RTEMS source RPMs typically include all required
     567patches, but do not include the large @code{.tar.gz} or @code{.tgz} files
     568for each component such as BINUTILS, GCC, or NEWLIB.  These are shared
     569by all RTEMS RPMs regardless of target CPU and there was no reason to
     570duplicate them.  You will have to get the required source archive files
     571by hand and place them in the @code{SOURCES} directory before attempting
     572to build.  If you forget to do this, RPM is smart -- it will tell you
     573what is missing. You can fetch any missing files and try again.
     574
     575@c
     576@c  Building AUTOCONF using RPM
     577@c
     578@subsection Building AUTOCONF using RPM
     579
     580This section illustrates the invocation of RPM to build a new, locally
     581compiled, AUTOCONF binary RPM that matches the installed source RPM.
     582This example assumes that all of the required source is installed.
     583
     584@example
     585rpm -U @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-autoconf-<VERSION>-<RPM_RELEASE>.src.rpm
     586@end example
     587
     588@example
     589cd <RPM_ROOT_DIRECTORY>/SPECS
     590rpm -bb i386-rtems@value{RTEMSAPI}-autoconf-<VERSION>.spec
     591@end example
     592
     593If the build completes successfully, RPMS like the following will be
     594generated in a build-host architecture specific subdirectory of the RPMs
     595directory under the RPM root directory.
     596
     597@example
     598@value{RTEMSRPMPREFIX}rtems@value{RTEMSAPI}-autoconf-<VERSION>-<RPM_RELEASE>.<ARCH>.rpm
     599@end example
     600
     601NOTE: It may be necessary to remove the build tree in the @code{BUILD}
     602directory under the RPM root directory.
     603
     604@c
     605@c  Building AUTOMAKE using RPM
     606@c
     607@subsection Building AUTOMAKE using RPM
     608
     609This section illustrates the invocation of RPM to build a new, locally
     610compiled, AUTOMAKE binary RPM that matches the installed source RPM.
     611This example assumes that all of the required source is installed.
     612
     613@example
     614rpm -U @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-automake-<VERSION>-<RPM_RELEASE>.src.rpm
     615@end example
     616
     617@example
     618cd <RPM_ROOT_DIRECTORY>/SPECS
     619rpm -bb i386-rtems@value{RTEMSAPI}-automake-<VERSION>.spec
     620@end example
     621
     622If the build completes successfully, RPMS like the following will be
     623generated in a build-host architecture specific subdirectory of the RPMs
     624directory under the RPM root directory.
     625
     626@example
     627@value{RTEMSRPMPREFIX}rtems@value{RTEMSAPI}-automake-<VERSION>-<RPM_RELEASE>.<ARCH>.rpm
     628@end example
     629
     630NOTE: It may be necessary to remove the build tree in the @code{BUILD}
     631directory under the RPM root directory.
     632
     633
     634@c
     635@c  Building BINUTILS using RPM
     636@c
     637@subsection Building BINUTILS using RPM
     638
     639This section illustrates the invocation of RPM to build a new, locally
     640compiled, binutils binary RPM that matches the installed source RPM.
     641This example assumes that all of the required source is installed.
     642
     643@example
     644rpm -U @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-binutils-<VERSION>-<RPM_RELEASE>.src.rpm
     645@end example
     646
     647@example
     648cd <RPM_ROOT_DIRECTORY>/SPECS
     649rpm -bb i386-rtems@value{RTEMSAPI}-binutils-<VERSION>.spec
     650@end example
     651
     652If the build completes successfully, RPMS like the following will be
     653generated in a build-host architecture specific subdirectory of the RPMS
     654directory under the RPM root directory.
     655
     656@example
     657@value{RTEMSRPMPREFIX}binutils-common-<VERSION>-<RPM_RELEASE>.<ARCH>.rpm
     658@value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-binutils-<VERSION>-<RPM_RELEASE>.<ARCH>.rpm
     659@end example
     660
     661NOTE: It may be necessary to remove the build tree in the @code{BUILD}
     662directory under the RPM root directory.
     663
     664@c
     665@c  Building GCC and NEWLIB using RPM
     666@c
     667@subsection Building GCC and NEWLIB using RPM
     668
     669This section illustrates the invocation of RPM to build a new,
     670locally compiled, set of GCC and NEWLIB binary RPMs that match the
     671installed source RPM.  It is also necessary to install the BINUTILS
     672RPMs and place them in your PATH.  This example assumes that all of
     673the required source is installed.
     674
     675@example
     676cd <RPM_ROOT_DIRECTORY>/SPECS
     677rpm -bb i386-rtems@value{RTEMSAPI}-gcc-<VERSION>.spec
     678@end example
     679
     680If the build completes successfully, a set of RPMS like the following will
     681be generated in a build-host architecture specific subdirectory
     682of the RPMS directory under the RPM root directory.
     683
     684@example
     685@value{RTEMSRPMPREFIX}gcc-common-<VERSION>-<RPM>.<DIST>.noarch.rpm \
     686@value{RTEMSRPMPREFIX}newlib-common-<VERSION>-<RPM>.<DIST>.noarch.rpm \
     687@value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-gcc-<VERSION>-<RPM>.<ARCH>.rpm \
     688@value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-newlib-<VERSION>-<RPM>.<ARCH>.rpm \
     689@value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-libgcc-<VERSION>-<RPM>.<ARCH>.rpm \
     690@value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-gcc-c++-<VERSION>-<RPM>.<ARCH>.rpm \
     691@value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-libstd++-<VERSION>-<RPM>.<ARCH>.rpm
     692@end example
     693
     694NOTE: Some targets do not support building all languages.
     695
     696NOTE: It may be necessary to remove the build tree in the
     697@code{BUILD} directory under the RPM root directory.
     698
     699@c
     700@c Building the GDB using RPM
     701@c
     702@subsection Building the GDB using RPM
     703
     704The following example illustrates the invocation of RPM to build a new,
     705locally compiled, binutils binary RPM that matches the installed source
     706RPM.  This example assumes that all of the required source is installed.
     707
     708
     709@example
     710rpm -U @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-gdb-<VERSION>-<RPM_RELEASE>.src.rpm
     711@end example
     712
     713@example
     714cd <RPM_ROOT_DIRECTORY>/SPECS
     715rpm -bb i386-rtems@value{RTEMSAPI}-gdb-<VERSION>.spec
     716@end example
     717
     718If the build completes successfully, RPMS like the following will
     719be generated in a build-host architecture specific subdirectory
     720of the RPMS directory under the RPM root directory.
     721
     722@example
     723@value{RTEMSRPMPREFIX}gdb-common-<VERSION>-<RPM_RELEASE>.<ARCH>.rpm
     724@value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-gdb-<VERSION>-<RPM_RELEASE>.<ARCH>.rpm
     725@end example
     726
     727NOTE: It may be necessary to remove the build tree in the
     728@code{BUILD} directory under the RPM root directory.
    871729
    872730@c
     
    933791
    934792@example
    935 find @value{BINUTILSUNTAR} -name config.status -print
     793find binutils-<VERSION> -name config.status -print
    936794@end example
    937795
     
    950808
    951809@example
    952 -I../../@value{BINUTILSUNTAR}/gcc -I/@value{BINUTILSUNTAR}/gcc/include -I.
     810-I../../binutils-<VERSION>/gcc -I/binutils-<VERSION>/gcc/include -I.
    953811@end example
    954812
  • doc/started/buildrt.t

    r84d6744 r9aff0a7  
    11@c
    2 @c
    3 @c  COPYRIGHT (c) 1988-2002.
     2@c  COPYRIGHT (c) 1988-2010.
    43@c  On-Line Applications Research Corporation (OAR).
    54@c  All rights reserved.
     
    1211@section Obtain the RTEMS Source Code
    1312
    14 This section provides pointers to the RTEMS source code and
    15 Hello World example program.  These files should be
    16 placed in your @code{archive} directory. 
     13This section provides pointers to the RTEMS source code and example
     14programs.  These files should be placed in your @code{archive} directory.
     15The set of tarballs which comprise an RTEMS release is placed in a
     16directory whose name if the release on the ftp site.  The RTEMS ftp site
     17is accessible via both the ftp and http protocols at the following URLs:
     18 
     19@itemize @bullet
     20@item @uref{http://www.rtems.org/ftp/pub/rtems,http://www.rtems.org/ftp/pub/rtems}
     21@item @uref{ftp://www.rtems.org/pub/rtems,ftp://www.rtems.org/pub/rtems}
     22@end itemize
    1723
    18 @subheading @value{RTEMSVERSION}
    19 @example
    20     FTP Site:    @value{RTEMSFTPSITE}
    21     Directory:   @value{RTEMSFTPDIR}/@value{VERSION}
    22     File:        @value{RTEMSTAR}
    23     URL:         @uref{ftp://@value{RTEMSFTPSITE}@value{RTEMSFTPDIR}/@value{VERSION}/@value{RTEMSTAR},,ftp://@value{RTEMSFTPSITE}@value{RTEMSFTPDIR}/@value{VERSION}/@value{RTEMSTAR}}
    24 @end example
    25 
    26 @subheading RTEMS Examples including Hello World
    27 @example
    28     FTP Site:    @value{RTEMSFTPSITE}
    29     Directory:   @value{RTEMSFTPDIR}/@value{VERSION}
    30     File:        examples-@value{VERSION}.tar.bz2
    31     URL:         @uref{ftp://@value{RTEMSFTPSITE}@value{RTEMSFTPDIR}/@value{VERSION}/examples-@value{VERSION}.tar.bz2,,ftp://@value{RTEMSFTPSITE}@value{RTEMSFTPDIR}/@value{VERSION}/examples-@value{VERSION}.tar.bz2}
    32 @end example
     24Associated with each RTEMS Release is a set of example programs.
     25Prior to the 4.10 Release Series, these examples were in a "Class
     26Examples" and an "Examples" collection.  Beginning with the 4.10 Release
     27Series, these examples collections were merged and other examples added.
     28This new collection is called "Examples V2".  It is contained in the file
     29@code{examples-v2-<VERSION>.tar.bz2>} within the RTEMS release directory.
    3330
    3431@c
     
    4340@example
    4441cd tools
    45 tar xjf ../archive/@value{RTEMSTAR}
     42tar xjf ../archive/rtems-@value{RTEMSAPI}.<VERSION>.tar.bz2
    4643@end example
    4744
    48 This creates the directory @value{RTEMSUNTAR}.
    49 
     45This creates the directory rtems-@value{RTEMSAPI}.<VERSION>
    5046
    5147@section Add <INSTALL_POINT>/bin to Executable PATH
     
    5450in your search path.  It is important to have the RTEMS toolset first
    5551in your path to ensure that you are using the intended version of all
    56 tools.  The following command prepends the directory
    57 where the tools were installed in a previous step:
     52tools.  The following command prepends the directory where
     53the tools were installed in a previous step.  If you are using
     54binaries provided by the RTEMS Project, the <INSTALL_POINT> will be
     55@code{/opt/rtems-@value{RTEMSAPI}}
    5856
    5957@example
     
    6159@end example
    6260
    63 NOTE:  The above command is in Bourne shell (@code{sh}) syntax and
    64 should work with the Korn (@code{ksh}) and GNU Bourne Again Shell
    65 (@code{bash}).  It will not work with the C Shell (@code{csh}) or
    66 derivatives of the C Shell.
     61@b{NOTE:}  The above command is in Bourne shell (@code{sh}) syntax and should
     62work with the Korn (@code{ksh}) and GNU Bourne Again Shell (@code{bash}).
     63It will not work with the C Shell (@code{csh}) or derivatives of the
     64C Shell.
    6765
    6866@section Verifying the Operation of the Cross Toolset
     
    8482
    8583@example
    86 m68k-rtems-gcc -v -S f.c
     84m68k-rtems@value{RTEMSAPI}-gcc -v -S f.c
    8785@end example
    8886
    89 Where @code{m68k-rtems-gcc} should be changed to match the installed
    90 name of your cross compiler.  The result of this command will be
    91 a sequence of output showing where the cross-compiler searched for
    92 and found its subcomponents.  Verify that these paths correspond
    93 to your <INSTALL_POINT>.
     87Where @code{m68k} should be changed to match the target architecture
     88of your cross compiler.  The result of this command will be a sequence
     89of output showing where the cross-compiler searched for and found
     90its subcomponents.  Verify that these paths correspond to your
     91<INSTALL_POINT>.
    9492
    9593Look at the created file @code{f.s} and verify that it is in fact
     
    10098
    10199@example
    102 m68k-rtems-gcc -v -c f.c
     100m68k-rtems@code{RTEMSAPI}-gcc -v -c f.c
    103101@end example
    104102
    105 If this produces messages that indicate the assembly code is
    106 not valid, then it is likely that you have fallen victim to
    107 one of the problems described in
    108 @ref{Error Message Indicates Invalid Option to Assembler}
    109 Don't feel bad about this, one of the most common installation errors
    110 is for the cross-compiler not to be able to find the cross assembler
    111 and default to using the native @code{as}.  This can result in very confusing
    112 error messages.
     103If this produces messages that indicate the assembly code is not valid,
     104then it is likely that you have fallen victim to one of the problems
     105described in @ref{Error Message Indicates Invalid Option to Assembler}
     106Please do not feel bad about this and do not give up, one of the most
     107common installation errors is for the cross-compiler not to be able
     108to find the cross assembler and default to using the native @code{as}.
     109This can result in very confusing error messages.
    113110
    114111@section Building RTEMS for a Specific Target and BSP
     
    131128
    132129Make a build directory under tools and build the RTEMS product in this
    133 directory. The @code{../@value{RTEMSUNTAR}/configure}
    134 command has numerous command line
    135 arguments. These arguments are discussed in detail in documentation that
    136 comes with the RTEMS distribution. A full list of these arguments can be
    137 obtained by running @code{../@value{RTEMSUNTAR}/configure --help}
    138 If you followed the procedure
    139 described in the section @ref{Unarchive the RTEMS Source}, these
    140 configuration options can be found in the file
    141 tools/@value{RTEMSUNTAR}/README.configure.
     130directory. The @code{../rtems-@value{RTEMSAPI}.<VERSION>/configure}
     131command has numerous command line arguments. These arguments are
     132discussed in detail in documentation that comes with the RTEMS
     133distribution. A full list of these arguments can be obtained by running
     134@code{../rtems-@value{RTEMSAPI}.<VERSION>/configure --help} If you
     135followed the procedure described in the section @ref{Unarchive the
     136RTEMS Source}, these configuration options can be found in the file
     137tools/rtems-@value{RTEMSAPI}.<VERSION>/README.configure.
    142138
    143139@b{NOTE}: The GNAT/RTEMS run-time implementation is based on the POSIX
    144 API.  Thus the RTEMS configuration for a GNAT/RTEMS environment MUST
    145 include the @code{--enable-posix} flag.
     140API and the GNAT/RTEMS run-time cannot be compiled with networking
     141disabled. Your application does not have to use networking but it must
     142be enabled.  Thus the RTEMS configuration for a GNAT/RTEMS environment
     143MUST include the @code{--enable-posix --enable-networking} flag.
    146144
    147145The following shows the command sequence required to configure,
     
    153151mkdir build-rtems
    154152cd build-rtems
    155 ../@value{RTEMSUNTAR}/configure --target=<TARGET_CONFIGURATION> \
     153../rtems-@value{RTEMSAPI}.VERSION/configure --target=<TARGET_CONFIGURATION> \
    156154    --disable-posix --disable-networking --disable-cxx \
    157     --enable-rtemsbsp=<BOARD_SUPPORT_PACKAGE>\
     155    --enable-rtemsbsp=<BSP>\
    158156    --prefix=<INSTALL_POINT>
    159157make all install
    160158@end example
    161159
    162 Where the list of currently supported <TARGET_CONFIGURATION>'s and
    163 <BOARD_SUPPORT_PACKAGE>'s can be found in
    164 tools/@value{RTEMSUNTAR}/README.configure.
     160<TARGET> is of the form <CPU>-rtems@value{RTEMSAPI} and the list of
     161currently supported <TARGET> configuration's and <BSP>'s can be found in
     162@code{tools/RTEMS-@value{RTEMSAPI}.<VERSION>/README.configure}.
    165163
    166 <INSTALL_POINT> is typically the installation point for the
    167 tools and defaults to @code{@value{RTEMSPREFIX}}.
     164<INSTALL_POINT> is typically the installation point for the tools and
     165defaults to @code{/opt/rtems-@value{RTEMSAPI}}.
    168166
    169 BSP is a supported BSP for the selected CPU family.  The list of
    170 supported BSPs may be found in the file
    171 tools/@value{RTEMSUNTAR}/README.configure
    172 in the RTEMS source tree.  If the BSP parameter is not specified,
    173 then all supported BSPs for the selected CPU family will be built.
     167BSP is a supported BSP for the selected CPU family.
     168The list of supported BSPs may be found in the file
     169@code{tools/rtems-@value{RTEMSAPI}.<VERSION>/README.configure} in the
     170RTEMS source tree.  If the BSP parameter is not specified, then all
     171supported BSPs for the selected CPU family will be built.
    174172
    175 @b{NOTE:}  The POSIX API must be enabled to use GNAT/RTEMS.
     173@b{NOTE:} The POSIX API and networking must be enabled to use GNAT/RTEMS.
    176174
    177175@b{NOTE:} The @code{make} utility used should be GNU make.
  • doc/started/intro.t

    r84d6744 r9aff0a7  
    11@c
    2 @c  COPYRIGHT (c) 1988-2002.
     2@c  COPYRIGHT (c) 1988-2010.
    33@c  On-Line Applications Research Corporation (OAR).
    44@c  All rights reserved.
     
    1919@item GNU Cross Compilation Tools for RTEMS on your build-host system
    2020@item RTEMS OS for the target
    21 @item GDB Debugger
     21@item GNU Debugger (GDB)
    2222@end itemize
    2323
     
    160160@uref{mailto:@value{RTEMSUSERS},@value{RTEMSUSERS}}
    161161
    162 This mailing list is dedicated to the discussion of issues related
    163 to RTEMS, including GNAT/RTEMS.  If you have questions about RTEMS,
    164 wish to make suggestions, or just want to pick up hints, this is a
    165 good list to monitor.  Subscribe by sending an empty mail message to
    166 @uref{mailto:@value{RTEMSUSERSSUBSCRIBE},@value{RTEMSUSERSSUBSCRIBE}}.
    167 Messages sent to @uref{mailto:@value{RTEMSUSERS},@value{RTEMSUSERS}}
    168 are posted to the list.
    169 
    170 @subsection CrossGCC Mailing List
    171 
    172 @uref{mailto:crossgcc@@sources.redhat.com,crossgcc@@sources.redhat.com}
    173 
    174 This mailing list is dedicated to the use of the GNU tools in
    175 cross development environments.  Most of the discussions
    176 focus on embedded issues.  Information on subscribing
    177 to this mailing list is included in the
    178 @uref{http://www.objsw.com/CrossGCC/,CrossGCC FAQ}.
    179 
    180 The CrossGCC FAQ and Wiki are are available
    181 at @uref{http://www.billgatliff.com,http://www.billgatliff.com}.
     162This is the primary  mailing list for the discussion of issues
     163related to RTEMS, including GNAT/RTEMS.  If you have questions
     164about RTEMS, wish to make suggestions, track development efforts,
     165or just want to pick up hints, this is a good list to monitor.
     166If you would like to browse the thousands of messages in the fifteen
     167year archive of the mailing list or subscribe to it, please visit
     168@uref{http://www.rtems.org/mailman,http://www.rtems.org/mailman} for
     169more information,
    182170
    183171@subsection GCC Mailing Lists
    184 
    185172
    186173The GCC Project is hosted at @uref{http://gcc.gnu.org,http://gcc.gnu.org}.
    187174They maintain multiple mailing lists that are described at the web site
    188175along with subscription information.
    189 
  • doc/started/nextstep.t

    r84d6744 r9aff0a7  
    11@c
    2 @c
    3 @c  COPYRIGHT (c) 1988-2002.
     2@c  COPYRIGHT (c) 1988-2010.
    43@c  On-Line Applications Research Corporation (OAR).
    54@c  All rights reserved.
     
    109@chapter Where To Go From Here
    1110
    12 At this point, you should have successfully installed a
    13 GNU Cross Compilation Tools for RTEMS on your host system
    14 as well as the RTEMS OS for the target host.  You should
    15 have successfully linked the "hello world" program. You
    16 may even have downloaded the executable to that target
    17 and run it.  What do you do next?
     11At this point, you should have successfully installed a GNU Cross
     12Compilation Tools for RTEMS on your host system as well as the RTEMS OS
     13for the target host.  You should have successfully linked the "hello
     14world" program. You may even have downloaded the executable to that
     15target and run it.  What do you do next?
    1816
    19 The answer is that it depends.  You may be interested in
    20 writing an application that uses one of the multiple
    21 APIs supported by RTEMS.  You may need to investigate the
    22 network or filesystem support in RTEMS.  The common
    23 thread is that you are largely finished with this
    24 manual and ready to move on to others.
     17The answer is that it depends.  You may be interested in writing an
     18application that uses one of the multiple APIs supported by RTEMS.
     19You may need to investigate the network or filesystem support in RTEMS.
     20The common thread is that you are largely finished with this manual and
     21ready to move on to others.
    2522
    26 Whether or not you decide to dive in now and write
    27 application code or read some documentation first,
    28 this chapter is for you.  The first section provides
    29 a quick roadmap of some of the RTEMS documentation.
    30 The next section provides a brief overview of the
    31 RTEMS application structure.
     23Whether or not you decide to dive in now and write application code or
     24read some documentation first, this chapter is for you.  The first section
     25provides a quick roadmap of some of the RTEMS documentation.  The next
     26section provides a brief overview of the RTEMS application structure.
    3227
    3328@section Documentation Overview
    3429
    35 When writing RTEMS applications, you should find the
    36 following manuals useful because they define the
    37 calling interface to many of the services provided
    38 by RTEMS:
     30When writing RTEMS applications, you should find the following manuals
     31useful because they define the calling interface to many of the services
     32provided by RTEMS:
    3933
    4034@itemize @bullet
     
    4236Classic RTEMS API based on the RTEID specification.
    4337
    44 @item @b{RTEMS POSIX API User's Guide} describes the
    45 RTEMS POSIX API that is based on the POSIX 1003.1b API.
     38@item @b{RTEMS POSIX API User's Guide} describes the RTEMS POSIX API
     39that is based on the POSIX 1003.1b API. If there is any place where
     40this manual is thin or unclear, please refer to the OpenGroup Single
     41UNIX Specification.  RETEMS tracks that specification for future POSIX
     42revisions.
    4643
    47 @item @b{RTEMS ITRON 3.0 API User's Guide} describes
    48 the RTEMS implementation of the ITRON 3.0 API.
    49 
    50 @item @b{RTEMS Network Supplement} provides information
    51 on the network services provided by RTEMS.
     44@item @b{RTEMS Network Supplement} provides information on the network
     45services provided by RTEMS.  RTEMS provides a BSD sockets programming
     46interface so any network programming book should be helpful.
    5247
    5348@end itemize
    5449
    55 In addition, the following manuals from the GNU Cross
    56 Compilation Toolset include information on run-time services
    57 available.
     50In addition, the following manuals from the GNU Cross Compilation Toolset
     51include information on run-time services available.
    5852
    5953@itemize @bullet
    60 @item @b{Cygnus C Support Library} describes the Standard
    61 C Library functionality provided by Newlib's libc.
     54@item @b{Cygnus C Support Library} describes the Standard C Library
     55functionality provided by Newlib's libc.
    6256
    63 @item @b{Cygnus C Math Library} describes the Standard
    64 C Math Library functionality provided by Newlib's libm.
     57@item @b{Cygnus C Math Library} describes the Standard C Math Library
     58functionality provided by Newlib's libm.
    6559
    6660@end itemize
    6761
    68 Finally, the RTEMS FAQ and mailing list archives are available
    69 at @uref{@value{RTEMSHTTPURL}}.
     62Finally, the RTEMS FAQ, Wiki, and mailing list archives are available
     63at @uref{http://www.rtems.org, http://www.rtems.org}.
    7064
    71 There is a wealth of documentation available for RTEMS and
    72 the GNU tools supporting it.  If you run into something
    73 that is not clear or missing, bring it to our attention.
     65There is a wealth of documentation available for RTEMS and the GNU tools
     66supporting it.  If you run into something that is not clear or missing,
     67bring it to our attention.
    7468
    75 Also, some of the RTEMS documentation is still under
    76 construction.  If you would like to contribute to this
    77 effort, please contact the RTEMS Team at
    78 @uref{mailto:@value{RTEMSUSERS}, @value{RTEMSUSERS}}.
    79 If you are interested in sponsoring the development of a new
    80 feature, BSP, device driver, port of an existing library, etc.,
    81 please contact one of the RTEMS Service Providers listed
    82 at @uref{@value{RTEMSHTTPURL}/support.html,@value{RTEMSHTTPURL}/support.html}.
     69Also, some of the RTEMS documentation is still under construction.
     70If you would like to contribute to this effort, please contact the
     71RTEMS Team at @uref{mailto:@value{RTEMSUSERS}, @value{RTEMSUSERS}}.
     72If you are interested in sponsoring the development of a new feature,
     73BSP, device driver, port of an existing library, etc., please contact
     74@uref{mailto:sales@@oarcorp.com, sales@@oarcorp.com}.
    8375
    8476@section Writing an Application
     
    9082different from a standard UNIX hosted program.
    9183
    92 First, the application developer must provide configuration
    93 information for RTEMS.  This configuration information
    94 includes limits on the maximum number of various OS resources
    95 available and networking configuration among other things.
    96 See the @b{Configuring a System} in the
    97 @b{RTEMS Applications C User's Guide} for more details.
     84First, the application developer must provide configuration information
     85for RTEMS.  This configuration information includes limits on the maximum
     86number of various OS resources available and networking configuration
     87among other things.  See the @b{Configuring a System} in the @b{RTEMS
     88Applications C User's Guide} for more details.
    9889
    99 Second, RTEMS applications may or may not start at
    100 @code{main()}.  Applications begin execution at
    101 one or more user configurable application
    102 initialization tasks or threads.  It is possible
    103 to configure an application to start with a
    104 single thread that whose entry point is @code{main()}.
     90Second, RTEMS applications may or may not start at @code{main()}.
     91Applications begin execution at one or more user configurable application
     92initialization tasks or threads.  It is possible to configure an
     93application to start with a single thread that whose entry point is
     94@code{main()}.
    10595
    106 Each API supported by RTEMS (Classic, POSIX, and ITRON)
    107 allows the user to configure a set of one or more tasks
    108 that are created and started automatically
    109 during RTEMS initialization.  The RTEMS Automatic
    110 Configuration Generation (@code{confdefs.h}) scheme can be
    111 used to easily generate the configuration information for
    112 an application that starts with a single initialization task. 
    113 By convention, unless overridden, the default name of the
    114 initialization task varies based up API.
     96Each API supported by RTEMS (Internal, Classic, and POSIX) allows
     97the user to configure a set of one or more tasks that are created and
     98started automatically during RTEMS initialization.  The RTEMS Automatic
     99Configuration Generation (@code{confdefs.h}) scheme can be used to easily
     100generate the configuration information for an application that starts
     101with a single initialization task.  By convention, unless overridden,
     102the default name of the initialization task varies based up API.
    115103
    116104@itemize @bullet
     
    118106
    119107@item @code{POSIX_Init} - single POSIX API Initialization Thread
    120 
    121 @item @code{ITRON_Init} - single ITRON API Initialization Task
    122108@end itemize
    123109
     
    135121completes by deleting itself.
    136122
    137 As you begin to write RTEMS application code, you may be confused
    138 by the range of alternatives.  Supporting multiple tasking
    139 APIs can make the choices confusing.  Many application groups
    140 writing new code choose one of the APIs as their primary API
    141 and only use services from the others if nothing comparable
    142 is in their preferred one.  However, the support for multiple
    143 APIs is a powerful feature when integrating code from multiple
    144 sources.  You can write new code using POSIX services and
    145 still use services written in terms of the other APIs.
    146 Moreover, by adding support for yet another API, one could
    147 provide the infrastructure required to migrate from a
    148 legacy RTOS with a non-standard API to an API like POSIX.
     123As you begin to write RTEMS application code, you may be confused by the
     124range of alternatives.  Supporting multiple tasking APIs can make the
     125choices confusing.  Many application groups writing new code choose one
     126of the APIs as their primary API and only use services from the others if
     127nothing comparable is in their preferred one.  However, the support for
     128multiple APIs is a powerful feature when integrating code from multiple
     129sources.  You can write new code using POSIX services and still use
     130services written in terms of the other APIs.  Moreover, by adding support
     131for yet another API, one could provide the infrastructure required to
     132migrate from a legacy RTOS with a non-standard API to an API like POSIX.
    149133
    150134
  • doc/started/nt.t

    r84d6744 r9aff0a7  
    11@c
    2 @c  COPYRIGHT (c) 1988-2002.
     2@c  COPYRIGHT (c) 1988-2010.
    33@c  On-Line Applications Research Corporation (OAR).
    44@c  All rights reserved.
     
    1616with input from
    1717@uref{mailto:<D.J@@fiddes.surfaid.org>, David Fiddes <D.J@@fiddes.surfaid.org>}.
    18 It was based upon his successful but unnecessarily
    19 painful efforts with Cygwin beta versions.
    20 Cygwin and this chapter have been updated multiple times since
    21 those early days although their pioneering efforts
    22 and input is still greatly appreciated.
     18It was based upon his successful but unnecessarily painful efforts with
     19Cygwin beta versions.  Cygwin and this chapter have been updated multiple
     20times since those early days although their pioneering efforts and input
     21is still greatly appreciated.
    2322
    2423@section Microsoft Windows Version Requirements
    2524
    26 RTEMS users report fewer problems when using Microsoft
    27 Windows NT, 2000, or XP.  Although, the open source tools
    28 that are used in RTEMS development do execute on Windows 95,
    29 98, or ME, they tend to be more stable when used with
    30 the modern Windows variants.
     25RTEMS users report fewer problems when using Microsoft Windows XP or newer.
    3126
    3227@section Cygwin
    3328
    34 For RTEMS development, the recommended approach is to use
    35 Cygwin 1.0 or later. Cygwin is  available from
    36 @uref{http://sources.redhat.com/cygwin, http://sources.redhat.com/cygwin}
    37 Recent versions of Cygwin are vastly improved over the beta
    38 versions.  Most of the oddities, instabilities, and performance
    39 problems have been resolved.  The installation procedure
    40 is much simpler.  However, there are a handful of issues
    41 that remain to successfully use Cygwin as an RTEMS development
    42 environment.
     29For RTEMS development, the recommended approach is to use Cygwin. Cygwin
     30is  available from @uref{http://www.cygwin.com, http://www.cygwin.com} .
     31The primary issues reported by users of Cygwin is that it is slower
     32on the same hardware than a native GNU/Linux installation and strange
     33issues over carriage return/line feed inconsistencies between UNIX and
     34Windows environments.  However, there are a handful of other issues that
     35may turn up when using Cygwin as an RTEMS development environment.
    4336
    4437@itemize @bullet
     
    8073many confusing errors will result. 
    8174
    82 @item A user has reported that they needed
    83 to set CYGWIN=ntsec for chmod to work correctly, but had to set
    84 CYGWIN=nontsec for compile to work properly (otherwise there were
    85 complaints about permissions on a temporary file).
     75@item A user has reported that they needed to set @code{CYGWIN=ntsec}
     76for chmod to work correctly, but had to set @code{CYGWIN=nontsec}
     77for compile to work properly (otherwise there were complaints about
     78permissions on a temporary file).
    8679
    8780@item If you want to build the tools from source, you have the
    8881same options as UNIX users.
    8982
    90 @item You may have to uncompress archives during this
    91 process.  You must @b{NOT} use @code{WinZip} or
    92 @code{PKZip}.  Instead the un-archiving process uses
    93 the GNU @code{zip} and @code{tar} programs as shown below:
     83@item You may have to uncompress archives during this process.  You must
     84@b{NOT} use @code{WinZip} or @code{PKZip}.  Instead the un-archiving
     85process uses the GNU @code{zip} and @code{tar} programs as shown below:
    9486
    9587@example
     
    10395@section Text Editor
    10496
    105 You absolutely have to use a text editor which can
    106 save files with Unix format. So do @b{NOT} use Notepad
    107 or Wordpad!  There are a number of editors
    108 freely available that can be used. 
     97You absolutely have to use a text editor which can save files with Unix
     98format. So do @b{NOT} use Notepad or Wordpad!  There are a number of
     99editors freely available that can be used.
    109100
    110101@itemize @bullet
    111102@item @b{VIM} (@b{Vi IMproved}) is available from
    112 @uref{http://www.vim.org/,http://www.vim.org/}. 
    113 This editor has the very handy ability to easily
    114 read and write files in either DOS or UNIX style.
     103@uref{http://www.vim.org/,http://www.vim.org/}.  This editor has the very
     104handy ability to easily read and write files in either DOS or UNIX style.
    115105
    116106@item @b{GNU Emacs} is available for many platforms
    117 including MS-Windows.  The official homepage
    118 is @uref{http://www.gnu.org/software/emacs/emacs.html,
     107including MS-Windows.  The official homepage is
     108@uref{http://www.gnu.org/software/emacs/emacs.html,
    119109http://www.gnu.org/software/emacs/emacs.html}.
    120110The GNU Emacs on Windows NT and Windows 95/98 FAQ is at
     
    124114@end itemize
    125115
    126 If you do accidentally end up with files
    127 having MS-DOS style line termination, then you
    128 may have to convert them to Unix format for some
    129 Cygwin programs to operate on them properly. The
    130 program @code{dos2unix} can be used to put them
     116If you do accidentally end up with files having MS-DOS style line
     117termination, then you may have to convert them to Unix format for some
     118Cygwin programs to operate on them properly. The program @code{dos2unix}
     119can be used to put them
    131120back into Unix format as shown below:
    132121
     
    138127@section System Requirements
    139128
    140 Although the finished cross-compiler is fairly easy on resources,
    141 building it can take a significant amount of processing power and
    142 disk space. 
     129Although the finished cross-compiler is fairly easy on resources, building
     130it can take a significant amount of processing power and disk space.
     131Luckily, desktop computers have progressed very far since this guide
     132was originally written so it is unlikely you will have any problems.
     133Just do not use an old cast-off machine with < 1 GB RAM and a 1 Ghz CPU.
     134Unless, of course, you enjoy waiting for things to complete.
    143135
    144 @itemize @bullet
    145 
    146 @item The faster the CPU, the better. The tools and Cygwin can be
    147 @b{very} CPU hungry.
    148 
    149 @item The more RAM, the better.  Reports are that when building GCC
    150 and GDB, peak memory usage can exceed 256 megabytes.
    151 
    152 @item The more disk space, the better. You need more if you are building
    153 the GNU tools and the amount of disk space for binaries is obviously
    154 directly dependent upon the number of CPUs you have cross toolsets
    155 installed for.
    156 
    157 @end itemize
    158 
     136The more disk space, the better. You need more if you are building the
     137GNU tools and the amount of disk space for binaries is obviously directly
     138dependent upon the number of CPUs you have cross toolsets installed for.
     139In addition to the disk space requirements documented earlier for tool
     140building, you will also have to have enough space to install the Cygwin
     141environment.
  • doc/started/require.t

    r84d6744 r9aff0a7  
    11@c
    2 @c  COPYRIGHT (c) 1988-2002.
     2@c  COPYRIGHT (c) 1988-2010.
    33@c  On-Line Applications Research Corporation (OAR).
    44@c  All rights reserved.
     
    2222|              Component             |   Disk Space Required    |
    2323+------------------------------------+--------------------------+
    24 |        archive directory           |        55 Mbytes         |
    25 |        tools src unarchived        |       350 Mbytes         |
    26 |  each individual build directory   |     up to 750 Mbytes     |
    27 |     each installation directory    |      20-200 Mbytes       |
     24|        archive directory           |       120 Mbytes         |
     25|        tools src unarchived        |      1400 Mbytes         |
     26|  each individual build directory   |     up to 2500 Mbytes    |
     27|     each installation directory    |       900 Mbytes         |
    2828+------------------------------------+--------------------------+
    2929@end example
    3030
    31 It is important to understand that the above requirements only address
    32 the GNU C/C++ Cross Compiler Tools themselves.  Adding additional
    33 languages such as Fortran or Objective-C can increase the size
    34 of the build and installation directories.  Also, the unarchived
    35 source and build directories can be removed after the tools are
    36 installed.
     31It is important to understand that the above requirements only address the
     32GNU C/C++ Cross Compiler Tools themselves.  Adding additional languages
     33such as Ada or Go can increase the size of the build and installation
     34directories.  Also, the unarchived source and build directories can be
     35removed after the tools are installed.
    3736
    3837After the tools themselves are installed, RTEMS must be built
     
    4746account in order to estimate the amount of disk space required
    4847to build RTEMS itself.  Attempting to build multiple BSPs in
    49 a single step increases the disk space requirements.  Similarly
    50 enabling optional features increases the build and install
     48a single step increases the disk space requirements.  One some
     49target architectures, this can lead to disk usage during the build
     50of over one gigabyte.
     51
     52Similarly enabling optional features increases the build and install
    5153space requirements.  In particular, enabling and building
    5254the RTEMS tests results in a significant increase in build
     
    5759
    5860The instructions in this manual should work on any computer running
    59 a UNIX variant.  Some native GNU tools are used by this procedure
    60 including:
     61a POSIX environment including GNU/Linux and Cygwin.  Mingw users may
     62encounter additional issues due to the limited POSIX compatibility.
     63Some native GNU tools are used by this procedure including:
    6164
    6265@itemize @bullet
     
    6669@end itemize
    6770
    68 In addition, some native utilities may be deficient for building
    69 the GNU tools.
     71In addition, some native utilities may be deficient for building the
     72GNU tools.  On hosts which have m4 but it is not GNU m4, it is not
     73uncommon to have to install GNU m4. Similarly, some shells are not
     74capable of fully supporting the RTEMS configure scripts.
    7075
    7176@subsection GCC
     
    130135@end itemize
    131136
    132 @subsection Linux
     137@subsection Distribution Independent Potential GNU/Linux Issues
    133138
    134 The following problems have been reported by Linux users:
     139The following problems have been reported by users of various GNU/Linux
     140distributions:
    135141
    136142@itemize @bullet
     
    150156@end itemize
    151157
    152 @section Archive and Build Directories
     158@subsection GNU/Linux Distrobutions using Debian Packaging Format
    153159
    154 If you are using RPM or another packaging format that supports
    155 building a package from source, then there is probably a directory
    156 structure assumed by that packaging format.  Otherwise, you
    157 are free to use whatever organization you like.  However, this
    158 document will use the directory organization described
    159 in @ref{Archive and Build Directory Format}.
     160The 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.
    160161
    161 @subsection RPM Archive and Build Directory Format
     162The 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.
    162163
    163 For RPM, it is assumed that the following subdirectories
    164 are under a root directory such as @code{/usr/src/redhat}:
    165 
    166 @example
    167 BUILD
    168 RPMS
    169 SOURCES
    170 SPECS
    171 SRPMS
    172 @end example
    173 
    174 For the purposes of this document, the RPM @code{SOURCES} directory
    175 is the directory into which all tool source and patches are
    176 assumed to reside.  The @code{BUILD} directory is where the actual
    177 build is performed when building binaries from a source RPM.
    178 The @code{SOURCES} and @code{BUILD} are logically equivalent to
    179 the @code{archive} and @code{tools} directory discussed in the
    180 next section.
    181 
    182 @subsection Archive and Build Directory Format
    183 
    184 When no packaging format requirements are present, the root directory for
    185 the storage of source archives and patches as well as for building the
    186 tools is up to the user.  The only concern is that there be enough
    187 disk space to complete the build.  In this document, the following
    188 organization will be used.
    189 
    190 Make an @code{archive} directory to contain the downloaded
    191 source code and a @code{tools} directory to be used as a build
    192 directory.  The command sequence to do this is shown
    193 below:
    194 
    195 @example
    196 mkdir archive
    197 mkdir tools
    198 @end example
    199 
    200 This will result in an initial directory structure similar to the
    201 one shown in the following figure:
    202 
    203 @example
    204 @group
    205 /whatever/prefix/you/choose/
    206         archive/
    207         tools/
    208 
    209 @end group
    210 @end example
    211 
    212 @c @ifset use-html
    213 @c @html
    214 @c <IMG SRC="sfile12c.jpg" WIDTH=417 HEIGHT=178
    215 @c      ALT="Starting Directory Organization">
    216 @c @end html
    217 @c @end ifset
    218 
    219 
     164Alternatively, 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.
  • doc/started/sample.t

    r84d6744 r9aff0a7  
    11@c
    2 @c  COPYRIGHT (c) 1988-2002.
     2@c  COPYRIGHT (c) 1988-2010.
    33@c  On-Line Applications Research Corporation (OAR).
    44@c  All rights reserved.
     
    5353commonly used BSPs classified by their RTEMS CPU family and pointers
    5454to instructions on how to use them.  [NOTE: All file names should be
    55 prepended with @value{RTEMSUNTAR}/c/src/lib/libbsp.]
     55prepended with @code{rtems-@value{RTEMSAPI}.<VERSION>/c/src/lib/libbsp}.]
    5656
    5757@need 1000
     
    148148@example
    149149cd tools
    150 tar xjf ../archive/examples-VERSION.tgz
    151 @end example
    152 
    153 The sample applications most likely to be of interest to you are:
    154 
    155 @itemize @bullet
    156 @item hello_world_c - C Hello World application with a simple
    157 RTEMS configuration and an entry point not called @code{main()}.
    158 
    159 @item simple_main - Very simple program starting at @code{main()}
    160 and shutting down RTEMS via @code{exit()} without any other operations.
    161 It uses the default configuration inside RTEMS which is only
    162 intended to satisfy @code{autoconf} probes and extremely simple
    163 console-based applications.
    164 
    165 @item libcpp - Simple C++ library for RTEMS showing how to build an
    166 application library written in C++.
    167 
    168 @item psx_sched_report - POSIX Scheduler Reporter is a program
    169 that prints out some scheduler attributes of the RTEMS POSIX API.
    170 
    171 @end itemize
    172 
    173 Each tests is found in a separate subdirectory and built using the
    174 same command sequence.  The @code{hello_world_c} sample will be used
     150tar xjf ../archive/examples-v2-@value{RTEMSAPI}.<VERSION>.tgz
     151@end example
     152
     153Each tests is found in a separate subdirectory and built using the same
     154command sequence.  The @code{hello/hello_world_c} sample will be used
    175155as an example.
    176156
     
    193173
    194174@example
    195 hello_world_c/o-optimize/<filename>.exe
    196 @end example
    197 
    198 The other C/C++ sample applications are built using a similar procedure.
     175hello_world_c/o-optimize/<filename>.ralf
     176@end example
     177
     178The other sample applications are built using a similar procedure.
    199179
    200180@c
     
    203183@section Ada Sample Applications
    204184
    205 The Ada sample application set primarily includes a
    206 a simple Hello World Ada program which can be used
    207 as a starting point for GNAT/RTEMS applications.
    208 Use the following command to unarchive the Ada sample
     185The Ada sample application set primarily includes a a simple Hello
     186World Ada program which can be used as a starting point for GNAT/RTEMS
     187applications.  Use the following command to unarchive the Ada sample
    209188applications:
    210189
    211190@example
    212191cd tools
    213 tar xjf ../archive/ada-examples-@value{VERSION}.tar.bz2
     192tar xjf ../archive/ada-examples-@value{RTEMSAPI}.<VERSION>.tgz
    214193@end example
    215194
     
    220199an opportunity for a volunteer project.
    221200
    222 At this time, there is a
    223 
    224 Provided are example Makefiles for multiple BSPs.  Copy one of these to
    225 the file Makefile.<BOARD_SUPPORT_PACKAGE> and edit it as appropriate for
    226 your local configuration.
     201If your BSP requires special arguments when linking, you may have to augment the file @code{ada-examples-@value{RTEMSAPI}.<VERSION>/Makefile.shared}.  Most RTEMS BSPs do not require special linking arguments so this should not be frequently needed.
    227202
    228203Use the  <INSTALLATION_POINT> and <BOARD_SUPPORT_PACKAGE> specified when
     
    234209
    235210@example
    236 cd tools/hello_world_ada
    237 make -f Makefile.<BOARD_SUPPORT_PACKAGE>
    238 @end example
    239 
    240 NOTE: GNU make is the preferred @code{make} utility.  Other @code{make}
    241 implementations may work but all testing is done with GNU make.
    242 
    243 If the BSP specific modifications to the Makefile were correct and
    244 no errors are detected during the sample application build, it is
     211cd tools/ada-examples-@value{RTEMSAPI}.<VERSION>/ada-examples/hello_world_ada
     212@end example
     213
     214If no errors are detected during the sample application build, it is
    245215reasonable to assume that the build of the GNAT/RTEMS Cross Compiler Tools
    246 for RTEMS and RTEMS itself for the selected host and target
    247 combination was done properly.
     216for RTEMS and RTEMS itself for the selected host and target combination
     217was done properly.
    248218
    249219@section Application Executable
     
    253223
    254224@example
    255 tools/hello_world_ada/o-optimize/<filename>.exe
     225tools/@code{ada-examples-@value{RTEMSAPI}.<VERSION>}/hello_world_ada/o-optimize/<filename>.exe
    256226@end example
    257227
     
    264234@section More Information on RTEMS Application Makefiles
    265235
    266 These sample applications are examples of simple
    267 RTEMS applications that use the RTEMS Application Makefile
    268 system.  This Makefile system simplifies building
    269 RTEMS applications by providing Makefile templates and
    270 capturing the configuration information used to build
    271 RTEMS specific to your BSP.  Building an RTEMS application
    272 for different BSPs is as simple as switching the
    273 setting of @code{RTEMS_MAKEFILE_PATH}.  This Makefile
     236These sample applications are examples of simple RTEMS applications
     237that use the RTEMS Application Makefile system.  This Makefile system
     238simplifies building RTEMS applications by providing Makefile templates and
     239capturing the configuration information used to build RTEMS specific to
     240your BSP.  Building an RTEMS application for different BSPs is as simple
     241as switching the setting of @code{RTEMS_MAKEFILE_PATH}.  This Makefile
    274242system is described in the file @code{make/README}.
     243
     244It is very likely in the future that the RTEMS examples built using an
     245installed RTEMS will be converted to autoconf.
     246
  • doc/started/started.texi

    r84d6744 r9aff0a7  
    99
    1010@c
    11 @c  COPYRIGHT (c) 1988-2002.
     11@c  COPYRIGHT (c) 1988-2010.
    1212@c  On-Line Applications Research Corporation (OAR).
    1313@c  All rights reserved.
     
    2323@include common/setup.texi
    2424@include common/rtems.texi
    25 
    26 @c
    27 @c  Now set all the tool version dependent information
    28 @c
    29 @include tversions.texi
    3025
    3126@ifset use-ascii
Note: See TracChangeset for help on using the changeset viewer.