From e184e3d5961db26ad0f41342787ad087f79f3431 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Sun, 2 Jan 2011 16:12:02 +0000 Subject: 2011-01-02 Danila Bespalov * started/buildc.t, started/buildrt.t, started/nt.t, started/require.t, started/sample.t: Review and improve. --- doc/ChangeLog | 5 ++ doc/started/buildc.t | 144 ++++++++++++++++++++++++++++---------------------- doc/started/buildrt.t | 41 +++++++++----- doc/started/nt.t | 29 ++++++---- doc/started/require.t | 12 ++--- doc/started/sample.t | 47 ++++++++-------- 6 files changed, 164 insertions(+), 114 deletions(-) (limited to 'doc') diff --git a/doc/ChangeLog b/doc/ChangeLog index cc085424ee..ec47a37210 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2011-01-02 Danila Bespalov + + * started/buildc.t, started/buildrt.t, started/nt.t, started/require.t, + started/sample.t: Review and improve. + 2010-12-16 Joel Sherrill * develenv/direct.t: Remove Getting Started with GNAT/RTEMS. diff --git a/doc/started/buildc.t b/doc/started/buildc.t index 3d2cd3ecd6..b33e841958 100644 --- a/doc/started/buildc.t +++ b/doc/started/buildc.t @@ -8,12 +8,13 @@ @chapter Building the GNU Cross Compiler Toolset -NOTE: This chapter does @b{NOT} apply if you installed prebuilt toolset -executables for BINUTILS, GCC, NEWLIB, and GDB. If you installed -prebuilt executables for all of those, proceed to @ref{Building RTEMS}. -If you require a GDB with a special configuration to connect to your -target board, then proceed to @ref{Installing GDB Without RPM} -for some advice. +@b{NOTE}: This chapter describes the steps required to build cross-compilation +toolset on Linux (and possibly Windows using Cygwin) systems. This chapter +does @b{NOT} apply if you installed prebuilt toolset executables for BINUTILS, +GCC, NEWLIB, and GDB. If you installed prebuilt executables for all of those, +proceed to @ref{Building RTEMS}. If you require a GDB with a special +configuration to connect to your target board, then proceed to +@ref{Installing GDB Without RPM} for some advice. This chapter describes the steps required to acquire the source code for a GNU cross compiler toolset, apply any required RTEMS specific patches, @@ -52,9 +53,14 @@ patches for a particular target architecture. All patches and RPM specification files are kept in CVS. They are not included in release tarballs. You will have to access the CVS branch for RTEMS @value{RTEMSAPI}. For details on this, -visit @uref{http://www.rtems.org, http://www.rtems.org} and look for -instructions on accessing the RTEMS Source Code Repository in read-only -mode. +visit @uref{http://www.rtems.org/wiki/index.php/RTEMS_CVS_Repository, http://www.rtems.org/wiki/index.php/RTEMS_CVS_Repository} and look for +instructions on accessing the RTEMS Source Code Repository in read-only mode. +You can either do a complete checkout of the source tree or use a web +interface. A typical checkout command would look like this: +@c TODO: pointing the user to the wiki entry might be enough. +@example +cvs -d :pserver:anoncvs@@www.rtems.com:/usr1/CVS -z 9 co -P rtems +@end example In the checked out source code, you will need to look in the subdirectory @code{contrib/crossrpms/autotools} to determine the versions of AUTOCONF @@ -62,9 +68,10 @@ and AUTOMAKE as well as any patches required. In this directory are a few files you will need to look at. The first is @code{Makefile.am} which defines the versions of AUTOCONF and AUTOMAKE required for this RTEMS Release Series. Make a note of the version numbers required for -AUTOCONF and AUTOMAKE. Then examine the following files to determine -the master location for the source tarballs and to determine if a patch -is required for each tool version cited in the @code{Makefile.am}. +AUTOCONF and AUTOMAKE (AUTOCONF_VERS and AUTOMAKE_VERS respectively). Then +examine the following files to determine the master location for the source +tarballs and to determine if a patch is required for each tool version cited in +the @code{Makefile.am}. @example autoconf-sources.add @@ -75,6 +82,10 @@ If any patches are required, they will be in the @code{contrib/crossrpms/patches} subdirectory of your checked out RTEMS source tree. +If no patches are required, you can use a package manager provided by your +Linux distribution to install AUTOMAKE and AUTOCONF to avoid building them from +source. + In the checked out source code, you will need to look in the subdirectory @code{contrib/crossrpms/rtems@value{RTEMSAPI}} to determine the target specific tool versions and patches required. In this directory, you @@ -101,12 +112,6 @@ This is the entire set of source tarballs and patches required for a toolset targeting the selected architecture. In many cases, this will be the same versions required by other targets on this RTEMS Release Series. -Depending on the build method chosen, you may have to download source -and patches or only patches. Also the destination directory for the -downloaded source is dependent on the build method followed. But the -versions required are the same. Specific information on what to download -and where to place it is in subsequent sections. - @c @c Obtain Source and Patches @c @@ -171,13 +176,13 @@ Patches are in the @code{contrib/crossrpms/patches}. @c @subsection Unarchiving the Tools -NOTE: This step is required if building any of the tools without using RPM. +@b{NOTE}: This step is required if building any of the tools without using RPM. It is @b{NOT} required if using the procedure described in @ref{Using RPM to Build Tools}. This section describes the process of unarchiving the tools that comprise an RTEMS toolset. GNU source distributions are archived using @code{tar} and -compressed using either @code{gzip} or @code{bzip}. +compressed using either @code{gzip} or @code{bzip}. If compressed with @code{gzip}, the extension @code{.gz} is used. If compressed with @code{bzip}, the extension @code{.bz2} is used. @@ -199,7 +204,7 @@ the following directories will have been created under @code{tools}. @item automake- @item binutils- @item gcc- -@item binutils- +@item newlib- @item gdb- @end itemize @@ -222,23 +227,25 @@ The tree should look something like the following figure: @subsection Applying RTEMS Project Tool Patches -NOTE: This step is required if building any of the tools IF they have a +@b{NOTE}: This step is required if building any of the tools IF they have a patch currently required and you are building the tools without using RPM. is @b{NOT} required if using the procedure described in @ref{Using RPM to Build Tools}. This section describes the process of applying the RTEMS patches to any of the tools. -If a patch is required for a particular tool source tree, then you will -perform a command similar to the following to apply the patch. In this -example, should be replaced by the appropriate tool directory -and with the appropriate patch file. +If a patch is required for a particular tool source tree, it is placed in the +@code{contrib/crossrpms/patches} directory in the CVS tree. Make sure the +patch version is the same as of the tool you are building. You will perform a +command similar to the following to apply the patch. In this example, +should be replaced by the appropriate tool directory and with the +appropriate patch file. @example cd tools/ cat ../../archive/ | patch -p1 @end example -NOTE: If you add the @code{--dry-run} option to the @code{patch} command +@b{NOTE}: If you add the @code{--dry-run} option to the @code{patch} command in the above commands, it will attempt to apply the patch and report any issues without actually modifying any files. @@ -260,21 +267,25 @@ If any files are found with the .rej extension, a patch has been rejected. This should not happen with a good patch file which is properly applied. @c -@c Installing AUTOCONF Without RPM +@c Installing AUTOCONF From Source @c -@subsection Installing AUTOCONF Without RPM +@subsection Installing AUTOCONF From Source The following example illustrates the invocation of @code{configure} -and @code{make} to build and install autoconf-. This tool is +and @code{make} to build and install autoconf-. This tool is installed as a native utility and is independent of any RTEMS target. +@b{NOTE}: If no patch is required for Autoconf and Automake, you can use the +standard package manager provided by your Linux distribution to install them. +Of course, the versions provided by your package manager should be the same +that specified in Makefile.am or better. + @example mkdir b-autoconf cd b-autoconf ../autoconf-/configure --prefix=@value{RTEMSPREFIX} -make all -make info +make make install @end example @@ -286,13 +297,13 @@ refer to the documentation for autoconf- or invoke the autoconf-VERSION> @code{configure} command with the @code{--help} option. @c -@c Installing AUTOMAKE Without RPM +@c Installing AUTOMAKE From Source @c -@subsection Installing AUTOMAKE Without RPM +@subsection Installing AUTOMAKE From Source The following example illustrates the invocation of @code{configure} -and @code{make} to build and install automake-. This tool is +and @code{make} to build and install automake-. This tool is installed as a native utility and is independent of any RTEMS target. @example @@ -312,9 +323,9 @@ refer to the documentation for automake- or invoke the automake-VERSION> @code{configure} command with the @code{--help} option. @c -@c Installing BINUTILS Without RPM +@c Installing BINUTILS From Source @c -@subsection Installing BINUTILS Without RPM +@subsection Installing BINUTILS From Source The following example illustrates the invocation of @code{configure} and @code{make} to build and install binutils- @@ -346,6 +357,14 @@ containing the executables is the prefix used above with export PATH=@value{RTEMSPREFIX}/bin:$@{PATH@} @end example +As you will need to frequently run various commands in the +@value{RTEMSPREFIX}/bin, you can update your @code{~/.bashrc} to include this +line. After doing that, don't forget to run +@example +source ~/.bashrc +@end example +for the changes to take place. + Failure to have the binutils in the path will cause the GCC and NEWLIB build to fail with an error message similar to: @@ -358,11 +377,11 @@ sparc-rtems@value{RTEMSAPI}-ar: command not found @c @subsection Installing GCC and NEWLIB Without RPM -Before building gcc- and newlib-, +Before building gcc- and newlib-, binutils- must be installed and the directory containing those executables must be in your PATH. -The C Library is built as a subordinate component of +The C Library is built as a subordinate component of gcc-. Because of this, the newlib- directory source must be available inside the gcc- source tree. This is normally accomplished using a symbolic @@ -390,7 +409,7 @@ make info make install @end example -After gcc- is built and installed the +After gcc- is built and installed the build directory @code{b-gcc} may be removed. For more information on the invocation of @code{configure}, please @@ -408,11 +427,11 @@ If you want a GCC toolset that includes support for Ada the host environment and additional build steps to perform. It is critical that you use the same version of GCC/GNAT as the native compiler. GNAT must be compiled with an Ada compiler -and when building a GNAT cross-compiler, it should be -the same version of GNAT itself. +and when building a GNAT cross-compiler, it should be +the same version of GNAT itself. It is also important to verify whether there is an RTEMS specific -Ada patch required for GCC. These can be found in +Ada patch required for GCC. These can be found in @uref{http://www.rtems.org/ftp/pub/rtems/people/joel/ada, http://www.rtems.org/ftp/pub/rtems/people/joel/ada}. The patch is often a minor version or two behind GCC but will usually apply cleanly. @@ -458,7 +477,7 @@ After gcc- is built and installed the build directory @c @subsection Installing GDB Without RPM -NOTE: This step is NOT required if prebuilt executables for the +@b{NOTE}: This step is NOT required if prebuilt executables for the GDB were installed and they meet your target interface requirements. @@ -538,7 +557,7 @@ RPM is a packaging format which can be used to distribute binary files as well as to capture the procedure and source code used to produce those binary files. For RPM, it is assumed that the following subdirectories are under a root directory such as @code{/usr/src/redhat} or -@code{/usr/local/src/redhat}) on your machine. +@code{/usr/local/src/redhat}) on your machine. @example BUILD @@ -551,7 +570,7 @@ SRPMS For the purposes of this document, the RPM @code{SOURCES} directory is the directory into which all tool source and patches are assumed to reside. The @code{BUILD} directory is where the actual build is performed when -building binaries from a source RPM. +building binaries from a source RPM. RPM automatically unarchives the source and applies any needed patches so you do @b{NOT} have to manually perform the procedures described @@ -581,7 +600,7 @@ This section illustrates the invocation of RPM to build a new, locally compiled, AUTOCONF binary RPM that matches the installed source RPM. This example assumes that all of the required source is installed. -@example +@example rpm -U @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-autoconf--.src.rpm @end example @@ -598,7 +617,7 @@ directory under the RPM root directory. @value{RTEMSRPMPREFIX}rtems@value{RTEMSAPI}-autoconf--..rpm @end example -NOTE: It may be necessary to remove the build tree in the @code{BUILD} +@b{NOTE}: It may be necessary to remove the build tree in the @code{BUILD} directory under the RPM root directory. @c @@ -610,7 +629,7 @@ This section illustrates the invocation of RPM to build a new, locally compiled, AUTOMAKE binary RPM that matches the installed source RPM. This example assumes that all of the required source is installed. -@example +@example rpm -U @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-automake--.src.rpm @end example @@ -627,7 +646,7 @@ directory under the RPM root directory. @value{RTEMSRPMPREFIX}rtems@value{RTEMSAPI}-automake--..rpm @end example -NOTE: It may be necessary to remove the build tree in the @code{BUILD} +@b{NOTE}: It may be necessary to remove the build tree in the @code{BUILD} directory under the RPM root directory. @@ -640,7 +659,7 @@ This section illustrates the invocation of RPM to build a new, locally compiled, binutils binary RPM that matches the installed source RPM. This example assumes that all of the required source is installed. -@example +@example rpm -U @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-binutils--.src.rpm @end example @@ -691,9 +710,9 @@ of the RPMS directory under the RPM root directory. @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-libstd++--..rpm @end example -NOTE: Some targets do not support building all languages. +@b{NOTE}: Some targets do not support building all languages. -NOTE: It may be necessary to remove the build tree in the +@b{NOTE}: It may be necessary to remove the build tree in the @code{BUILD} directory under the RPM root directory. @c @@ -724,7 +743,7 @@ of the RPMS directory under the RPM root directory. @value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-gdb--..rpm @end example -NOTE: It may be necessary to remove the build tree in the +@b{NOTE}: It may be necessary to remove the build tree in the @code{BUILD} directory under the RPM root directory. @c @@ -749,13 +768,13 @@ This can occur for one of the following reasons: @end itemize If you are using binutils 2.9.1 or newer with certain older versions of -gcc, they do not agree on what the name of the newly +gcc, they do not agree on what the name of the newly generated cross assembler is. Older binutils called it @code{as.new} which became @code{as.new.exe} under Windows. This is not a valid file name, so @code{as.new} is now called @code{as-new}. By using the latest released tool versions and RTEMS patches, this problem will be avoided. -If binutils did not successfully build the cross assembler, then +If binutils did not successfully build the cross assembler, then the new cross gcc (@code{xgcc}) used to build the libraries can not find it. Make sure the build of the binutils succeeded. @@ -767,7 +786,7 @@ in your PATH. As a general rule, including "." in your PATH is a security risk and should be avoided. Remove "." from your PATH. -NOTE: In some environments, it may be difficult to remove "." +@b{NOTE}: In some environments, it may be difficult to remove "." completely from your PATH. In this case, make sure that "." is after the system directories containing "as" and "ld". @@ -783,7 +802,7 @@ If you see error messages like the following, @end itemize -Then it is likely that one or more of your gnu tools is +Then it is likely that one or more of your gnu tools is already configured locally in its source tree. You can check for this by searching for the @code{config.status} file in the various tool source trees. The following command @@ -793,7 +812,7 @@ does this for the binutils source: find binutils- -name config.status -print @end example -The solution for this is to execute the command +The solution for this is to execute the command @code{make distclean} in each of the GNU tools root source directory. This should remove all generated files including Makefiles. @@ -810,9 +829,8 @@ this: -I../../binutils-/gcc -I/binutils-/gcc/include -I. @end example -Note that the tool source directory is searched before the +Note that the tool source directory is searched before the build directory. -This situation can be avoided entirely by never using -the source tree as the build directory -- even for - +This situation can be avoided entirely by never using +the source tree as the build directory. diff --git a/doc/started/buildrt.t b/doc/started/buildrt.t index 8c951b116f..a18f0d9847 100644 --- a/doc/started/buildrt.t +++ b/doc/started/buildrt.t @@ -13,9 +13,9 @@ This section provides pointers to the RTEMS source code and example programs. These files should be placed in your @code{archive} directory. The set of tarballs which comprise an RTEMS release is placed in a -directory whose name if the release on the ftp site. The RTEMS ftp site +directory whose name is the release on the ftp site. The RTEMS ftp site is accessible via both the ftp and http protocols at the following URLs: - + @itemize @bullet @item @uref{http://www.rtems.org/ftp/pub/rtems,http://www.rtems.org/ftp/pub/rtems} @item @uref{ftp://www.rtems.org/pub/rtems,ftp://www.rtems.org/pub/rtems} @@ -35,7 +35,7 @@ This new collection is called "Examples V2". It is contained in the file @section Unarchive the RTEMS Source Use the following command sequence to unpack the RTEMS source into the -tools directory: +tools directory: @example cd tools @@ -44,6 +44,20 @@ tar xjf ../archive/rtems-@value{RTEMSAPI}..tar.bz2 This creates the directory rtems-@value{RTEMSAPI}. +@section Obtaining the RTEMS Source from CVS + +Instead of downloading release tarballs you may choose to check out the current +RTEMS source from CVS. For details on accessing RTEMS CVS repository consult +@uref{http://www.rtems.org/wiki/index.php/RTEMS_CVS_Repository, http://www.rtems.org/wiki/index.php/RTEMS_CVS_Repository}. The steps required +to obtain the source code from CVS are usually like the following: +@example +$ cvs -d :pserver:anoncvs@@www.rtems.com:/usr1/CVS login +Logging in to :pserver:anoncvs@@www.rtems.com:2401/usr1/CVS +CVS password: +$ cvs -d :pserver:anoncvs@@www.rtems.com:/usr1/CVS -z 9 co -P rtems # for the main RTEMS source +$ cvs -d :pserver:anoncvs@@www.rtems.com:/usr1/CVS -z 9 co -P examples-v2 # for examples +@end example + @section Add /bin to Executable PATH In order to compile RTEMS, you must have the cross compilation toolset @@ -65,9 +79,9 @@ C Shell. @section Verifying the Operation of the Cross Toolset -In order to insure that the cross-compiler is invoking the correct +In order to ensure that the cross-compiler is invoking the correct subprograms (like @code{as} and @code{ld}), one can test assemble -a small program. When in verbose mode, @code{gcc} prints out information +a small program. When in verbose mode, @code{gcc} prints out information showing where it found the subprograms it invokes. In a temporary working directory, place the following function in a file named @code{f.c}: @@ -110,9 +124,9 @@ This can result in very confusing error messages. @section Building RTEMS for a Specific Target and BSP -This section describes how to configure and build RTEMS -so that it is specifically tailored for your BSP and the -CPU model it uses. There is currently only one supported +This section describes how to configure and build RTEMS +so that it is specifically tailored for your BSP (Board Support Package) +and the CPU model it uses. There is currently only one supported method to compile and install RTEMS: @itemize @bullet @@ -120,7 +134,7 @@ method to compile and install RTEMS: @end itemize Direct invocation of @code{configure} and @code{make} provides more control -and easier recovery from problems when building. +and easier recovery from problems when building. This section describes how to build RTEMS. @@ -133,8 +147,8 @@ discussed in detail in documentation that comes with the RTEMS distribution. A full list of these arguments can be obtained by running @code{../rtems-@value{RTEMSAPI}./configure --help} If you followed the procedure described in the section @ref{Unarchive the -RTEMS Source}, these configuration options can be found in the file -tools/rtems-@value{RTEMSAPI}./README.configure. +RTEMS Source} or @ref{Obtaining the RTEMS Source from CVS}, these configuration options can be found in the file +rtems-@value{RTEMSAPI}./README.configure. @b{NOTE}: The GNAT/RTEMS run-time implementation is based on the POSIX API and the GNAT/RTEMS run-time cannot be compiled with networking @@ -144,7 +158,7 @@ MUST include the @code{--enable-posix --enable-networking} flag. The following shows the command sequence required to configure, compile, and install RTEMS with the POSIX API, FreeBSD TCP/IP, -and C++ support disabled. RTEMS will be built to target +and C++ support disabled. RTEMS will be built to target the @code{BOARD_SUPPORT_PACKAGE} board. @example @@ -154,7 +168,8 @@ cd build-rtems --disable-posix --disable-networking --disable-cxx \ --enable-rtemsbsp=\ --prefix= -make all install +make all +make install @end example is of the form -rtems@value{RTEMSAPI} and the list of diff --git a/doc/started/nt.t b/doc/started/nt.t index 289c58aa76..8b241d5b79 100644 --- a/doc/started/nt.t +++ b/doc/started/nt.t @@ -11,9 +11,9 @@ This chapter discusses the installation of the GNU tool chain on a computer running the Microsoft Windows operating system. -This chapter was originally written by -@uref{mailto:g_montel@@yahoo.com, Geoffroy Montel } -with input from +This chapter was originally written by +@uref{mailto:g_montel@@yahoo.com, Geoffroy Montel } +with input from @uref{mailto:, David Fiddes }. It was based upon his successful but unnecessarily painful efforts with Cygwin beta versions. Cygwin and this chapter have been updated multiple @@ -24,7 +24,7 @@ is still greatly appreciated. RTEMS users report fewer problems when using Microsoft Windows XP or newer. -@section Cygwin +@section Cygwin For RTEMS development, the recommended approach is to use Cygwin. Cygwin is available from @uref{http://www.cygwin.com, http://www.cygwin.com} . @@ -55,7 +55,7 @@ GNU bash, version 2.04.5(12)-release (i686-pc-cygwin) Copyright 1999 Free Software Foundation, Inc. @end example -If you get an error or it claims to be any other shell, you need +If you get an error or it claims to be any other shell, you need to copy it to a fake name and copy @code{/bin/bash.exe} to @code{/bin/sh.exe}: @@ -70,14 +70,14 @@ shell scripts properly. @item Make sure you unarchive and build in a binary mounted filesystem (e.g. mounted with the @code{-b} option). Otherwise, -many confusing errors will result. +many confusing errors will result. @item A user has reported that they needed to set @code{CYGWIN=ntsec} for chmod to work correctly, but had to set @code{CYGWIN=nontsec} for compile to work properly (otherwise there were complaints about permissions on a temporary file). -@item If you want to build the tools from source, you have the +@item If you want to build the tools from source, you have the same options as UNIX users. @item You may have to uncompress archives during this process. You must @@ -85,20 +85,27 @@ same options as UNIX users. process uses the GNU @code{zip} and @code{tar} programs as shown below: @example -tar -xzvf archive.tgz +tar -xzvf archive.tgz @end example @code{tar} is provided with Cygwin. @end itemize +@section MingGW + +You might consider choosing MinGW since it provides better perfomance. There is a wiki entry on a MinGW RTEMS toolset installer available at @uref{http://www.rtems.org/wiki/index.php/MinGW_Tools_for_Windows,http://www.rtems.org/wiki/index.php/MinGW_Tools_for_Windows}. Also, there are prebuilt tools for different architectures available for download at @uref{http://www.rtems.org/ftp/pub/rtems/mingw32,http://www.rtems.org/ftp/pub/rtems/mingw32}. + @section Text Editor -You absolutely have to use a text editor which can save files with Unix -format. So do @b{NOT} use Notepad or Wordpad! There are a number of -editors freely available that can be used. +You absolutely have to use a text editor which can save files with Unix format. +So do @b{NOT} use Notepad or Wordpad! Basically, any more or less advanced +text editor is usually able to do that. There is a number of editors freely +available that can be used. @itemize @bullet +@item @b{Notepad++} has an interface familiar to Windows users and can be downloaded from @uref{http://notepad-plus-plus.org/,http://notepad-plus-plus.org/}. + @item @b{VIM} (@b{Vi IMproved}) is available from @uref{http://www.vim.org/,http://www.vim.org/}. This editor has the very handy ability to easily read and write files in either DOS or UNIX style. diff --git a/doc/started/require.t b/doc/started/require.t index 2c874c72a9..8f43cc1209 100644 --- a/doc/started/require.t +++ b/doc/started/require.t @@ -8,14 +8,14 @@ @chapter Requirements -This chapter describes the build-host system requirements and initial steps +This chapter describes the build-host system requirements and initial steps in installing the GNU Cross Compiler Tools and RTEMS on a build-host. @section Disk Space A fairly large amount of disk space is required to perform the build of the GNU C/C++ Cross Compiler Tools for RTEMS. The following table may help in -assessing the amount of disk space required for your installation: +assessing the amount of disk space required for your installation: @example +------------------------------------+--------------------------+ @@ -45,7 +45,7 @@ will tend to be in the 40-60 Mbyte range. There are a number of factors which must be taken into account in order to estimate the amount of disk space required to build RTEMS itself. Attempting to build multiple BSPs in -a single step increases the disk space requirements. One some +a single step increases the disk space requirements. On some target architectures, this can lead to disk usage during the build of over one gigabyte. @@ -87,7 +87,7 @@ compiler. Both NEWLIB and RTEMS use GNU make specific features and can only be built using GNU make. Many systems include a make utility that is not GNU make. The safest way to meet this requirement is to ensure that when you invoke -the command @code{make}, it is GNU make. This can be verified by +the command @code{make}, it is GNU make. This can be verified by attempting to print the GNU make version information: @example @@ -95,7 +95,7 @@ make --version @end example If you have GNU make and another make on your system, it is common to put -the directory containing GNU make before the directory containing other +the directory containing GNU make before the directory containing other implementations of make. @subsection GNU makeinfo Version Requirements @@ -155,7 +155,7 @@ to at least GNU fileutils version 3.16 to resolve this problem. @end itemize -@subsection GNU/Linux Distrobutions using Debian Packaging Format +@subsection GNU/Linux Distrobutions using Debian Packaging Format The RTEMS Project does not currently provide prebuilt toolsets in the Debian packaging format used by the Debian and Ubuntu distributions. If you are using a distribution using this packaging format, then you have two options for installing the RTEMS toolset. diff --git a/doc/started/sample.t b/doc/started/sample.t index 930a2822b0..701fca60ba 100644 --- a/doc/started/sample.t +++ b/doc/started/sample.t @@ -8,20 +8,20 @@ @chapter Building the Sample Applications -The RTEMS distribution includes a number of sample C, C++, +The RTEMS distribution includes a number of sample C, C++, Ada, and networking applications. This chapter will provide an overview of those sample applications. @c -@c Set the Environment Variable RTEMS_MAKEFILE_PATH -@c -@section Set the Environment Variable RTEMS_MAKEFILE_PATH +@c Set the Environment Variable RTEMS_MAKEFILE_PATH +@c +@section Set the Environment Variable RTEMS_MAKEFILE_PATH The sample application sets use the RTEMS Application Makefiles. -This requires that the environment variable +This requires that the environment variable @code{RTEMS_MAKEFILE_PATH} point to the appropriate directory containing the installed RTEMS image built to target your particular CPU and -board support package combination. +board support package combination. @example export RTEMS_MAKEFILE_PATH=/-rtems/ @@ -30,17 +30,17 @@ export RTEMS_MAKEFILE_PATH=/-rtems/ and are those used when configuring and installing RTEMS. -NOTE: In release 4.0, BSPs were installed at +@b{NOTE}: In release 4.0, BSPs were installed at @code{/rtems/}. This was changed to be more in compliance with GNU standards. -NOTE: GNU make is the preferred @code{make} utility. Other @code{make} +@b{NOTE}: GNU make is the preferred @code{make} utility. Other @code{make} implementations may work but all testing is done with GNU make. If no errors are detected during the sample application build, it is reasonable to assume that the build of the GNU Cross Compiler Tools for RTEMS and RTEMS itself for the selected host and target -combination was done properly. +combination was done properly. @c @c Executing the Sample Applications @@ -97,7 +97,7 @@ The TX3904 is a MIPS R3000 class CPU with serial ports and timers integrated with the processor. This BSP can be used with either real hardware or with the simulator included with @code{mipstx39-rtems-gdb}. An application can be run on the simulator -by executing the following commands upon entering @code{mipstx39-rtems-gdb}: +by executing the following commands upon entering @code{mipstx39-rtems-gdb}: @example target sim --board=jmr3904 @@ -117,10 +117,11 @@ The simulator is complicated to initialize by hand. The user is referred to the script @code{powerpc/psim/tools/psim}. @item sparc/erc32 -The ERC32 is a radiation hardened SPARC V7. This BSP can be used with -either real ERC32 hardware or with the simulator included with -@code{sparc-rtems-gdb}. An application can be run on the simulator -by executing the following commands upon entering @code{sparc-rtems-gdb}: +The ERC32 is a radiation hardened SPARC V7. This BSP can be used with either +real ERC32 hardware or with the simulator included with @code{sparc-rtems-gdb} +(for this, you should configure RTEMS to use @code{sis} BSP). An application +can be run on the simulator by executing the following commands upon entering +@code{sparc-rtems-gdb}: @example target sim @@ -128,6 +129,10 @@ load run @end example +In case that you don't need a debugger, an application can be run by +@code{spart-rtems-run}. + + @end table RTEMS has many more BSPs and new BSPs for commercial boards and CPUs @@ -141,7 +146,7 @@ with on-CPU peripherals are generally welcomed. The C/C++ sample application set includes a number of simple applications. Some demonstrate some basic functionality in RTEMS such as writing a file, closing it, and reading it back while others can serve as -starting points for RTEMS applications or libraries. Start by +starting points for RTEMS applications or libraries. Start by unarchiving them so you can peruse them. Use a command similar to the following to unarchive the sample applications: @@ -159,8 +164,8 @@ as an example. @c @subheading Build the C Hello World Application -Use the following command to start the build of the sample hello -world application: +Use the following command to start the build of the sample hello +world application: @example cd hello_world_c @@ -169,7 +174,7 @@ make If the sample application has successfully been built, then the application -executable is placed in the following directory: +executable is placed in the following directory: @example hello_world_c/o-optimize/.ralf @@ -205,7 +210,7 @@ configuring and installing RTEMS. @section Build the Sample Application -Use the following command to start the build of the sample application: +Use the following command to start the build of the sample application: @example cd tools/ada-examples-@value{RTEMSAPI}./ada-examples/hello_world_ada @@ -216,10 +221,10 @@ reasonable to assume that the build of the GNAT/RTEMS Cross Compiler Tools for RTEMS and RTEMS itself for the selected host and target combination was done properly. -@section Application Executable +@section Application Executable If the sample application has successfully been build, then the application -executable is placed in the following directory: +executable is placed in the following directory: @example tools/@code{ada-examples-@value{RTEMSAPI}.}/hello_world_ada/o-optimize/.exe -- cgit v1.2.3