1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
2 @c This is part of the GCC manual.
3 @c For copying conditions, see the file gcc.texi.
6 @chapter Installing GNU CC
7 @cindex installing GNU CC
9 Note most of this information is out of date and superseded by the
10 new GCC install manual @file{gcc/doc/install.texi}. It is
11 provided for historical reference only.
14 * Configurations:: Configurations Supported by GNU CC.
15 * Cross-Compiler:: Building and installing a cross-compiler.
16 * VMS Install:: See below for installation on VMS.
19 Here is the procedure for installing GNU CC on a GNU or Unix system.
20 See @ref{VMS Install}, for VMS systems.
24 If you have chosen a configuration for GNU CC which requires other GNU
25 tools (such as GAS or the GNU linker) instead of the standard system
26 tools, install the required tools in the build directory under the names
27 @file{as}, @file{ld} or whatever is appropriate. This will enable the
28 compiler to find the proper tools for compilation of the program
31 Alternatively, you can do subsequent compilation using a value of the
32 @code{PATH} environment variable such that the necessary GNU tools come
33 before the standard system tools.
36 Specify the host, build and target machine configurations. You do this
37 when you run the @file{configure} script.
39 The @dfn{build} machine is the system which you are using, the
40 @dfn{host} machine is the system where you want to run the resulting
41 compiler (normally the build machine), and the @dfn{target} machine is
42 the system for which you want the compiler to generate code.
44 If you are building a compiler to produce code for the machine it runs
45 on (a native compiler), you normally do not need to specify any operands
46 to @file{configure}; it will try to guess the type of machine you are on
47 and use that as the build, host and target machines. So you don't need
48 to specify a configuration when building a native compiler unless
49 @file{configure} cannot figure out what your configuration is or guesses
52 In those cases, specify the build machine's @dfn{configuration name}
53 with the @option{--host} option; the host and target will default to be
54 the same as the host machine. (If you are building a cross-compiler,
55 see @ref{Cross-Compiler}.)
60 ./configure --host=sparc-sun-sunos4.1
63 A configuration name may be canonical or it may be more or less
66 A canonical configuration name has three parts, separated by dashes.
67 It looks like this: @samp{@var{cpu}-@var{company}-@var{system}}.
68 (The three parts may themselves contain dashes; @file{configure}
69 can figure out which dashes serve which purpose.) For example,
70 @samp{m68k-sun-sunos4.1} specifies a Sun 3.
72 You can also replace parts of the configuration by nicknames or aliases.
73 For example, @samp{sun3} stands for @samp{m68k-sun}, so
74 @samp{sun3-sunos4.1} is another way to specify a Sun 3.
76 You can specify a version number after any of the system types, and some
77 of the CPU types. In most cases, the version is irrelevant, and will be
78 ignored. So you might as well specify the version if you know it.
80 See @ref{Configurations}, for a list of supported configuration names and
81 notes on many of the configurations. You should check the notes in that
82 section before proceeding any further with the installation of GNU CC@.
87 @section Configurations Supported by GNU CC
88 @cindex configurations supported by GNU CC
90 Here are the possible CPU types:
93 @c gmicro, fx80, spur and tahoe omitted since they don't work.
94 1750a, a29k, alpha, arm, avr, c@var{n}, clipper, dsp16xx, elxsi, fr30, h8300,
95 hppa1.0, hppa1.1, i370, i386, i486, i586, i686, i786, i860, i960, m32r,
96 m68000, m68k, m6811, m6812, m88k, mcore, mips, mipsel, mips64, mips64el,
97 mn10200, mn10300, ns32k, pdp11, powerpc, powerpcle, romp, rs6000, sh, sparc,
98 sparclite, sparc64, v850, vax, we32k.
101 Here are the recognized company names. As you can see, customary
102 abbreviations are used rather than the longer official names.
104 @c What should be done about merlin, tek*, dolphin?
106 acorn, alliant, altos, apollo, apple, att, bull,
107 cbm, convergent, convex, crds, dec, dg, dolphin,
108 elxsi, encore, harris, hitachi, hp, ibm, intergraph, isi,
109 mips, motorola, ncr, next, ns, omron, plexus,
110 sequent, sgi, sony, sun, tti, unicom, wrs.
113 The company name is meaningful only to disambiguate when the rest of
114 the information supplied is insufficient. You can omit it, writing
115 just @samp{@var{cpu}-@var{system}}, if it is not needed. For example,
116 @samp{vax-ultrix4.2} is equivalent to @samp{vax-dec-ultrix4.2}.
118 Here is a list of system types:
121 386bsd, aix, acis, amigaos, aos, aout, aux, bosx, bsd, clix, coff, ctix, cxux,
122 dgux, dynix, ebmon, ecoff, elf, esix, freebsd, hms, genix, gnu, linux,
123 linux-gnu, hiux, hpux, iris, irix, isc, luna, lynxos, mach, minix, msdos, mvs,
124 netbsd, newsos, nindy, ns, osf, osfrose, ptx, riscix, riscos, rtu, sco, sim,
125 solaris, sunos, sym, sysv, udi, ultrix, unicos, uniplus, unos, vms, vsta,
126 vxworks, winnt, xenix.
130 You can omit the system type; then @file{configure} guesses the
131 operating system from the CPU and company.
133 You can add a version number to the system type; this may or may not
134 make a difference. For example, you can write @samp{bsd4.3} or
135 @samp{bsd4.4} to distinguish versions of BSD@. In practice, the version
136 number is most needed for @samp{sysv3} and @samp{sysv4}, which are often
139 @samp{linux-gnu} is the canonical name for the GNU/Linux target; however
140 GNU CC will also accept @samp{linux}. The version of the kernel in use is
141 not relevant on these systems. A suffix such as @samp{libc1} or @samp{aout}
142 distinguishes major versions of the C library; all of the suffixed versions
145 If you specify an impossible combination such as @samp{i860-dg-vms},
146 then you may get an error message from @file{configure}, or it may
147 ignore part of the information and do the best it can with the rest.
148 @file{configure} always prints the canonical name for the alternative
149 that it used. GNU CC does not support all possible alternatives.
151 Often a particular model of machine has a name. Many machine names are
152 recognized as aliases for CPU/company combinations. Thus, the machine
153 name @samp{sun3}, mentioned above, is an alias for @samp{m68k-sun}.
154 Sometimes we accept a company name as a machine name, when the name is
155 popularly used for a particular machine. Here is a table of the known
159 3300, 3b1, 3b@var{n}, 7300, altos3068, altos,
160 apollo68, att-7300, balance,
161 convex-c@var{n}, crds, decstation-3100,
162 decstation, delta, encore,
163 fx2800, gmicro, hp7@var{nn}, hp8@var{nn},
164 hp9k2@var{nn}, hp9k3@var{nn}, hp9k7@var{nn},
165 hp9k8@var{nn}, iris4d, iris, isi68,
166 m3230, magnum, merlin, miniframe,
167 mmax, news-3600, news800, news, next,
168 pbd, pc532, pmax, powerpc, powerpcle, ps2, risc-news,
169 rtpc, sun2, sun386i, sun386, sun3,
170 sun4, symmetry, tower-32, tower.
174 Remember that a machine name specifies both the cpu type and the company
176 If you want to install your own homemade configuration files, you can
177 use @samp{local} as the company name to access them. If you use
178 configuration @samp{@var{cpu}-local}, the configuration name
179 without the cpu prefix
180 is used to form the configuration file names.
182 Thus, if you specify @samp{m68k-local}, configuration uses
183 files @file{m68k.md}, @file{local.h}, @file{m68k.c},
184 @file{xm-local.h}, @file{t-local}, and @file{x-local}, all in the
185 directory @file{config/m68k}.
187 Here is a list of configurations that have special treatment or special
188 things you must know:
192 See @ref{VMS Install}, for details on how to install GNU CC on VMS@.
196 @section Building and Installing a Cross-Compiler
197 @cindex cross-compiler, installation
199 GNU CC can function as a cross-compiler for many machines, but not all.
203 Cross-compilers for the Mips as target using the Mips assembler
204 currently do not work, because the auxiliary programs
205 @file{mips-tdump.c} and @file{mips-tfile.c} can't be compiled on
206 anything but a Mips. It does work to cross compile for a Mips
207 if you use the GNU assembler and linker.
210 Cross-compilers between machines with different floating point formats
211 have not all been made to work. GNU CC now has a floating point
212 emulator with which these can work, but each target machine description
213 needs to be updated to take advantage of it.
216 Cross-compilation between machines of different word sizes is
217 somewhat problematic and sometimes does not work.
220 Since GNU CC generates assembler code, you probably need a
221 cross-assembler that GNU CC can run, in order to produce object files.
222 If you want to link on other than the target machine, you need a
223 cross-linker as well. You also need header files and libraries suitable
224 for the target machine that you can install on the host machine.
227 * Steps of Cross:: Using a cross-compiler involves several steps
228 that may be carried out on different machines.
229 * Configure Cross:: Configuring a cross-compiler.
230 * Tools and Libraries:: Where to put the linker and assembler, and the C library.
231 * Cross Headers:: Finding and installing header files
232 for a cross-compiler.
233 * Build Cross:: Actually compiling the cross-compiler.
237 @subsection Steps of Cross-Compilation
239 To compile and run a program using a cross-compiler involves several
244 Run the cross-compiler on the host machine to produce assembler files
245 for the target machine. This requires header files for the target
249 Assemble the files produced by the cross-compiler. You can do this
250 either with an assembler on the target machine, or with a
251 cross-assembler on the host machine.
254 Link those files to make an executable. You can do this either with a
255 linker on the target machine, or with a cross-linker on the host
256 machine. Whichever machine you use, you need libraries and certain
257 startup files (typically @file{crt@dots{}.o}) for the target machine.
260 It is most convenient to do all of these steps on the same host machine,
261 since then you can do it all with a single invocation of GNU CC@. This
262 requires a suitable cross-assembler and cross-linker. For some targets,
263 the GNU assembler and linker are available.
265 @node Configure Cross
266 @subsection Configuring a Cross-Compiler
268 To build GNU CC as a cross-compiler, you start out by running
269 @file{configure}. Use the @option{--target=@var{target}} to specify the
270 target type. If @file{configure} was unable to correctly identify the
271 system you are running on, also specify the @option{--build=@var{build}}
272 option. For example, here is how to configure for a cross-compiler that
273 produces code for an HP 68030 system running BSD on a system that
274 @file{configure} can correctly identify:
277 ./configure --target=m68k-hp-bsd4.3
280 @node Tools and Libraries
281 @subsection Tools and Libraries for a Cross-Compiler
283 If you have a cross-assembler and cross-linker available, you should
284 install them now. Put them in the directory
285 @file{/usr/local/@var{target}/bin}. Here is a table of the tools
286 you should put in this directory:
290 This should be the cross-assembler.
293 This should be the cross-linker.
296 This should be the cross-archiver: a program which can manipulate
297 archive files (linker libraries) in the target machine's format.
300 This should be a program to construct a symbol table in an archive file.
303 The installation of GNU CC will find these programs in that directory,
304 and copy or link them to the proper place to for the cross-compiler to
305 find them when run later.
307 The easiest way to provide these files is to build the Binutils package
308 and GAS@. Configure them with the same @option{--host} and @option{--target}
309 options that you use for configuring GNU CC, then build and install
310 them. They install their executables automatically into the proper
311 directory. Alas, they do not support all the targets that GNU CC
314 If you want to install libraries to use with the cross-compiler, such as
315 a standard C library, put them in the directory
316 @file{/usr/local/@var{target}/lib}; installation of GNU CC copies
317 all the files in that subdirectory into the proper place for GNU CC to
318 find them and link with them. Here's an example of copying some
319 libraries from a target machine:
322 ftp @var{target-machine}
323 lcd /usr/local/@var{target}/lib
333 The precise set of libraries you'll need, and their locations on
334 the target machine, vary depending on its operating system.
337 Many targets require ``start files'' such as @file{crt0.o} and
338 @file{crtn.o} which are linked into each executable; these too should be
339 placed in @file{/usr/local/@var{target}/lib}. There may be several
340 alternatives for @file{crt0.o}, for use with profiling or other
341 compilation options. Check your target's definition of
342 @code{STARTFILE_SPEC} to find out what start files it uses.
343 Here's an example of copying these files from a target machine:
346 ftp @var{target-machine}
347 lcd /usr/local/@var{target}/lib
357 @subsection Cross-Compilers and Header Files
359 If you are cross-compiling a standalone program or a program for an
360 embedded system, then you may not need any header files except the few
361 that are part of GNU CC (and those of your program). However, if you
362 intend to link your program with a standard C library such as
363 @file{libc.a}, then you probably need to compile with the header files
364 that go with the library you use.
366 The GNU C compiler does not come with these files, because (1) they are
367 system-specific, and (2) they belong in a C library, not in a compiler.
369 If the GNU C library supports your target machine, then you can get the
370 header files from there (assuming you actually use the GNU library when
371 you link your program).
373 If your target machine comes with a C compiler, it probably comes with
374 suitable header files also. If you make these files accessible from the host
375 machine, the cross-compiler can use them also.
377 Otherwise, you're on your own in finding header files to use when
380 When you have found suitable header files, you should put them in the
381 directory @file{/usr/local/@var{target}/include}, before building the
382 cross compiler. Then installation will run fixincludes properly and
383 install the corrected versions of the header files where the compiler
386 Provide the header files before you build the cross-compiler, because
387 the build stage actually runs the cross-compiler to produce parts of
388 @file{libgcc.a}. (These are the parts that @emph{can} be compiled with
389 GNU CC@.) Some of them need suitable header files.
391 Here's an example showing how to copy the header files from a target
392 machine. On the target machine, do this:
395 (cd /usr/include; tar cf - .) > tarfile
398 Then, on the host machine, do this:
401 ftp @var{target-machine}
402 lcd /usr/local/@var{target}/include
409 @subsection Actually Building the Cross-Compiler
411 Now you can proceed just as for compiling a single-machine compiler
412 through the step of building stage 1.
414 If your target is exotic, you may need to provide the header file
415 @file{float.h}.One way to do this is to compile @file{enquire} and run
416 it on your target machine. The job of @file{enquire} is to run on the
417 target machine and figure out by experiment the nature of its floating
418 point representation. @file{enquire} records its findings in the header
419 file @file{float.h}. If you can't produce this file by running
420 @file{enquire} on the target machine, then you will need to come up with
421 a suitable @file{float.h} in some other way (or else, avoid using it in
424 Do not try to build stage 2 for a cross-compiler. It doesn't work to
425 rebuild GNU CC as a cross-compiler using the cross-compiler, because
426 that would produce a program that runs on the target machine, not on the
427 host. For example, if you compile a 386-to-68030 cross-compiler with
428 itself, the result will not be right either for the 386 (because it was
429 compiled into 68030 code) or for the 68030 (because it was configured
430 for a 386 as the host). If you want to compile GNU CC into 68030 code,
431 whether you compile it on a 68030 or with a cross-compiler on a 386, you
432 must specify a 68030 as the host when you configure it.
434 To install the cross-compiler, use @samp{make install}, as usual.
437 @section Installing GNU CC on VMS
438 @cindex VMS installation
439 @cindex installing GNU CC on VMS
441 The VMS version of GNU CC is distributed in a backup saveset containing
442 both source code and precompiled binaries.
444 To install the @file{gcc} command so you can use the compiler easily, in
445 the same manner as you use the VMS C compiler, you must install the VMS CLD
446 file for GNU CC as follows:
450 Define the VMS logical names @samp{GNU_CC} and @samp{GNU_CC_INCLUDE}
451 to point to the directories where the GNU CC executables
452 (@file{gcc-cpp.exe}, @file{gcc-cc1.exe}, etc.) and the C include files are
453 kept respectively. This should be done with the commands:
456 $ assign /system /translation=concealed -
458 $ assign /system /translation=concealed -
459 disk:[gcc.include.] gnu_cc_include
463 with the appropriate disk and directory names. These commands can be
464 placed in your system startup file so they will be executed whenever
465 the machine is rebooted. You may, if you choose, do this via the
466 @file{GCC_INSTALL.COM} script in the @file{[GCC]} directory.
469 Install the @file{GCC} command with the command line:
472 $ set command /table=sys$common:[syslib]dcltables -
473 /output=sys$common:[syslib]dcltables gnu_cc:[000000]gcc
474 $ install replace sys$common:[syslib]dcltables
478 To install the help file, do the following:
481 $ library/help sys$library:helplib.hlb gcc.hlp
485 Now you can invoke the compiler with a command like @samp{gcc /verbose
486 file.c}, which is equivalent to the command @samp{gcc -v -c file.c} in
490 If you wish to use GNU C++ you must first install GNU CC, and then
491 perform the following steps:
495 Define the VMS logical name @samp{GNU_GXX_INCLUDE} to point to the
496 directory where the preprocessor will search for the C++ header files.
497 This can be done with the command:
500 $ assign /system /translation=concealed -
501 disk:[gcc.gxx_include.] gnu_gxx_include
505 with the appropriate disk and directory name. If you are going to be
506 using a C++ runtime library, this is where its install procedure will install
510 Obtain the file @file{gcc-cc1plus.exe}, and place this in the same
511 directory that @file{gcc-cc1.exe} is kept.
513 The GNU C++ compiler can be invoked with a command like @samp{gcc /plus
514 /verbose file.cc}, which is equivalent to the command @samp{g++ -v -c
518 We try to put corresponding binaries and sources on the VMS distribution
519 tape. But sometimes the binaries will be from an older version than the
520 sources, because we don't always have time to update them. (Use the
521 @samp{/version} option to determine the version number of the binaries and
522 compare it with the source file @file{version.c} to tell whether this is
523 so.) In this case, you should use the binaries you get to recompile the
524 sources. If you must recompile, here is how:
528 Execute the command procedure @file{vmsconfig.com} to set up the files
529 @file{tm.h}, @file{config.h}, @file{aux-output.c}, and @file{md.}, and
530 to create files @file{tconfig.h} and @file{hconfig.h}. This procedure
531 also creates several linker option files used by @file{make-cc1.com} and
532 a data file used by @file{make-l2.com}.
539 Setup the logical names and command tables as defined above. In
540 addition, define the VMS logical name @samp{GNU_BISON} to point at the
541 to the directories where the Bison executable is kept. This should be
542 done with the command:
545 $ assign /system /translation=concealed -
546 disk:[bison.] gnu_bison
549 You may, if you choose, use the @file{INSTALL_BISON.COM} script in the
550 @file{[BISON]} directory.
553 Install the @samp{BISON} command with the command line:
556 $ set command /table=sys$common:[syslib]dcltables -
557 /output=sys$common:[syslib]dcltables -
558 gnu_bison:[000000]bison
559 $ install replace sys$common:[syslib]dcltables
563 Type @samp{@@make-gcc} to recompile everything, or submit the file
564 @file{make-gcc.com} to a batch queue. If you wish to build the GNU C++
565 compiler as well as the GNU CC compiler, you must first edit
566 @file{make-gcc.com} and follow the instructions that appear in the
570 In order to use GCC, you need a library of functions which GCC compiled code
571 will call to perform certain tasks, and these functions are defined in the
572 file @file{libgcc2.c}. To compile this you should use the command procedure
573 @file{make-l2.com}, which will generate the library @file{libgcc2.olb}.
574 @file{libgcc2.olb} should be built using the compiler built from
575 the same distribution that @file{libgcc2.c} came from, and
576 @file{make-gcc.com} will automatically do all of this for you.
578 To install the library, use the following commands:
581 $ library gnu_cc:[000000]gcclib/delete=(new,eprintf)
582 $ library gnu_cc:[000000]gcclib/delete=L_*
583 $ library libgcc2/extract=*/output=libgcc2.obj
584 $ library gnu_cc:[000000]gcclib libgcc2.obj
587 The first command simply removes old modules that will be replaced with
588 modules from @file{libgcc2} under different module names. The modules
589 @code{new} and @code{eprintf} may not actually be present in your
590 @file{gcclib.olb}---if the VMS librarian complains about those modules
591 not being present, simply ignore the message and continue on with the
592 next command. The second command removes the modules that came from the
593 previous version of the library @file{libgcc2.c}.
595 Whenever you update the compiler on your system, you should also update the
596 library with the above procedure.
599 You may wish to build GCC in such a way that no files are written to the
600 directory where the source files reside. An example would be the when
601 the source files are on a read-only disk. In these cases, execute the
602 following DCL commands (substituting your actual path names):
605 $ assign dua0:[gcc.build_dir.]/translation=concealed, -
606 dua1:[gcc.source_dir.]/translation=concealed gcc_build
607 $ set default gcc_build:[000000]
611 where the directory @file{dua1:[gcc.source_dir]} contains the source
612 code, and the directory @file{dua0:[gcc.build_dir]} is meant to contain
613 all of the generated object files and executables. Once you have done
614 this, you can proceed building GCC as described above. (Keep in mind
615 that @file{gcc_build} is a rooted logical name, and thus the device
616 names in each element of the search list must be an actual physical
617 device name rather than another rooted logical name).
620 @strong{If you are building GNU CC with a previous version of GNU CC,
621 you also should check to see that you have the newest version of the
622 assembler}. In particular, GNU CC version 2 treats global constant
623 variables slightly differently from GNU CC version 1, and GAS version
624 1.38.1 does not have the patches required to work with GCC version 2.
625 If you use GAS 1.38.1, then @code{extern const} variables will not have
626 the read-only bit set, and the linker will generate warning messages
627 about mismatched psect attributes for these variables. These warning
628 messages are merely a nuisance, and can safely be ignored.
631 If you want to build GNU CC with the VAX C compiler, you will need to
632 make minor changes in @file{make-cccp.com} and @file{make-cc1.com}
633 to choose alternate definitions of @code{CC}, @code{CFLAGS}, and
634 @code{LIBS}. See comments in those files. However, you must
635 also have a working version of the GNU assembler (GNU as, aka GAS) as
636 it is used as the back end for GNU CC to produce binary object modules
637 and is not included in the GNU CC sources. GAS is also needed to
638 compile @file{libgcc2} in order to build @file{gcclib} (see above);
639 @file{make-l2.com} expects to be able to find it operational in
640 @file{gnu_cc:[000000]gnu-as.exe}.
642 To use GNU CC on VMS, you need the VMS driver programs
643 @file{gcc.exe}, @file{gcc.com}, and @file{gcc.cld}. They are
644 distributed with the VMS binaries (@file{gcc-vms}) rather than the
645 GNU CC sources. GAS is also included in @file{gcc-vms}, as is Bison.
647 Once you have successfully built GNU CC with VAX C, you should use the
648 resulting compiler to rebuild itself. Before doing this, be sure to
649 restore the @code{CC}, @code{CFLAGS}, and @code{LIBS} definitions in
650 @file{make-cccp.com} and @file{make-cc1.com}. The second generation
651 compiler will be able to take advantage of many optimizations that must
652 be suppressed when building with other compilers.
655 Under previous versions of GNU CC, the generated code would occasionally
656 give strange results when linked with the sharable @file{VAXCRTL} library.
657 Now this should work.
659 Even with this version, however, GNU CC itself should not be linked with
660 the sharable @file{VAXCRTL}. The version of @code{qsort} in
661 @file{VAXCRTL} has a bug (known to be present in VMS versions V4.6
662 through V5.5) which causes the compiler to fail.
664 The executables are generated by @file{make-cc1.com} and
665 @file{make-cccp.com} use the object library version of @file{VAXCRTL} in
666 order to make use of the @code{qsort} routine in @file{gcclib.olb}. If
667 you wish to link the compiler executables with the shareable image
668 version of @file{VAXCRTL}, you should edit the file @file{tm.h} (created
669 by @file{vmsconfig.com}) to define the macro @code{QSORT_WORKAROUND}.
671 @code{QSORT_WORKAROUND} is always defined when GNU CC is compiled with
672 VAX C, to avoid a problem in case @file{gcclib.olb} is not yet