source: rtems/doc/started/buildrt.t @ e184e3d

4.115
Last change on this file since e184e3d was e184e3d, checked in by Joel Sherrill <joel.sherrill@…>, on Jan 2, 2011 at 4:12:02 PM

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.
  • Property mode set to 100644
File size: 7.3 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2010.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Building RTEMS
10
11@section Obtain the RTEMS Source Code
12
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 is 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
23
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.
30
31@c
32@c  Unarchive the RTEMS Source
33@c
34
35@section Unarchive the RTEMS Source
36
37Use the following command sequence to unpack the RTEMS source into the
38tools directory:
39
40@example
41cd tools
42tar xjf ../archive/rtems-@value{RTEMSAPI}.<VERSION>.tar.bz2
43@end example
44
45This creates the directory rtems-@value{RTEMSAPI}.<VERSION>
46
47@section Obtaining the RTEMS Source from CVS
48
49Instead of downloading release tarballs you may choose to check out the current
50RTEMS source from CVS. For details on accessing RTEMS CVS repository consult
51@uref{http://www.rtems.org/wiki/index.php/RTEMS_CVS_Repository, http://www.rtems.org/wiki/index.php/RTEMS_CVS_Repository}.  The steps required
52to obtain the source code from CVS are usually like the following:
53@example
54$ cvs -d :pserver:anoncvs@@www.rtems.com:/usr1/CVS login
55Logging in to :pserver:anoncvs@@www.rtems.com:2401/usr1/CVS
56CVS password:
57$ cvs -d :pserver:anoncvs@@www.rtems.com:/usr1/CVS -z 9 co -P rtems  # for the main RTEMS source
58$ cvs -d :pserver:anoncvs@@www.rtems.com:/usr1/CVS -z 9 co -P examples-v2  # for examples
59@end example
60
61@section Add <INSTALL_POINT>/bin to Executable PATH
62
63In order to compile RTEMS, you must have the cross compilation toolset
64in your search path.  It is important to have the RTEMS toolset first
65in your path to ensure that you are using the intended version of all
66tools.  The following command prepends the directory where
67the tools were installed in a previous step.  If you are using
68binaries provided by the RTEMS Project, the <INSTALL_POINT> will be
69@code{/opt/rtems-@value{RTEMSAPI}}
70
71@example
72export PATH=<INSTALL_POINT>/bin:$@{PATH@}
73@end example
74
75@b{NOTE:}  The above command is in Bourne shell (@code{sh}) syntax and should
76work with the Korn (@code{ksh}) and GNU Bourne Again Shell (@code{bash}).
77It will not work with the C Shell (@code{csh}) or derivatives of the
78C Shell.
79
80@section Verifying the Operation of the Cross Toolset
81
82In order to ensure that the cross-compiler is invoking the correct
83subprograms (like @code{as} and @code{ld}), one can test assemble
84a small program.  When in verbose mode, @code{gcc} prints out information
85showing where it found the subprograms it invokes.  In a temporary
86working directory, place the following function in a file named @code{f.c}:
87
88@example
89int f( int x )
90@{
91  return x + 1;
92@}
93@end example
94
95Then assemble the file using a command similar to the following:
96
97@example
98m68k-rtems@value{RTEMSAPI}-gcc -v -S f.c
99@end example
100
101Where @code{m68k} should be changed to match the target architecture
102of your cross compiler.  The result of this command will be a sequence
103of output showing where the cross-compiler searched for and found
104its subcomponents.  Verify that these paths correspond to your
105<INSTALL_POINT>.
106
107Look at the created file @code{f.s} and verify that it is in fact
108for your target processor.
109
110Then try to compile the file @code{f.c} directly to object code
111using a command like the following:
112
113@example
114m68k-rtems@code{RTEMSAPI}-gcc -v -c f.c
115@end example
116
117If this produces messages that indicate the assembly code is not valid,
118then it is likely that you have fallen victim to one of the problems
119described in @ref{Error Message Indicates Invalid Option to Assembler}
120Please do not feel bad about this and do not give up, one of the most
121common installation errors is for the cross-compiler not to be able
122to find the cross assembler and default to using the native @code{as}.
123This can result in very confusing error messages.
124
125@section Building RTEMS for a Specific Target and BSP
126
127This section describes how to configure and build RTEMS
128so that it is specifically tailored for your BSP (Board Support Package)
129and the CPU model it uses.  There is currently only one supported
130method to compile and install RTEMS:
131
132@itemize @bullet
133@item direct invocation of @code{configure} and @code{make}
134@end itemize
135
136Direct invocation of @code{configure} and @code{make} provides more control
137and easier recovery from problems when building.
138
139This section describes how to build RTEMS.
140
141@subsection Using the RTEMS configure Script Directly
142
143Make a build directory under tools and build the RTEMS product in this
144directory. The @code{../rtems-@value{RTEMSAPI}.<VERSION>/configure}
145command has numerous command line arguments. These arguments are
146discussed in detail in documentation that comes with the RTEMS
147distribution. A full list of these arguments can be obtained by running
148@code{../rtems-@value{RTEMSAPI}.<VERSION>/configure --help} If you
149followed the procedure described in the section @ref{Unarchive the
150RTEMS Source} or @ref{Obtaining the RTEMS Source from CVS}, these configuration options can be found in the file
151rtems-@value{RTEMSAPI}.<VERSION>/README.configure.
152
153@b{NOTE}: The GNAT/RTEMS run-time implementation is based on the POSIX
154API and the GNAT/RTEMS run-time cannot be compiled with networking
155disabled. Your application does not have to use networking but it must
156be enabled.  Thus the RTEMS configuration for a GNAT/RTEMS environment
157MUST include the @code{--enable-posix --enable-networking} flag.
158
159The following shows the command sequence required to configure,
160compile, and install RTEMS with the POSIX API, FreeBSD TCP/IP,
161and C++ support disabled.  RTEMS will be built to target
162the @code{BOARD_SUPPORT_PACKAGE} board.
163
164@example
165mkdir build-rtems
166cd build-rtems
167../rtems-@value{RTEMSAPI}.VERSION/configure --target=<TARGET_CONFIGURATION> \
168    --disable-posix --disable-networking --disable-cxx \
169    --enable-rtemsbsp=<BSP>\
170    --prefix=<INSTALL_POINT>
171make all
172make install
173@end example
174
175<TARGET> is of the form <CPU>-rtems@value{RTEMSAPI} and the list of
176currently supported <TARGET> configuration's and <BSP>'s can be found in
177@code{tools/RTEMS-@value{RTEMSAPI}.<VERSION>/README.configure}.
178
179<INSTALL_POINT> is typically the installation point for the tools and
180defaults to @code{/opt/rtems-@value{RTEMSAPI}}.
181
182BSP is a supported BSP for the selected CPU family.
183The list of supported BSPs may be found in the file
184@code{tools/rtems-@value{RTEMSAPI}.<VERSION>/README.configure} in the
185RTEMS source tree.  If the BSP parameter is not specified, then all
186supported BSPs for the selected CPU family will be built.
187
188@b{NOTE:} The POSIX API and networking must be enabled to use GNAT/RTEMS.
189
190@b{NOTE:} The @code{make} utility used should be GNU make.
Note: See TracBrowser for help on using the repository browser.