blob: 303e5f1e91c095f83d17cfb338690c94f6837166 [file] [log] [blame]
This is Info file, produced by Makeinfo version 1.68 from the
input file gcc.texi.
This file documents the use and the internals of the GNU compiler.
Published by the Free Software Foundation 59 Temple Place - Suite 330
Boston, MA 02111-1307 USA
Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998
Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "GNU General Public License," "Funding for
Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the sections entitled "GNU General Public
License," "Funding for Free Software," and "Protect Your Freedom--Fight
`Look And Feel'", and this permission notice, may be included in
translations approved by the Free Software Foundation instead of in the
original English.

File:, Node: Installation, Next: C Extensions, Prev: Invoking GCC, Up: Top
Installing GNU CC
* Menu:
* Configurations:: Configurations Supported by GNU CC.
* Other Dir:: Compiling in a separate directory (not where the source is).
* Cross-Compiler:: Building and installing a cross-compiler.
* Sun Install:: See below for installation on the Sun.
* VMS Install:: See below for installation on VMS.
* Collect2:: How `collect2' works; how it finds `ld'.
* Header Dirs:: Understanding the standard header file directories.
Here is the procedure for installing GNU CC on a Unix system. See
*Note VMS Install::, for VMS systems. In this section we assume you
compile in the same directory that contains the source files; see *Note
Other Dir::, to find out how to compile in a separate directory on Unix
You cannot install GNU C by itself on MSDOS; it will not compile
under any MSDOS compiler except itself. You need to get the complete
compilation package DJGPP, which includes binaries as well as sources,
and includes all the necessary compilation tools and libraries.
1. If you have built GNU CC previously in the same directory for a
different target machine, do `make distclean' to delete all files
that might be invalid. One of the files this deletes is
`Makefile'; if `make distclean' complains that `Makefile' does not
exist, it probably means that the directory is already suitably
2. On a System V release 4 system, make sure `/usr/bin' precedes
`/usr/ucb' in `PATH'. The `cc' command in `/usr/ucb' uses
libraries which have bugs.
3. Specify the host, build and target machine configurations. You do
this by running the file `configure'.
The "build" machine is the system which you are using, the "host"
machine is the system where you want to run the resulting compiler
(normally the build machine), and the "target" machine is the
system for which you want the compiler to generate code.
If you are building a compiler to produce code for the machine it
runs on (a native compiler), you normally do not need to specify
any operands to `configure'; it will try to guess the type of
machine you are on and use that as the build, host and target
machines. So you don't need to specify a configuration when
building a native compiler unless `configure' cannot figure out
what your configuration is or guesses wrong.
In those cases, specify the build machine's "configuration name"
with the `--build' option; the host and target will default to be
the same as the build machine. (If you are building a
cross-compiler, see *Note Cross-Compiler::.)
Here is an example:
./configure --build=sparc-sun-sunos4.1
A configuration name may be canonical or it may be more or less
A canonical configuration name has three parts, separated by
dashes. It looks like this: `CPU-COMPANY-SYSTEM'. (The three
parts may themselves contain dashes; `configure' can figure out
which dashes serve which purpose.) For example,
`m68k-sun-sunos4.1' specifies a Sun 3.
You can also replace parts of the configuration by nicknames or
aliases. For example, `sun3' stands for `m68k-sun', so
`sun3-sunos4.1' is another way to specify a Sun 3. You can also
use simply `sun3-sunos', since the version of SunOS is assumed by
default to be version 4.
You can specify a version number after any of the system types,
and some of the CPU types. In most cases, the version is
irrelevant, and will be ignored. So you might as well specify the
version if you know it.
See *Note Configurations::, for a list of supported configuration
names and notes on many of the configurations. You should check
the notes in that section before proceeding any further with the
installation of GNU CC.
There are four additional options you can specify independently to
describe variant hardware and software configurations. These are
`--with-gnu-as', `--with-gnu-ld', `--with-stabs' and `--nfp'.
If you will use GNU CC with the GNU assembler (GAS), you
should declare this by using the `--with-gnu-as' option when
you run `configure'.
Using this option does not install GAS. It only modifies the
output of GNU CC to work with GAS. Building and installing
GAS is up to you.
Conversely, if you *do not* wish to use GAS and do not specify
`--with-gnu-as' when building GNU CC, it is up to you to make
sure that GAS is not installed. GNU CC searches for a
program named `as' in various directories; if the program it
finds is GAS, then it runs GAS. If you are not sure where
GNU CC finds the assembler it is using, try specifying `-v'
when you run it.
The systems where it makes a difference whether you use GAS
`hppa1.0-ANY-ANY', `hppa1.1-ANY-ANY', `i386-ANY-sysv',
`i860-ANY-bsd', `m68k-bull-sysv',
`m68k-hp-hpux', `m68k-sony-bsd',
`m68k-altos-sysv', `m68000-hp-hpux',
`m68000-att-sysv', `ANY-lynx-lynxos', and `mips-ANY'). On
any other system, `--with-gnu-as' has no effect.
On the systems listed above (except for the HP-PA, for ISC on
the 386, and for `mips-sgi-irix5.*'), if you use GAS, you
should also use the GNU linker (and specify `--with-gnu-ld').
Specify the option `--with-gnu-ld' if you plan to use the GNU
linker with GNU CC.
This option does not cause the GNU linker to be installed; it
just modifies the behavior of GNU CC to work with the GNU
linker. Specifically, it inhibits the installation of
`collect2', a program which otherwise serves as a front-end
for the system's linker on most configurations.
On MIPS based systems and on Alphas, you must specify whether
you want GNU CC to create the normal ECOFF debugging format,
or to use BSD-style stabs passed through the ECOFF symbol
table. The normal ECOFF debug format cannot fully handle
languages other than C. BSD stabs format can handle other
languages, but it only works with the GNU debugger GDB.
Normally, GNU CC uses the ECOFF debugging format by default;
if you prefer BSD stabs, specify `--with-stabs' when you
configure GNU CC.
No matter which default you choose when you configure GNU CC,
the user can use the `-gcoff' and `-gstabs+' options to
specify explicitly the debug format for a particular
`--with-stabs' is meaningful on the ISC system on the 386,
also, if `--with-gas' is used. It selects use of stabs
debugging information embedded in COFF output. This kind of
debugging information supports C++ well; ordinary COFF
debugging information does not.
`--with-stabs' is also meaningful on 386 systems running
SVR4. It selects use of stabs debugging information embedded
in ELF output. The C++ compiler currently (2.6.0) does not
support the DWARF debugging information normally used on 386
SVR4 platforms; stabs provide a workable alternative. This
requires gas and gdb, as the normal SVR4 tools can not
generate or interpret stabs.
On certain systems, you must specify whether the machine has
a floating point unit. These systems include
`m68k-sun-sunosN' and `m68k-isi-bsd'. On any other system,
`--nfp' currently has no effect, though perhaps there are
other systems where it could usefully make a difference.
Certain systems, notably Linux-based GNU systems, can't be
relied on to supply a threads facility for the Objective C
runtime and so will default to single-threaded runtime. They
may, however, have a library threads implementation
available, in which case threads can be enabled with this
option by supplying a suitable TYPE, probably `posix'. The
possibilities for TYPE are `single', `posix', `win32',
`solaris', `irix' and `mach'.
The `configure' script searches subdirectories of the source
directory for other compilers that are to be integrated into GNU
CC. The GNU compiler for C++, called G++ is in a subdirectory
named `cp'. `configure' inserts rules into `Makefile' to build
all of those compilers.
Here we spell out what files will be set up by `configure'.
Normally you need not be concerned with these files.
* A file named `config.h' is created that contains a `#include'
of the top-level config file for the machine you will run the
compiler on (*note Config::.). This file is responsible for
defining information about the host machine. It includes
The top-level config file is located in the subdirectory
`config'. Its name is always `xm-SOMETHING.h'; usually
`xm-MACHINE.h', but there are some exceptions.
If your system does not support symbolic links, you might
want to set up `config.h' to contain a `#include' command
which refers to the appropriate file.
* A file named `tconfig.h' is created which includes the
top-level config file for your target machine. This is used
for compiling certain programs to run on that machine.
* A file named `tm.h' is created which includes the
machine-description macro file for your target machine. It
should be in the subdirectory `config' and its name is often
* The command file `configure' also constructs the file
`Makefile' by adding some text to the template file
`'. The additional text comes from files in the
`config' directory, named `t-TARGET' and `x-HOST'. If these
files do not exist, it means nothing needs to be added for a
given target or host.
4. The standard directory for installing GNU CC is `/usr/local/lib'.
If you want to install its files somewhere else, specify
`--prefix=DIR' when you run `configure'. Here DIR is a directory
name to use instead of `/usr/local' for all purposes with one
exception: the directory `/usr/local/include' is searched for
header files no matter where you install the compiler. To override
this name, use the `--local-prefix' option below.
5. Specify `--local-prefix=DIR' if you want the compiler to search
directory `DIR/include' for locally installed header files
*instead* of `/usr/local/include'.
You should specify `--local-prefix' *only* if your site has a
different convention (not `/usr/local') for where to put
site-specific files.
The default value for `--local-prefix' is `/usr/local' regardless
of the value of `--prefix'. Specifying `--prefix' has no effect
on which directory GNU CC searches for local header files. This
may seem counterintuitive, but actually it is logical.
The purpose of `--prefix' is to specify where to *install GNU CC*.
The local header files in `/usr/local/include'--if you put any in
that directory--are not part of GNU CC. They are part of other
programs--perhaps many others. (GNU CC installs its own header
files in another directory which is based on the `--prefix' value.)
*Do not* specify `/usr' as the `--local-prefix'! The directory
you use for `--local-prefix' *must not* contain any of the
system's standard header files. If it did contain them, certain
programs would be miscompiled (including GNU Emacs, on certain
targets), because this would override and nullify the header file
corrections made by the `fixincludes' script.
Indications are that people who use this option use it based on
mistaken ideas of what it is for. People use it as if it specified
where to install part of GNU CC. Perhaps they make this assumption
because installing GNU CC creates the directory.
6. Make sure the Bison parser generator is installed. (This is
unnecessary if the Bison output files `c-parse.c' and `cexp.c' are
more recent than `c-parse.y' and `cexp.y' and you do not plan to
change the `.y' files.)
Bison versions older than Sept 8, 1988 will produce incorrect
output for `c-parse.c'.
7. If you have chosen a configuration for GNU CC which requires other
GNU tools (such as GAS or the GNU linker) instead of the standard
system tools, install the required tools in the build directory
under the names `as', `ld' or whatever is appropriate. This will
enable the compiler to find the proper tools for compilation of
the program `enquire'.
Alternatively, you can do subsequent compilation using a value of
the `PATH' environment variable such that the necessary GNU tools
come before the standard system tools.
8. Build the compiler. Just type `make LANGUAGES=c' in the compiler
`LANGUAGES=c' specifies that only the C compiler should be
compiled. The makefile normally builds compilers for all the
supported languages; currently, C, C++ and Objective C. However,
C is the only language that is sure to work when you build with
other non-GNU C compilers. In addition, building anything but C
at this stage is a waste of time.
In general, you can specify the languages to build by typing the
argument `LANGUAGES="LIST"', where LIST is one or more words from
the list `c', `c++', and `objective-c'. If you have any
additional GNU compilers as subdirectories of the GNU CC source
directory, you may also specify their names in this list.
Ignore any warnings you may see about "statement not reached" in
`insn-emit.c'; they are normal. Also, warnings about "unknown
escape sequence" are normal in `genopinit.c' and perhaps some
other files. Likewise, you should ignore warnings about "constant
is so large that it is unsigned" in `insn-emit.c' and
`insn-recog.c' and a warning about a comparison always being zero
in `enquire.o'. Any other compilation errors may represent bugs in
the port to your machine or operating system, and should be
investigated and reported (*note Bugs::.).
Some commercial compilers fail to compile GNU CC because they have
bugs or limitations. For example, the Microsoft compiler is said
to run out of macro space. Some Ultrix compilers run out of
expression space; then you need to break up the statement where
the problem happens.
9. If you are building a cross-compiler, stop here. *Note
10. Move the first-stage object files and executables into a
subdirectory with this command:
make stage1
The files are moved into a subdirectory named `stage1'. Once
installation is complete, you may wish to delete these files with
`rm -r stage1'.
11. If you have chosen a configuration for GNU CC which requires other
GNU tools (such as GAS or the GNU linker) instead of the standard
system tools, install the required tools in the `stage1'
subdirectory under the names `as', `ld' or whatever is
appropriate. This will enable the stage 1 compiler to find the
proper tools in the following stage.
Alternatively, you can do subsequent compilation using a value of
the `PATH' environment variable such that the necessary GNU tools
come before the standard system tools.
12. Recompile the compiler with itself, with this command:
make CC="stage1/xgcc -Bstage1/" CFLAGS="-g -O2"
This is called making the stage 2 compiler.
The command shown above builds compilers for all the supported
languages. If you don't want them all, you can specify the
languages to build by typing the argument `LANGUAGES="LIST"'. LIST
should contain one or more words from the list `c', `c++',
`objective-c', and `proto'. Separate the words with spaces.
`proto' stands for the programs `protoize' and `unprotoize'; they
are not a separate language, but you use `LANGUAGES' to enable or
disable their installation.
If you are going to build the stage 3 compiler, then you might
want to build only the C language in stage 2.
Once you have built the stage 2 compiler, if you are short of disk
space, you can delete the subdirectory `stage1'.
On a 68000 or 68020 system lacking floating point hardware, unless
you have selected a `tm.h' file that expects by default that there
is no such hardware, do this instead:
make CC="stage1/xgcc -Bstage1/" CFLAGS="-g -O2 -msoft-float"
13. If you wish to test the compiler by compiling it with itself one
more time, install any other necessary GNU tools (such as GAS or
the GNU linker) in the `stage2' subdirectory as you did in the
`stage1' subdirectory, then do this:
make stage2
make CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O2"
This is called making the stage 3 compiler. Aside from the `-B'
option, the compiler options should be the same as when you made
the stage 2 compiler. But the `LANGUAGES' option need not be the
same. The command shown above builds compilers for all the
supported languages; if you don't want them all, you can specify
the languages to build by typing the argument `LANGUAGES="LIST"',
as described above.
If you do not have to install any additional GNU tools, you may
use the command
instead of making `stage1', `stage2', and performing the two
compiler builds.
14. Then compare the latest object files with the stage 2 object
files--they ought to be identical, aside from time stamps (if any).
On some systems, meaningful comparison of object files is
impossible; they always appear "different." This is currently
true on Solaris and some systems that use ELF object file format.
On some versions of Irix on SGI machines and DEC Unix (OSF/1) on
Alpha systems, you will not be able to compare the files without
specifying `-save-temps'; see the description of individual
systems above to see if you get comparison failures. You may have
similar problems on other systems.
Use this command to compare the files:
make compare
This will mention any object files that differ between stage 2 and
stage 3. Any difference, no matter how innocuous, indicates that
the stage 2 compiler has compiled GNU CC incorrectly, and is
therefore a potentially serious bug which you should investigate
and report (*note Bugs::.).
If your system does not put time stamps in the object files, then
this is a faster way to compare them (using the Bourne shell):
for file in *.o; do
cmp $file stage2/$file
If you have built the compiler with the `-mno-mips-tfile' option on
MIPS machines, you will not be able to compare the files.
15. Install the compiler driver, the compiler's passes and run-time
support with `make install'. Use the same value for `CC',
`CFLAGS' and `LANGUAGES' that you used when compiling the files
that are being installed. One reason this is necessary is that
some versions of Make have bugs and recompile files gratuitously
when you do this step. If you use the same variable values, those
files will be recompiled properly.
For example, if you have built the stage 2 compiler, you can use
the following command:
make install CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O" LANGUAGES="LIST"
This copies the files `cc1', `cpp' and `libgcc.a' to files `cc1',
`cpp' and `libgcc.a' in the directory
`/usr/local/lib/gcc-lib/TARGET/VERSION', which is where the
compiler driver program looks for them. Here TARGET is the target
machine type specified when you ran `configure', and VERSION is
the version number of GNU CC. This naming scheme permits various
versions and/or cross-compilers to coexist. It also copies the
executables for compilers for other languages (e.g., `cc1plus' for
C++) to the same directory.
This also copies the driver program `xgcc' into
`/usr/local/bin/gcc', so that it appears in typical execution
search paths. It also copies `gcc.1' into `/usr/local/man/man1'
and info pages into `/usr/local/info'.
On some systems, this command causes recompilation of some files.
This is usually due to bugs in `make'. You should either ignore
this problem, or use GNU Make.
*Warning: there is a bug in `alloca' in the Sun library. To avoid
this bug, be sure to install the executables of GNU CC that were
compiled by GNU CC. (That is, the executables from stage 2 or 3,
not stage 1.) They use `alloca' as a built-in function and never
the one in the library.*
(It is usually better to install GNU CC executables from stage 2
or 3, since they usually run faster than the ones compiled with
some other compiler.)
16. If you're going to use C++, it's likely that you need to also
install a C++ runtime library. Just as GNU C does not distribute
a C runtime library, it also does not include a C++ runtime
library. All I/O functionality, special class libraries, etc., are
provided by the C++ runtime library.
Here's one way to build and install a C++ runtime library for GNU
* Build and install GNU CC, so that invoking `gcc' obtains the
GNU CC that was just built.
* Obtain a copy of a compatible `libstdc++' distribution. For
example, the `libstdc++-2.8.0.tar.gz' distribution should be
compatible with GCC 2.8.0. GCC distributors normally
distribute `libstdc++' as well.
* Set the `CXX' environment variable to `gcc' while running the
`libstdc++' distribution's `configure' command. Use the same
`configure' options that you used when you invoked GCC's
`configure' command.
* Invoke `make' to build the C++ runtime.
* Invoke `make install' to install the C++ runtime.
To summarize, after building and installing GNU CC, invoke the
following shell commands in the topmost directory of the C++
library distribution. For CONFIGURE-OPTIONS, use the same options
that you used to configure GNU CC.
$ CXX=gcc ./configure CONFIGURE-OPTIONS
$ make
$ make install
17. GNU CC includes a runtime library for Objective-C because it is an
integral part of the language. You can find the files associated
with the library in the subdirectory `objc'. The GNU Objective-C
Runtime Library requires header files for the target's C library in
order to be compiled,and also requires the header files for the
target's thread library if you want thread support. *Note
Cross-Compilers and Header Files: Cross Headers, for discussion
about header files issues for cross-compilation.
When you run `configure', it picks the appropriate Objective-C
thread implementation file for the target platform. In some
situations, you may wish to choose a different back-end as some
platforms support multiple thread implementations or you may wish
to disable thread support completely. You do this by specifying a
value for the OBJC_THREAD_FILE makefile variable on the command
line when you run make, for example:
make CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O2" OBJC_THREAD_FILE=thr-single
Below is a list of the currently available back-ends.
* thr-single Disable thread support, should work for all
* thr-decosf1 DEC OSF/1 thread support.
* thr-irix SGI IRIX thread support.
* thr-mach Generic MACH thread support, known to work on
* thr-os2 IBM OS/2 thread support.
* thr-posix Generix POSIX thread support.
* thr-pthreads PCThreads on Linux-based GNU systems.
* thr-solaris SUN Solaris thread support.
* thr-win32 Microsoft Win32 API thread support.