1 This is Info file gcc.info, produced by Makeinfo version 1.67 from the
4 This file documents the use and the internals of the GNU compiler.
6 Published by the Free Software Foundation 59 Temple Place - Suite 330
7 Boston, MA 02111-1307 USA
9 Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998
10 Free Software Foundation, Inc.
12 Permission is granted to make and distribute verbatim copies of this
13 manual provided the copyright notice and this permission notice are
14 preserved on all copies.
16 Permission is granted to copy and distribute modified versions of
17 this manual under the conditions for verbatim copying, provided also
18 that the sections entitled "GNU General Public License," "Funding for
19 Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are
20 included exactly as in the original, and provided that the entire
21 resulting derived work is distributed under the terms of a permission
22 notice identical to this one.
24 Permission is granted to copy and distribute translations of this
25 manual into another language, under the above conditions for modified
26 versions, except that the sections entitled "GNU General Public
27 License," "Funding for Free Software," and "Protect Your Freedom--Fight
28 `Look And Feel'", and this permission notice, may be included in
29 translations approved by the Free Software Foundation instead of in the
33 File: gcc.info, Node: Installation, Next: C Extensions, Prev: Invoking GCC, Up: Top
40 * Configurations:: Configurations Supported by GNU CC.
41 * Other Dir:: Compiling in a separate directory (not where the source is).
42 * Cross-Compiler:: Building and installing a cross-compiler.
43 * Sun Install:: See below for installation on the Sun.
44 * VMS Install:: See below for installation on VMS.
45 * Collect2:: How `collect2' works; how it finds `ld'.
46 * Header Dirs:: Understanding the standard header file directories.
48 Here is the procedure for installing GNU CC on a Unix system. See
49 *Note VMS Install::, for VMS systems. In this section we assume you
50 compile in the same directory that contains the source files; see *Note
51 Other Dir::, to find out how to compile in a separate directory on Unix
54 You cannot install GNU C by itself on MSDOS; it will not compile
55 under any MSDOS compiler except itself. You need to get the complete
56 compilation package DJGPP, which includes binaries as well as sources,
57 and includes all the necessary compilation tools and libraries.
59 1. If you have built GNU CC previously in the same directory for a
60 different target machine, do `make distclean' to delete all files
61 that might be invalid. One of the files this deletes is
62 `Makefile'; if `make distclean' complains that `Makefile' does not
63 exist, it probably means that the directory is already suitably
66 2. On a System V release 4 system, make sure `/usr/bin' precedes
67 `/usr/ucb' in `PATH'. The `cc' command in `/usr/ucb' uses
68 libraries which have bugs.
70 3. Specify the host, build and target machine configurations. You do
71 this by running the file `configure'.
73 The "build" machine is the system which you are using, the "host"
74 machine is the system where you want to run the resulting compiler
75 (normally the build machine), and the "target" machine is the
76 system for which you want the compiler to generate code.
78 If you are building a compiler to produce code for the machine it
79 runs on (a native compiler), you normally do not need to specify
80 any operands to `configure'; it will try to guess the type of
81 machine you are on and use that as the build, host and target
82 machines. So you don't need to specify a configuration when
83 building a native compiler unless `configure' cannot figure out
84 what your configuration is or guesses wrong.
86 In those cases, specify the build machine's "configuration name"
87 with the `--host' option; the host and target will default to be
88 the same as the host machine. (If you are building a
89 cross-compiler, see *Note Cross-Compiler::.)
93 ./configure --build=sparc-sun-sunos4.1
95 A configuration name may be canonical or it may be more or less
98 A canonical configuration name has three parts, separated by
99 dashes. It looks like this: `CPU-COMPANY-SYSTEM'. (The three
100 parts may themselves contain dashes; `configure' can figure out
101 which dashes serve which purpose.) For example,
102 `m68k-sun-sunos4.1' specifies a Sun 3.
104 You can also replace parts of the configuration by nicknames or
105 aliases. For example, `sun3' stands for `m68k-sun', so
106 `sun3-sunos4.1' is another way to specify a Sun 3. You can also
107 use simply `sun3-sunos', since the version of SunOS is assumed by
108 default to be version 4.
110 You can specify a version number after any of the system types,
111 and some of the CPU types. In most cases, the version is
112 irrelevant, and will be ignored. So you might as well specify the
113 version if you know it.
115 See *Note Configurations::, for a list of supported configuration
116 names and notes on many of the configurations. You should check
117 the notes in that section before proceeding any further with the
118 installation of GNU CC.
120 There are four additional options you can specify independently to
121 describe variant hardware and software configurations. These are
122 `--with-gnu-as', `--with-gnu-ld', `--with-stabs' and `--nfp'.
125 If you will use GNU CC with the GNU assembler (GAS), you
126 should declare this by using the `--with-gnu-as' option when
129 Using this option does not install GAS. It only modifies the
130 output of GNU CC to work with GAS. Building and installing
133 Conversely, if you *do not* wish to use GAS and do not specify
134 `--with-gnu-as' when building GNU CC, it is up to you to make
135 sure that GAS is not installed. GNU CC searches for a
136 program named `as' in various directories; if the program it
137 finds is GAS, then it runs GAS. If you are not sure where
138 GNU CC finds the assembler it is using, try specifying `-v'
141 The systems where it makes a difference whether you use GAS
143 `hppa1.0-ANY-ANY', `hppa1.1-ANY-ANY', `i386-ANY-sysv',
145 `i860-ANY-bsd', `m68k-bull-sysv',
146 `m68k-hp-hpux', `m68k-sony-bsd',
147 `m68k-altos-sysv', `m68000-hp-hpux',
148 `m68000-att-sysv', `ANY-lynx-lynxos', and `mips-ANY'). On
149 any other system, `--with-gnu-as' has no effect.
151 On the systems listed above (except for the HP-PA, for ISC on
152 the 386, and for `mips-sgi-irix5.*'), if you use GAS, you
153 should also use the GNU linker (and specify `--with-gnu-ld').
156 Specify the option `--with-gnu-ld' if you plan to use the GNU
159 This option does not cause the GNU linker to be installed; it
160 just modifies the behavior of GNU CC to work with the GNU
161 linker. Specifically, it inhibits the installation of
162 `collect2', a program which otherwise serves as a front-end
163 for the system's linker on most configurations.
166 On MIPS based systems and on Alphas, you must specify whether
167 you want GNU CC to create the normal ECOFF debugging format,
168 or to use BSD-style stabs passed through the ECOFF symbol
169 table. The normal ECOFF debug format cannot fully handle
170 languages other than C. BSD stabs format can handle other
171 languages, but it only works with the GNU debugger GDB.
173 Normally, GNU CC uses the ECOFF debugging format by default;
174 if you prefer BSD stabs, specify `--with-stabs' when you
177 No matter which default you choose when you configure GNU CC,
178 the user can use the `-gcoff' and `-gstabs+' options to
179 specify explicitly the debug format for a particular
182 `--with-stabs' is meaningful on the ISC system on the 386,
183 also, if `--with-gas' is used. It selects use of stabs
184 debugging information embedded in COFF output. This kind of
185 debugging information supports C++ well; ordinary COFF
186 debugging information does not.
188 `--with-stabs' is also meaningful on 386 systems running
189 SVR4. It selects use of stabs debugging information embedded
190 in ELF output. The C++ compiler currently (2.6.0) does not
191 support the DWARF debugging information normally used on 386
192 SVR4 platforms; stabs provide a workable alternative. This
193 requires gas and gdb, as the normal SVR4 tools can not
194 generate or interpret stabs.
197 On certain systems, you must specify whether the machine has
198 a floating point unit. These systems include
199 `m68k-sun-sunosN' and `m68k-isi-bsd'. On any other system,
200 `--nfp' currently has no effect, though perhaps there are
201 other systems where it could usefully make a difference.
203 `--enable-threads=TYPE'
204 Certain systems, notably Linux-based GNU systems, can't be
205 relied on to supply a threads facility for the Objective C
206 runtime and so will default to single-threaded runtime. They
207 may, however, have a library threads implementation
208 available, in which case threads can be enabled with this
209 option by supplying a suitable TYPE, probably `posix'. The
210 possibilities for TYPE are `single', `posix', `win32',
211 `solaris', `irix' and `mach'.
213 The `configure' script searches subdirectories of the source
214 directory for other compilers that are to be integrated into GNU
215 CC. The GNU compiler for C++, called G++ is in a subdirectory
216 named `cp'. `configure' inserts rules into `Makefile' to build
217 all of those compilers.
219 Here we spell out what files will be set up by `configure'.
220 Normally you need not be concerned with these files.
222 * A file named `config.h' is created that contains a `#include'
223 of the top-level config file for the machine you will run the
224 compiler on (*note Config::.). This file is responsible for
225 defining information about the host machine. It includes
228 The top-level config file is located in the subdirectory
229 `config'. Its name is always `xm-SOMETHING.h'; usually
230 `xm-MACHINE.h', but there are some exceptions.
232 If your system does not support symbolic links, you might
233 want to set up `config.h' to contain a `#include' command
234 which refers to the appropriate file.
236 * A file named `tconfig.h' is created which includes the
237 top-level config file for your target machine. This is used
238 for compiling certain programs to run on that machine.
240 * A file named `tm.h' is created which includes the
241 machine-description macro file for your target machine. It
242 should be in the subdirectory `config' and its name is often
245 * The command file `configure' also constructs the file
246 `Makefile' by adding some text to the template file
247 `Makefile.in'. The additional text comes from files in the
248 `config' directory, named `t-TARGET' and `x-HOST'. If these
249 files do not exist, it means nothing needs to be added for a
250 given target or host.
252 4. The standard directory for installing GNU CC is `/usr/local/lib'.
253 If you want to install its files somewhere else, specify
254 `--prefix=DIR' when you run `configure'. Here DIR is a directory
255 name to use instead of `/usr/local' for all purposes with one
256 exception: the directory `/usr/local/include' is searched for
257 header files no matter where you install the compiler. To override
258 this name, use the `--local-prefix' option below.
260 5. Specify `--local-prefix=DIR' if you want the compiler to search
261 directory `DIR/include' for locally installed header files
262 *instead* of `/usr/local/include'.
264 You should specify `--local-prefix' *only* if your site has a
265 different convention (not `/usr/local') for where to put
268 The default value for `--local-prefix' is `/usr/local' regardless
269 of the value of `--prefix'. Specifying `--prefix' has no effect
270 on which directory GNU CC searches for local header files. This
271 may seem counterintuitive, but actually it is logical.
273 The purpose of `--prefix' is to specify where to *install GNU CC*.
274 The local header files in `/usr/local/include'--if you put any in
275 that directory--are not part of GNU CC. They are part of other
276 programs--perhaps many others. (GNU CC installs its own header
277 files in another directory which is based on the `--prefix' value.)
279 *Do not* specify `/usr' as the `--local-prefix'! The directory
280 you use for `--local-prefix' *must not* contain any of the
281 system's standard header files. If it did contain them, certain
282 programs would be miscompiled (including GNU Emacs, on certain
283 targets), because this would override and nullify the header file
284 corrections made by the `fixincludes' script.
286 Indications are that people who use this option use it based on
287 mistaken ideas of what it is for. People use it as if it specified
288 where to install part of GNU CC. Perhaps they make this assumption
289 because installing GNU CC creates the directory.
291 6. Make sure the Bison parser generator is installed. (This is
292 unnecessary if the Bison output files `c-parse.c' and `cexp.c' are
293 more recent than `c-parse.y' and `cexp.y' and you do not plan to
294 change the `.y' files.)
296 Bison versions older than Sept 8, 1988 will produce incorrect
297 output for `c-parse.c'.
299 7. If you have chosen a configuration for GNU CC which requires other
300 GNU tools (such as GAS or the GNU linker) instead of the standard
301 system tools, install the required tools in the build directory
302 under the names `as', `ld' or whatever is appropriate. This will
303 enable the compiler to find the proper tools for compilation of
304 the program `enquire'.
306 Alternatively, you can do subsequent compilation using a value of
307 the `PATH' environment variable such that the necessary GNU tools
308 come before the standard system tools.
310 8. Build the compiler. Just type `make LANGUAGES=c' in the compiler
313 `LANGUAGES=c' specifies that only the C compiler should be
314 compiled. The makefile normally builds compilers for all the
315 supported languages; currently, C, C++ and Objective C. However,
316 C is the only language that is sure to work when you build with
317 other non-GNU C compilers. In addition, building anything but C
318 at this stage is a waste of time.
320 In general, you can specify the languages to build by typing the
321 argument `LANGUAGES="LIST"', where LIST is one or more words from
322 the list `c', `c++', and `objective-c'. If you have any
323 additional GNU compilers as subdirectories of the GNU CC source
324 directory, you may also specify their names in this list.
326 Ignore any warnings you may see about "statement not reached" in
327 `insn-emit.c'; they are normal. Also, warnings about "unknown
328 escape sequence" are normal in `genopinit.c' and perhaps some
329 other files. Likewise, you should ignore warnings about "constant
330 is so large that it is unsigned" in `insn-emit.c' and
331 `insn-recog.c' and a warning about a comparison always being zero
332 in `enquire.o'. Any other compilation errors may represent bugs in
333 the port to your machine or operating system, and should be
334 investigated and reported (*note Bugs::.).
336 Some commercial compilers fail to compile GNU CC because they have
337 bugs or limitations. For example, the Microsoft compiler is said
338 to run out of macro space. Some Ultrix compilers run out of
339 expression space; then you need to break up the statement where
342 9. If you are building a cross-compiler, stop here. *Note
345 10. Move the first-stage object files and executables into a
346 subdirectory with this command:
350 The files are moved into a subdirectory named `stage1'. Once
351 installation is complete, you may wish to delete these files with
354 11. If you have chosen a configuration for GNU CC which requires other
355 GNU tools (such as GAS or the GNU linker) instead of the standard
356 system tools, install the required tools in the `stage1'
357 subdirectory under the names `as', `ld' or whatever is
358 appropriate. This will enable the stage 1 compiler to find the
359 proper tools in the following stage.
361 Alternatively, you can do subsequent compilation using a value of
362 the `PATH' environment variable such that the necessary GNU tools
363 come before the standard system tools.
365 12. Recompile the compiler with itself, with this command:
367 make CC="stage1/xgcc -Bstage1/" CFLAGS="-g -O2"
369 This is called making the stage 2 compiler.
371 The command shown above builds compilers for all the supported
372 languages. If you don't want them all, you can specify the
373 languages to build by typing the argument `LANGUAGES="LIST"'. LIST
374 should contain one or more words from the list `c', `c++',
375 `objective-c', and `proto'. Separate the words with spaces.
376 `proto' stands for the programs `protoize' and `unprotoize'; they
377 are not a separate language, but you use `LANGUAGES' to enable or
378 disable their installation.
380 If you are going to build the stage 3 compiler, then you might
381 want to build only the C language in stage 2.
383 Once you have built the stage 2 compiler, if you are short of disk
384 space, you can delete the subdirectory `stage1'.
386 On a 68000 or 68020 system lacking floating point hardware, unless
387 you have selected a `tm.h' file that expects by default that there
388 is no such hardware, do this instead:
390 make CC="stage1/xgcc -Bstage1/" CFLAGS="-g -O2 -msoft-float"
392 13. If you wish to test the compiler by compiling it with itself one
393 more time, install any other necessary GNU tools (such as GAS or
394 the GNU linker) in the `stage2' subdirectory as you did in the
395 `stage1' subdirectory, then do this:
398 make CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O2"
400 This is called making the stage 3 compiler. Aside from the `-B'
401 option, the compiler options should be the same as when you made
402 the stage 2 compiler. But the `LANGUAGES' option need not be the
403 same. The command shown above builds compilers for all the
404 supported languages; if you don't want them all, you can specify
405 the languages to build by typing the argument `LANGUAGES="LIST"',
408 If you do not have to install any additional GNU tools, you may
411 make bootstrap LANGUAGES=LANGUAGE-LIST BOOT_CFLAGS=OPTION-LIST
413 instead of making `stage1', `stage2', and performing the two
416 14. Then compare the latest object files with the stage 2 object
417 files--they ought to be identical, aside from time stamps (if any).
419 On some systems, meaningful comparison of object files is
420 impossible; they always appear "different." This is currently
421 true on Solaris and some systems that use ELF object file format.
422 On some versions of Irix on SGI machines and DEC Unix (OSF/1) on
423 Alpha systems, you will not be able to compare the files without
424 specifying `-save-temps'; see the description of individual
425 systems above to see if you get comparison failures. You may have
426 similar problems on other systems.
428 Use this command to compare the files:
432 This will mention any object files that differ between stage 2 and
433 stage 3. Any difference, no matter how innocuous, indicates that
434 the stage 2 compiler has compiled GNU CC incorrectly, and is
435 therefore a potentially serious bug which you should investigate
436 and report (*note Bugs::.).
438 If your system does not put time stamps in the object files, then
439 this is a faster way to compare them (using the Bourne shell):
442 cmp $file stage2/$file
445 If you have built the compiler with the `-mno-mips-tfile' option on
446 MIPS machines, you will not be able to compare the files.
448 15. Install the compiler driver, the compiler's passes and run-time
449 support with `make install'. Use the same value for `CC',
450 `CFLAGS' and `LANGUAGES' that you used when compiling the files
451 that are being installed. One reason this is necessary is that
452 some versions of Make have bugs and recompile files gratuitously
453 when you do this step. If you use the same variable values, those
454 files will be recompiled properly.
456 For example, if you have built the stage 2 compiler, you can use
457 the following command:
459 make install CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O" LANGUAGES="LIST"
461 This copies the files `cc1', `cpp' and `libgcc.a' to files `cc1',
462 `cpp' and `libgcc.a' in the directory
463 `/usr/local/lib/gcc-lib/TARGET/VERSION', which is where the
464 compiler driver program looks for them. Here TARGET is the
465 canonicalized form of target machine type specified when you ran
466 `configure', and VERSION is the version number of GNU CC. This
467 naming scheme permits various versions and/or cross-compilers to
468 coexist. It also copies the executables for compilers for other
469 languages (e.g., `cc1plus' for C++) to the same directory.
471 This also copies the driver program `xgcc' into
472 `/usr/local/bin/gcc', so that it appears in typical execution
473 search paths. It also copies `gcc.1' into `/usr/local/man/man1'
474 and info pages into `/usr/local/info'.
476 On some systems, this command causes recompilation of some files.
477 This is usually due to bugs in `make'. You should either ignore
478 this problem, or use GNU Make.
480 *Warning: there is a bug in `alloca' in the Sun library. To avoid
481 this bug, be sure to install the executables of GNU CC that were
482 compiled by GNU CC. (That is, the executables from stage 2 or 3,
483 not stage 1.) They use `alloca' as a built-in function and never
484 the one in the library.*
486 (It is usually better to install GNU CC executables from stage 2
487 or 3, since they usually run faster than the ones compiled with
488 some other compiler.)
490 16. If you're going to use C++, it's likely that you need to also
491 install a C++ runtime library. Just as GNU C does not distribute
492 a C runtime library, it also does not include a C++ runtime
493 library. All I/O functionality, special class libraries, etc., are
494 provided by the C++ runtime library.
496 The standard C++ runtime library for GNU CC is called `libstdc++'.
497 An obsolescent library `libg++' may also be available, but it's
498 necessary only for older software that hasn't been converted yet;
499 if you don't know whether you need `libg++' then you probably don't
502 Here's one way to build and install `libstdc++' for GNU CC:
504 * Build and install GNU CC, so that invoking `gcc' obtains the
505 GNU CC that was just built.
507 * Obtain a copy of a compatible `libstdc++' distribution. For
508 example, the `libstdc++-2.8.0.tar.gz' distribution should be
509 compatible with GCC 2.8.0. GCC distributors normally
510 distribute `libstdc++' as well.
512 * Set the `CXX' environment variable to `gcc' while running the
513 `libstdc++' distribution's `configure' command. Use the same
514 `configure' options that you used when you invoked GCC's
517 * Invoke `make' to build the C++ runtime.
519 * Invoke `make install' to install the C++ runtime.
521 To summarize, after building and installing GNU CC, invoke the
522 following shell commands in the topmost directory of the C++
523 library distribution. For CONFIGURE-OPTIONS, use the same options
524 that you used to configure GNU CC.
526 $ CXX=gcc ./configure CONFIGURE-OPTIONS
530 17. GNU CC includes a runtime library for Objective-C because it is an
531 integral part of the language. You can find the files associated
532 with the library in the subdirectory `objc'. The GNU Objective-C
533 Runtime Library requires header files for the target's C library in
534 order to be compiled,and also requires the header files for the
535 target's thread library if you want thread support. *Note
536 Cross-Compilers and Header Files: Cross Headers, for discussion
537 about header files issues for cross-compilation.
539 When you run `configure', it picks the appropriate Objective-C
540 thread implementation file for the target platform. In some
541 situations, you may wish to choose a different back-end as some
542 platforms support multiple thread implementations or you may wish
543 to disable thread support completely. You do this by specifying a
544 value for the OBJC_THREAD_FILE makefile variable on the command
545 line when you run make, for example:
547 make CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O2" OBJC_THREAD_FILE=thr-single
549 Below is a list of the currently available back-ends.
551 * thr-single Disable thread support, should work for all
554 * thr-decosf1 DEC OSF/1 thread support.
556 * thr-irix SGI IRIX thread support.
558 * thr-mach Generic MACH thread support, known to work on
561 * thr-os2 IBM OS/2 thread support.
563 * thr-posix Generix POSIX thread support.
565 * thr-pthreads PCThreads on Linux-based GNU systems.
567 * thr-solaris SUN Solaris thread support.
569 * thr-win32 Microsoft Win32 API thread support.