Imagelibrary/rtems
1
0
Fork 1
mirror of https://gitlab.rtems.org/rtems/rtos/rtems.git synced 2025-11-16 12:34:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

2011-01-02 Danila Bespalov <danila DOT bespalov AT gmail DOT com>

Browse Source 
* started/buildc.t, started/buildrt.t, started/nt.t, started/require.t,
	started/sample.t: Review and improve.
This commit is contained in:
Joel Sherrill
2011-01-02 16:12:05 +00:00
parent 04064003a2
commit 6565d038aa
6 changed files with 147 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
doc/ChangeLog
View File

@@ -1,3 +1,8 @@
2011-01-02 Danila Bespalov <danila DOT bespalov AT gmail DOT com>
* started/buildc.t, started/buildrt.t, started/nt.t, started/require.t,
started/sample.t: Review and improve.
2010-11-24 Joel Sherrill <joel.sherrilL@OARcorp.com>
PR 1674/doc

45
doc/started/buildc.t
View File

@@ -75,6 +75,10 @@ of each component as well as any required RTEMS specific patches.
@c URL: ftp://@value{BINUTILSFTPSITE}@value{BINUTILSFTPDIR}/@value{BINUTILSTAR}
@c @end ifset
@end example
If no patches are required, you can use a package manager provided by your
Linux distribution to install AUTOMAKE and AUTOCONF to avoid building them from
source.
@need 1000
@subheading @value{NEWLIBUNTAR}
@@ -132,7 +136,7 @@ It is @b{NOT} required if using the procedure
described in @ref{Using RPM to Build BINUTILS GCC and NEWLIB}.
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.
@@ -224,6 +228,11 @@ you should use @code{bzcat} instead of @code{cat} as shown above.
Check to see if any of these patches have been rejected using the following
sequence:
@b{NOTE}: If no patch is required for Autoconf and Automake, you can use the
standard package manager provided by your Linux distribution to install them.
Of course, the versions provided by your package manager should be the same
that specified in Makefile.am or better.
@example
cd tools/@value{GCCUNTAR}
@@ -494,8 +503,7 @@ mkdir b-binutils
cd b-binutils
../@value{BINUTILSUNTAR}/configure --target=sparc-rtems@value{RTEMSAPI} \
--prefix=@value{RTEMSPREFIX}
make all
make info
make
make install
@end example
@@ -567,6 +575,14 @@ build directory @code{b-gcc} may be removed.
For more information on the invocation of @code{configure}, please
refer to the documentation for @value{GCCUNTAR} or
invoke the @value{GCCUNTAR} @code{configure} command with the
As you will need to frequently run various commands in the
@value{RTEMSPREFIX}/bin, you can update your @code{~/.bashrc} to include this
line. After doing that, don't forget to run
@example
source ~/.bashrc
@end example
for the changes to take place.
@code{--help} option.
@c
@@ -579,8 +595,8 @@ 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.
The build procedure is the same until the configure step.
A GCC toolset with GNAT enabled requires that @code{ada}
@@ -822,7 +838,7 @@ of the RPMS directory under the RPM root directory.
@value{RTEMSRPMPREFIX}i386-rtems@value{RTEMSAPI}-gdb-@value{GDBVERSION}-@value{GDBRPMRELEASE}.i386.rpm
@end example
NOTE: It may be necessary to remove the build tree in the
@b{NOTE}: It may be necessary to remove the build tree in the
@code{BUILD} directory under the RPM root directory.
@c
@@ -891,13 +907,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.
@@ -909,7 +925,7 @@ in your PATH. As a general rule, including "." in your PATH
is a security risk and should be avoided. Remove "." from
your PATH.
NOTE: In some environments, it may be difficult to remove "."
@b{NOTE}: In some environments, it may be difficult to remove "."
completely from your PATH. In this case, make sure that "."
is after the system directories containing "as" and "ld".
@@ -925,7 +941,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
@@ -935,7 +951,7 @@ does this for the binutils source:
find @value{BINUTILSUNTAR} -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.
@@ -952,9 +968,8 @@ this:
-I../../@value{BINUTILSUNTAR}/gcc -I/@value{BINUTILSUNTAR}/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.

33
doc/started/buildrt.t
View File

@@ -38,7 +38,7 @@ placed in your @code{archive} directory.
@section Unarchive the RTEMS Source
Use the following command sequence to unpack the RTEMS source into the
tools directory:
tools directory:
@example
cd tools
@@ -47,6 +47,20 @@ tar xjf ../archive/@value{RTEMSTAR}
This creates the directory @value{RTEMSUNTAR}.
@section Obtaining the RTEMS Source from CVS
Instead of downloading release tarballs you may choose to check out the current
RTEMS source from CVS. For details on accessing RTEMS CVS repository consult
@uref{http://www.rtems.org/wiki/index.php/RTEMS_CVS_Repository, http://www.rtems.org/wiki/index.php/RTEMS_CVS_Repository}. The steps required
to obtain the source code from CVS are usually like the following:
@example
$ cvs -d :pserver:anoncvs@@www.rtems.com:/usr1/CVS login
Logging in to :pserver:anoncvs@@www.rtems.com:2401/usr1/CVS
CVS password:
$ cvs -d :pserver:anoncvs@@www.rtems.com:/usr1/CVS -z 9 co -P rtems # for the main RTEMS source
$ cvs -d :pserver:anoncvs@@www.rtems.com:/usr1/CVS -z 9 co -P examples-v2 # for examples
@end example
@section Add <INSTALL_POINT>/bin to Executable PATH
@@ -67,9 +81,9 @@ derivatives of the C Shell.
@section Verifying the Operation of the Cross Toolset
In order to insure that the cross-compiler is invoking the correct
In order to ensure that the cross-compiler is invoking the correct
subprograms (like @code{as} and @code{ld}), one can test assemble
a small program. When in verbose mode, @code{gcc} prints out information
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}:
@@ -113,9 +127,9 @@ 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
@@ -123,7 +137,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.
@@ -146,7 +160,7 @@ include the @code{--enable-posix} 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
@@ -156,7 +170,8 @@ cd build-rtems
--disable-posix --disable-networking --disable-cxx \
--enable-rtemsbsp=<BOARD_SUPPORT_PACKAGE>\
--prefix=<INSTALL_POINT>
make all install
make all
make install
@end example
Where the list of currently supported <TARGET_CONFIGURATION>'s and

126
doc/started/nt.t
View File

@@ -1,5 +1,5 @@
@c
@c COPYRIGHT (c) 1988-2002.
@c COPYRIGHT (c) 1988-2010.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@@ -11,35 +11,28 @@
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 <g_montel@@yahoo.com>}
with input from
This chapter was originally written by
@uref{mailto:g_montel@@yahoo.com, Geoffroy Montel <g_montel@@yahoo.com>}
with input from
@uref{mailto:<D.J@@fiddes.surfaid.org>, David Fiddes <D.J@@fiddes.surfaid.org>}.
It was based upon his successful but unnecessarily
painful efforts with Cygwin beta versions.
Cygwin and this chapter have been updated multiple times since
those early days although their pioneering efforts
and input is still greatly appreciated.
It was based upon his successful but unnecessarily painful efforts with
Cygwin beta versions. Cygwin and this chapter have been updated multiple
times since those early days although their pioneering efforts and input
is still greatly appreciated.
@section Microsoft Windows Version Requirements
RTEMS users report fewer problems when using Microsoft
Windows NT, 2000, or XP. Although, the open source tools
that are used in RTEMS development do execute on Windows 95,
98, or ME, they tend to be more stable when used with
the modern Windows variants.
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 1.0 or later. Cygwin is available from
@uref{http://sources.redhat.com/cygwin, http://sources.redhat.com/cygwin}
Recent versions of Cygwin are vastly improved over the beta
versions. Most of the oddities, instabilities, and performance
problems have been resolved. The installation procedure
is much simpler. However, there are a handful of issues
that remain to successfully use Cygwin as an RTEMS development
environment.
For RTEMS development, the recommended approach is to use Cygwin. Cygwin
is available from @uref{http://www.cygwin.com, http://www.cygwin.com} .
The primary issues reported by users of Cygwin is that it is slower
on the same hardware than a native GNU/Linux installation and strange
issues over carriage return/line feed inconsistencies between UNIX and
Windows environments. However, there are a handful of other issues that
may turn up when using Cygwin as an RTEMS development environment.
@itemize @bullet
@@ -62,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}:
@@ -77,45 +70,49 @@ 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 CYGWIN=ntsec for chmod to work correctly, but had to set
CYGWIN=nontsec for compile to work properly (otherwise there were
complaints about permissions on a temporary file).
@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 @b{NOT} use @code{WinZip} or
@code{PKZip}. Instead the un-archiving process uses
the GNU @code{zip} and @code{tar} programs as shown below:
@item You may have to uncompress archives during this process. You must
@b{NOT} use @code{WinZip} or @code{PKZip}. Instead the un-archiving
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.
@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.
@item @b{GNU Emacs} is available for many platforms
including MS-Windows. The official homepage
is @uref{http://www.gnu.org/software/emacs/emacs.html,
including MS-Windows. The official homepage is
@uref{http://www.gnu.org/software/emacs/emacs.html,
http://www.gnu.org/software/emacs/emacs.html}.
The GNU Emacs on Windows NT and Windows 95/98 FAQ is at
@uref{http://www.gnu.org/software/emacs/windows/ntemacs.html,
@@ -123,11 +120,10 @@ http://www.gnu.org/software/emacs/windows/ntemacs.html}.
@end itemize
If you do accidentally end up with files
having MS-DOS style line termination, then you
may have to convert them to Unix format for some
Cygwin programs to operate on them properly. The
program @code{dos2unix} can be used to put them
If you do accidentally end up with files having MS-DOS style line
termination, then you may have to convert them to Unix format for some
Cygwin programs to operate on them properly. The program @code{dos2unix}
can be used to put them
back into Unix format as shown below:
@example
@@ -137,22 +133,16 @@ Dos2Unix: Cleaning file XYZ ...
@section System Requirements
Although the finished cross-compiler is fairly easy on resources,
building it can take a significant amount of processing power and
disk space.
@itemize @bullet
@item The faster the CPU, the better. The tools and Cygwin can be
@b{very} CPU hungry.
@item The more RAM, the better. Reports are that when building GCC
and GDB, peak memory usage can exceed 256 megabytes.
@item The more disk space, the better. You need more if you are building
the GNU tools and the amount of disk space for binaries is obviously
directly dependent upon the number of CPUs you have cross toolsets
installed for.
@end itemize
Although the finished cross-compiler is fairly easy on resources, building
it can take a significant amount of processing power and disk space.
Luckily, desktop computers have progressed very far since this guide
was originally written so it is unlikely you will have any problems.
Just do not use an old cast-off machine with < 1 GB RAM and a 1 Ghz CPU.
Unless, of course, you enjoy waiting for things to complete.
The more disk space, the better. You need more if you are building the
GNU tools and the amount of disk space for binaries is obviously directly
dependent upon the number of CPUs you have cross toolsets installed for.
In addition to the disk space requirements documented earlier for tool
building, you will also have to have enough space to install the Cygwin
environment.

8
doc/started/require.t
View File

@@ -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
+------------------------------------+--------------------------+
@@ -82,7 +82,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
@@ -90,7 +90,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

47
doc/started/sample.t
View File

@@ -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=<INSTALLATION_POINT>/<CPU>-rtems/<BOARD_SUPPORT_PACKAGE>
@@ -30,17 +30,17 @@ export RTEMS_MAKEFILE_PATH=<INSTALLATION_POINT>/<CPU>-rtems/<BOARD_SUPPORT_PACKA
Where <INSTALLATION_POINT> and <BOARD_SUPPORT_PACKAGE> are those used when
configuring and installing RTEMS.
NOTE: In release 4.0, BSPs were installed at
@b{NOTE}: In release 4.0, BSPs were installed at
@code{<INSTALLATION_POINT>/rtems/<BOARD_SUPPORT_PACKAGE>}. This
was changed to be more in compliance with GNU standards.
NOTE: GNU make is the preferred @code{make} utility. Other @code{make}
@b{NOTE}: GNU make is the preferred @code{make} utility. Other @code{make}
implementations may work but all testing is done with GNU make.
If no errors are detected during the sample application build, it is
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:
@@ -179,8 +184,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
@@ -189,7 +194,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/<filename>.exe
@@ -230,7 +235,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/hello_world_ada
@@ -246,10 +251,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/hello_world_ada/o-optimize/<filename>.exe