OSDN Git Service

f5968b1f26bc7dd976d549f006457d2bfc1929b1
[pf3gnuchains/gcc-fork.git] / gcc / install.texi
1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000 Free Software Foundation, Inc.
2 @c This is part of the GCC manual.
3 @c For copying conditions, see the file gcc.texi.
4
5 @c The text of this file appears in the file INSTALL
6 @c in the GCC distribution, as well as in the GCC manual.
7
8 Note most of this information is out of date and superseded by the EGCS
9 install procedures.  It is provided for historical reference only.
10
11 @ifclear INSTALLONLY
12 @node Installation
13 @chapter Installing GNU CC
14 @end ifclear
15 @cindex installing GNU CC
16
17 @menu
18 * Configuration Files::  Files created by running @code{configure}.
19 * Configurations::    Configurations Supported by GNU CC.
20 * Other Dir::     Compiling in a separate directory (not where the source is).
21 * Cross-Compiler::   Building and installing a cross-compiler.
22 * Sun Install::   See below for installation on the Sun.
23 * VMS Install::   See below for installation on VMS.
24 * Collect2::      How @code{collect2} works; how it finds @code{ld}.
25 * Header Dirs::   Understanding the standard header file directories.
26 @end menu
27
28 Here is the procedure for installing GNU CC on a GNU or Unix system.
29 See @ref{VMS Install}, for VMS systems.  In this section we assume you
30 compile in the same directory that contains the source files; see
31 @ref{Other Dir}, to find out how to compile in a separate directory on
32 Unix systems.
33
34 You cannot install GNU C by itself on MSDOS; it will not compile under
35 any MSDOS compiler except itself.  You need to get the complete
36 compilation package DJGPP, which includes binaries as well as sources,
37 and includes all the necessary compilation tools and libraries.
38
39 @enumerate
40 @item
41 If you have built GNU CC previously in the same directory for a
42 different target machine, do @samp{make distclean} to delete all files
43 that might be invalid.  One of the files this deletes is
44 @file{Makefile}; if @samp{make distclean} complains that @file{Makefile}
45 does not exist, it probably means that the directory is already suitably
46 clean.
47
48 @item
49 On a System V release 4 system, make sure @file{/usr/bin} precedes
50 @file{/usr/ucb} in @code{PATH}.  The @code{cc} command in
51 @file{/usr/ucb} uses libraries which have bugs.
52
53 @cindex Bison parser generator
54 @cindex parser generator, Bison
55 @item
56 Make sure the Bison parser generator is installed.  (This is unnecessary
57 if the Bison output file @file{c-parse.c} is more recent than
58 @file{c-parse.y},and you do not plan to change the @samp{.y} file.)
59
60 Bison versions older than Sept 8, 1988 will produce incorrect output
61 for @file{c-parse.c}.
62
63 @item
64 If you have chosen a configuration for GNU CC which requires other GNU
65 tools (such as GAS or the GNU linker) instead of the standard system
66 tools, install the required tools in the build directory under the names
67 @file{as}, @file{ld} or whatever is appropriate.  This will enable the
68 compiler to find the proper tools for compilation of the program
69 @file{enquire}.
70
71 Alternatively, you can do subsequent compilation using a value of the
72 @code{PATH} environment variable such that the necessary GNU tools come
73 before the standard system tools.
74
75 @item
76 Specify the host, build and target machine configurations.  You do this
77 when you run the @file{configure} script.
78
79 The @dfn{build} machine is the system which you are using, the
80 @dfn{host} machine is the system where you want to run the resulting
81 compiler (normally the build machine), and the @dfn{target} machine is
82 the system for which you want the compiler to generate code.
83
84 If you are building a compiler to produce code for the machine it runs
85 on (a native compiler), you normally do not need to specify any operands
86 to @file{configure}; it will try to guess the type of machine you are on
87 and use that as the build, host and target machines.  So you don't need
88 to specify a configuration when building a native compiler unless
89 @file{configure} cannot figure out what your configuration is or guesses
90 wrong.
91
92 In those cases, specify the build machine's @dfn{configuration name}
93 with the @samp{--host} option; the host and target will default to be
94 the same as the host machine.  (If you are building a cross-compiler,
95 see @ref{Cross-Compiler}.)
96
97 Here is an example:
98
99 @smallexample
100 ./configure --host=sparc-sun-sunos4.1
101 @end smallexample
102
103 A configuration name may be canonical or it may be more or less
104 abbreviated.
105
106 A canonical configuration name has three parts, separated by dashes.
107 It looks like this: @samp{@var{cpu}-@var{company}-@var{system}}.
108 (The three parts may themselves contain dashes; @file{configure}
109 can figure out which dashes serve which purpose.)  For example,
110 @samp{m68k-sun-sunos4.1} specifies a Sun 3.
111
112 You can also replace parts of the configuration by nicknames or aliases.
113 For example, @samp{sun3} stands for @samp{m68k-sun}, so
114 @samp{sun3-sunos4.1} is another way to specify a Sun 3.  You can also
115 use simply @samp{sun3-sunos}, since the version of SunOS is assumed by
116 default to be version 4.
117
118 You can specify a version number after any of the system types, and some
119 of the CPU types.  In most cases, the version is irrelevant, and will be
120 ignored.  So you might as well specify the version if you know it.
121
122 See @ref{Configurations}, for a list of supported configuration names and
123 notes on many of the configurations.  You should check the notes in that
124 section before proceeding any further with the installation of GNU CC.
125
126 @item
127 When running @code{configure}, you may also need to specify certain
128 additional options that describe variant hardware and software
129 configurations.  These are @samp{--with-gnu-as}, @samp{--with-gnu-ld},
130 @samp{--with-stabs} and @samp{--nfp}.
131
132 @table @samp
133 @item --with-gnu-as
134 If you will use GNU CC with the GNU assembler (GAS), you should declare
135 this by using the @samp{--with-gnu-as} option when you run
136 @file{configure}.
137
138 Using this option does not install GAS.  It only modifies the output of
139 GNU CC to work with GAS.  Building and installing GAS is up to you.
140
141 Conversely, if you @emph{do not} wish to use GAS and do not specify
142 @samp{--with-gnu-as} when building GNU CC, it is up to you to make sure
143 that GAS is not installed.  GNU CC searches for a program named
144 @code{as} in various directories; if the program it finds is GAS, then
145 it runs GAS.  If you are not sure where GNU CC finds the assembler it is
146 using, try specifying @samp{-v} when you run it.
147
148 The systems where it makes a difference whether you use GAS are@*
149 @samp{hppa1.0-@var{any}-@var{any}}, @samp{hppa1.1-@var{any}-@var{any}},
150 @samp{i386-@var{any}-sysv}, @samp{i386-@var{any}-isc},@*
151 @samp{i860-@var{any}-bsd}, @samp{m68k-bull-sysv},@*
152 @samp{m68k-hp-hpux}, @samp{m68k-sony-bsd},@*
153 @samp{m68k-altos-sysv}, @samp{m68000-hp-hpux},@*
154 @samp{m68000-att-sysv}, @samp{@var{any}-lynx-lynxos},
155 and @samp{mips-@var{any}}).
156 On any other system, @samp{--with-gnu-as} has no effect.
157
158 On the systems listed above (except for the HP-PA, for ISC on the
159 386, and for @samp{mips-sgi-irix5.*}), if you use GAS, you should also
160 use the GNU linker (and specify @samp{--with-gnu-ld}).
161
162 @item --with-gnu-ld
163 Specify the option @samp{--with-gnu-ld} if you plan to use the GNU
164 linker with GNU CC.
165
166 This option does not cause the GNU linker to be installed; it just
167 modifies the behavior of GNU CC to work with the GNU linker.
168 @c Specifically, it inhibits the installation of @code{collect2}, a program
169 @c which otherwise serves as a front-end for the system's linker on most
170 @c configurations.
171
172 @item --with-stabs
173 On MIPS based systems and on Alphas, you must specify whether you want
174 GNU CC to create the normal ECOFF debugging format, or to use BSD-style
175 stabs passed through the ECOFF symbol table.  The normal ECOFF debug
176 format cannot fully handle languages other than C.  BSD stabs format can
177 handle other languages, but it only works with the GNU debugger GDB.
178
179 Normally, GNU CC uses the ECOFF debugging format by default; if you
180 prefer BSD stabs, specify @samp{--with-stabs} when you configure GNU
181 CC.
182
183 No matter which default you choose when you configure GNU CC, the user
184 can use the @samp{-gcoff} and @samp{-gstabs+} options to specify explicitly
185 the debug format for a particular compilation.
186
187 @samp{--with-stabs} is meaningful on the ISC system on the 386, also, if
188 @samp{--with-gas} is used.  It selects use of stabs debugging
189 information embedded in COFF output.  This kind of debugging information
190 supports C++ well; ordinary COFF debugging information does not.
191
192 @samp{--with-stabs} is also meaningful on 386 systems running SVR4.  It
193 selects use of stabs debugging information embedded in ELF output.  The
194 C++ compiler currently (2.6.0) does not support the DWARF debugging
195 information normally used on 386 SVR4 platforms; stabs provide a
196 workable alternative.  This requires gas and gdb, as the normal SVR4
197 tools can not generate or interpret stabs.
198
199 @item --nfp
200 On certain systems, you must specify whether the machine has a floating
201 point unit.  These systems include @samp{m68k-sun-sunos@var{n}} and
202 @samp{m68k-isi-bsd}.  On any other system, @samp{--nfp} currently has no
203 effect, though perhaps there are other systems where it could usefully
204 make a difference.
205
206 @cindex Haifa scheduler
207 @cindex scheduler, experimental
208 @item --enable-haifa
209 @itemx --disable-haifa
210 Use @samp{--enable-haifa} to enable use of an experimental instruction
211 scheduler (from IBM Haifa).  This may or may not produce better code.
212 Some targets on which it is known to be a win enable it by default; use
213 @samp{--disable-haifa} to disable it in these cases.  @code{configure}
214 will print out whether the Haifa scheduler is enabled when it is run.
215
216 @cindex Objective C threads
217 @cindex threads, Objective C
218 @item --enable-threads=@var{type}
219 Certain systems, notably Linux-based GNU systems, can't be relied on to
220 supply a threads facility for the Objective C runtime and so will
221 default to single-threaded runtime.  They may, however, have a library
222 threads implementation available, in which case threads can be enabled
223 with this option by supplying a suitable @var{type}, probably
224 @samp{posix}.  The possibilities for @var{type} are @samp{single},
225 @samp{posix}, @samp{win32}, @samp{solaris}, @samp{irix} and @samp{mach}.
226
227 @cindex Internal Compiler Checking
228 @item --enable-checking
229 When you specify this option, the compiler is built to perform checking
230 of tree node types when referencing fields of that node.  This does not
231 change the generated code, but adds error checking within the compiler.
232 This will slow down the compiler and may only work properly if you
233 are building the compiler with GNU C.
234
235 The @file{configure} script searches subdirectories of the source
236 directory for other compilers that are to be integrated into GNU CC.
237 The GNU compiler for C++, called G++ is in a subdirectory named
238 @file{cp}.  @file{configure} inserts rules into @file{Makefile} to build
239 all of those compilers.
240
241 Here we spell out what files will be set up by @code{configure}.  Normally
242 you need not be concerned with these files.
243
244 @itemize @bullet
245 @item
246 @ifset INTERNALS
247 A file named @file{config.h} is created that contains a @samp{#include}
248 of the top-level config file for the machine you will run the compiler
249 on (@pxref{Config}).  This file is responsible for defining information
250 about the host machine.  It includes @file{tm.h}.
251 @end ifset
252 @ifclear INTERNALS
253 A file named @file{config.h} is created that contains a @samp{#include}
254 of the top-level config file for the machine you will run the compiler
255 on (@pxref{Config,,The Configuration File, gcc.info, Using and Porting
256 GCC}).  This file is responsible for defining information about the host
257 machine.  It includes @file{tm.h}.
258 @end ifclear
259
260 The top-level config file is located in the subdirectory @file{config}.
261 Its name is always @file{xm-@var{something}.h}; usually
262 @file{xm-@var{machine}.h}, but there are some exceptions.
263
264 If your system does not support symbolic links, you might want to
265 set up @file{config.h} to contain a @samp{#include} command which
266 refers to the appropriate file.
267
268 @item
269 A file named @file{tconfig.h} is created which includes the top-level config
270 file for your target machine.  This is used for compiling certain
271 programs to run on that machine.
272
273 @item
274 A file named @file{tm.h} is created which includes the
275 machine-description macro file for your target machine.  It should be in
276 the subdirectory @file{config} and its name is often
277 @file{@var{machine}.h}.
278 @end itemize
279
280 @cindex Native Language Support
281 @cindex NLS
282 @item --enable-nls
283 @itemx --disable-nls
284 The @samp{--enable-nls} option enables Native Language Support (NLS),
285 which lets GCC output diagnostics in languages other than American
286 English. Native Language Support is enabled by default if not doing a 
287 canadian cross build. The @samp{--disable-nls} option disables NLS.
288
289 @cindex @code{gettext}
290 @item --with-included-gettext
291 If NLS is enbled, the @samp{--with-included-gettext} option causes the build
292 procedure to prefer its copy of GNU @code{gettext}. This is the default. If
293 you want the GCC build procedure to prefer the host's @code{gettext}
294 libraries, use @samp{--without-included-gettext}.
295
296 @cindex @code{catgets}
297 @item --with-catgets
298 If NLS is enabled, and if the host lacks @code{gettext} but has the
299 inferior @code{catgets} interface, the GCC build procedure normally
300 ignores @code{catgets} and instead uses GCC's copy of the GNU
301 @code{gettext} library.  The @samp{--with-catgets} option causes the
302 build procedure to use the host's @code{catgets} in this situation.
303
304 @cindex @code{maintainer-mode}
305 @item --enable-maintainer-mode
306 The build rules that regenerate the GCC master message catalog
307 @code{gcc.pot} are normally disabled. This is because it can only be rebuilt
308 if the complete source tree is present. If you have changed the sources and
309 want to rebuild the catalog, configuring with
310 @samp{--enable-maintainer-mode} will enable this. Note that you need a
311 special version of the @code{gettext} tools to do so.
312
313 @cindex Windows32 Registry support
314 @item --enable-win32-registry
315 @itemx --enable-win32-registry=@var{KEY}
316 @itemx --disable-win32-registry
317 The @samp{--enable-win32-registry} option enables Windows-hosted GCC
318 to look up installations paths in the registry using the following key:
319
320 @smallexample
321 @code{HKEY_LOCAL_MACHINE\SOFTWARE\Free Software Foundation\<KEY>}
322 @end smallexample
323
324 <KEY> defaults to GCC version number, and can be overridden by the
325 @code{--enable-win32-registry=KEY} option. Vendors and distributors
326 who use custom installers are encouraged to provide a different key,
327 perhaps one comprised of vendor name and GCC version number, to
328 avoid conflict with existing installations. This feature is enabled
329 by default, and can be disabled by @code{--disable-win32-registry}
330 option.  This option has no effect on the other hosts.
331 @end table
332
333 @item
334 In certain cases, you should specify certain other options when you run
335 @code{configure}.
336
337 @itemize @bullet
338 @item
339 The standard directory for installing GNU CC is @file{/usr/local/lib}.
340 If you want to install its files somewhere else, specify
341 @samp{--prefix=@var{dir}} when you run @file{configure}.  Here @var{dir}
342 is a directory name to use instead of @file{/usr/local} for all purposes
343 with one exception: the directory @file{/usr/local/include} is searched
344 for header files no matter where you install the compiler.  To override
345 this name, use the @code{--with-local-prefix} option below.  The directory
346 you specify need not exist, but its parent directory must exist.
347
348 @item
349 Specify @samp{--with-local-prefix=@var{dir}} if you want the compiler to
350 search directory @file{@var{dir}/include} for locally installed header
351 files @emph{instead} of @file{/usr/local/include}.
352
353 You should specify @samp{--with-local-prefix} @strong{only} if your site has
354 a different convention (not @file{/usr/local}) for where to put
355 site-specific files.
356
357 The default value for @samp{--with-local-prefix} is @file{/usr/local}
358 regardless of the value of @samp{--prefix}.  Specifying @samp{--prefix}
359 has no effect on which directory GNU CC searches for local header files.
360 This may seem counterintuitive, but actually it is logical.
361
362 The purpose of @samp{--prefix} is to specify where to @emph{install GNU
363 CC}.  The local header files in @file{/usr/local/include}---if you put
364 any in that directory---are not part of GNU CC.  They are part of other
365 programs---perhaps many others.  (GNU CC installs its own header files
366 in another directory which is based on the @samp{--prefix} value.)
367
368 @strong{Do not} specify @file{/usr} as the @samp{--with-local-prefix}!  The
369 directory you use for @samp{--with-local-prefix} @strong{must not} contain
370 any of the system's standard header files.  If it did contain them,
371 certain programs would be miscompiled (including GNU Emacs, on certain
372 targets), because this would override and nullify the header file
373 corrections made by the @code{fixincludes} script.
374
375 Indications are that people who use this option use it based on
376 mistaken ideas of what it is for.  People use it as if it specified
377 where to install part of GNU CC.  Perhaps they make this assumption
378 because installing GNU CC creates the directory.
379 @end itemize
380
381 @item
382 Build the compiler.  Just type @samp{make LANGUAGES=c} in the compiler
383 directory.
384
385 @samp{LANGUAGES=c} specifies that only the C compiler should be
386 compiled.  The makefile normally builds compilers for all the supported
387 languages; currently, C, C++ and Objective C.  However, C is the only
388 language that is sure to work when you build with other non-GNU C
389 compilers.  In addition, building anything but C at this stage is a
390 waste of time.
391
392 In general, you can specify the languages to build by typing the
393 argument @samp{LANGUAGES="@var{list}"}, where @var{list} is one or more
394 words from the list @samp{c}, @samp{c++}, and @samp{objective-c}.  If
395 you have any additional GNU compilers as subdirectories of the GNU CC
396 source directory, you may also specify their names in this list.
397
398 Ignore any warnings you may see about ``statement not reached'' in
399 @file{insn-emit.c}; they are normal.  Also, warnings about ``unknown
400 escape sequence'' are normal in @file{genopinit.c} and perhaps some
401 other files.  Likewise, you should ignore warnings about ``constant is
402 so large that it is unsigned'' in @file{insn-emit.c} and
403 @file{insn-recog.c}, and a warning about a comparison always being zero
404 in @file{enquire.o}.  Any other compilation errors may represent bugs in
405 the port to your machine or operating system, and
406 @ifclear INSTALLONLY
407 should be investigated and reported (@pxref{Bugs}).
408 @end ifclear
409 @ifset INSTALLONLY
410 should be investigated and reported.
411 @end ifset
412
413 Some compilers fail to compile GNU CC because they have bugs or
414 limitations.  For example, the Microsoft compiler is said to run out of
415 macro space.  Some Ultrix compilers run out of expression space; then
416 you need to break up the statement where the problem happens.
417
418 @item
419 If you are building a cross-compiler, stop here.  @xref{Cross-Compiler}.
420
421 @cindex stage1
422 @item
423 Move the first-stage object files and executables into a subdirectory
424 with this command:
425
426 @smallexample
427 make stage1
428 @end smallexample
429
430 The files are moved into a subdirectory named @file{stage1}.
431 Once installation is complete, you may wish to delete these files
432 with @code{rm -r stage1}.
433
434 @item
435 If you have chosen a configuration for GNU CC which requires other GNU
436 tools (such as GAS or the GNU linker) instead of the standard system
437 tools, install the required tools in the @file{stage1} subdirectory
438 under the names @file{as}, @file{ld} or whatever is appropriate.  This
439 will enable the stage 1 compiler to find the proper tools in the
440 following stage.
441
442 Alternatively, you can do subsequent compilation using a value of the
443 @code{PATH} environment variable such that the necessary GNU tools come
444 before the standard system tools.
445
446 @item
447 Recompile the compiler with itself, with this command:
448
449 @smallexample
450 make CC="stage1/xgcc -Bstage1/" CFLAGS="-g -O2"
451 @end smallexample
452
453 This is called making the stage 2 compiler.
454
455 The command shown above builds compilers for all the supported
456 languages.  If you don't want them all, you can specify the languages to
457 build by typing the argument @samp{LANGUAGES="@var{list}"}.  @var{list}
458 should contain one or more words from the list @samp{c}, @samp{c++},
459 @samp{objective-c}, and @samp{proto}.  Separate the words with spaces.
460 @samp{proto} stands for the programs @code{protoize} and
461 @code{unprotoize}; they are not a separate language, but you use
462 @code{LANGUAGES} to enable or disable their installation.
463
464 If you are going to build the stage 3 compiler, then you might want to
465 build only the C language in stage 2.
466
467 Once you have built the stage 2 compiler, if you are short of disk
468 space, you can delete the subdirectory @file{stage1}.
469
470 On a 68000 or 68020 system lacking floating point hardware,
471 unless you have selected a @file{tm.h} file that expects by default
472 that there is no such hardware, do this instead:
473
474 @smallexample
475 make CC="stage1/xgcc -Bstage1/" CFLAGS="-g -O2 -msoft-float"
476 @end smallexample
477
478 @item
479 If you wish to test the compiler by compiling it with itself one more
480 time, install any other necessary GNU tools (such as GAS or the GNU
481 linker) in the @file{stage2} subdirectory as you did in the
482 @file{stage1} subdirectory, then do this:
483
484 @smallexample
485 make stage2
486 make CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O2"
487 @end smallexample
488
489 @noindent
490 This is called making the stage 3 compiler.  Aside from the @samp{-B}
491 option, the compiler options should be the same as when you made the
492 stage 2 compiler.  But the @code{LANGUAGES} option need not be the
493 same.  The command shown above builds compilers for all the supported
494 languages; if you don't want them all, you can specify the languages to
495 build by typing the argument @samp{LANGUAGES="@var{list}"}, as described
496 above.
497
498 If you do not have to install any additional GNU tools, you may use the
499 command
500
501 @smallexample
502 make bootstrap LANGUAGES=@var{language-list} BOOT_CFLAGS=@var{option-list}
503 @end smallexample
504
505 @noindent
506 instead of making @file{stage1}, @file{stage2}, and performing
507 the two compiler builds.
508
509 @item
510 Compare the latest object files with the stage 2 object files---they
511 ought to be identical, aside from time stamps (if any).
512
513 On some systems, meaningful comparison of object files is impossible;
514 they always appear ``different.''  This is currently true on Solaris and
515 some systems that use ELF object file format.  On some versions of Irix
516 on SGI machines and DEC Unix (OSF/1) on Alpha systems, you will not be
517 able to compare the files without specifying @file{-save-temps}; see the
518 description of individual systems above to see if you get comparison
519 failures.  You may have similar problems on other systems.
520
521 Use this command to compare the files:
522
523 @smallexample
524 make compare
525 @end smallexample
526
527 This will mention any object files that differ between stage 2 and stage
528 3.  Any difference, no matter how innocuous, indicates that the stage 2
529 compiler has compiled GNU CC incorrectly, and is therefore a potentially
530 @ifclear INSTALLONLY
531 serious bug which you should investigate and report (@pxref{Bugs}).
532 @end ifclear
533 @ifset INSTALLONLY
534 serious bug which you should investigate and report.
535 @end ifset
536
537 If your system does not put time stamps in the object files, then this
538 is a faster way to compare them (using the Bourne shell):
539
540 @smallexample
541 for file in *.o; do
542 cmp $file stage2/$file
543 done
544 @end smallexample
545
546 If you have built the compiler with the @samp{-mno-mips-tfile} option on
547 MIPS machines, you will not be able to compare the files.
548
549 @item
550 Install the compiler driver, the compiler's passes and run-time support
551 with @samp{make install}.  Use the same value for @code{CC},
552 @code{CFLAGS} and @code{LANGUAGES} that you used when compiling the
553 files that are being installed.  One reason this is necessary is that
554 some versions of Make have bugs and recompile files gratuitously when
555 you do this step.  If you use the same variable values, those files will
556 be recompiled properly.
557
558 For example, if you have built the stage 2 compiler, you can use the
559 following command:
560
561 @smallexample
562 make install CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O" LANGUAGES="@var{list}"
563 @end smallexample
564
565 @noindent
566 This copies the files @file{cc1}, @file{cpp} and @file{libgcc.a} to
567 files @file{cc1}, @file{cpp} and @file{libgcc.a} in the directory
568 @file{/usr/local/lib/gcc-lib/@var{target}/@var{version}}, which is where
569 the compiler driver program looks for them.  Here @var{target} is the
570 canonicalized form of target machine type specified when you ran
571 @file{configure}, and @var{version} is the version number of GNU CC.
572 This naming scheme permits various versions and/or cross-compilers to
573 coexist.  It also copies the executables for compilers for other
574 languages (e.g., @file{cc1plus} for C++) to the same directory.
575
576 This also copies the driver program @file{xgcc} into
577 @file{/usr/local/bin/gcc}, so that it appears in typical execution
578 search paths.  It also copies @file{gcc.1} into
579 @file{/usr/local/man/man1} and info pages into @file{/usr/local/info}.
580
581 On some systems, this command causes recompilation of some files.  This
582 is usually due to bugs in @code{make}.  You should either ignore this
583 problem, or use GNU Make.
584
585 @cindex @code{alloca} and SunOS
586 @strong{Warning: there is a bug in @code{alloca} in the Sun library.  To
587 avoid this bug, be sure to install the executables of GNU CC that were
588 compiled by GNU CC.  (That is, the executables from stage 2 or 3, not
589 stage 1.)  They use @code{alloca} as a built-in function and never the
590 one in the library.}
591
592 (It is usually better to install GNU CC executables from stage 2 or 3,
593 since they usually run faster than the ones compiled with some other
594 compiler.)
595
596 @item
597 @cindex C++ runtime library
598 @cindex @code{libstdc++}
599 If you're going to use C++, you need to install the C++ runtime library.
600 This includes all I/O functionality, special class libraries, etc.
601
602 The standard C++ runtime library for GNU CC is called @samp{libstdc++}.
603 An obsolescent library @samp{libg++} may also be available, but it's
604 necessary only for older software that hasn't been converted yet; if
605 you don't know whether you need @samp{libg++} then you probably don't
606 need it.
607
608 Here's one way to build and install @samp{libstdc++} for GNU CC:
609
610 @itemize @bullet
611 @item
612 Build and install GNU CC, so that invoking @samp{gcc} obtains the GNU CC
613 that was just built.
614
615 @item
616 Obtain a copy of a compatible @samp{libstdc++} distribution.  For
617 example, the @samp{libstdc++-2.8.0.tar.gz} distribution should be
618 compatible with GCC 2.8.0.  GCC distributors normally distribute
619 @samp{libstdc++} as well.
620
621 @item
622 Set the @samp{CXX} environment variable to @samp{gcc} while running the
623 @samp{libstdc++} distribution's @file{configure} command.  Use the same
624 @file{configure} options that you used when you invoked GCC's
625 @file{configure} command.
626
627 @item
628 Invoke @samp{make} to build the C++ runtime.
629
630 @item
631 Invoke @samp{make install} to install the C++ runtime.
632
633 @end itemize
634
635 To summarize, after building and installing GNU CC, invoke the following
636 shell commands in the topmost directory of the C++ library distribution.
637 For @var{configure-options}, use the same options that
638 you used to configure GNU CC.
639
640 @example
641 $ CXX=gcc ./configure @var{configure-options}
642 $ make
643 $ make install
644 @end example
645
646 @item
647 GNU CC includes a runtime library for Objective-C because it is an
648 integral part of the language.  You can find the files associated with
649 the library in the subdirectory @file{objc}.  The GNU Objective-C
650 Runtime Library requires header files for the target's C library in
651 order to be compiled,and also requires the header files for the target's
652 thread library if you want thread support.  @xref{Cross Headers,
653 Cross-Compilers and Header Files, Cross-Compilers and Header Files}, for
654 discussion about header files issues for cross-compilation.
655
656 When you run @file{configure}, it picks the appropriate Objective-C
657 thread implementation file for the target platform.  In some situations,
658 you may wish to choose a different back-end as some platforms support
659 multiple thread implementations or you may wish to disable thread
660 support completely.  You do this by specifying a value for the
661 @var{OBJC_THREAD_FILE} makefile variable on the command line when you
662 run make, for example:
663
664 @smallexample
665 make CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O2" OBJC_THREAD_FILE=thr-single
666 @end smallexample
667
668 @noindent
669 Below is a list of the currently available back-ends.
670
671 @itemize @bullet
672 @item thr-single
673 Disable thread support, should work for all platforms.
674 @item thr-decosf1
675 DEC OSF/1 thread support.
676 @item thr-irix
677 SGI IRIX thread support.
678 @item thr-mach
679 Generic MACH thread support, known to work on NEXTSTEP.
680 @item thr-os2
681 IBM OS/2 thread support.
682 @item thr-posix
683 Generix POSIX thread support.
684 @item thr-pthreads
685 PCThreads on Linux-based GNU systems.
686 @item thr-solaris
687 SUN Solaris thread support.
688 @item thr-win32
689 Microsoft Win32 API thread support.
690 @end itemize
691 @end enumerate
692
693 @node Configuration Files
694 @section Files Created by @code{configure}
695
696 Here we spell out what files will be set up by @code{configure}.  Normally
697 you need not be concerned with these files.
698
699 @itemize @bullet
700 @item
701 @ifset INTERNALS
702 A file named @file{config.h} is created that contains a @samp{#include}
703 of the top-level config file for the machine you will run the compiler
704 on (@pxref{Config}).  This file is responsible for defining information
705 about the host machine.  It includes @file{tm.h}.
706 @end ifset
707 @ifclear INTERNALS
708 A file named @file{config.h} is created that contains a @samp{#include}
709 of the top-level config file for the machine you will run the compiler
710 on (@pxref{Config,,The Configuration File, gcc.info, Using and Porting
711 GCC}).  This file is responsible for defining information about the host
712 machine.  It includes @file{tm.h}.
713 @end ifclear
714
715 The top-level config file is located in the subdirectory @file{config}.
716 Its name is always @file{xm-@var{something}.h}; usually
717 @file{xm-@var{machine}.h}, but there are some exceptions.
718
719 If your system does not support symbolic links, you might want to
720 set up @file{config.h} to contain a @samp{#include} command which
721 refers to the appropriate file.
722
723 @item
724 A file named @file{tconfig.h} is created which includes the top-level config
725 file for your target machine.  This is used for compiling certain
726 programs to run on that machine.
727
728 @item
729 A file named @file{tm.h} is created which includes the
730 machine-description macro file for your target machine.  It should be in
731 the subdirectory @file{config} and its name is often
732 @file{@var{machine}.h}.
733
734 @item
735 The command file @file{configure} also constructs the file
736 @file{Makefile} by adding some text to the template file
737 @file{Makefile.in}.  The additional text comes from files in the
738 @file{config} directory, named @file{t-@var{target}} and
739 @file{x-@var{host}}.  If these files do not exist, it means nothing
740 needs to be added for a given target or host.
741 @end itemize
742
743 @node Configurations
744 @section Configurations Supported by GNU CC
745 @cindex configurations supported by GNU CC
746
747 Here are the possible CPU types:
748
749 @quotation
750 @c gmicro, fx80, spur and tahoe omitted since they don't work.
751 1750a, a29k, alpha, arm, avr, c@var{n}, clipper, dsp16xx, elxsi, fr30, h8300,
752 hppa1.0, hppa1.1, i370, i386, i486, i586, i686, i786, i860, i960, m32r,
753 m68000, m68k, m88k, mcore, mips, mipsel, mips64, mips64el, mn10200, mn10300,
754 ns32k, pdp11, powerpc, powerpcle, romp, rs6000, sh, sparc, sparclite,
755 sparc64, v850, vax, we32k.
756 @end quotation
757
758 Here are the recognized company names.  As you can see, customary
759 abbreviations are used rather than the longer official names.
760
761 @c What should be done about merlin, tek*, dolphin?
762 @quotation
763 acorn, alliant, altos, apollo, apple, att, bull,
764 cbm, convergent, convex, crds, dec, dg, dolphin,
765 elxsi, encore, harris, hitachi, hp, ibm, intergraph, isi,
766 mips, motorola, ncr, next, ns, omron, plexus,
767 sequent, sgi, sony, sun, tti, unicom, wrs.
768 @end quotation
769
770 The company name is meaningful only to disambiguate when the rest of
771 the information supplied is insufficient.  You can omit it, writing
772 just @samp{@var{cpu}-@var{system}}, if it is not needed.  For example,
773 @samp{vax-ultrix4.2} is equivalent to @samp{vax-dec-ultrix4.2}.
774
775 Here is a list of system types:
776
777 @quotation
778 386bsd, aix, acis, amigaos, aos, aout, aux, bosx, bsd, clix, coff, ctix, cxux,
779 dgux, dynix, ebmon, ecoff, elf, esix, freebsd, hms, genix, gnu, linux-gnu,
780 hiux, hpux, iris, irix, isc, luna, lynxos, mach, minix, msdos, mvs,
781 netbsd, newsos, nindy, ns, osf, osfrose, ptx, riscix, riscos, rtu, sco, sim,
782 solaris, sunos, sym, sysv, udi, ultrix, unicos, uniplus, unos, vms, vsta,
783 vxworks, winnt, xenix.
784 @end quotation
785
786 @noindent
787 You can omit the system type; then @file{configure} guesses the
788 operating system from the CPU and company.
789
790 You can add a version number to the system type; this may or may not
791 make a difference.  For example, you can write @samp{bsd4.3} or
792 @samp{bsd4.4} to distinguish versions of BSD.  In practice, the version
793 number is most needed for @samp{sysv3} and @samp{sysv4}, which are often
794 treated differently.
795
796 If you specify an impossible combination such as @samp{i860-dg-vms},
797 then you may get an error message from @file{configure}, or it may
798 ignore part of the information and do the best it can with the rest.
799 @file{configure} always prints the canonical name for the alternative
800 that it used.  GNU CC does not support all possible alternatives.
801
802 Often a particular model of machine has a name.  Many machine names are
803 recognized as aliases for CPU/company combinations.  Thus, the machine
804 name @samp{sun3}, mentioned above, is an alias for @samp{m68k-sun}.
805 Sometimes we accept a company name as a machine name, when the name is
806 popularly used for a particular machine.  Here is a table of the known
807 machine names:
808
809 @quotation
810 3300, 3b1, 3b@var{n}, 7300, altos3068, altos,
811 apollo68, att-7300, balance,
812 convex-c@var{n}, crds, decstation-3100,
813 decstation, delta, encore,
814 fx2800, gmicro, hp7@var{nn}, hp8@var{nn},
815 hp9k2@var{nn}, hp9k3@var{nn}, hp9k7@var{nn},
816 hp9k8@var{nn}, iris4d, iris, isi68,
817 m3230, magnum, merlin, miniframe,
818 mmax, news-3600, news800, news, next,
819 pbd, pc532, pmax, powerpc, powerpcle, ps2, risc-news,
820 rtpc, sun2, sun386i, sun386, sun3,
821 sun4, symmetry, tower-32, tower.
822 @end quotation
823
824 @noindent
825 Remember that a machine name specifies both the cpu type and the company
826 name.
827 If you want to install your own homemade configuration files, you can
828 use @samp{local} as the company name to access them.  If you use
829 configuration @samp{@var{cpu}-local}, the configuration name
830 without the cpu prefix
831 is used to form the configuration file names.
832
833 Thus, if you specify @samp{m68k-local}, configuration uses
834 files @file{m68k.md}, @file{local.h}, @file{m68k.c},
835 @file{xm-local.h}, @file{t-local}, and @file{x-local}, all in the
836 directory @file{config/m68k}.
837
838 Here is a list of configurations that have special treatment or special
839 things you must know:
840
841 @table @samp
842 @item 1750a-*-*
843 MIL-STD-1750A processors.
844
845 The MIL-STD-1750A cross configuration produces output for
846 @code{as1750}, an assembler/linker available under the GNU Public
847 License for the 1750A. @code{as1750} can be obtained at 
848 @emph{ftp://ftp.fta-berlin.de/pub/crossgcc/1750gals/}.
849 A similarly licensed simulator for
850 the 1750A is available from same address.
851
852 You should ignore a fatal error during the building of libgcc (libgcc is
853 not yet implemented for the 1750A.)
854
855 The @code{as1750} assembler requires the file @file{ms1750.inc}, which is
856 found in the directory @file{config/1750a}.
857
858 GNU CC produced the same sections as the Fairchild F9450 C Compiler,
859 namely:
860
861 @table @code
862 @item Normal
863 The program code section.
864
865 @item Static
866 The read/write (RAM) data section.
867
868 @item Konst
869 The read-only (ROM) constants section.
870
871 @item Init
872 Initialization section (code to copy KREL to SREL).
873 @end table
874
875 The smallest addressable unit is 16 bits (BITS_PER_UNIT is 16).  This
876 means that type `char' is represented with a 16-bit word per character.
877 The 1750A's "Load/Store Upper/Lower Byte" instructions are not used by
878 GNU CC.
879
880 @item alpha-*-osf1
881 Systems using processors that implement the DEC Alpha architecture and
882 are running the DEC Unix (OSF/1) operating system, for example the DEC
883 Alpha AXP systems.CC.)
884
885 GNU CC writes a @samp{.verstamp} directive to the assembler output file
886 unless it is built as a cross-compiler.  It gets the version to use from
887 the system header file @file{/usr/include/stamp.h}.  If you install a
888 new version of DEC Unix, you should rebuild GCC to pick up the new version
889 stamp.
890
891 Note that since the Alpha is a 64-bit architecture, cross-compilers from
892 32-bit machines will not generate code as efficient as that generated
893 when the compiler is running on a 64-bit machine because many
894 optimizations that depend on being able to represent a word on the
895 target in an integral value on the host cannot be performed.  Building
896 cross-compilers on the Alpha for 32-bit machines has only been tested in
897 a few cases and may not work properly.
898
899 @code{make compare} may fail on old versions of DEC Unix unless you add
900 @samp{-save-temps} to @code{CFLAGS}.  On these systems, the name of the
901 assembler input file is stored in the object file, and that makes
902 comparison fail if it differs between the @code{stage1} and
903 @code{stage2} compilations.  The option @samp{-save-temps} forces a
904 fixed name to be used for the assembler input file, instead of a
905 randomly chosen name in @file{/tmp}.  Do not add @samp{-save-temps}
906 unless the comparisons fail without that option.  If you add
907 @samp{-save-temps}, you will have to manually delete the @samp{.i} and
908 @samp{.s} files after each series of compilations.
909
910 GNU CC now supports both the native (ECOFF) debugging format used by DBX
911 and GDB and an encapsulated STABS format for use only with GDB.  See the
912 discussion of the @samp{--with-stabs} option of @file{configure} above
913 for more information on these formats and how to select them.
914
915 There is a bug in DEC's assembler that produces incorrect line numbers
916 for ECOFF format when the @samp{.align} directive is used.  To work
917 around this problem, GNU CC will not emit such alignment directives
918 while writing ECOFF format debugging information even if optimization is
919 being performed.  Unfortunately, this has the very undesirable
920 side-effect that code addresses when @samp{-O} is specified are
921 different depending on whether or not @samp{-g} is also specified.
922
923 To avoid this behavior, specify @samp{-gstabs+} and use GDB instead of
924 DBX.  DEC is now aware of this problem with the assembler and hopes to
925 provide a fix shortly.
926
927 @item arc-*-elf
928 Argonaut ARC processor.
929 This configuration is intended for embedded systems.
930
931 @item arm-*-aout
932 Advanced RISC Machines ARM-family processors.  These are often used in
933 embedded applications.  There are no standard Unix configurations.
934 This configuration corresponds to the basic instruction sequences and will
935 produce @file{a.out} format object modules.
936
937 You may need to make a variant of the file @file{arm.h} for your particular
938 configuration.
939
940 @item arm-*-elf
941 This configuration is intended for embedded systems.
942
943 @item arm-*-linux-gnuaout
944 Any of the ARM-family processors running the Linux-based GNU system with
945 the @file{a.out} binary format.  This is an obsolete configuration.
946
947 @item arm-*-linux-gnu
948 @itemx arm-*-linux-gnuoldld
949 Any of the ARM-family processors running the Linux-based GNU system with
950 the @file{ELF} binary format.  You must use version 2.9.1.0.22 or later
951 of the GNU/Linux binutils, which you can download from
952 @file{ftp.varesearch.com:/pub/support/hjl/binutils}.
953
954 These two configurations differ only in the required version of GNU
955 binutils.  For binutils 2.9.1.0.x, use @samp{arm-*-linux-gnuoldld}.  For 
956 newer versions of binutils, use @samp{arm-*-linux-gnu}.
957
958 @item arm-*-riscix
959 The ARM2 or ARM3 processor running RISC iX, Acorn's port of BSD Unix.
960 If you are running a version of RISC iX prior to 1.2 then you must
961 specify the version number during configuration.  Note that the
962 assembler shipped with RISC iX does not support stabs debugging
963 information; a new version of the assembler, with stabs support
964 included, is now available from Acorn and via ftp
965 @file{ftp.acorn.com:/pub/riscix/as+xterm.tar.Z}.  To enable stabs
966 debugging, pass @samp{--with-gnu-as} to configure.
967
968 You will need to install GNU @file{sed} before you can run configure.
969
970 @item a29k
971 AMD Am29k-family processors.  These are normally used in embedded
972 applications.  There are no standard Unix configurations.
973 This configuration
974 corresponds to AMD's standard calling sequence and binary interface
975 and is compatible with other 29k tools.
976
977 You may need to make a variant of the file @file{a29k.h} for your
978 particular configuration.
979
980 @item a29k-*-bsd
981 AMD Am29050 used in a system running a variant of BSD Unix.
982
983 @item avr
984 ATMEL AVR-family micro controllers.  These are used in embedded
985 applications.  There are no standard Unix configurations.
986 Supports following MCU's:
987  - AT90S23xx
988  - ATtiny22
989  - AT90S44xx
990  - AT90S85xx
991  - ATmega603/603L
992  - ATmega103/103L
993
994 @item decstation-*
995 MIPS-based DECstations can support three different personalities:
996 Ultrix, DEC OSF/1, and OSF/rose.  (Alpha-based DECstation products have
997 a configuration name beginning with @samp{alpha-dec}.)  To configure GCC
998 for these platforms use the following configurations:
999
1000 @table @samp
1001 @item decstation-ultrix
1002 Ultrix configuration.
1003
1004 @item decstation-osf1
1005 Dec's version of OSF/1.
1006
1007 @item decstation-osfrose
1008 Open Software Foundation reference port of OSF/1 which uses the
1009 OSF/rose object file format instead of ECOFF.  Normally, you
1010 would not select this configuration.
1011 @end table
1012
1013 The MIPS C compiler needs to be told to increase its table size
1014 for switch statements with the @samp{-Wf,-XNg1500} option in
1015 order to compile @file{cp/parse.c}.  If you use the @samp{-O2}
1016 optimization option, you also need to use @samp{-Olimit 3000}.
1017 Both of these options are automatically generated in the
1018 @file{Makefile} that the shell script @file{configure} builds.
1019 If you override the @code{CC} make variable and use the MIPS
1020 compilers, you may need to add @samp{-Wf,-XNg1500 -Olimit 3000}.
1021
1022 @item elxsi-elxsi-bsd
1023 The Elxsi's C compiler has known limitations that prevent it from
1024 compiling GNU C.  Please contact @code{mrs@@cygnus.com} for more details.
1025
1026 @item dsp16xx
1027 A port to the AT&T DSP1610 family of processors.
1028
1029 @ignore
1030 @item fx80
1031 Alliant FX/8 computer.  Note that the standard installed C compiler in
1032 Concentrix 5.0 has a bug which prevent it from compiling GNU CC
1033 correctly.  You can patch the compiler bug as follows:
1034
1035 @smallexample
1036 cp /bin/pcc ./pcc
1037 adb -w ./pcc - << EOF
1038 15f6?w 6610
1039 EOF
1040 @end smallexample
1041
1042 Then you must use the @samp{-ip12} option when compiling GNU CC
1043 with the patched compiler, as shown here:
1044
1045 @smallexample
1046 make CC="./pcc -ip12" CFLAGS=-w
1047 @end smallexample
1048
1049 Note also that Alliant's version of DBX does not manage to work with the
1050 output from GNU CC.
1051 @end ignore
1052
1053 @item h8300-*-*
1054 Hitachi H8/300 series of processors.
1055
1056 The calling convention and structure layout has changed in release 2.6.
1057 All code must be recompiled.  The calling convention now passes the
1058 first three arguments in function calls in registers.  Structures are no
1059 longer a multiple of 2 bytes.
1060
1061 @item hppa*-*-*
1062 There are several variants of the HP-PA processor which run a variety
1063 of operating systems.  GNU CC must be configured to use the correct
1064 processor type and operating system, or GNU CC will not function correctly.
1065 The easiest way to handle this problem is to @emph{not} specify a target
1066 when configuring GNU CC, the @file{configure} script will try to automatically
1067 determine the right processor type and operating system.
1068
1069 @samp{-g} does not work on HP-UX, since that system uses a peculiar
1070 debugging format which GNU CC does not know about.  However, @samp{-g}
1071 will work if you also use GAS and GDB in conjunction with GCC.  We
1072 highly recommend using GAS for all HP-PA configurations.
1073
1074 You should be using GAS-2.6 (or later) along with GDB-4.16 (or later).  These
1075 can be retrieved from all the traditional GNU ftp archive sites.
1076
1077 On some versions of HP-UX, you will need to install GNU @file{sed}.
1078
1079 You will need to be install GAS into a directory before @code{/bin},
1080 @code{/usr/bin}, and @code{/usr/ccs/bin} in your search path.  You
1081 should install GAS before you build GNU CC.
1082
1083 To enable debugging, you must configure GNU CC with the @samp{--with-gnu-as}
1084 option before building.
1085
1086 @item i370-*-*
1087 This port is very preliminary and has many known bugs.  We hope to
1088 have a higher-quality port for this machine soon.
1089
1090 @item i386-*-linux-gnuoldld
1091 Use this configuration to generate @file{a.out} binaries on Linux-based
1092 GNU systems if you do not have gas/binutils version 2.5.2 or later
1093 installed. This is an obsolete configuration.
1094
1095 @item i386-*-linux-gnuaout
1096 Use this configuration to generate @file{a.out} binaries on Linux-based
1097 GNU systems. This configuration is being superseded. You must use
1098 gas/binutils version 2.5.2 or later.
1099
1100 @item i386-*-linux-gnu
1101 Use this configuration to generate ELF binaries on Linux-based GNU
1102 systems.  You must use gas/binutils version 2.5.2 or later.
1103
1104 @item i386-*-sco
1105 Compilation with RCC is recommended.  Also, it may be a good idea to
1106 link with GNU malloc instead of the malloc that comes with the system.
1107
1108 @item i386-*-sco3.2v4
1109 Use this configuration for SCO release 3.2 version 4.
1110
1111 @item i386-*-sco3.2v5*
1112 Use this for the SCO OpenServer Release family including 5.0.0, 5.0.2, 
1113 5.0.4, 5.0.5, Internet FastStart 1.0, and Internet FastStart 1.1.
1114
1115 GNU CC can generate COFF binaries if you specify @samp{-mcoff} or ELF
1116 binaries, the default.    A full @samp{make bootstrap} is recommended
1117 so that an ELF compiler that builds ELF is generated.                   
1118
1119 You must have TLS597 from @uref{ftp://ftp.sco.com/TLS} installed for ELF
1120 C++ binaries to work correctly on releases before 5.0.4. 
1121
1122 The native SCO assembler that is provided with the OS at no charge
1123 is normally required.  If, however, you must be able to use the GNU
1124 assembler (perhaps you have complex asms) you must configure this
1125 package @samp{--with-gnu-as}.  To do this, install (cp or symlink)
1126 gcc/as to your copy of the GNU assembler.  You must use a recent version
1127 of GNU binutils; version 2.9.1 seems to work well.  If you select this
1128 option, you will be unable to build COFF images.  Trying to do so will
1129 result in non-obvious failures.  In general, the "--with-gnu-as" option
1130 isn't as well tested as the native assembler.
1131
1132 @emph{NOTE:} If you are building C++, you must follow the instructions
1133 about invoking @samp{make bootstrap} because the native OpenServer
1134 compiler may build a @file{cc1plus} that will not correctly parse many
1135 valid C++ programs.  You must do a @samp{make bootstrap} if you are
1136 building with the native compiler.
1137
1138 @item i386-*-isc
1139 It may be a good idea to link with GNU malloc instead of the malloc that
1140 comes with the system.
1141
1142 In ISC version 4.1, @file{sed} core dumps when building
1143 @file{deduced.h}.  Use the version of @file{sed} from version 4.0.
1144
1145 @item i386-*-esix
1146 It may be good idea to link with GNU malloc instead of the malloc that
1147 comes with the system.
1148
1149 @item i386-ibm-aix
1150 You need to use GAS version 2.1 or later, and LD from
1151 GNU binutils version 2.2 or later.
1152
1153 @item i386-sequent-bsd
1154 Go to the Berkeley universe before compiling.
1155
1156 @item i386-sequent-ptx1*
1157 @itemx i386-sequent-ptx2*
1158 You must install GNU @file{sed} before running @file{configure}.
1159
1160 @item i386-sun-sunos4
1161 You may find that you need another version of GNU CC to begin
1162 bootstrapping with, since the current version when built with the
1163 system's own compiler seems to get an infinite loop compiling part of
1164 @file{libgcc2.c}.  GNU CC version 2 compiled with GNU CC (any version)
1165 seems not to have this problem.
1166
1167 See @ref{Sun Install}, for information on installing GNU CC on Sun
1168 systems.
1169
1170 @item i[345]86-*-winnt3.5
1171 This version requires a GAS that has not yet been released.  Until it
1172 is, you can get a prebuilt binary version via anonymous ftp from
1173 @file{cs.washington.edu:pub/gnat} or @file{cs.nyu.edu:pub/gnat}. You
1174 must also use the Microsoft header files from the Windows NT 3.5 SDK.
1175 Find these on the CDROM in the @file{/mstools/h} directory dated 9/4/94.  You
1176 must use a fixed version of Microsoft linker made especially for NT 3.5,
1177 which is also is available on the NT 3.5 SDK CDROM.  If you do not have
1178 this linker, can you also use the linker from Visual C/C++ 1.0 or 2.0.
1179
1180 Installing GNU CC for NT builds a wrapper linker, called @file{ld.exe},
1181 which mimics the behaviour of Unix @file{ld} in the specification of
1182 libraries (@samp{-L} and @samp{-l}).  @file{ld.exe} looks for both Unix
1183 and Microsoft named libraries.  For example, if you specify
1184 @samp{-lfoo}, @file{ld.exe} will look first for @file{libfoo.a}
1185 and then for @file{foo.lib}.
1186
1187 You may install GNU CC for Windows NT in one of two ways, depending on
1188 whether or not you have a Unix-like shell and various Unix-like
1189 utilities.
1190
1191 @enumerate
1192 @item
1193 If you do not have a Unix-like shell and few Unix-like utilities, you
1194 will use a DOS style batch script called @file{configure.bat}.  Invoke
1195 it as @code{configure winnt} from an MSDOS console window or from the
1196 program manager dialog box.  @file{configure.bat} assumes you have
1197 already installed and have in your path a Unix-like @file{sed} program
1198 which is used to create a working @file{Makefile} from @file{Makefile.in}.
1199
1200 @file{Makefile} uses the Microsoft Nmake program maintenance utility and
1201 the Visual C/C++ V8.00 compiler to build GNU CC.  You need only have the
1202 utilities @file{sed} and @file{touch} to use this installation method,
1203 which only automatically builds the compiler itself.  You must then
1204 examine what @file{fixinc.winnt} does, edit the header files by hand and
1205 build @file{libgcc.a} manually.
1206
1207 @item
1208 The second type of installation assumes you are running a Unix-like
1209 shell, have a complete suite of Unix-like utilities in your path, and
1210 have a previous version of GNU CC already installed, either through
1211 building it via the above installation method or acquiring a pre-built
1212 binary.  In this case, use the @file{configure} script in the normal
1213 fashion.
1214 @end enumerate
1215
1216 @item i860-intel-osf1
1217 This is the Paragon.
1218 @ifset INSTALLONLY
1219 If you have version 1.0 of the operating system, you need to take
1220 special steps to build GNU CC due to peculiarities of the system.  Newer
1221 system versions have no problem.  See the section `Installation Problems'
1222 in the GNU CC Manual.
1223 @end ifset
1224 @ifclear INSTALLONLY
1225 If you have version 1.0 of the operating system,
1226 see @ref{Installation Problems}, for special things you need to do to
1227 compensate for peculiarities in the system.
1228 @end ifclear
1229
1230 @item *-lynx-lynxos
1231 LynxOS 2.2 and earlier comes with GNU CC 1.x already installed as
1232 @file{/bin/gcc}.  You should compile with this instead of @file{/bin/cc}.
1233 You can tell GNU CC to use the GNU assembler and linker, by specifying
1234 @samp{--with-gnu-as --with-gnu-ld} when configuring.  These will produce
1235 COFF format object files and executables;  otherwise GNU CC will use the
1236 installed tools, which produce @file{a.out} format executables.
1237
1238 @item m32r-*-elf
1239 Mitsubishi M32R processor.
1240 This configuration is intended for embedded systems.
1241
1242 @item m68000-hp-bsd
1243 HP 9000 series 200 running BSD.  Note that the C compiler that comes
1244 with this system cannot compile GNU CC; contact @code{law@@cygnus.com}
1245 to get binaries of GNU CC for bootstrapping.
1246
1247 @item m68k-altos
1248 Altos 3068.  You must use the GNU assembler, linker and debugger.
1249 Also, you must fix a kernel bug.  Details in the file @file{README.ALTOS}.
1250
1251 @item m68k-apple-aux
1252 Apple Macintosh running A/UX.
1253 You may configure GCC  to use either the system assembler and
1254 linker or the GNU assembler and linker.  You should use the GNU configuration
1255 if you can, especially if you also want to use GNU C++.  You enabled
1256 that configuration with + the @samp{--with-gnu-as} and @samp{--with-gnu-ld}
1257 options to @code{configure}.
1258
1259 Note the C compiler that comes
1260 with this system cannot compile GNU CC.  You can find binaries of GNU CC
1261 for bootstrapping on @code{jagubox.gsfc.nasa.gov}.
1262 You will also a patched version of @file{/bin/ld} there that
1263 raises some of the arbitrary limits found in the original.
1264
1265 @item m68k-att-sysv
1266 AT&T 3b1, a.k.a. 7300 PC.  This version of GNU CC cannot
1267 be compiled with the system C compiler, which is too buggy.
1268 You will need to get a previous version of GCC and use it to
1269 bootstrap.  Binaries are available from the OSU-CIS archive, at
1270 @url{ftp://archive.cis.ohio-state.edu/pub/att7300/}.
1271
1272 @item m68k-bull-sysv
1273 Bull DPX/2 series 200 and 300 with BOS-2.00.45 up to BOS-2.01. GNU CC works
1274 either with native assembler or GNU assembler. You can use
1275 GNU assembler with native coff generation by providing @samp{--with-gnu-as} to
1276 the configure script or use GNU assembler with dbx-in-coff encapsulation
1277 by providing @samp{--with-gnu-as --stabs}. For any problem with native
1278 assembler or for availability of the DPX/2 port of GAS, contact
1279 @code{F.Pierresteguy@@frcl.bull.fr}.
1280
1281 @item m68k-crds-unox
1282 Use @samp{configure unos} for building on Unos.
1283
1284 The Unos assembler is named @code{casm} instead of @code{as}.  For some
1285 strange reason linking @file{/bin/as} to @file{/bin/casm} changes the
1286 behavior, and does not work.  So, when installing GNU CC, you should
1287 install the following script as @file{as} in the subdirectory where
1288 the passes of GCC are installed:
1289
1290 @example
1291 #!/bin/sh
1292 casm $*
1293 @end example
1294
1295 The default Unos library is named @file{libunos.a} instead of
1296 @file{libc.a}.  To allow GNU CC to function, either change all
1297 references to @samp{-lc} in @file{gcc.c} to @samp{-lunos} or link
1298 @file{/lib/libc.a} to @file{/lib/libunos.a}.
1299
1300 @cindex @code{alloca}, for Unos
1301 When compiling GNU CC with the standard compiler, to overcome bugs in
1302 the support of @code{alloca}, do not use @samp{-O} when making stage 2.
1303 Then use the stage 2 compiler with @samp{-O} to make the stage 3
1304 compiler.  This compiler will have the same characteristics as the usual
1305 stage 2 compiler on other systems.  Use it to make a stage 4 compiler
1306 and compare that with stage 3 to verify proper compilation.
1307
1308 (Perhaps simply defining @code{ALLOCA} in @file{x-crds} as described in
1309 the comments there will make the above paragraph superfluous.  Please
1310 inform us of whether this works.)
1311
1312 Unos uses memory segmentation instead of demand paging, so you will need
1313 a lot of memory.  5 Mb is barely enough if no other tasks are running.
1314 If linking @file{cc1} fails, try putting the object files into a library
1315 and linking from that library.
1316
1317 @item m68k-hp-hpux
1318 HP 9000 series 300 or 400 running HP-UX.  HP-UX version 8.0 has a bug in
1319 the assembler that prevents compilation of GNU CC.  To fix it, get patch
1320 PHCO_4484 from HP.
1321
1322 In addition, if you wish to use gas @samp{--with-gnu-as} you must use
1323 gas version 2.1 or later, and you must use the GNU linker version 2.1 or
1324 later.  Earlier versions of gas relied upon a program which converted the
1325 gas output into the native HP-UX format, but that program has not been
1326 kept up to date.  gdb does not understand that native HP-UX format, so
1327 you must use gas if you wish to use gdb.
1328
1329 @item m68k-sun
1330 Sun 3.  We do not provide a configuration file to use the Sun FPA by
1331 default, because programs that establish signal handlers for floating
1332 point traps inherently cannot work with the FPA.
1333
1334 See @ref{Sun Install}, for information on installing GNU CC on Sun
1335 systems.
1336
1337 @item m88k-*-svr3
1338 Motorola m88k running the AT&T/Unisoft/Motorola V.3 reference port.
1339 These systems tend to use the Green Hills C, revision 1.8.5, as the
1340 standard C compiler.  There are apparently bugs in this compiler that
1341 result in object files differences between stage 2 and stage 3.  If this
1342 happens, make the stage 4 compiler and compare it to the stage 3
1343 compiler.  If the stage 3 and stage 4 object files are identical, this
1344 suggests you encountered a problem with the standard C compiler; the
1345 stage 3 and 4 compilers may be usable.
1346
1347 It is best, however, to use an older version of GNU CC for bootstrapping
1348 if you have one.
1349
1350 @item m88k-*-dgux
1351 Motorola m88k running DG/UX.  To build 88open BCS native or cross
1352 compilers on DG/UX, specify the configuration name as
1353 @samp{m88k-*-dguxbcs} and build in the 88open BCS software development
1354 environment.  To build ELF native or cross compilers on DG/UX, specify
1355 @samp{m88k-*-dgux} and build in the DG/UX ELF development environment.
1356 You set the software development environment by issuing
1357 @samp{sde-target} command and specifying either @samp{m88kbcs} or
1358 @samp{m88kdguxelf} as the operand.
1359
1360 If you do not specify a configuration name, @file{configure} guesses the
1361 configuration based on the current software development environment.
1362
1363 @item m88k-tektronix-sysv3
1364 Tektronix XD88 running UTekV 3.2e.  Do not turn on
1365 optimization while building stage1 if you bootstrap with
1366 the buggy Green Hills compiler.  Also, The bundled LAI
1367 System V NFS is buggy so if you build in an NFS mounted
1368 directory, start from a fresh reboot, or avoid NFS all together.
1369 Otherwise you may have trouble getting clean comparisons
1370 between stages.
1371
1372 @item mips-mips-bsd
1373 MIPS machines running the MIPS operating system in BSD mode.  It's
1374 possible that some old versions of the system lack the functions
1375 @code{memcpy}, @code{memcmp}, and @code{memset}.  If your system lacks
1376 these, you must remove or undo the definition of
1377 @code{TARGET_MEM_FUNCTIONS} in @file{mips-bsd.h}.
1378
1379 The MIPS C compiler needs to be told to increase its table size
1380 for switch statements with the @samp{-Wf,-XNg1500} option in
1381 order to compile @file{cp/parse.c}.  If you use the @samp{-O2}
1382 optimization option, you also need to use @samp{-Olimit 3000}.
1383 Both of these options are automatically generated in the
1384 @file{Makefile} that the shell script @file{configure} builds.
1385 If you override the @code{CC} make variable and use the MIPS
1386 compilers, you may need to add @samp{-Wf,-XNg1500 -Olimit 3000}.
1387
1388 @item mips-mips-riscos*
1389 The MIPS C compiler needs to be told to increase its table size
1390 for switch statements with the @samp{-Wf,-XNg1500} option in
1391 order to compile @file{cp/parse.c}.  If you use the @samp{-O2}
1392 optimization option, you also need to use @samp{-Olimit 3000}.
1393 Both of these options are automatically generated in the
1394 @file{Makefile} that the shell script @file{configure} builds.
1395 If you override the @code{CC} make variable and use the MIPS
1396 compilers, you may need to add @samp{-Wf,-XNg1500 -Olimit 3000}.
1397
1398 MIPS computers running RISC-OS can support four different
1399 personalities: default, BSD 4.3, System V.3, and System V.4
1400 (older versions of RISC-OS don't support V.4).  To configure GCC
1401 for these platforms use the following configurations:
1402
1403 @table @samp
1404 @item mips-mips-riscos@code{rev}
1405 Default configuration for RISC-OS, revision @code{rev}.
1406
1407 @item mips-mips-riscos@code{rev}bsd
1408 BSD 4.3 configuration for RISC-OS, revision @code{rev}.
1409
1410 @item mips-mips-riscos@code{rev}sysv4
1411 System V.4 configuration for RISC-OS, revision @code{rev}.
1412
1413 @item mips-mips-riscos@code{rev}sysv
1414 System V.3 configuration for RISC-OS, revision @code{rev}.
1415 @end table
1416
1417 The revision @code{rev} mentioned above is the revision of
1418 RISC-OS to use.  You must reconfigure GCC when going from a
1419 RISC-OS revision 4 to RISC-OS revision 5.  This has the effect of
1420 avoiding a linker
1421 @ifclear INSTALLONLY
1422 bug (see @ref{Installation Problems}, for more details).
1423 @end ifclear
1424 @ifset INSTALLONLY
1425 bug.
1426 @end ifset
1427
1428 @item mips-sgi-*
1429 In order to compile GCC on an SGI running IRIX 4, the "c.hdr.lib"
1430 option must be installed from the CD-ROM supplied from Silicon Graphics.
1431 This is found on the 2nd CD in release 4.0.1.
1432
1433 In order to compile GCC on an SGI running IRIX 5, the "compiler_dev.hdr"
1434 subsystem must be installed from the IDO CD-ROM supplied by Silicon
1435 Graphics.
1436
1437 @code{make compare} may fail on version 5 of IRIX unless you add
1438 @samp{-save-temps} to @code{CFLAGS}.  On these systems, the name of the
1439 assembler input file is stored in the object file, and that makes
1440 comparison fail if it differs between the @code{stage1} and
1441 @code{stage2} compilations.  The option @samp{-save-temps} forces a
1442 fixed name to be used for the assembler input file, instead of a
1443 randomly chosen name in @file{/tmp}.  Do not add @samp{-save-temps}
1444 unless the comparisons fail without that option.  If you do you
1445 @samp{-save-temps}, you will have to manually delete the @samp{.i} and
1446 @samp{.s} files after each series of compilations.
1447
1448 The MIPS C compiler needs to be told to increase its table size
1449 for switch statements with the @samp{-Wf,-XNg1500} option in
1450 order to compile @file{cp/parse.c}.  If you use the @samp{-O2}
1451 optimization option, you also need to use @samp{-Olimit 3000}.
1452 Both of these options are automatically generated in the
1453 @file{Makefile} that the shell script @file{configure} builds.
1454 If you override the @code{CC} make variable and use the MIPS
1455 compilers, you may need to add @samp{-Wf,-XNg1500 -Olimit 3000}.
1456
1457 On Irix version 4.0.5F, and perhaps on some other versions as well,
1458 there is an assembler bug that reorders instructions incorrectly.  To
1459 work around it, specify the target configuration
1460 @samp{mips-sgi-irix4loser}.  This configuration inhibits assembler
1461 optimization.
1462
1463 In a compiler configured with target @samp{mips-sgi-irix4}, you can turn
1464 off assembler optimization by using the @samp{-noasmopt} option.  This
1465 compiler option passes the option @samp{-O0} to the assembler, to
1466 inhibit reordering.
1467
1468 The @samp{-noasmopt} option can be useful for testing whether a problem
1469 is due to erroneous assembler reordering.  Even if a problem does not go
1470 away with @samp{-noasmopt}, it may still be due to assembler
1471 reordering---perhaps GNU CC itself was miscompiled as a result.
1472
1473 To enable debugging under Irix 5, you must use GNU as 2.5 or later,
1474 and use the @samp{--with-gnu-as} configure option when configuring gcc.
1475 GNU as is distributed as part of the binutils package.
1476
1477 @item mips-sony-sysv
1478 Sony MIPS NEWS.  This works in NEWSOS 5.0.1, but not in 5.0.2 (which
1479 uses ELF instead of COFF).  Support for 5.0.2 will probably be provided
1480 soon by volunteers.  In particular, the linker does not like the
1481 code generated by GCC when shared libraries are linked in.
1482
1483 @item ns32k-encore
1484 Encore ns32000 system.  Encore systems are supported only under BSD.
1485
1486 @item ns32k-*-genix
1487 National Semiconductor ns32000 system.  Genix has bugs in @code{alloca}
1488 and @code{malloc}; you must get the compiled versions of these from GNU
1489 Emacs.
1490
1491 @item ns32k-sequent
1492 Go to the Berkeley universe before compiling.
1493
1494 @item ns32k-utek
1495 UTEK ns32000 system (``merlin'').  The C compiler that comes with this
1496 system cannot compile GNU CC; contact @samp{tektronix!reed!mason} to get
1497 binaries of GNU CC for bootstrapping.
1498
1499 @item romp-*-aos
1500 @itemx romp-*-mach
1501 The only operating systems supported for the IBM RT PC are AOS and
1502 MACH.  GNU CC does not support AIX running on the RT.  We recommend you
1503 compile GNU CC with an earlier version of itself; if you compile GNU CC
1504 with @code{hc}, the Metaware compiler, it will work, but you will get
1505 mismatches between the stage 2 and stage 3 compilers in various files.
1506 These errors are minor differences in some floating-point constants and
1507 can be safely ignored; the stage 3 compiler is correct.
1508
1509 @item rs6000-*-aix
1510 @itemx powerpc-*-aix
1511 Various early versions of each release of the IBM XLC compiler will not
1512 bootstrap GNU CC.  Symptoms include differences between the stage2 and
1513 stage3 object files, and errors when compiling @file{libgcc.a} or
1514 @file{enquire}.  Known problematic releases include: xlc-1.2.1.8,
1515 xlc-1.3.0.0 (distributed with AIX 3.2.5), and xlc-1.3.0.19.  Both
1516 xlc-1.2.1.28 and xlc-1.3.0.24 (PTF 432238) are known to produce working
1517 versions of GNU CC, but most other recent releases correctly bootstrap
1518 GNU CC.
1519
1520 Release 4.3.0 of AIX and ones prior to AIX 3.2.4 include a version of
1521 the IBM assembler which does not accept debugging directives: assembler
1522 updates are available as PTFs.  Also, if you are using AIX 3.2.5 or
1523 greater and the GNU assembler, you must have a version modified after
1524 October 16th, 1995 in order for the GNU C compiler to build.  See the
1525 file @file{README.RS6000} for more details on any of these problems.
1526
1527 GNU CC does not yet support the 64-bit PowerPC instructions.
1528
1529 Objective C does not work on this architecture because it makes assumptions
1530 that are incompatible with the calling conventions.
1531
1532 AIX on the RS/6000 provides support (NLS) for environments outside of
1533 the United States.  Compilers and assemblers use NLS to support
1534 locale-specific representations of various objects including
1535 floating-point numbers ("." vs "," for separating decimal fractions).
1536 There have been problems reported where the library linked with GNU CC
1537 does not produce the same floating-point formats that the assembler
1538 accepts.  If you have this problem, set the LANG environment variable to
1539 "C" or "En_US".
1540
1541 Due to changes in the way that GNU CC invokes the binder (linker) for AIX
1542 4.1, you may now receive warnings of duplicate symbols from the link step
1543 that were not reported before.  The assembly files generated by GNU CC for
1544 AIX have always included multiple symbol definitions for certain global
1545 variable and function declarations in the original program.  The warnings
1546 should not prevent the linker from producing a correct library or runnable
1547 executable.
1548
1549 By default, AIX 4.1 produces code that can be used on either Power or
1550 PowerPC processors.
1551
1552 You can specify a default version for the @samp{-mcpu=}@var{cpu_type}
1553 switch by using the configure option @samp{--with-cpu-}@var{cpu_type}.
1554
1555 @item powerpc-*-elf
1556 @itemx powerpc-*-sysv4
1557 PowerPC system in big endian mode, running System V.4.
1558
1559 You can specify a default version for the @samp{-mcpu=}@var{cpu_type}
1560 switch by using the configure option @samp{--with-cpu-}@var{cpu_type}.
1561
1562 @item powerpc-*-linux-gnu
1563 PowerPC system in big endian mode, running the Linux-based GNU system.
1564
1565 You can specify a default version for the @samp{-mcpu=}@var{cpu_type}
1566 switch by using the configure option @samp{--with-cpu-}@var{cpu_type}.
1567
1568 @item powerpc-*-eabiaix
1569 Embedded PowerPC system in big endian mode with -mcall-aix selected as
1570 the default.
1571
1572 You can specify a default version for the @samp{-mcpu=}@var{cpu_type}
1573 switch by using the configure option @samp{--with-cpu-}@var{cpu_type}.
1574
1575 @item powerpc-*-eabisim
1576 Embedded PowerPC system in big endian mode for use in running under the
1577 PSIM simulator.
1578
1579 You can specify a default version for the @samp{-mcpu=}@var{cpu_type}
1580 switch by using the configure option @samp{--with-cpu-}@var{cpu_type}.
1581
1582 @item powerpc-*-eabi
1583 Embedded PowerPC system in big endian mode.
1584
1585 You can specify a default version for the @samp{-mcpu=}@var{cpu_type}
1586 switch by using the configure option @samp{--with-cpu-}@var{cpu_type}.
1587
1588 @item powerpcle-*-elf
1589 @itemx powerpcle-*-sysv4
1590 PowerPC system in little endian mode, running System V.4.
1591
1592 You can specify a default version for the @samp{-mcpu=}@var{cpu_type}
1593 switch by using the configure option @samp{--with-cpu-}@var{cpu_type}.
1594
1595 @item powerpcle-*-solaris2*
1596 PowerPC system in little endian mode, running Solaris 2.5.1 or higher.
1597
1598 You can specify a default version for the @samp{-mcpu=}@var{cpu_type}
1599 switch by using the configure option @samp{--with-cpu-}@var{cpu_type}.
1600 Beta versions of the Sun 4.0 compiler do not seem to be able to build
1601 GNU CC correctly.  There are also problems with the host assembler and
1602 linker that are fixed by using the GNU versions of these tools.
1603
1604 @item powerpcle-*-eabisim
1605 Embedded PowerPC system in little endian mode for use in running under
1606 the PSIM simulator.
1607
1608 @itemx powerpcle-*-eabi
1609 Embedded PowerPC system in little endian mode.
1610
1611 You can specify a default version for the @samp{-mcpu=}@var{cpu_type}
1612 switch by using the configure option @samp{--with-cpu-}@var{cpu_type}.
1613
1614 @item powerpcle-*-winnt
1615 @itemx powerpcle-*-pe
1616 PowerPC system in little endian mode running Windows NT.
1617
1618 You can specify a default version for the @samp{-mcpu=}@var{cpu_type}
1619 switch by using the configure option @samp{--with-cpu-}@var{cpu_type}.
1620
1621 @item vax-dec-ultrix
1622 Don't try compiling with Vax C (@code{vcc}).  It produces incorrect code
1623 in some cases (for example, when @code{alloca} is used).
1624
1625 Meanwhile, compiling @file{cp/parse.c} with pcc does not work because of
1626 an internal table size limitation in that compiler.  To avoid this
1627 problem, compile just the GNU C compiler first, and use it to recompile
1628 building all the languages that you want to run.
1629
1630 @item sparc-sun-*
1631 See @ref{Sun Install}, for information on installing GNU CC on Sun
1632 systems.
1633
1634 @item vax-dec-vms
1635 See @ref{VMS Install}, for details on how to install GNU CC on VMS.
1636
1637 @item we32k-*-*
1638 These computers are also known as the 3b2, 3b5, 3b20 and other similar
1639 names.  (However, the 3b1 is actually a 68000; see
1640 @ref{Configurations}.)
1641
1642 Don't use @samp{-g} when compiling with the system's compiler.  The
1643 system's linker seems to be unable to handle such a large program with
1644 debugging information.
1645
1646 The system's compiler runs out of capacity when compiling @file{stmt.c}
1647 in GNU CC.  You can work around this by building @file{cpp} in GNU CC
1648 first, then use that instead of the system's preprocessor with the
1649 system's C compiler to compile @file{stmt.c}.  Here is how:
1650
1651 @smallexample
1652 mv /lib/cpp /lib/cpp.att
1653 cp cpp /lib/cpp.gnu
1654 echo '/lib/cpp.gnu -traditional $@{1+"$@@"@}' > /lib/cpp
1655 chmod +x /lib/cpp
1656 @end smallexample
1657
1658 The system's compiler produces bad code for some of the GNU CC
1659 optimization files.  So you must build the stage 2 compiler without
1660 optimization.  Then build a stage 3 compiler with optimization.
1661 That executable should work.  Here are the necessary commands:
1662
1663 @smallexample
1664 make LANGUAGES=c CC=stage1/xgcc CFLAGS="-Bstage1/ -g"
1665 make stage2
1666 make CC=stage2/xgcc CFLAGS="-Bstage2/ -g -O"
1667 @end smallexample
1668
1669 You may need to raise the ULIMIT setting to build a C++ compiler,
1670 as the file @file{cc1plus} is larger than one megabyte.
1671 @end table
1672
1673 @node Other Dir
1674 @section Compilation in a Separate Directory
1675 @cindex other directory, compilation in
1676 @cindex compilation in a separate directory
1677 @cindex separate directory, compilation in
1678
1679 If you wish to build the object files and executables in a directory
1680 other than the one containing the source files, here is what you must
1681 do differently:
1682
1683 @enumerate
1684 @item
1685 Make sure you have a version of Make that supports the @code{VPATH}
1686 feature.  (GNU Make supports it, as do Make versions on most BSD
1687 systems.)
1688
1689 @item
1690 If you have ever run @file{configure} in the source directory, you must undo
1691 the configuration.  Do this by running:
1692
1693 @example
1694 make distclean
1695 @end example
1696
1697 @item
1698 Go to the directory in which you want to build the compiler before
1699 running @file{configure}:
1700
1701 @example
1702 mkdir gcc-sun3
1703 cd gcc-sun3
1704 @end example
1705
1706 On systems that do not support symbolic links, this directory must be
1707 on the same file system as the source code directory.
1708
1709 @item
1710 Specify where to find @file{configure} when you run it:
1711
1712 @example
1713 ../gcc/configure @dots{}
1714 @end example
1715
1716 This also tells @code{configure} where to find the compiler sources;
1717 @code{configure} takes the directory from the file name that was used to
1718 invoke it.  But if you want to be sure, you can specify the source
1719 directory with the @samp{--srcdir} option, like this:
1720
1721 @example
1722 ../gcc/configure --srcdir=../gcc @var{other options}
1723 @end example
1724
1725 The directory you specify with @samp{--srcdir} need not be the same
1726 as the one that @code{configure} is found in.
1727 @end enumerate
1728
1729 Now, you can run @code{make} in that directory.  You need not repeat the
1730 configuration steps shown above, when ordinary source files change.  You
1731 must, however, run @code{configure} again when the configuration files
1732 change, if your system does not support symbolic links.
1733
1734 @node Cross-Compiler
1735 @section Building and Installing a Cross-Compiler
1736 @cindex cross-compiler, installation
1737
1738 GNU CC can function as a cross-compiler for many machines, but not all.
1739
1740 @itemize @bullet
1741 @item
1742 Cross-compilers for the Mips as target using the Mips assembler
1743 currently do not work, because the auxiliary programs
1744 @file{mips-tdump.c} and @file{mips-tfile.c} can't be compiled on
1745 anything but a Mips.  It does work to cross compile for a Mips
1746 if you use the GNU assembler and linker.
1747
1748 @item
1749 Cross-compilers between machines with different floating point formats
1750 have not all been made to work.  GNU CC now has a floating point
1751 emulator with which these can work, but each target machine description
1752 needs to be updated to take advantage of it.
1753
1754 @item
1755 Cross-compilation between machines of different word sizes is
1756 somewhat problematic and sometimes does not work.
1757 @end itemize
1758
1759 Since GNU CC generates assembler code, you probably need a
1760 cross-assembler that GNU CC can run, in order to produce object files.
1761 If you want to link on other than the target machine, you need a
1762 cross-linker as well.  You also need header files and libraries suitable
1763 for the target machine that you can install on the host machine.
1764
1765 @menu
1766 * Steps of Cross::      Using a cross-compiler involves several steps
1767                           that may be carried out on different machines.
1768 * Configure Cross::     Configuring a cross-compiler.
1769 * Tools and Libraries:: Where to put the linker and assembler, and the C library.
1770 * Cross Headers::       Finding and installing header files
1771                           for a cross-compiler.
1772 * Cross Runtime::       Supplying arithmetic runtime routines (@file{libgcc1.a}).
1773 * Build Cross::         Actually compiling the cross-compiler.
1774 @end menu
1775
1776 @node Steps of Cross
1777 @subsection Steps of Cross-Compilation
1778
1779 To compile and run a program using a cross-compiler involves several
1780 steps:
1781
1782 @itemize @bullet
1783 @item
1784 Run the cross-compiler on the host machine to produce assembler files
1785 for the target machine.  This requires header files for the target
1786 machine.
1787
1788 @item
1789 Assemble the files produced by the cross-compiler.  You can do this
1790 either with an assembler on the target machine, or with a
1791 cross-assembler on the host machine.
1792
1793 @item
1794 Link those files to make an executable.  You can do this either with a
1795 linker on the target machine, or with a cross-linker on the host
1796 machine.  Whichever machine you use, you need libraries and certain
1797 startup files (typically @file{crt@dots{}.o}) for the target machine.
1798 @end itemize
1799
1800 It is most convenient to do all of these steps on the same host machine,
1801 since then you can do it all with a single invocation of GNU CC.  This
1802 requires a suitable cross-assembler and cross-linker.  For some targets,
1803 the GNU assembler and linker are available.
1804
1805 @node Configure Cross
1806 @subsection Configuring a Cross-Compiler
1807
1808 To build GNU CC as a cross-compiler, you start out by running
1809 @file{configure}.  Use the @samp{--target=@var{target}} to specify the
1810 target type.  If @file{configure} was unable to correctly identify the
1811 system you are running on, also specify the @samp{--build=@var{build}}
1812 option.  For example, here is how to configure for a cross-compiler that
1813 produces code for an HP 68030 system running BSD on a system that
1814 @file{configure} can correctly identify:
1815
1816 @smallexample
1817 ./configure --target=m68k-hp-bsd4.3
1818 @end smallexample
1819
1820 @node Tools and Libraries
1821 @subsection Tools and Libraries for a Cross-Compiler
1822
1823 If you have a cross-assembler and cross-linker available, you should
1824 install them now.  Put them in the directory
1825 @file{/usr/local/@var{target}/bin}.  Here is a table of the tools
1826 you should put in this directory:
1827
1828 @table @file
1829 @item as
1830 This should be the cross-assembler.
1831
1832 @item ld
1833 This should be the cross-linker.
1834
1835 @item ar
1836 This should be the cross-archiver: a program which can manipulate
1837 archive files (linker libraries) in the target machine's format.
1838
1839 @item ranlib
1840 This should be a program to construct a symbol table in an archive file.
1841 @end table
1842
1843 The installation of GNU CC will find these programs in that directory,
1844 and copy or link them to the proper place to for the cross-compiler to
1845 find them when run later.
1846
1847 The easiest way to provide these files is to build the Binutils package
1848 and GAS.  Configure them with the same @samp{--host} and @samp{--target}
1849 options that you use for configuring GNU CC, then build and install
1850 them.  They install their executables automatically into the proper
1851 directory.  Alas, they do not support all the targets that GNU CC
1852 supports.
1853
1854 If you want to install libraries to use with the cross-compiler, such as
1855 a standard C library, put them in the directory
1856 @file{/usr/local/@var{target}/lib}; installation of GNU CC copies
1857 all the files in that subdirectory into the proper place for GNU CC to
1858 find them and link with them.  Here's an example of copying some
1859 libraries from a target machine:
1860
1861 @example
1862 ftp @var{target-machine}
1863 lcd /usr/local/@var{target}/lib
1864 cd /lib
1865 get libc.a
1866 cd /usr/lib
1867 get libg.a
1868 get libm.a
1869 quit
1870 @end example
1871
1872 @noindent
1873 The precise set of libraries you'll need, and their locations on
1874 the target machine, vary depending on its operating system.
1875
1876 @cindex start files
1877 Many targets require ``start files'' such as @file{crt0.o} and
1878 @file{crtn.o} which are linked into each executable; these too should be
1879 placed in @file{/usr/local/@var{target}/lib}.  There may be several
1880 alternatives for @file{crt0.o}, for use with profiling or other
1881 compilation options.  Check your target's definition of
1882 @code{STARTFILE_SPEC} to find out what start files it uses.
1883 Here's an example of copying these files from a target machine:
1884
1885 @example
1886 ftp @var{target-machine}
1887 lcd /usr/local/@var{target}/lib
1888 prompt
1889 cd /lib
1890 mget *crt*.o
1891 cd /usr/lib
1892 mget *crt*.o
1893 quit
1894 @end example
1895
1896 @node Cross Runtime
1897 @subsection @file{libgcc.a} and Cross-Compilers
1898
1899 Code compiled by GNU CC uses certain runtime support functions
1900 implicitly.  Some of these functions can be compiled successfully with
1901 GNU CC itself, but a few cannot be.  These problem functions are in the
1902 source file @file{libgcc1.c}; the library made from them is called
1903 @file{libgcc1.a}.
1904
1905 When you build a native compiler, these functions are compiled with some
1906 other compiler--the one that you use for bootstrapping GNU CC.
1907 Presumably it knows how to open code these operations, or else knows how
1908 to call the run-time emulation facilities that the machine comes with.
1909 But this approach doesn't work for building a cross-compiler.  The
1910 compiler that you use for building knows about the host system, not the
1911 target system.
1912
1913 So, when you build a cross-compiler you have to supply a suitable
1914 library @file{libgcc1.a} that does the job it is expected to do.
1915
1916 To compile @file{libgcc1.c} with the cross-compiler itself does not
1917 work.  The functions in this file are supposed to implement arithmetic
1918 operations that GNU CC does not know how to open code for your target
1919 machine.  If these functions are compiled with GNU CC itself, they
1920 will compile into infinite recursion.
1921
1922 On any given target, most of these functions are not needed.  If GNU CC
1923 can open code an arithmetic operation, it will not call these functions
1924 to perform the operation.  It is possible that on your target machine,
1925 none of these functions is needed.  If so, you can supply an empty
1926 library as @file{libgcc1.a}.
1927
1928 Many targets need library support only for multiplication and division.
1929 If you are linking with a library that contains functions for
1930 multiplication and division, you can tell GNU CC to call them directly
1931 by defining the macros @code{MULSI3_LIBCALL}, and the like.  These
1932 macros need to be defined in the target description macro file.  For
1933 some targets, they are defined already.  This may be sufficient to
1934 avoid the need for libgcc1.a; if so, you can supply an empty library.
1935
1936 Some targets do not have floating point instructions; they need other
1937 functions in @file{libgcc1.a}, which do floating arithmetic.
1938 Recent versions of GNU CC have a file which emulates floating point.
1939 With a certain amount of work, you should be able to construct a
1940 floating point emulator that can be used as @file{libgcc1.a}.  Perhaps
1941 future versions will contain code to do this automatically and
1942 conveniently.  That depends on whether someone wants to implement it.
1943
1944 Some embedded targets come with all the necessary @file{libgcc1.a}
1945 routines written in C or assembler.  These targets build
1946 @file{libgcc1.a} automatically and you do not need to do anything
1947 special for them.  Other embedded targets do not need any
1948 @file{libgcc1.a} routines since all the necessary operations are
1949 supported by the hardware.
1950
1951 If your target system has another C compiler, you can configure GNU CC
1952 as a native compiler on that machine, build just @file{libgcc1.a} with
1953 @samp{make libgcc1.a} on that machine, and use the resulting file with
1954 the cross-compiler.  To do this, execute the following on the target
1955 machine:
1956
1957 @example
1958 cd @var{target-build-dir}
1959 ./configure --host=sparc --target=sun3
1960 make libgcc1.a
1961 @end example
1962
1963 @noindent
1964 And then this on the host machine:
1965
1966 @example
1967 ftp @var{target-machine}
1968 binary
1969 cd @var{target-build-dir}
1970 get libgcc1.a
1971 quit
1972 @end example
1973
1974 Another way to provide the functions you need in @file{libgcc1.a} is to
1975 define the appropriate @code{perform_@dots{}} macros for those
1976 functions.  If these definitions do not use the C arithmetic operators
1977 that they are meant to implement, you should be able to compile them
1978 with the cross-compiler you are building.  (If these definitions already
1979 exist for your target file, then you are all set.)
1980
1981 To build @file{libgcc1.a} using the perform macros, use
1982 @samp{LIBGCC1=libgcc1.a OLDCC=./xgcc} when building the compiler.
1983 Otherwise, you should place your replacement library under the name
1984 @file{libgcc1.a} in the directory in which you will build the
1985 cross-compiler, before you run @code{make}.
1986
1987 @node Cross Headers
1988 @subsection Cross-Compilers and Header Files
1989
1990 If you are cross-compiling a standalone program or a program for an
1991 embedded system, then you may not need any header files except the few
1992 that are part of GNU CC (and those of your program).  However, if you
1993 intend to link your program with a standard C library such as
1994 @file{libc.a}, then you probably need to compile with the header files
1995 that go with the library you use.
1996
1997 The GNU C compiler does not come with these files, because (1) they are
1998 system-specific, and (2) they belong in a C library, not in a compiler.
1999
2000 If the GNU C library supports your target machine, then you can get the
2001 header files from there (assuming you actually use the GNU library when
2002 you link your program).
2003
2004 If your target machine comes with a C compiler, it probably comes with
2005 suitable header files also.  If you make these files accessible from the host
2006 machine, the cross-compiler can use them also.
2007
2008 Otherwise, you're on your own in finding header files to use when
2009 cross-compiling.
2010
2011 When you have found suitable header files, put them in the directory
2012 @file{/usr/local/@var{target}/include}, before building the cross
2013 compiler.  Then installation will run fixincludes properly and install
2014 the corrected versions of the header files where the compiler will use
2015 them.
2016
2017 Provide the header files before you build the cross-compiler, because
2018 the build stage actually runs the cross-compiler to produce parts of
2019 @file{libgcc.a}.  (These are the parts that @emph{can} be compiled with
2020 GNU CC.)  Some of them need suitable header files.
2021
2022 Here's an example showing how to copy the header files from a target
2023 machine.  On the target machine, do this:
2024
2025 @example
2026 (cd /usr/include; tar cf - .) > tarfile
2027 @end example
2028
2029 Then, on the host machine, do this:
2030
2031 @example
2032 ftp @var{target-machine}
2033 lcd /usr/local/@var{target}/include
2034 get tarfile
2035 quit
2036 tar xf tarfile
2037 @end example
2038
2039 @node Build Cross
2040 @subsection Actually Building the Cross-Compiler
2041
2042 Now you can proceed just as for compiling a single-machine compiler
2043 through the step of building stage 1.  If you have not provided some
2044 sort of @file{libgcc1.a}, then compilation will give up at the point
2045 where it needs that file, printing a suitable error message.  If you
2046 do provide @file{libgcc1.a}, then building the compiler will automatically
2047 compile and link a test program called @file{libgcc1-test}; if you get
2048 errors in the linking, it means that not all of the necessary routines
2049 in @file{libgcc1.a} are available.
2050
2051 You must provide the header file @file{float.h}.  One way to do this is
2052 to compile @file{enquire} and run it on your target machine.  The job of
2053 @file{enquire} is to run on the target machine and figure out by
2054 experiment the nature of its floating point representation.
2055 @file{enquire} records its findings in the header file @file{float.h}.
2056 If you can't produce this file by running @file{enquire} on the target
2057 machine, then you will need to come up with a suitable @file{float.h} in
2058 some other way (or else, avoid using it in your programs).
2059
2060 Do not try to build stage 2 for a cross-compiler.  It doesn't work to
2061 rebuild GNU CC as a cross-compiler using the cross-compiler, because
2062 that would produce a program that runs on the target machine, not on the
2063 host.  For example, if you compile a 386-to-68030 cross-compiler with
2064 itself, the result will not be right either for the 386 (because it was
2065 compiled into 68030 code) or for the 68030 (because it was configured
2066 for a 386 as the host).  If you want to compile GNU CC into 68030 code,
2067 whether you compile it on a 68030 or with a cross-compiler on a 386, you
2068 must specify a 68030 as the host when you configure it.
2069
2070 To install the cross-compiler, use @samp{make install}, as usual.
2071
2072 @node Sun Install
2073 @section Installing GNU CC on the Sun
2074 @cindex Sun installation
2075 @cindex installing GNU CC on the Sun
2076
2077 On Solaris, do not use the linker or other tools in
2078 @file{/usr/ucb} to build GNU CC.  Use @code{/usr/ccs/bin}.
2079
2080 If the assembler reports @samp{Error: misaligned data} when bootstrapping,
2081 you are probably using an obsolete version of the GNU assembler.  Upgrade
2082 to the latest version of GNU @code{binutils}, or use the Solaris assembler.
2083
2084 Make sure the environment variable @code{FLOAT_OPTION} is not set when
2085 you compile @file{libgcc.a}.  If this option were set to @code{f68881}
2086 when @file{libgcc.a} is compiled, the resulting code would demand to be
2087 linked with a special startup file and would not link properly without
2088 special pains.
2089
2090 @cindex @code{alloca}, for SunOS
2091 There is a bug in @code{alloca} in certain versions of the Sun library.
2092 To avoid this bug, install the binaries of GNU CC that were compiled by
2093 GNU CC.  They use @code{alloca} as a built-in function and never the one
2094 in the library.
2095
2096 Some versions of the Sun compiler crash when compiling GNU CC.  The
2097 problem is a segmentation fault in cpp.  This problem seems to be due to
2098 the bulk of data in the environment variables.  You may be able to avoid
2099 it by using the following command to compile GNU CC with Sun CC:
2100
2101 @example
2102 make CC="TERMCAP=x OBJS=x LIBFUNCS=x STAGESTUFF=x cc"
2103 @end example
2104
2105 SunOS 4.1.3 and 4.1.3_U1 have bugs that can cause intermittent core
2106 dumps when compiling GNU CC.  A common symptom is an
2107 internal compiler error which does not recur if you run it again.
2108 To fix the problem, install Sun recommended patch 100726 (for SunOS 4.1.3)
2109 or 101508 (for SunOS 4.1.3_U1), or upgrade to a later SunOS release.
2110
2111 @node VMS Install
2112 @section Installing GNU CC on VMS
2113 @cindex VMS installation
2114 @cindex installing GNU CC on VMS
2115
2116 The VMS version of GNU CC is distributed in a backup saveset containing
2117 both source code and precompiled binaries.
2118
2119 To install the @file{gcc} command so you can use the compiler easily, in
2120 the same manner as you use the VMS C compiler, you must install the VMS CLD
2121 file for GNU CC as follows:
2122
2123 @enumerate
2124 @item
2125 Define the VMS logical names @samp{GNU_CC} and @samp{GNU_CC_INCLUDE}
2126 to point to the directories where the GNU CC executables
2127 (@file{gcc-cpp.exe}, @file{gcc-cc1.exe}, etc.) and the C include files are
2128 kept respectively.  This should be done with the commands:@refill
2129
2130 @smallexample
2131 $ assign /system /translation=concealed -
2132   disk:[gcc.] gnu_cc
2133 $ assign /system /translation=concealed -
2134   disk:[gcc.include.] gnu_cc_include
2135 @end smallexample
2136
2137 @noindent
2138 with the appropriate disk and directory names.  These commands can be
2139 placed in your system startup file so they will be executed whenever
2140 the machine is rebooted.  You may, if you choose, do this via the
2141 @file{GCC_INSTALL.COM} script in the @file{[GCC]} directory.
2142
2143 @item
2144 Install the @file{GCC} command with the command line:
2145
2146 @smallexample
2147 $ set command /table=sys$common:[syslib]dcltables -
2148   /output=sys$common:[syslib]dcltables gnu_cc:[000000]gcc
2149 $ install replace sys$common:[syslib]dcltables
2150 @end smallexample
2151
2152 @item
2153 To install the help file, do the following:
2154
2155 @smallexample
2156 $ library/help sys$library:helplib.hlb gcc.hlp
2157 @end smallexample
2158
2159 @noindent
2160 Now you can invoke the compiler with a command like @samp{gcc /verbose
2161 file.c}, which is equivalent to the command @samp{gcc -v -c file.c} in
2162 Unix.
2163 @end enumerate
2164
2165 If you wish to use GNU C++ you must first install GNU CC, and then
2166 perform the following steps:
2167
2168 @enumerate
2169 @item
2170 Define the VMS logical name @samp{GNU_GXX_INCLUDE} to point to the
2171 directory where the preprocessor will search for the C++ header files.
2172 This can be done with the command:@refill
2173
2174 @smallexample
2175 $ assign /system /translation=concealed -
2176   disk:[gcc.gxx_include.] gnu_gxx_include
2177 @end smallexample
2178
2179 @noindent
2180 with the appropriate disk and directory name.  If you are going to be
2181 using a C++ runtime library, this is where its install procedure will install
2182 its header files.
2183
2184 @item
2185 Obtain the file @file{gcc-cc1plus.exe}, and place this in the same
2186 directory that @file{gcc-cc1.exe} is kept.
2187
2188 The GNU C++ compiler can be invoked with a command like @samp{gcc /plus
2189 /verbose file.cc}, which is equivalent to the command @samp{g++ -v -c
2190 file.cc} in Unix.
2191 @end enumerate
2192
2193 We try to put corresponding binaries and sources on the VMS distribution
2194 tape.  But sometimes the binaries will be from an older version than the
2195 sources, because we don't always have time to update them.  (Use the
2196 @samp{/version} option to determine the version number of the binaries and
2197 compare it with the source file @file{version.c} to tell whether this is
2198 so.)  In this case, you should use the binaries you get to recompile the
2199 sources.  If you must recompile, here is how:
2200
2201 @enumerate
2202 @item
2203 Execute the command procedure @file{vmsconfig.com} to set up the files
2204 @file{tm.h}, @file{config.h}, @file{aux-output.c}, and @file{md.}, and
2205 to create files @file{tconfig.h} and @file{hconfig.h}.  This procedure
2206 also creates several linker option files used by @file{make-cc1.com} and
2207 a data file used by @file{make-l2.com}.@refill
2208
2209 @smallexample
2210 $ @@vmsconfig.com
2211 @end smallexample
2212
2213 @item
2214 Setup the logical names and command tables as defined above.  In
2215 addition, define the VMS logical name @samp{GNU_BISON} to point at the
2216 to the directories where the Bison executable is kept.  This should be
2217 done with the command:@refill
2218
2219 @smallexample
2220 $ assign /system /translation=concealed -
2221   disk:[bison.] gnu_bison
2222 @end smallexample
2223
2224 You may, if you choose, use the @file{INSTALL_BISON.COM} script in the
2225 @file{[BISON]} directory.
2226
2227 @item
2228 Install the @samp{BISON} command with the command line:@refill
2229
2230 @smallexample
2231 $ set command /table=sys$common:[syslib]dcltables -
2232   /output=sys$common:[syslib]dcltables -
2233   gnu_bison:[000000]bison
2234 $ install replace sys$common:[syslib]dcltables
2235 @end smallexample
2236
2237 @item
2238 Type @samp{@@make-gcc} to recompile everything (alternatively, submit
2239 the file @file{make-gcc.com} to a batch queue).  If you wish to build
2240 the GNU C++ compiler as well as the GNU CC compiler, you must first edit
2241 @file{make-gcc.com} and follow the instructions that appear in the
2242 comments.@refill
2243
2244 @item
2245 In order to use GCC, you need a library of functions which GCC compiled code
2246 will call to perform certain tasks, and these functions are defined in the
2247 file @file{libgcc2.c}.  To compile this you should use the command procedure
2248 @file{make-l2.com}, which will generate the library @file{libgcc2.olb}.
2249 @file{libgcc2.olb} should be built using the compiler built from
2250 the same distribution that @file{libgcc2.c} came from, and
2251 @file{make-gcc.com} will automatically do all of this for you.
2252
2253 To install the library, use the following commands:@refill
2254
2255 @smallexample
2256 $ library gnu_cc:[000000]gcclib/delete=(new,eprintf)
2257 $ library gnu_cc:[000000]gcclib/delete=L_*
2258 $ library libgcc2/extract=*/output=libgcc2.obj
2259 $ library gnu_cc:[000000]gcclib libgcc2.obj
2260 @end smallexample
2261
2262 The first command simply removes old modules that will be replaced with
2263 modules from @file{libgcc2} under different module names.  The modules
2264 @code{new} and @code{eprintf} may not actually be present in your
2265 @file{gcclib.olb}---if the VMS librarian complains about those modules
2266 not being present, simply ignore the message and continue on with the
2267 next command.  The second command removes the modules that came from the
2268 previous version of the library @file{libgcc2.c}.
2269
2270 Whenever you update the compiler on your system, you should also update the
2271 library with the above procedure.
2272
2273 @item
2274 You may wish to build GCC in such a way that no files are written to the
2275 directory where the source files reside.  An example would be the when
2276 the source files are on a read-only disk.  In these cases, execute the
2277 following DCL commands (substituting your actual path names):
2278
2279 @smallexample
2280 $ assign dua0:[gcc.build_dir.]/translation=concealed, -
2281          dua1:[gcc.source_dir.]/translation=concealed  gcc_build
2282 $ set default gcc_build:[000000]
2283 @end smallexample
2284
2285 @noindent
2286 where the directory @file{dua1:[gcc.source_dir]} contains the source
2287 code, and the directory @file{dua0:[gcc.build_dir]} is meant to contain
2288 all of the generated object files and executables.  Once you have done
2289 this, you can proceed building GCC as described above.  (Keep in mind
2290 that @file{gcc_build} is a rooted logical name, and thus the device
2291 names in each element of the search list must be an actual physical
2292 device name rather than another rooted logical name).
2293
2294 @item
2295 @strong{If you are building GNU CC with a previous version of GNU CC,
2296 you also should check to see that you have the newest version of the
2297 assembler}.  In particular, GNU CC version 2 treats global constant
2298 variables slightly differently from GNU CC version 1, and GAS version
2299 1.38.1 does not have the patches required to work with GCC version 2.
2300 If you use GAS 1.38.1, then @code{extern const} variables will not have
2301 the read-only bit set, and the linker will generate warning messages
2302 about mismatched psect attributes for these variables.  These warning
2303 messages are merely a nuisance, and can safely be ignored.
2304
2305 If you are compiling with a version of GNU CC older than 1.33, specify
2306 @samp{/DEFINE=("inline=")} as an option in all the compilations.  This
2307 requires editing all the @code{gcc} commands in @file{make-cc1.com}.
2308 (The older versions had problems supporting @code{inline}.)  Once you
2309 have a working 1.33 or newer GNU CC, you can change this file back.
2310
2311 @item
2312 If you want to build GNU CC with the VAX C compiler, you will need to
2313 make minor changes in @file{make-cccp.com} and @file{make-cc1.com}
2314 to choose alternate definitions of @code{CC}, @code{CFLAGS}, and
2315 @code{LIBS}.  See comments in those files.  However, you must
2316 also have a working version of the GNU assembler (GNU as, aka GAS) as
2317 it is used as the back-end for GNU CC to produce binary object modules
2318 and is not included in the GNU CC sources.  GAS is also needed to
2319 compile @file{libgcc2} in order to build @file{gcclib} (see above);
2320 @file{make-l2.com} expects to be able to find it operational in
2321 @file{gnu_cc:[000000]gnu-as.exe}.
2322
2323 To use GNU CC on VMS, you need the VMS driver programs
2324 @file{gcc.exe}, @file{gcc.com}, and @file{gcc.cld}.  They are
2325 distributed with the VMS binaries (@file{gcc-vms}) rather than the
2326 GNU CC sources.  GAS is also included in @file{gcc-vms}, as is Bison.
2327
2328 Once you have successfully built GNU CC with VAX C, you should use the
2329 resulting compiler to rebuild itself.  Before doing this, be sure to
2330 restore the @code{CC}, @code{CFLAGS}, and @code{LIBS} definitions in
2331 @file{make-cccp.com} and @file{make-cc1.com}.  The second generation
2332 compiler will be able to take advantage of many optimizations that must
2333 be suppressed when building with other compilers.
2334 @end enumerate
2335
2336 Under previous versions of GNU CC, the generated code would occasionally
2337 give strange results when linked with the sharable @file{VAXCRTL} library.
2338 Now this should work.
2339
2340 Even with this version, however, GNU CC itself should not be linked with
2341 the sharable @file{VAXCRTL}.  The version of @code{qsort} in
2342 @file{VAXCRTL} has a bug (known to be present in VMS versions V4.6
2343 through V5.5) which causes the compiler to fail.
2344
2345 The executables are generated by @file{make-cc1.com} and
2346 @file{make-cccp.com} use the object library version of @file{VAXCRTL} in
2347 order to make use of the @code{qsort} routine in @file{gcclib.olb}.  If
2348 you wish to link the compiler executables with the shareable image
2349 version of @file{VAXCRTL}, you should edit the file @file{tm.h} (created
2350 by @file{vmsconfig.com}) to define the macro @code{QSORT_WORKAROUND}.
2351
2352 @code{QSORT_WORKAROUND} is always defined when GNU CC is compiled with
2353 VAX C, to avoid a problem in case @file{gcclib.olb} is not yet
2354 available.
2355
2356 @node Collect2
2357 @section @code{collect2}
2358
2359 GNU CC uses a utility called @code{collect2} on nearly all systems to arrange
2360 to call various initialization functions at start time.
2361
2362 The program @code{collect2} works by linking the program once and
2363 looking through the linker output file for symbols with particular names
2364 indicating they are constructor functions.  If it finds any, it
2365 creates a new temporary @samp{.c} file containing a table of them,
2366 compiles it, and links the program a second time including that file.
2367
2368 @findex __main
2369 @cindex constructors, automatic calls
2370 The actual calls to the constructors are carried out by a subroutine
2371 called @code{__main}, which is called (automatically) at the beginning
2372 of the body of @code{main} (provided @code{main} was compiled with GNU
2373 CC).  Calling @code{__main} is necessary, even when compiling C code, to
2374 allow linking C and C++ object code together.  (If you use
2375 @samp{-nostdlib}, you get an unresolved reference to @code{__main},
2376 since it's defined in the standard GCC library.  Include @samp{-lgcc} at
2377 the end of your compiler command line to resolve this reference.)
2378
2379 The program @code{collect2} is installed as @code{ld} in the directory
2380 where the passes of the compiler are installed.  When @code{collect2}
2381 needs to find the @emph{real} @code{ld}, it tries the following file
2382 names:
2383
2384 @itemize @bullet
2385 @item
2386 @file{real-ld} in the directories listed in the compiler's search
2387 directories.
2388
2389 @item
2390 @file{real-ld} in the directories listed in the environment variable
2391 @code{PATH}.
2392
2393 @item
2394 The file specified in the @code{REAL_LD_FILE_NAME} configuration macro,
2395 if specified.
2396
2397 @item
2398 @file{ld} in the compiler's search directories, except that
2399 @code{collect2} will not execute itself recursively.
2400
2401 @item
2402 @file{ld} in @code{PATH}.
2403 @end itemize
2404
2405 ``The compiler's search directories'' means all the directories where
2406 @code{gcc} searches for passes of the compiler.  This includes
2407 directories that you specify with @samp{-B}.
2408
2409 Cross-compilers search a little differently:
2410
2411 @itemize @bullet
2412 @item
2413 @file{real-ld} in the compiler's search directories.
2414
2415 @item
2416 @file{@var{target}-real-ld} in @code{PATH}.
2417
2418 @item
2419 The file specified in the @code{REAL_LD_FILE_NAME} configuration macro,
2420 if specified.
2421
2422 @item
2423 @file{ld} in the compiler's search directories.
2424
2425 @item
2426 @file{@var{target}-ld} in @code{PATH}.
2427 @end itemize
2428
2429 @code{collect2} explicitly avoids running @code{ld} using the file name
2430 under which @code{collect2} itself was invoked.  In fact, it remembers
2431 up a list of such names---in case one copy of @code{collect2} finds
2432 another copy (or version) of @code{collect2} installed as @code{ld} in a
2433 second place in the search path.
2434
2435 @code{collect2} searches for the utilities @code{nm} and @code{strip}
2436 using the same algorithm as above for @code{ld}.
2437
2438 @node Header Dirs
2439 @section Standard Header File Directories
2440
2441 @code{GCC_INCLUDE_DIR} means the same thing for native and cross.  It is
2442 where GNU CC stores its private include files, and also where GNU CC
2443 stores the fixed include files.  A cross compiled GNU CC runs
2444 @code{fixincludes} on the header files in @file{$(tooldir)/include}.
2445 (If the cross compilation header files need to be fixed, they must be
2446 installed before GNU CC is built.  If the cross compilation header files
2447 are already suitable for ANSI C and GNU CC, nothing special need be
2448 done).
2449
2450 @code{GPLUSPLUS_INCLUDE_DIR} means the same thing for native and cross.  It
2451 is where @code{g++} looks first for header files.  The C++ library
2452 installs only target independent header files in that directory.
2453
2454 @code{LOCAL_INCLUDE_DIR} is used only for a native compiler.  It is
2455 normally @file{/usr/local/include}.  GNU CC searches this directory so
2456 that users can install header files in @file{/usr/local/include}.
2457
2458 @code{CROSS_INCLUDE_DIR} is used only for a cross compiler.  GNU CC
2459 doesn't install anything there.
2460
2461 @code{TOOL_INCLUDE_DIR} is used for both native and cross compilers.  It
2462 is the place for other packages to install header files that GNU CC will
2463 use.  For a cross-compiler, this is the equivalent of
2464 @file{/usr/include}.  When you build a cross-compiler,
2465 @code{fixincludes} processes any header files in this directory.