source: rtems/doc/started_ada/buildada.t @ 6449498

4.104.114.84.9
Last change on this file since 6449498 was 6449498, checked in by Joel Sherrill <joel.sherrill@…>, on Jan 17, 2002 at 9:47:47 PM

2001-01-17 Joel Sherrill <joel@…>

  • SUPPORT, LICENSE: New files.
  • Numerous files touched as part of merging the 4.5 branch onto the mainline development trunk and ensuring that the script that cuts snapshots and releases works on the documentation.
  • Property mode set to 100644
File size: 20.0 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2002.
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 GNAT 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@c    URL:         @uref{ftp://@value{GCC-FTPSITE}@value{GCC-FTPDIR}/@value{GCC-TAR},Download @value{GCC-VERSION}}
60    URL:         ftp://@value{GCC-FTPSITE}@value{GCC-FTPDIR}/@value{GCC-TAR}
61@end ifset
62@end example
63
64@subheading @value{GNAT-VERSION}
65@example
66    FTP Site:    @value{GNAT-FTPSITE}
67    Directory:   @value{GNAT-FTPDIR}
68    File:        @value{GNAT-TAR}
69@ifset use-html
70@c    URL:         @uref{ ftp://@value{GNAT-FTPSITE}@value{GNAT-FTPDIR}/@value{GNAT-TAR}, Download @value{GNAT-VERSION}}
71    URL:         ftp://@value{GNAT-FTPSITE}@value{GNAT-FTPDIR}/@value{GNAT-TAR}
72@end ifset
73@end example
74
75@subheading @value{BINUTILS-VERSION}
76@example
77    FTP Site:    @value{BINUTILS-FTPSITE}
78    Directory:   @value{BINUTILS-FTPDIR}
79    File:        @value{BINUTILS-TAR}
80@ifset use-html
81@c    URL:         @uref{ftp://@value{BINUTILS-FTPSITE}@value{BINUTILS-FTPDIR}/@value{BINUTILS-TAR}, Download @value{BINUTILS-VERSION}}
82    URL:         ftp://@value{BINUTILS-FTPSITE}@value{BINUTILS-FTPDIR}/@value{BINUTILS-TAR}
83@end ifset
84@end example
85
86@subheading @value{NEWLIB-VERSION}
87@example
88    FTP Site:    @value{NEWLIB-FTPSITE}
89    Directory:   @value{NEWLIB-FTPDIR}
90    File:        @value{NEWLIB-TAR}
91@ifset use-html
92@c    URL:         @uref{ftp://@value{NEWLIB-FTPSITE}@value{NEWLIB-FTPDIR}/@value{NEWLIB-TAR}, Download @value{NEWLIB-VERSION}}
93    URL:         ftp://@value{NEWLIB-FTPSITE}@value{NEWLIB-FTPDIR}/@value{NEWLIB-TAR}
94@end ifset
95@end example
96
97@subheading @value{RTEMS-VERSION}
98@example
99    FTP Site:    @value{RTEMS-FTPSITE}
100    Directory:   @value{RTEMS-FTPDIR}
101    File:        @value{RTEMS-TAR}
102@ifset use-html
103@c    URL:         @uref{ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}, Download RTEMS components}
104    URL:         ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}
105@end ifset
106@end example
107
108@subheading RTEMS Hello World
109@example
110    FTP Site:    @value{RTEMS-FTPSITE}
111    Directory:   @value{RTEMS-FTPDIR}
112    File:        hello_world_ada.tgz
113@ifset use-html
114@c    URL:         @uref{ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}/ada_tools/hello_world_ada.tgz, Download RTEMS Hello World}
115    URL:         ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}/ada_tools/hello_world_ada.tgz
116@end ifset       
117@end example
118
119@subheading RTEMS Specific Tool Patches and Scripts
120@example
121    FTP Site:    @value{RTEMS-FTPSITE}
122    Directory:   @value{RTEMS-FTPDIR}/ada_tools/source
123    File:        @value{BUILDTOOLS-TAR}
124@ifset BINUTILS-RTEMSPATCH
125    File:        @value{BINUTILS-RTEMSPATCH}
126@end ifset
127@ifset NEWLIB-RTEMSPATCH
128    File:        @value{NEWLIB-RTEMSPATCH}
129@end ifset
130@ifset GCC-RTEMSPATCH
131    File:        @value{GCC-RTEMSPATCH}
132@end ifset
133@ifset GNAT-RTEMSPATCH
134    File:        @value{GNAT-RTEMSPATCH}
135@end ifset
136@ifset use-html
137@c    URL:         @uref{ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}/ada_tools/source, Download RTEMS patches}
138    URL:         ftp://@value{RTEMS-FTPSITE}@value{RTEMS-FTPDIR}/ada_tools/source
139@end ifset
140@end example
141
142@section Unarchiving the Tools
143
144While in the @code{tools} directory, unpack the compressed
145tar files using the following command sequence:
146
147@example
148cd tools
149tar xzf ../archive/@value{GCC-TAR}
150tar xzf ../archive/@value{GNAT-TAR}
151tar xzf ../archive/@value{BINUTILS-TAR}
152tar xzf ../archive/@value{NEWLIB-TAR}
153tar xzf ../archive/@value{BUILDTOOLS-TAR}
154@end example
155
156After the compressed tar files have been unpacked, the following
157directories will have been created under tools.
158
159@itemize @bullet
160@item @value{BINUTILS-UNTAR}
161@item @value{GCC-UNTAR}
162@item @value{GNAT-UNTAR}
163@item @value{NEWLIB-UNTAR}
164@end itemize
165
166There will also be a set of scripts in the current directory
167which aid in building the tools and RTEMS.  They are:
168
169@itemize @bullet
170@item bit_ada
171@item bit_gdb
172@item bit_rtems
173@item common.sh
174@item user.cfg
175@end itemize
176
177When the @code{bit_ada} script is executed later in this process,
178it will automatically create two other subdirectories:
179
180@itemize @bullet
181@item src
182@item build-$@{CPU@}-tools
183@end itemize
184
185Similarly, the @code{bit_gdb} script will create the
186subdirectory @code{build-$@{CPU@}-gdb} and
187the @code{bit_rtems} script will create the
188subdirectory @code{build-$@{CPU@}-rtems}.
189
190The directory tree should look something like the following figure:
191
192@example
193@group
194/whatever/prefix/you/choose/
195        archive/
196            @value{GCC-TAR}
197            @value{GNAT-TAR}
198            @value{BINUTILS-TAR}
199            @value{NEWLIB-TAR}
200            @value{RTEMS-TAR}
201            @value{BUILDTOOLS-TAR}
202@ifset GCC-RTEMSPATCH
203            @value{GCC-RTEMSPATCH}
204@end ifset
205@ifset BINUTILS-RTEMSPATCH
206            @value{BINUTILS-RTEMSPATCH}
207@end ifset
208@ifset NEWLIB-RTEMSPATCH
209            @value{NEWLIB-RTEMSPATCH}
210@end ifset
211@ifset GNAT-RTEMSPATCH
212            @value{GNAT-RTEMSPATCH}
213@end ifset
214            hello_world_ada.tgz
215            bit_ada
216        tools/
217            @value{BINUTILS-UNTAR}/
218            @value{GCC-UNTAR}/
219            @value{GNAT-UNTAR}/
220            @value{NEWLIB-UNTAR}/
221            bit_ada
222            bit_gdb
223            bit_rtems
224            common.sh
225            user.cfg
226@end group
227@end example
228
229@c @ifset use-html
230@c @html
231@c <IMG SRC="bit_ada.jpg" WIDTH=816 HEIGHT=267 ALT="Directory Organization">
232@c @end html
233@c @end ifset
234
235@c
236@c  Host Specific Notes
237@c
238
239@section Host Specific Notes
240
241@subsection Solaris 2.x
242
243The build scripts are written in "shell".  The program @code{/bin/sh}
244on Solaris 2.x is not robust enough to execute these scripts.  If you
245are on a Solaris 2.x host, then change the first line of the files
246@code{bit_ada}, @code{bit_gdb}, and @code{bit_rtems} to use the
247@code{/bin/ksh} shell instead.
248
249@c
250@c  Reading the Documentation
251@c
252
253@section Reading the Tools Documentation
254
255Each of the tools in the GNU development suite comes with documentation.
256It is in the reader's and tool maintainers' interest that one read the
257documentation before posting a problem to a mailing list or news group.
258
259
260@c
261@c  GCC patches
262@c
263
264@section Apply RTEMS Patch to GCC
265
266@ifclear GCC-RTEMSPATCH
267No RTEMS specific patches are required for @value{GCC-VERSION} to
268support @value{RTEMS-VERSION}.
269@end ifclear
270
271@ifset GCC-RTEMSPATCH
272
273Apply the patch using the following command sequence:
274
275@example
276cd tools/@value{GCC-UNTAR}
277zcat ../../archive/@value{GCC-RTEMSPATCH} | patch -p1
278@end example
279
280Check to see if any of these patches have been rejected using the following
281sequence:
282
283@example
284cd tools/@value{GCC-UNTAR}
285find . -name "*.rej" -print
286@end example
287
288If any files are found with the .rej extension, a patch has been rejected.
289This should not happen with a good patch file which is properly applied.
290
291@end ifset
292
293@c
294@c  BINUTILS patches
295@c
296
297@section Apply RTEMS Patch to binutils
298
299@ifclear BINUTILS-RTEMSPATCH
300No RTEMS specific patches are required for @value{BINUTILS-VERSION} to
301support @value{RTEMS-VERSION}.
302@end ifclear
303
304@ifset BINUTILS-RTEMSPATCH
305Apply the patch using the following command sequence:
306
307@example
308cd tools/@value{BINUTILS-UNTAR}
309zcat ../../archive/@value{BINUTILS-RTEMSPATCH} | patch -p1
310@end example
311
312Check to see if any of these patches have been rejected using the following
313sequence:
314
315@example
316cd tools/@value{BINUTILS-UNTAR}
317find . -name "*.rej" -print
318@end example
319
320If any files are found with the .rej extension, a patch has been rejected.
321This should not happen with a good patch file which is properly applied.
322
323@end ifset
324
325@c
326@c  Newlib patches
327@c
328
329@section Apply RTEMS Patch to newlib
330
331@ifclear NEWLIB-RTEMSPATCH
332No RTEMS specific patches are required for @value{NEWLIB-VERSION} to
333support @value{RTEMS-VERSION}.
334@end ifclear
335
336@ifset NEWLIB-RTEMSPATCH
337
338Apply the patch using the following command sequence:
339
340@example
341cd tools/@value{NEWLIB-UNTAR}
342zcat ../../archive/@value{NEWLIB-RTEMSPATCH} | patch -p1
343@end example
344
345Check to see if any of these patches have been rejected using the following
346sequence:
347
348@example
349cd tools/@value{NEWLIB-UNTAR}
350find . -name "*.rej" -print
351@end example
352
353If any files are found with the .rej extension, a patch has been rejected.
354This should not happen with a good patch file which is properly applied.
355
356@end ifset
357
358@c 
359@c  GNAT patches
360@c
361
362@section Apply RTEMS Patch to GNAT
363
364@ifclear GNAT-RTEMSPATCH
365No RTEMS specific patches are required for @value{GNAT-VERSION} to
366support @value{RTEMS-VERSION}.
367@end ifclear
368
369@ifset GNAT-RTEMSPATCH
370
371Apply the patch using the following command sequence:
372
373@example
374cd tools/@value{GNAT-UNTAR}
375zcat ../../archive/@value{GNAT-RTEMSPATCH} | patch -p1
376@end example
377
378Check to see if any of these patches have been rejected using the following
379sequence:
380
381@example
382cd tools/@value{GNAT-UNTAR}
383find . -name "*.rej" -print
384@end example
385
386If any files are found with the .rej extension, a patch has been rejected.
387This should not happen with a good patch file which is properly applied.
388
389@end ifset
390
391@c
392@c  Copy the ada directory
393@c
394
395
396@section Copy the ada Subdirectory to the GCC Source Tree
397
398Copy the ada subtree in the patched subtree of
399tools/@value{GNAT-UNTAR}/src to the
400tools/@value{GCC-UNTAR} directory:
401
402@example
403cd tools/@value{GNAT-UNTAR}/src
404cp -r ada ../../@value{GCC-UNTAR}
405@end example
406
407
408@c
409@c  Localizing the Configuration
410@c
411
412@section Localizing the Configuration
413
414Edit the @code{user.cfg} file to alter the settings of various
415variables which are used to tailor the build process.
416Each of the variables set in @code{user.cfg} may be modified
417as described below:
418
419@table @code
420@item INSTALL_POINT
421is the location where you wish the GNU C/C++ cross compilation tools for
422RTEMS to be built. It is recommended that the directory chosen to receive
423these tools be named so that it is clear from which gcc distribution it
424was generated and for which target system the tools are to produce code for.
425
426@b{WARNING}: The @code{INSTALL_POINT} should not be a subdirectory
427under the build directory.  The build directory will be removed
428automatically upon successful completion of the build procedure.
429
430@item BINUTILS
431is the directory under tools that contains @value{BINUTILS-UNTAR}.
432For example:
433
434@example
435BINUTILS=@value{BINUTILS-UNTAR}
436@end example
437
438@item GCC
439is the directory under tools that contains @value{GCC-UNTAR}.
440For example,
441
442@example
443GCC=@value{GCC-UNTAR}
444@end example
445
446Note that the gnat version is not needed because the gnat source
447is built as part of building gcc.
448
449@item NEWLIB
450is the directory under tools that contains @value{NEWLIB-UNTAR}.
451For example:
452
453@example
454NEWLIB=@value{NEWLIB-UNTAR}
455@end example
456
457@item BUILD_DOCS
458is set to "yes" if you want to install documentation.  This requires
459that tools supporting documentation production be installed.  This
460currently is limited to the GNU texinfo package.
461For example:
462
463@example
464BUILD_DOCS=yes
465@end example
466
467@item BUILD_OTHER_LANGUAGES
468is set to "yes" if you want to build languages other than C and C++.  At
469the current time, the set of alternative languages includes Java, Fortran,
470and Objective-C.  These alternative languages do not always build cross.
471Hence this option defaults to "no".
472
473For example:
474
475@example
476BUILD_OTHER_LANGUAGES=yes
477@end example
478
479@b{NOTE:} Based upon the version of the compiler being used, it may not
480be possible to build languages other than C and C++ cross.  In many cases,
481the language run-time support libraries are not "multilib'ed".  Thus the
482executable code in these libraries will be for the default compiler settings
483and not necessarily be correct for your CPU model.
484
485@item RTEMS
486is the directory under tools that contails @value{RTEMS-UNTAR}.
487
488@item ENABLE_RTEMS_POSIX
489is set to "yes" if you want to enable the RTEMS POSIX API support.
490At this time, this feature is not supported by the UNIX ports of RTEMS
491and is forced to "no" for those targets.  This corresponds to the
492@code{configure} option @code{--enable-posix}.
493
494This must be enabled to support the GNAT/RTEMS run-time.
495
496@item ENABLE_RTEMS_ITRON
497is set to "yes" if you want to enable the RTEMS ITRON API support.
498At this time, this feature is not supported by the UNIX ports of RTEMS
499and is forced to "no" for those targets.  This corresponds to the
500@code{configure} option @code{--enable-itron}.
501
502@item ENABLE_RTEMS_MP
503is set to "yes" if you want to enable the RTEMS multiprocessing
504support.  This feature is not supported by all RTEMS BSPs and
505is automatically forced to "no" for those BSPs.  This corresponds to the
506@code{configure} option @code{--enable-multiprocessing}.
507
508@item ENABLE_RTEMS_CXX
509is set to "yes" if you want to build the RTEMS C++ support including
510the C++ Wrapper for the Classic API.  This corresponds to the
511@code{configure} option @code{--enable-cxx}.
512
513@item ENABLE_RTEMS_TESTS
514is set to "yes" if you want to build the RTEMS Test Suite.  If this
515is set to "no", then only the Sample Tests will be built.  Setting
516this option to "yes" significantly increases the amount of disk
517space required to build RTEMS.
518This corresponds to the @code{configure} option @code{--enable-tests}.
519
520@item ENABLE_RTEMS_TCPIP
521is set to "yes" if you want to build the RTEMS TCP/IP Stack.  If a
522particular BSP does not support TCP/IP, then this feature is automatically
523disabled.  This corresponds to the @code{configure} option
524@code{--enable-tcpip}.
525
526@item ENABLE_RTEMS_NONDEBUG
527is set to "yes" if you want to build RTEMS in a fully optimized
528state.  This corresponds to executing @code{make} after configuring
529the source tree.
530
531@item ENABLE_RTEMS_DEBUG
532is set to "yes" if you want to build RTEMS in a debug version.
533When built for debug, RTEMS will include run-time code to
534perform consistency checks such as heap consistency checks.
535Although the precise compilation arguments are BSP dependent,
536the debug version of RTEMS is usually built at a lower optimization
537level.  This is usually done to reduce inlining which can make
538tracing code execution difficult.  This corresponds to executing
539@code{make VARIANT=debug} after configuring
540the source tree.
541
542@item INSTALL_RTEMS
543is set to "yes" if you want to install RTEMS after building it.
544This corresponds to executing @code{make install} after configuring
545and building the source tree.
546
547@item ENABLE_RTEMS_MAINTAINER_MODE
548is set to "yes" if you want to enabled maintainer mode functionality
549in the RTEMS Makefile.  This is disabled by default and it is not
550expected that most users will want to enable this.  When this option
551is enabled, the build process may attempt to regenerate files that
552require tools not required when this option is disabled.
553This corresponds to the @code{configure} option
554@code{--enable-maintainer-mode}.
555
556@end table
557
558@section Running the bit_ada Script
559
560After the @code{bit_ada} script has been modified to reflect the
561local installation, the modified @code{bit_ada} script is run
562using the following sequence:
563
564@example
565cd tools
566./bit_ada <target configuration>
567@end example
568
569Where <target configuration> is one of the following:
570
571@itemize @bullet
572@item hppa1.1
573@item i386
574@item i386-elf
575@item i386-go32
576@item i960
577@item m68k
578@item mips64orion
579@item powerpc
580@item sh
581@item sparc
582@end itemize
583
584NOTE:  The above list of target configurations is the list of RTEMS supported
585targets.  Only a subset of these have been tested with GNAT/RTEMS.  For more
586information, contact your GNAT/RTEMS representative.
587
588The build process can take a while to complete.  Many users find it
589handy to run the build process in the background, capture the output
590in a file, and monitor the output.  This can be done as follows:
591
592@example
593./bit_ada <target configuration> >bit.log 2>&1 &
594tail -f bit.log
595@end example
596
597If no errors are encountered, the @code{bit_ada} script will conclude by
598printing messages similar to the following:
599
600@example
601
602The src and build-i386-tools subdirectory may now be removed.
603
604Started:  Fri Apr 10 10:14:07 CDT 1998
605Finished: Fri Apr 10 12:01:33 CDT 1998
606@end example
607
608If the @code{bit_ada} script successfully completes, then the
609GNU C/C++ cross compilation tools are installed.
610
611If the @code{bit_ada} script does not successfully complete, then investigation
612will be required to determine the source of the error.
613
614@c
615@c Common Problems
616@c
617
618@section Common Problems
619
620@subsection Error Message Indicates Invalid Option to Assembler
621
622If a message like this is printed then the new cross compiler
623is most likely using the native assembler instead of the cross
624assembler or vice-versa (native compiler using new cross assembler).
625This can occur for one of the following reasons:
626
627@itemize @bullet
628
629@item Binutils Patch Improperly Applied
630@item Binutils Not Built
631@item Current Directory is in Your PATH
632
633@end itemize
634
635If you are using binutils 2.9.1 or newer with certain older versions of
636gcc, they do not agree on what the name of the newly
637generated cross assembler is.  Older binutils called it @code{as.new}
638which became @code{as.new.exe} under Windows.  This is not a valid
639file name, so @code{as.new} is now called @code{as-new}.  By using the latest
640released tool versions and RTEMS patches, this problem will be avoided.
641
642If binutils did not successfully build the cross assembler, then
643the new cross gcc (@code{xgcc}) used to build the libraries can not
644find it.  Make sure the build of the binutils succeeded.
645
646If you include the current directory in your PATH, then there
647is a chance that the native compiler will accidentally use
648the new cross assembler instead of the native one.  This usually
649indicates that "." is before the standard system directories
650in your PATH.  As a general rule, including "." in your PATH
651is a security risk and should be avoided.  Remove "." from
652your PATH.
653
654NOTE:  In some environments, it may be difficult to remove "."
655completely from your PATH.  In this case, make sure that "."
656is after the system directories containing "as" and "ld".
657
658@subsection Error Messages Indicating Configuration Problems
659
660If you see error messages like the following,
661
662@itemize @bullet
663
664@item cannot configure libiberty
665@item coff-emulation not found
666@item etc.
667
668@end itemize
669
670Then it is likely that one or more of your gnu tools is
671already configured locally in its source tree.  You can check
672for this by searching for the @code{config.status} file
673in the various tool source trees.  The following command
674does this for the binutils source:
675
676@example
677find @value{BINUTILS-UNTAR} -name config.status -print
678@end example
679
680The solution for this is to execute the command
681@code{make distclean} in each of the GNU tools
682root source directory.  This should remove all
683generated files including Makefiles.
684
685This situation usually occurs when you have previously
686built the tool source for some non-RTEMS target.  The
687generated configuration specific files are still in
688the source tree and the include path specified during
689the RTEMS build accidentally picks up the previous
690configuration.  The include path used is something like
691this:
692
693@example
694-I../../@value{BINUTILS-UNTAR}/gcc -I/@value{BINUTILS-UNTAR}/gcc/include -I.
695@end example
696
697Note that the tool source directory is searched before the
698build directory.
699
700This situation can be avoided entirely by never using
701the source tree as the build directory -- even for
702
Note: See TracBrowser for help on using the repository browser.