| This is Info file gcc.info, 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: gcc.info, 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 |
| systems. |
| |
| 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 |
| clean. |
| |
| 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 |
| abbreviated. |
| |
| 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'. |
| |
| `--with-gnu-as' |
| 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 |
| are |
| `hppa1.0-ANY-ANY', `hppa1.1-ANY-ANY', `i386-ANY-sysv', |
| `i386-ANY-isc', |
| `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'). |
| |
| `--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. |
| |
| `--with-stabs' |
| 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 |
| compilation. |
| |
| `--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. |
| |
| `--nfp' |
| 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. |
| |
| `--enable-threads=TYPE' |
| 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 |
| `tm.h'. |
| |
| 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 |
| `MACHINE.h'. |
| |
| * The command file `configure' also constructs the file |
| `Makefile' by adding some text to the template file |
| `Makefile.in'. 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 |
| directory. |
| |
| `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 |
| Cross-Compiler::. |
| |
| 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 |
| |
| make bootstrap LANGUAGES=LANGUAGE-LIST BOOT_CFLAGS=OPTION-LIST |
| |
| 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 |
| done |
| |
| 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 |
| CC: |
| |
| * 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 |
| platforms. |
| |
| * thr-decosf1 DEC OSF/1 thread support. |
| |
| * thr-irix SGI IRIX thread support. |
| |
| * thr-mach Generic MACH thread support, known to work on |
| NEXTSTEP. |
| |
| * 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. |
| |
