source: rtems/doc/started/buildc.t @ cdf30aba

4.104.114.84.9
Last change on this file since cdf30aba was cdf30aba, checked in by Joel Sherrill <joel.sherrill@…>, on Oct 27, 1998 at 7:28:20 PM

Update from David Fiddes.

  • Property mode set to 100644
File size: 12.4 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-1998.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Building the GNU C/C++ Cross Compiler Toolset
10
11This chapter describes the steps required to acquire the
12source code for a GNU cross compiler toolset, apply
13any required RTEMS specific patches, compile that
14toolset and install it.
15
16@section Create the Archive and Build Directories
17
18Start by making the @code{archive} directory to contain the downloaded
19source code and the @code{tools} directory to be used as a build
20directory.  The command sequence to do this is shown
21below:
22
23@example
24mkdir archive
25mkdir tools
26@end example
27
28This will result in an initial directory structure similar to the
29one shown in the following figure:
30
31@example
32@group
33/whatever/prefix/you/choose/
34        archive/
35        tools/
36
37@end group
38@end example
39
40@c @ifset use-html
41@c @html
42@c <IMG SRC="sfile12c.jpg" WIDTH=417 HEIGHT=178
43@c      ALT="Starting Directory Organization">
44@c @end html
45@c @end ifset
46
47@section Get All the Pieces
48
49This section lists the components of an RTEMS cross development system. 
50Included are the locations of each component as well as any required RTEMS
51specific patches.
52
53@subheading @value{GCC-VERSION}
54@example
55    FTP Site:    @value{GCC-FTPSITE}
56    Directory:   @value{GCC-FTPDIR}
57    File:        @value{GCC-TAR}
58@ifset use-html
59    URL:         @href{Download @value{GCC-VERSION},,,ftp://@value{GCC-FTPSITE}@value{GCC-HTTPDIR}}
60@end ifset
61@end example
62
63@subheading @value{BINUTILS-VERSION}
64@example
65    FTP Site:    @value{BINUTILS-FTPSITE}
66    Directory:   @value{BINUTILS-FTPDIR}
67    File:        @value{BINUTILS-TAR}
68@ifset use-html
69    URL:         @href{Download @value{BINUTILS-VERSION},,,ftp://@value{BINUTILS-FTPSITE}@value{BINUTILS-FTPDIR}/@value{BINUTILS-TAR}}
70@end ifset
71@end example
72
73@subheading @value{NEWLIB-VERSION}
74@example
75    FTP Site:    @value{NEWLIB-FTPSITE}
76    Directory:   @value{NEWLIB-FTPDIR}
77    File:        @value{NEWLIB-TAR}
78@ifset use-html
79    URL:         @href{Download @value{NEWLIB-VERSION},,,ftp://@value{NEWLIB-FTPSITE}@value{NEWLIB-FTPDIR}/@value{NEWLIB-TAR}}
80@end ifset
81@end example
82
83@subheading @value{RTEMS-VERSION}
84@example
85    FTP Site:    @value{RTEMS-FTPSITE}
86    Directory:   @value{RTEMS-FTPDIR}
87    File:        @value{RTEMS-TAR}
88@ifset use-html
89    URL:         @href{Download RTEMS components,,,ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}}
90@end ifset
91@end example
92
93@subheading RTEMS Hello World
94@example
95    FTP Site:    @value{RTEMS-FTPSITE}
96    Directory:   @value{RTEMS-FTPDIR}
97    File:        hello_world_c.tgz
98@ifset use-html
99    URL:         @href{Download RTEMS Hello World,,,ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}/hello_world_c.tgz}
100@end ifset
101@end example
102
103@subheading RTEMS Specific Tool Patches and Scripts
104@example
105    FTP Site:    @value{RTEMS-FTPSITE}
106    Directory:   @value{RTEMS-FTPDIR}/c_tools
107    File:        @value{BUILDTOOLS-TAR}
108@ifset BINUTILS-RTEMSPATCH
109    File:        @value{BINUTILS-RTEMSPATCH}
110@end ifset
111@ifset NEWLIB-RTEMSPATCH
112    File:        @value{NEWLIB-RTEMSPATCH}
113@end ifset
114@ifset GCC-RTEMSPATCH
115    File:        @value{GCC-RTEMSPATCH}
116@end ifset
117@ifset use-html
118    URL:         @href{Download RTEMS Patches and Scripts,,,ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}/c_tools}
119@end ifset
120@end example
121
122@section Unarchiving the Tools
123
124While in the @code{tools} directory, unpack the compressed
125tar files using the following command sequence:
126
127@example
128cd tools
129tar xzf ../archive/@value{GCC-TAR}
130tar xzf ../archive/@value{BINUTILS-TAR}
131tar xzf ../archive/@value{NEWLIB-TAR}
132tar xzf ../archive/@value{BUILDTOOLS-TAR}
133@end example
134
135After the compressed tar files have been unpacked, the following
136directories will have been created under tools.
137
138@itemize @bullet
139@item @value{BINUTILS-UNTAR}
140@item @value{GCC-UNTAR}
141@item @value{NEWLIB-UNTAR}
142@end itemize
143
144There will also be a set of scripts in the current directory
145which aid in building the tools and RTEMS.  They are:
146
147@itemize @bullet
148@item bit
149@item bit_gdb
150@item bit_rtems
151@item common.sh
152@item user.cfg
153@end itemize
154
155When the @code{bit} script is executed later in this process,
156it will automatically create two other subdirectories:
157
158@itemize @bullet
159@item src
160@item build-$@{CPU@}-tools
161@end itemize
162
163Similarly, the @code{bit_gdb} script will create the
164subdirectory @code{build-$@{CPU@}-gdb} and
165the @code{bit_rtems} script will create the
166subdirectory @code{build-$@{CPU@}-rtems}.
167
168The tree should look something like the following figure:
169
170@example
171@group
172/whatever/prefix/you/choose/
173        archive/
174            @value{GCC-TAR}
175            @value{BINUTILS-TAR}
176            @value{NEWLIB-TAR}
177            @value{RTEMS-TAR}
178            @value{BUILDTOOLS-TAR}
179@ifset GCC-RTEMSPATCH
180            @value{GCC-RTEMSPATCH}
181@end ifset
182@ifset BINUTILS-RTEMSPATCH
183            @value{BINUTILS-RTEMSPATCH}
184@end ifset
185@ifset NEWLIB-RTEMSPATCH
186            @value{NEWLIB-RTEMSPATCH}
187@end ifset
188            hello_world_c.tgz
189            bit
190        tools/
191            @value{BINUTILS-UNTAR}/
192            @value{GCC-UNTAR}/
193            @value{NEWLIB-UNTAR}/
194            @value{RTEMS-UNTAR}/
195            bit
196            bit_gdb
197            bit_rtems
198            common.sh
199            user.cfg
200@end group
201@end example
202
203
204@c @ifset use-html
205@c @html
206@c <IMG SRC="bit_c.jpg" WIDTH=816 HEIGHT=267 ALT="Directory Organization">
207@c @end html
208@c @end ifset
209
210@c
211@c  Host Specific Notes
212@c
213
214@section Host Specific Notes
215
216@subsection Solaris 2.x
217
218The build scripts are written in "shell".  The program @code{/bin/sh}
219on Solaris 2.x is not robust enough to execute these scripts.  If you
220are on a Solaris 2.x host, then change the first line of the files
221@code{bit}, @code{bit_gdb}, and @code{bit_rtems} to use the
222@code{/bin/ksh} shell instead.
223
224@subsection Linux
225
226@subsubsection Broken install Program
227
228Certain versions of GNU fileutils include a version of @code{install} which
229does not work properly.  Please perform the following test to see if you
230need to upgrade:
231
232@example
233install -c -d /tmp/foo/bar
234@end example
235
236If this does not create the specified directories your install
237program will not install RTEMS properly.   You will need to upgrade
238to at least GNU fileutile version 3.16 to resolve this problem.
239
240@c
241@c  Reading the Documentation
242@c
243
244@section Reading the Tools Documentation
245
246Each of the tools in the GNU development suite comes with documentation.
247It is in the reader's and tool maintainers' interest that one read the
248documentation before posting a problem to a mailing list or news group.
249
250@c
251@c  EGCS patches
252@c
253
254@section Apply RTEMS Patch to EGCS
255
256@ifclear GCC-RTEMSPATCH
257No RTEMS specific patches are required for @value{GCC-VERSION} to
258support @value{RTEMS-VERSION}.
259@end ifclear
260
261@ifset GCC-RTEMSPATCH
262
263Apply the patch using the following command sequence:
264
265@example
266cd tools/@value{GCC-UNTAR}
267zcat ../../archive/@value{GCC-RTEMSPATCH} | patch -p1
268@end example
269
270Check to see if any of these patches have been rejected using the following
271sequence:
272
273@example
274cd tools/@value{GCC-UNTAR}
275find . -name "*.rej" -print
276@end example
277
278If any files are found with the .rej extension, a patch has been rejected.
279This should not happen with a good patch file which is properly applied.
280
281@end ifset
282
283@c
284@c  BINUTILS patches
285@c
286
287@section Apply RTEMS Patch to binutils
288
289@ifclear BINUTILS-RTEMSPATCH
290No RTEMS specific patches are required for @value{BINUTILS-VERSION} to
291support @value{RTEMS-VERSION}.
292@end ifclear
293
294@ifset BINUTILS-RTEMSPATCH
295Apply the patch using the following command sequence:
296
297@example
298cd tools/@value{BINUTILS-UNTAR}
299zcat ../../archive/@value{BINUTILS-RTEMSPATCH} | patch -p1
300@end example
301
302Check to see if any of these patches have been rejected using the following
303sequence:
304
305@example
306cd tools/@value{BINUTILS-UNTAR}
307find . -name "*.rej" -print
308@end example
309
310If any files are found with the .rej extension, a patch has been rejected.
311This should not happen with a good patch file which is properly applied.
312
313@end ifset
314
315@c
316@c  Newlib patches
317@c
318
319@section Apply RTEMS Patch to newlib
320
321@ifclear NEWLIB-RTEMSPATCH
322No RTEMS specific patches are required for @value{NEWLIB-VERSION} to
323support @value{RTEMS-VERSION}.
324@end ifclear
325
326@ifset NEWLIB-RTEMSPATCH
327
328Apply the patch using the following command sequence:
329
330@example
331cd tools/@value{NEWLIB-UNTAR}
332zcat ../../archive/@value{NEWLIB-RTEMSPATCH} | patch -p1
333@end example
334
335Check to see if any of these patches have been rejected using the following
336sequence:
337
338@example
339cd tools/@value{NEWLIB-UNTAR}
340find . -name "*.rej" -print
341@end example
342
343If any files are found with the .rej extension, a patch has been rejected.
344This should not happen with a good patch file which is properly applied.
345
346@end ifset
347
348@c
349@c  Localizing the Configuration
350@c
351
352@section Localizing the Configuration
353
354Edit the @code{user.cfg} file to alter the settings of various
355variables which are used to tailor the build process.
356Each of the variables set in @code{user.cfg} may be modified
357as described below:
358
359@table @code
360@item INSTALL_POINT
361is the location where you wish the GNU C/C++ cross compilation tools for
362RTEMS to be built. It is recommended that the directory chosen to receive
363these tools be named so that it is clear from which egcs distribution it
364was generated and for which target system the tools are to produce code for.
365
366@b{WARNING}: The @code{INSTALL_POINT} should not be a subdirectory
367under the build directory.  The build directory will be removed
368automatically upon successful completion of the build procedure.
369
370@item BINUTILS
371is the directory under tools that contains @value{BINUTILS-UNTAR}.
372For example:
373
374@example
375BINUTILS=@value{BINUTILS-UNTAR}
376@end example
377
378@item GCC
379is the directory under tools that contains @value{GCC-UNTAR}.
380For example,
381
382@example
383GCC=@value{GCC-UNTAR}
384@end example
385
386@item NEWLIB
387is the directory under tools that contains @value{NEWLIB-UNTAR}.
388For example:
389
390@example
391NEWLIB=@value{NEWLIB-UNTAR}
392@end example
393
394@item BUILD_DOCS
395is set to "yes" if you want to install documentation.
396For example:
397
398@example
399BUILD_DOCS=yes
400@end example
401
402@item BUILD_OTHER_LANGUAGES
403is set to "yes" if you want to build languages other than C and C++.  At
404the current time, this enables Fortan and Objective-C.
405For example:
406
407@example
408BUILD_OTHER_LANGUAGES=yes
409@end example
410
411@b{NOTE:} Based upon the version of the compiler being used, it may not
412be possible to build languages other than C and C++ cross.  In many cases,
413the language run-time support libraries are not "multilib'ed".  Thus the
414executable code in these libraries will be for the default compiler settings
415and not necessarily be correct for your CPU model.
416
417@item RTEMS
418is the directory under tools that contails @value{RTEMS-UNTAR}.
419
420@item ENABLE_RTEMS_POSIX
421is set to "yes" if you want to enable the RTEMS POSIX API support.
422At this time, this feature is not supported by the UNIX ports of RTEMS
423and is forced to "no" for those targets.  This corresponds to the
424@code{configure} option @code{--enable-posix}.
425
426@item ENABLE_RTEMS_TESTS
427is set to "yes" if you want to build the RTEMS Test Suite.  If this
428is set to "no", then only the Sample Tests will be built.
429This corresponds to the @code{configure} option @code{--enable-tests}.
430
431@item ENABLE_RTEMS_TCPIP
432is set to "yes" if you want to build the RTEMS TCP/IP Stack.  If a
433particular BSP does not support TCP/IP, then this feature is automatically
434disabled.  This corresponds to the @code{configure} option
435@code{--enable-tcpip}.
436
437@item ENABLE_RTEMS_CXX
438is set to "yes" if you want to build the RTEMS C++ support including
439the C++ Wrapper for the Classic API.  This corresponds to the
440@code{configure} option @code{--enable-cxx}.
441@end table
442
443@section Running the bit Script
444
445After the @code{bit} script has been modified to reflect the
446local installation, the modified @code{bit} script is run
447using the following sequence:
448
449@example
450cd tools
451./bit <target configuration>
452@end example
453
454Where <target configuration> is one of the following:
455
456@itemize @bullet
457@item hppa1.1
458@item i386
459@item i386-elf
460@item i386-go32
461@item i960
462@item m68k
463@item mips64orion
464@item powerpc
465@item sh
466@item sparc
467@end itemize
468
469If no errors are encountered, the @code{bit} script will conclude by
470printing messages similar to the following:
471
472@example
473
474The src and build-i386-tools subdirectory may now be removed.
475
476Started:  Fri Apr 10 10:14:07 CDT 1998
477Finished: Fri Apr 10 12:01:33 CDT 1998
478@end example
479
480If the @code{bit} script successfully completes, then the
481GNU C/C++ cross compilation tools are installed.
482
483If the @code{bit} script does not successfully complete, then investigation
484will be required to determine the source of the error.
485
Note: See TracBrowser for help on using the repository browser.