From c446d93c756b52b25588a6816d1728f4852d2068 Mon Sep 17 00:00:00 2001 From: dje Date: Wed, 23 Apr 1997 13:50:37 +0000 Subject: [PATCH] Initial revision git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@13967 138bc75d-0d04-0410-961f-82ee72b054a4 --- gcc/install.texi | 2281 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 2281 insertions(+) create mode 100644 gcc/install.texi diff --git a/gcc/install.texi b/gcc/install.texi new file mode 100644 index 00000000000..7de6200c184 --- /dev/null +++ b/gcc/install.texi @@ -0,0 +1,2281 @@ +@c Copyright (C) 1988,89,92,93,94,95,96 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@c The text of this file appears in the file INSTALL +@c in the GCC distribution, as well as in the GCC manual. + +@ifclear INSTALLONLY +@node Installation +@chapter Installing GNU CC +@end ifclear +@cindex 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 @code{collect2} works; how it finds @code{ld}. +* Header Dirs:: Understanding the standard header file directories. +@end menu + +Here is the procedure for installing GNU CC on a Unix system. See +@ref{VMS Install}, for VMS systems. In this section we assume you +compile in the same directory that contains the source files; see +@ref{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. + +@enumerate +@item +If you have built GNU CC previously in the same directory for a +different target machine, do @samp{make distclean} to delete all files +that might be invalid. One of the files this deletes is +@file{Makefile}; if @samp{make distclean} complains that @file{Makefile} +does not exist, it probably means that the directory is already suitably +clean. + +@item +On a System V release 4 system, make sure @file{/usr/bin} precedes +@file{/usr/ucb} in @code{PATH}. The @code{cc} command in +@file{/usr/ucb} uses libraries which have bugs. + +@item +Specify the host, build and target machine configurations. You do this +by running the file @file{configure}. + +The @dfn{build} machine is the system which you are using, the +@dfn{host} machine is the system where you want to run the resulting +compiler (normally the build machine), and the @dfn{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 @file{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 +@file{configure} cannot figure out what your configuration is or guesses +wrong. + +In those cases, specify the build machine's @dfn{configuration name} +with the @samp{--build} option; the host and target will default to be +the same as the build machine. (If you are building a cross-compiler, +see @ref{Cross-Compiler}.) + +Here is an example: + +@smallexample +./configure --build=sparc-sun-sunos4.1 +@end smallexample + +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: @samp{@var{cpu}-@var{company}-@var{system}}. +(The three parts may themselves contain dashes; @file{configure} +can figure out which dashes serve which purpose.) For example, +@samp{m68k-sun-sunos4.1} specifies a Sun 3. + +You can also replace parts of the configuration by nicknames or aliases. +For example, @samp{sun3} stands for @samp{m68k-sun}, so +@samp{sun3-sunos4.1} is another way to specify a Sun 3. You can also +use simply @samp{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 @ref{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 +@samp{--with-gnu-as}, @samp{--with-gnu-ld}, @samp{--with-stabs} and +@samp{--nfp}. + +@table @samp +@item --with-gnu-as +If you will use GNU CC with the GNU assembler (GAS), you should declare +this by using the @samp{--with-gnu-as} option when you run +@file{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 @emph{do not} wish to use GAS and do not specify +@samp{--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 +@code{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 @samp{-v} when you run it. + +The systems where it makes a difference whether you use GAS are@* +@samp{hppa1.0-@var{any}-@var{any}}, @samp{hppa1.1-@var{any}-@var{any}}, +@samp{i386-@var{any}-sysv}, @samp{i386-@var{any}-isc},@* +@samp{i860-@var{any}-bsd}, @samp{m68k-bull-sysv},@* +@samp{m68k-hp-hpux}, @samp{m68k-sony-bsd},@* +@samp{m68k-altos-sysv}, @samp{m68000-hp-hpux},@* +@samp{m68000-att-sysv}, @samp{@var{any}-lynx-lynxos}, +and @samp{mips-@var{any}}). +On any other system, @samp{--with-gnu-as} has no effect. + +On the systems listed above (except for the HP-PA, for ISC on the +386, and for @samp{mips-sgi-irix5.*}), if you use GAS, you should also +use the GNU linker (and specify @samp{--with-gnu-ld}). + +@item --with-gnu-ld +Specify the option @samp{--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 @code{collect2}, a program +which otherwise serves as a front-end for the system's linker on most +configurations. + +@item --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 @samp{--with-stabs} when you configure GNU +CC. + +No matter which default you choose when you configure GNU CC, the user +can use the @samp{-gcoff} and @samp{-gstabs+} options to specify explicitly +the debug format for a particular compilation. + +@samp{--with-stabs} is meaningful on the ISC system on the 386, also, if +@samp{--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. + +@samp{--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. + +@item --nfp +On certain systems, you must specify whether the machine has a floating +point unit. These systems include @samp{m68k-sun-sunos@var{n}} and +@samp{m68k-isi-bsd}. On any other system, @samp{--nfp} currently has no +effect, though perhaps there are other systems where it could usefully +make a difference. + +@cindex Objective C threads +@cindex threads, Objective C +@item --enable-objcthreads=@var{type} +Certain systems, notably Linux, 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 @var{type}, probably @samp{posix}. +The possibilities for @var{type} are @samp{single}, @samp{posix}, +@samp{win32}, @samp{solaris}, @samp{irix} and @samp{mach}. +@end table + +The @file{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 +@file{cp}. @file{configure} inserts rules into @file{Makefile} to build +all of those compilers. + +Here we spell out what files will be set up by @code{configure}. Normally +you need not be concerned with these files. + +@itemize @bullet +@item +@ifset INTERNALS +A file named @file{config.h} is created that contains a @samp{#include} +of the top-level config file for the machine you will run the compiler +on (@pxref{Config}). This file is responsible for defining information +about the host machine. It includes @file{tm.h}. +@end ifset +@ifclear INTERNALS +A file named @file{config.h} is created that contains a @samp{#include} +of the top-level config file for the machine you will run the compiler +on (@pxref{Config,,The Configuration File, gcc.info, Using and Porting +GCC}). This file is responsible for defining information about the host +machine. It includes @file{tm.h}. +@end ifclear + +The top-level config file is located in the subdirectory @file{config}. +Its name is always @file{xm-@var{something}.h}; usually +@file{xm-@var{machine}.h}, but there are some exceptions. + +If your system does not support symbolic links, you might want to +set up @file{config.h} to contain a @samp{#include} command which +refers to the appropriate file. + +@item +A file named @file{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. + +@item +A file named @file{tm.h} is created which includes the +machine-description macro file for your target machine. It should be in +the subdirectory @file{config} and its name is often +@file{@var{machine}.h}. + +@item +The command file @file{configure} also constructs the file +@file{Makefile} by adding some text to the template file +@file{Makefile.in}. The additional text comes from files in the +@file{config} directory, named @file{t-@var{target}} and +@file{x-@var{host}}. If these files do not exist, it means nothing +needs to be added for a given target or host. +@end itemize + +@item +The standard directory for installing GNU CC is @file{/usr/local/lib}. +If you want to install its files somewhere else, specify +@samp{--prefix=@var{dir}} when you run @file{configure}. Here @var{dir} +is a directory name to use instead of @file{/usr/local} for all purposes +with one exception: the directory @file{/usr/local/include} is searched +for header files no matter where you install the compiler. To override +this name, use the @code{--local-prefix} option below. + +@item +Specify @samp{--local-prefix=@var{dir}} if you want the compiler to +search directory @file{@var{dir}/include} for locally installed header +files @emph{instead} of @file{/usr/local/include}. + +You should specify @samp{--local-prefix} @strong{only} if your site has +a different convention (not @file{/usr/local}) for where to put +site-specific files. + +The default value for @samp{--local-prefix} is @file{/usr/local} +regardless of the value of @samp{--prefix}. Specifying @samp{--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 @samp{--prefix} is to specify where to @emph{install GNU +CC}. The local header files in @file{/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 @samp{--prefix} value.) + +@strong{Do not} specify @file{/usr} as the @samp{--local-prefix}! The +directory you use for @samp{--local-prefix} @strong{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 @code{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. + +@cindex Bison parser generator +@cindex parser generator, Bison +@item +Make sure the Bison parser generator is installed. (This is +unnecessary if the Bison output files @file{c-parse.c} and +@file{cexp.c} are more recent than @file{c-parse.y} and @file{cexp.y} +and you do not plan to change the @samp{.y} files.) + +Bison versions older than Sept 8, 1988 will produce incorrect output +for @file{c-parse.c}. + +@item +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 +@file{as}, @file{ld} or whatever is appropriate. This will enable the +compiler to find the proper tools for compilation of the program +@file{enquire}. + +Alternatively, you can do subsequent compilation using a value of the +@code{PATH} environment variable such that the necessary GNU tools come +before the standard system tools. + +@item +Build the compiler. Just type @samp{make LANGUAGES=c} in the compiler +directory. + +@samp{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 @samp{LANGUAGES="@var{list}"}, where @var{list} is one or more +words from the list @samp{c}, @samp{c++}, and @samp{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 +@file{insn-emit.c}; they are normal. Also, warnings about ``unknown +escape sequence'' are normal in @file{genopinit.c} and perhaps some +other files. Likewise, you should ignore warnings about ``constant is +so large that it is unsigned'' in @file{insn-emit.c} and +@file{insn-recog.c} and a warning about a comparison always being zero +in @file{enquire.o}. Any other compilation errors may represent bugs in +the port to your machine or operating system, and +@ifclear INSTALLONLY +should be investigated and reported (@pxref{Bugs}). +@end ifclear +@ifset INSTALLONLY +should be investigated and reported. +@end ifset + +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. + +@item +If you are building a cross-compiler, stop here. @xref{Cross-Compiler}. + +@cindex stage1 +@item +Move the first-stage object files and executables into a subdirectory +with this command: + +@smallexample +make stage1 +@end smallexample + +The files are moved into a subdirectory named @file{stage1}. +Once installation is complete, you may wish to delete these files +with @code{rm -r stage1}. + +@item +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 @file{stage1} subdirectory +under the names @file{as}, @file{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 +@code{PATH} environment variable such that the necessary GNU tools come +before the standard system tools. + +@item +Recompile the compiler with itself, with this command: + +@smallexample +make CC="stage1/xgcc -Bstage1/" CFLAGS="-g -O2" +@end smallexample + +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 @samp{LANGUAGES="@var{list}"}. @var{list} +should contain one or more words from the list @samp{c}, @samp{c++}, +@samp{objective-c}, and @samp{proto}. Separate the words with spaces. +@samp{proto} stands for the programs @code{protoize} and +@code{unprotoize}; they are not a separate language, but you use +@code{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 @file{stage1}. + +On a 68000 or 68020 system lacking floating point hardware, +unless you have selected a @file{tm.h} file that expects by default +that there is no such hardware, do this instead: + +@smallexample +make CC="stage1/xgcc -Bstage1/" CFLAGS="-g -O2 -msoft-float" +@end smallexample + +@item +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 @file{stage2} subdirectory as you did in the +@file{stage1} subdirectory, then do this: + +@smallexample +make stage2 +make CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O2" +@end smallexample + +@noindent +This is called making the stage 3 compiler. Aside from the @samp{-B} +option, the compiler options should be the same as when you made the +stage 2 compiler. But the @code{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 @samp{LANGUAGES="@var{list}"}, as described +above. + +If you do not have to install any additional GNU tools, you may use the +command + +@smallexample +make bootstrap LANGUAGES=@var{language-list} BOOT_CFLAGS=@var{option-list} +@end smallexample + +@noindent +instead of making @file{stage1}, @file{stage2}, and performing +the two compiler builds. + +@item +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 @file{-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: + +@smallexample +make compare +@end smallexample + +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 +@ifclear INSTALLONLY +serious bug which you should investigate and report (@pxref{Bugs}). +@end ifclear +@ifset INSTALLONLY +serious bug which you should investigate and report. +@end ifset + +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): + +@smallexample +for file in *.o; do +cmp $file stage2/$file +done +@end smallexample + +If you have built the compiler with the @samp{-mno-mips-tfile} option on +MIPS machines, you will not be able to compare the files. + +@item +Install the compiler driver, the compiler's passes and run-time support +with @samp{make install}. Use the same value for @code{CC}, +@code{CFLAGS} and @code{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: + +@smallexample +make install CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O" LANGUAGES="@var{list}" +@end smallexample + +@noindent +This copies the files @file{cc1}, @file{cpp} and @file{libgcc.a} to +files @file{cc1}, @file{cpp} and @file{libgcc.a} in the directory +@file{/usr/local/lib/gcc-lib/@var{target}/@var{version}}, which is where +the compiler driver program looks for them. Here @var{target} is the +target machine type specified when you ran @file{configure}, and +@var{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., @file{cc1plus} for C++) to the same directory. + +This also copies the driver program @file{xgcc} into +@file{/usr/local/bin/gcc}, so that it appears in typical execution +search paths. It also copies @file{gcc.1} into +@file{/usr/local/man/man1} and info pages into @file{/usr/local/info}. + +On some systems, this command causes recompilation of some files. This +is usually due to bugs in @code{make}. You should either ignore this +problem, or use GNU Make. + +@cindex @code{alloca} and SunOS +@strong{Warning: there is a bug in @code{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 @code{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.) + +@item +If you're going to use C++, it's likely that you need to also install +the libg++ distribution. It should be available from the same +place where you got the GNU C distribution. Just as GNU C does not +distribute a C runtime library, it also does not include a C++ run-time +library. All I/O functionality, special class libraries, etc., are +available in the libg++ distribution. + +@item +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 @file{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. @xref{Cross Headers, +Cross-Compilers and Header Files, Cross-Compilers and Header Files}, for +discussion about header files issues for cross-compilation. + +When you run @file{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 +@var{OBJC_THREAD_FILE} makefile variable on the command line when you +run make, for example: + +@smallexample +make CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O2" OBJC_THREAD_FILE=thr-single +@end smallexample + +@noindent +Below is a list of the currently available back-ends. + +@itemize @bullet +@item thr-single +Disable thread support, should work for all platforms. +@item thr-decosf1 +DEC OSF/1 thread support. +@item thr-irix +SGI IRIX thread support. +@item thr-mach +Generic MACH thread support, known to work on NEXTSTEP. +@item thr-os2 +IBM OS/2 thread support. +@item thr-posix +Generix POSIX thread support. +@item thr-pthreads +PCThreads on Linux-based GNU systems. +@item thr-solaris +SUN Solaris thread support. +@item thr-win32 +Microsoft Win32 API thread support. +@end itemize +@end enumerate + +@node Configurations +@section Configurations Supported by GNU CC +@cindex configurations supported by GNU CC + +Here are the possible CPU types: + +@quotation +@c gmicro, alliant, spur and tahoe omitted since they don't work. +1750a, a29k, alpha, arm, c@var{n}, clipper, dsp16xx, elxsi, h8300, +hppa1.0, hppa1.1, i370, i386, i486, i586, i860, i960, m68000, m68k, +m88k, mips, mipsel, mips64, mips64el, ns32k, powerpc, powerpcle, +pyramid, romp, rs6000, sh, sparc, sparclite, sparc64, vax, we32k. +@end quotation + +Here are the recognized company names. As you can see, customary +abbreviations are used rather than the longer official names. + +@c What should be done about merlin, tek*, dolphin? +@quotation +acorn, alliant, altos, apollo, apple, att, bull, +cbm, convergent, convex, crds, dec, dg, dolphin, +elxsi, encore, harris, hitachi, hp, ibm, intergraph, isi, +mips, motorola, ncr, next, ns, omron, plexus, +sequent, sgi, sony, sun, tti, unicom, wrs. +@end quotation + +The company name is meaningful only to disambiguate when the rest of +the information supplied is insufficient. You can omit it, writing +just @samp{@var{cpu}-@var{system}}, if it is not needed. For example, +@samp{vax-ultrix4.2} is equivalent to @samp{vax-dec-ultrix4.2}. + +Here is a list of system types: + +@quotation +386bsd, aix, acis, amigados, aos, aout, aux, bosx, bsd, clix, coff, ctix, cxux, +dgux, dynix, ebmon, ecoff, elf, esix, freebsd, hms, genix, gnu, gnu/linux, +hiux, hpux, iris, irix, isc, luna, lynxos, mach, minix, msdos, mvs, +netbsd, newsos, nindy, ns, osf, osfrose, ptx, riscix, riscos, rtu, sco, sim, +solaris, sunos, sym, sysv, udi, ultrix, unicos, uniplus, unos, vms, vsta, +vxworks, winnt, xenix. +@end quotation + +@noindent +You can omit the system type; then @file{configure} guesses the +operating system from the CPU and company. + +You can add a version number to the system type; this may or may not +make a difference. For example, you can write @samp{bsd4.3} or +@samp{bsd4.4} to distinguish versions of BSD. In practice, the version +number is most needed for @samp{sysv3} and @samp{sysv4}, which are often +treated differently. + +If you specify an impossible combination such as @samp{i860-dg-vms}, +then you may get an error message from @file{configure}, or it may +ignore part of the information and do the best it can with the rest. +@file{configure} always prints the canonical name for the alternative +that it used. GNU CC does not support all possible alternatives. + +Often a particular model of machine has a name. Many machine names are +recognized as aliases for CPU/company combinations. Thus, the machine +name @samp{sun3}, mentioned above, is an alias for @samp{m68k-sun}. +Sometimes we accept a company name as a machine name, when the name is +popularly used for a particular machine. Here is a table of the known +machine names: + +@quotation +3300, 3b1, 3b@var{n}, 7300, altos3068, altos, +apollo68, att-7300, balance, +convex-c@var{n}, crds, decstation-3100, +decstation, delta, encore, +fx2800, gmicro, hp7@var{nn}, hp8@var{nn}, +hp9k2@var{nn}, hp9k3@var{nn}, hp9k7@var{nn}, +hp9k8@var{nn}, iris4d, iris, isi68, +m3230, magnum, merlin, miniframe, +mmax, news-3600, news800, news, next, +pbd, pc532, pmax, powerpc, powerpcle, ps2, risc-news, +rtpc, sun2, sun386i, sun386, sun3, +sun4, symmetry, tower-32, tower. +@end quotation + +@noindent +Remember that a machine name specifies both the cpu type and the company +name. +If you want to install your own homemade configuration files, you can +use @samp{local} as the company name to access them. If you use +configuration @samp{@var{cpu}-local}, the configuration name +without the cpu prefix +is used to form the configuration file names. + +Thus, if you specify @samp{m68k-local}, configuration uses +files @file{m68k.md}, @file{local.h}, @file{m68k.c}, +@file{xm-local.h}, @file{t-local}, and @file{x-local}, all in the +directory @file{config/m68k}. + +Here is a list of configurations that have special treatment or special +things you must know: + +@table @samp +@item 1750a-*-* +MIL-STD-1750A processors. + +The MIL-STD-1750A cross configuration produces output for +@code{as1750}, an assembler/linker available under the GNU Public +License for the 1750A. @code{as1750} can be obtained at +@emph{ftp://ftp.fta-berlin.de/pub/crossgcc/1750gals/}. +A similarly licensed simulator for +the 1750A is available from same address. + +You should ignore a fatal error during the building of libgcc (libgcc is +not yet implemented for the 1750A.) + +The @code{as1750} assembler requires the file @file{ms1750.inc}, which is +found in the directory @file{config/1750a}. + +GNU CC produced the same sections as the Fairchild F9450 C Compiler, +namely: + +@table @code +@item Normal +The program code section. + +@item Static +The read/write (RAM) data section. + +@item Konst +The read-only (ROM) constants section. + +@item Init +Initialization section (code to copy KREL to SREL). +@end table + +The smallest addressable unit is 16 bits (BITS_PER_UNIT is 16). This +means that type `char' is represented with a 16-bit word per character. +The 1750A's "Load/Store Upper/Lower Byte" instructions are not used by +GNU CC. + +@item alpha-*-osf1 +Systems using processors that implement the DEC Alpha architecture and +are running the DEC Unix (OSF/1) operating system, for example the DEC +Alpha AXP systems. (VMS on the Alpha is not currently supported by GNU +CC.) + +GNU CC writes a @samp{.verstamp} directive to the assembler output file +unless it is built as a cross-compiler. It gets the version to use from +the system header file @file{/usr/include/stamp.h}. If you install a +new version of DEC Unix, you should rebuild GCC to pick up the new version +stamp. + +Note that since the Alpha is a 64-bit architecture, cross-compilers from +32-bit machines will not generate code as efficient as that generated +when the compiler is running on a 64-bit machine because many +optimizations that depend on being able to represent a word on the +target in an integral value on the host cannot be performed. Building +cross-compilers on the Alpha for 32-bit machines has only been tested in +a few cases and may not work properly. + +@code{make compare} may fail on old versions of DEC Unix unless you add +@samp{-save-temps} to @code{CFLAGS}. On these systems, the name of the +assembler input file is stored in the object file, and that makes +comparison fail if it differs between the @code{stage1} and +@code{stage2} compilations. The option @samp{-save-temps} forces a +fixed name to be used for the assembler input file, instead of a +randomly chosen name in @file{/tmp}. Do not add @samp{-save-temps} +unless the comparisons fail without that option. If you add +@samp{-save-temps}, you will have to manually delete the @samp{.i} and +@samp{.s} files after each series of compilations. + +GNU CC now supports both the native (ECOFF) debugging format used by DBX +and GDB and an encapsulated STABS format for use only with GDB. See the +discussion of the @samp{--with-stabs} option of @file{configure} above +for more information on these formats and how to select them. + +There is a bug in DEC's assembler that produces incorrect line numbers +for ECOFF format when the @samp{.align} directive is used. To work +around this problem, GNU CC will not emit such alignment directives +while writing ECOFF format debugging information even if optimization is +being performed. Unfortunately, this has the very undesirable +side-effect that code addresses when @samp{-O} is specified are +different depending on whether or not @samp{-g} is also specified. + +To avoid this behavior, specify @samp{-gstabs+} and use GDB instead of +DBX. DEC is now aware of this problem with the assembler and hopes to +provide a fix shortly. + +@item arm +Advanced RISC Machines ARM-family processors. These are often used in +embedded applications. There are no standard Unix configurations. +This configuration corresponds to the basic instruction sequences and will +produce a.out format object modules. + +You may need to make a variant of the file @file{arm.h} for your particular +configuration. + +@item arm-*-riscix +The ARM2 or ARM3 processor running RISC iX, Acorn's port of BSD Unix. If +you are running a version of RISC iX prior to 1.2 then you must specify +the version number during configuration. Note that the assembler +shipped with RISC iX does not support stabs debugging information; a +new version of the assembler, with stabs support included, is now +available from Acorn. + +@item a29k +AMD Am29k-family processors. These are normally used in embedded +applications. There are no standard Unix configurations. +This configuration +corresponds to AMD's standard calling sequence and binary interface +and is compatible with other 29k tools. + +You may need to make a variant of the file @file{a29k.h} for your +particular configuration. + +@item a29k-*-bsd +AMD Am29050 used in a system running a variant of BSD Unix. + +@item decstation-* +DECstations can support three different personalities: Ultrix, +DEC OSF/1, and OSF/rose. To configure GCC for these platforms +use the following configurations: + +@table @samp +@item decstation-ultrix +Ultrix configuration. + +@item decstation-osf1 +Dec's version of OSF/1. + +@item decstation-osfrose +Open Software Foundation reference port of OSF/1 which uses the +OSF/rose object file format instead of ECOFF. Normally, you +would not select this configuration. +@end table + +The MIPS C compiler needs to be told to increase its table size +for switch statements with the @samp{-Wf,-XNg1500} option in +order to compile @file{cp/parse.c}. If you use the @samp{-O2} +optimization option, you also need to use @samp{-Olimit 3000}. +Both of these options are automatically generated in the +@file{Makefile} that the shell script @file{configure} builds. +If you override the @code{CC} make variable and use the MIPS +compilers, you may need to add @samp{-Wf,-XNg1500 -Olimit 3000}. + +@item elxsi-elxsi-bsd +The Elxsi's C compiler has known limitations that prevent it from +compiling GNU C. Please contact @code{mrs@@cygnus.com} for more details. + +@item dsp16xx +A port to the AT&T DSP1610 family of processors. + +@ignore +@item fx80 +Alliant FX/8 computer. Note that the standard installed C compiler in +Concentrix 5.0 has a bug which prevent it from compiling GNU CC +correctly. You can patch the compiler bug as follows: + +@smallexample +cp /bin/pcc ./pcc +adb -w ./pcc - << EOF +15f6?w 6610 +EOF +@end smallexample + +Then you must use the @samp{-ip12} option when compiling GNU CC +with the patched compiler, as shown here: + +@smallexample +make CC="./pcc -ip12" CFLAGS=-w +@end smallexample + +Note also that Alliant's version of DBX does not manage to work with the +output from GNU CC. +@end ignore + +@item h8300-*-* +The calling convention and structure layout has changed in release 2.6. +All code must be recompiled. The calling convention now passes the +first three arguments in function calls in registers. Structures are no +longer a multiple of 2 bytes. + +@item hppa*-*-* +There are several variants of the HP-PA processor which run a variety +of operating systems. GNU CC must be configured to use the correct +processor type and operating system, or GNU CC will not function correctly. +The easiest way to handle this problem is to @emph{not} specify a target +when configuring GNU CC, the @file{configure} script will try to automatically +determine the right processor type and operating system. + +@samp{-g} does not work on HP-UX, since that system uses a peculiar +debugging format which GNU CC does not know about. However, @samp{-g} +will work if you also use GAS and GDB in conjunction with GCC. We +highly recommend using GAS for all HP-PA configurations. + +You should be using GAS-2.6 (or later) along with GDB-4.16 (or later). These +can be retrieved from all the traditional GNU ftp archive sites. + +GAS will need to be installed into a directory before @code{/bin}, +@code{/usr/bin}, and @code{/usr/ccs/bin} in your search path. You +should install GAS before you build GNU CC. + +To enable debugging, you must configure GNU CC with the @samp{--with-gnu-as} +option before building. + +@item i370-*-* +This port is very preliminary and has many known bugs. We hope to +have a higher-quality port for this machine soon. + +@item i386-*-linuxoldld +Use this configuration to generate a.out binaries on Linux if you do not +have gas/binutils version 2.5.2 or later installed. This is an obsolete +configuration. + +@item i386-*-linuxaout +Use this configuration to generate a.out binaries on Linux. This configuration +is being superseded. You must use gas/binutils version 2.5.2 or +later. + +@item i386-*-linux +Use this configuration to generate ELF binaries on Linux. You must +use gas/binutils version 2.5.2 or later. + +@item i386-*-sco +Compilation with RCC is recommended. Also, it may be a good idea to +link with GNU malloc instead of the malloc that comes with the system. + +@item i386-*-sco3.2v4 +Use this configuration for SCO release 3.2 version 4. + +@item i386-*-sco3.2v5* +Use this for SCO Open Server Release 5.0. GNU CC can generate ELF +binaries (if you specify @samp{-melf}) or COFF binaries (the default). +If you are going to build your compiler in ELF mode (once you have +bootstrapped the first stage compiler) you @strong{must} specify +@samp{-melf} as part of CC, @emph{not} CFLAGS. You should +use some variant of: @samp{CC="stage1/xgcc -melf" CFLAGS="-Bstage1/"} etc. +If you do not do this, the boostrap will generate completely bogus versions +of libgcc.a generated. + +You must have TLS597 (from ftp.sco.com/TLS) installed for ELF +binaries to work correctly. Note that Open Server 5.0.2 @emph{does} +need TLS597 installed. + +@item i386-*-isc +It may be a good idea to link with GNU malloc instead of the malloc that +comes with the system. + +In ISC version 4.1, @file{sed} core dumps when building +@file{deduced.h}. Use the version of @file{sed} from version 4.0. + +@item i386-*-esix +It may be good idea to link with GNU malloc instead of the malloc that +comes with the system. + +@item i386-ibm-aix +You need to use GAS version 2.1 or later, and LD from +GNU binutils version 2.2 or later. + +@item i386-sequent-bsd +Go to the Berkeley universe before compiling. In addition, you probably +need to create a file named @file{string.h} containing just one line: +@samp{#include }. + +@item i386-sequent-ptx1* +Sequent DYNIX/ptx 1.x. + +@item i386-sequent-ptx2* +Sequent DYNIX/ptx 2.x. + +@item i386-sun-sunos4 +You may find that you need another version of GNU CC to begin +bootstrapping with, since the current version when built with the +system's own compiler seems to get an infinite loop compiling part of +@file{libgcc2.c}. GNU CC version 2 compiled with GNU CC (any version) +seems not to have this problem. + +See @ref{Sun Install}, for information on installing GNU CC on Sun +systems. + +@item i[345]86-*-winnt3.5 +This version requires a GAS that has not let been released. Until it +is, you can get a prebuilt binary version via anonymous ftp from +@file{cs.washington.edu:pub/gnat} or @file{cs.nyu.edu:pub/gnat}. You +must also use the Microsoft header files from the Windows NT 3.5 SDK. +Find these on the CDROM in the @file{/mstools/h} directory dated 9/4/94. You +must use a fixed version of Microsoft linker made especially for NT 3.5, +which is also is available on the NT 3.5 SDK CDROM. If you do not have +this linker, can you also use the linker from Visual C/C++ 1.0 or 2.0. + +Installing GNU CC for NT builds a wrapper linker, called @file{ld.exe}, +which mimics the behaviour of Unix @file{ld} in the specification of +libraries (@samp{-L} and @samp{-l}). @file{ld.exe} looks for both Unix +and Microsoft named libraries. For example, if you specify +@samp{-lfoo}, @file{ld.exe} will look first for @file{libfoo.a} +and then for @file{foo.lib}. + +You may install GNU CC for Windows NT in one of two ways, depending on +whether or not you have a Unix-like shell and various Unix-like +utilities. + +@enumerate +@item +If you do not have a Unix-like shell and few Unix-like utilities, you +will use a DOS style batch script called @file{configure.bat}. Invoke +it as @code{configure winnt} from an MSDOS console window or from the +program manager dialog box. @file{configure.bat} assumes you have +already installed and have in your path a Unix-like @file{sed} program +which is used to create a working @file{Makefile} from @file{Makefile.in}. + +@file{Makefile} uses the Microsoft Nmake program maintenance utility and +the Visual C/C++ V8.00 compiler to build GNU CC. You need only have the +utilities @file{sed} and @file{touch} to use this installation method, +which only automatically builds the compiler itself. You must then +examine what @file{fixinc.winnt} does, edit the header files by hand and +build @file{libgcc.a} manually. + +@item +The second type of installation assumes you are running a Unix-like +shell, have a complete suite of Unix-like utilities in your path, and +have a previous version of GNU CC already installed, either through +building it via the above installation method or acquiring a pre-built +binary. In this case, use the @file{configure} script in the normal +fashion. +@end enumerate + +@item i860-intel-osf1 +This is the Paragon. +@ifset INSTALLONLY +If you have version 1.0 of the operating system, you need to take +special steps to build GNU CC due to peculiarities of the system. Newer +system versions have no problem. See the section `Installation Problems' +in the GNU CC Manual. +@end ifset +@ifclear INSTALLONLY +If you have version 1.0 of the operating system, +see @ref{Installation Problems}, for special things you need to do to +compensate for peculiarities in the system. +@end ifclear + +@item *-lynx-lynxos +LynxOS 2.2 and earlier comes with GNU CC 1.x already installed as +@file{/bin/gcc}. You should compile with this instead of @file{/bin/cc}. +You can tell GNU CC to use the GNU assembler and linker, by specifying +@samp{--with-gnu-as --with-gnu-ld} when configuring. These will produce +COFF format object files and executables; otherwise GNU CC will use the +installed tools, which produce a.out format executables. + +@item m68000-hp-bsd +HP 9000 series 200 running BSD. Note that the C compiler that comes +with this system cannot compile GNU CC; contact @code{law@@cs.utah.edu} +to get binaries of GNU CC for bootstrapping. + +@item m68k-altos +Altos 3068. You must use the GNU assembler, linker and debugger. +Also, you must fix a kernel bug. Details in the file @file{README.ALTOS}. + +@item m68k-apple-aux +Apple Macintosh running A/UX. +You may configure GCC to use either the system assembler and +linker or the GNU assembler and linker. You should use the GNU configuration +if you can, especially if you also want to use GNU C++. You enabled +that configuration with + the @samp{--with-gnu-as} and @samp{--with-gnu-ld} +options to @code{configure}. + +Note the C compiler that comes +with this system cannot compile GNU CC. You can fine binaries of GNU CC +for bootstrapping on @code{jagubox.gsfc.nasa.gov}. +You will also a patched version of @file{/bin/ld} there that +raises some of the arbitrary limits found in the original. + +@item m68k-att-sysv +AT&T 3b1, a.k.a. 7300 PC. Special procedures are needed to compile GNU +CC with this machine's standard C compiler, due to bugs in that +compiler. You can bootstrap it more easily with +previous versions of GNU CC if you have them. + +Installing GNU CC on the 3b1 is difficult if you do not already have +GNU CC running, due to bugs in the installed C compiler. However, +the following procedure might work. We are unable to test it. + +@enumerate +@item +Comment out the @samp{#include "config.h"} line on line 37 of +@file{cccp.c} and do @samp{make cpp}. This makes a preliminary version +of GNU cpp. + +@item +Save the old @file{/lib/cpp} and copy the preliminary GNU cpp to that +file name. + +@item +Undo your change in @file{cccp.c}, or reinstall the original version, +and do @samp{make cpp} again. + +@item +Copy this final version of GNU cpp into @file{/lib/cpp}. + +@findex obstack_free +@item +Replace every occurrence of @code{obstack_free} in the file +@file{tree.c} with @code{_obstack_free}. + +@item +Run @code{make} to get the first-stage GNU CC. + +@item +Reinstall the original version of @file{/lib/cpp}. + +@item +Now you can compile GNU CC with itself and install it in the normal +fashion. +@end enumerate + +@item m68k-bull-sysv +Bull DPX/2 series 200 and 300 with BOS-2.00.45 up to BOS-2.01. GNU CC works +either with native assembler or GNU assembler. You can use +GNU assembler with native coff generation by providing @samp{--with-gnu-as} to +the configure script or use GNU assembler with dbx-in-coff encapsulation +by providing @samp{--with-gnu-as --stabs}. For any problem with native +assembler or for availability of the DPX/2 port of GAS, contact +@code{F.Pierresteguy@@frcl.bull.fr}. + +@item m68k-crds-unox +Use @samp{configure unos} for building on Unos. + +The Unos assembler is named @code{casm} instead of @code{as}. For some +strange reason linking @file{/bin/as} to @file{/bin/casm} changes the +behavior, and does not work. So, when installing GNU CC, you should +install the following script as @file{as} in the subdirectory where +the passes of GCC are installed: + +@example +#!/bin/sh +casm $* +@end example + +The default Unos library is named @file{libunos.a} instead of +@file{libc.a}. To allow GNU CC to function, either change all +references to @samp{-lc} in @file{gcc.c} to @samp{-lunos} or link +@file{/lib/libc.a} to @file{/lib/libunos.a}. + +@cindex @code{alloca}, for Unos +When compiling GNU CC with the standard compiler, to overcome bugs in +the support of @code{alloca}, do not use @samp{-O} when making stage 2. +Then use the stage 2 compiler with @samp{-O} to make the stage 3 +compiler. This compiler will have the same characteristics as the usual +stage 2 compiler on other systems. Use it to make a stage 4 compiler +and compare that with stage 3 to verify proper compilation. + +(Perhaps simply defining @code{ALLOCA} in @file{x-crds} as described in +the comments there will make the above paragraph superfluous. Please +inform us of whether this works.) + +Unos uses memory segmentation instead of demand paging, so you will need +a lot of memory. 5 Mb is barely enough if no other tasks are running. +If linking @file{cc1} fails, try putting the object files into a library +and linking from that library. + +@item m68k-hp-hpux +HP 9000 series 300 or 400 running HP-UX. HP-UX version 8.0 has a bug in +the assembler that prevents compilation of GNU CC. To fix it, get patch +PHCO_4484 from HP. + +In addition, if you wish to use gas @samp{--with-gnu-as} you must use +gas version 2.1 or later, and you must use the GNU linker version 2.1 or +later. Earlier versions of gas relied upon a program which converted the +gas output into the native HP/UX format, but that program has not been +kept up to date. gdb does not understand that native HP/UX format, so +you must use gas if you wish to use gdb. + +@item m68k-sun +Sun 3. We do not provide a configuration file to use the Sun FPA by +default, because programs that establish signal handlers for floating +point traps inherently cannot work with the FPA. + +See @ref{Sun Install}, for information on installing GNU CC on Sun +systems. + +@item m88k-*-svr3 +Motorola m88k running the AT&T/Unisoft/Motorola V.3 reference port. +These systems tend to use the Green Hills C, revision 1.8.5, as the +standard C compiler. There are apparently bugs in this compiler that +result in object files differences between stage 2 and stage 3. If this +happens, make the stage 4 compiler and compare it to the stage 3 +compiler. If the stage 3 and stage 4 object files are identical, this +suggests you encountered a problem with the standard C compiler; the +stage 3 and 4 compilers may be usable. + +It is best, however, to use an older version of GNU CC for bootstrapping +if you have one. + +@item m88k-*-dgux +Motorola m88k running DG/UX. To build 88open BCS native or cross +compilers on DG/UX, specify the configuration name as +@samp{m88k-*-dguxbcs} and build in the 88open BCS software development +environment. To build ELF native or cross compilers on DG/UX, specify +@samp{m88k-*-dgux} and build in the DG/UX ELF development environment. +You set the software development environment by issuing +@samp{sde-target} command and specifying either @samp{m88kbcs} or +@samp{m88kdguxelf} as the operand. + +If you do not specify a configuration name, @file{configure} guesses the +configuration based on the current software development environment. + +@item m88k-tektronix-sysv3 +Tektronix XD88 running UTekV 3.2e. Do not turn on +optimization while building stage1 if you bootstrap with +the buggy Green Hills compiler. Also, The bundled LAI +System V NFS is buggy so if you build in an NFS mounted +directory, start from a fresh reboot, or avoid NFS all together. +Otherwise you may have trouble getting clean comparisons +between stages. + +@item mips-mips-bsd +MIPS machines running the MIPS operating system in BSD mode. It's +possible that some old versions of the system lack the functions +@code{memcpy}, @code{memcmp}, and @code{memset}. If your system lacks +these, you must remove or undo the definition of +@code{TARGET_MEM_FUNCTIONS} in @file{mips-bsd.h}. + +The MIPS C compiler needs to be told to increase its table size +for switch statements with the @samp{-Wf,-XNg1500} option in +order to compile @file{cp/parse.c}. If you use the @samp{-O2} +optimization option, you also need to use @samp{-Olimit 3000}. +Both of these options are automatically generated in the +@file{Makefile} that the shell script @file{configure} builds. +If you override the @code{CC} make variable and use the MIPS +compilers, you may need to add @samp{-Wf,-XNg1500 -Olimit 3000}. + +@item mips-mips-riscos* +The MIPS C compiler needs to be told to increase its table size +for switch statements with the @samp{-Wf,-XNg1500} option in +order to compile @file{cp/parse.c}. If you use the @samp{-O2} +optimization option, you also need to use @samp{-Olimit 3000}. +Both of these options are automatically generated in the +@file{Makefile} that the shell script @file{configure} builds. +If you override the @code{CC} make variable and use the MIPS +compilers, you may need to add @samp{-Wf,-XNg1500 -Olimit 3000}. + +MIPS computers running RISC-OS can support four different +personalities: default, BSD 4.3, System V.3, and System V.4 +(older versions of RISC-OS don't support V.4). To configure GCC +for these platforms use the following configurations: + +@table @samp +@item mips-mips-riscos@code{rev} +Default configuration for RISC-OS, revision @code{rev}. + +@item mips-mips-riscos@code{rev}bsd +BSD 4.3 configuration for RISC-OS, revision @code{rev}. + +@item mips-mips-riscos@code{rev}sysv4 +System V.4 configuration for RISC-OS, revision @code{rev}. + +@item mips-mips-riscos@code{rev}sysv +System V.3 configuration for RISC-OS, revision @code{rev}. +@end table + +The revision @code{rev} mentioned above is the revision of +RISC-OS to use. You must reconfigure GCC when going from a +RISC-OS revision 4 to RISC-OS revision 5. This has the effect of +avoiding a linker +@ifclear INSTALLONLY +bug (see @ref{Installation Problems}, for more details). +@end ifclear +@ifset INSTALLONLY +bug. +@end ifset + +@item mips-sgi-* +In order to compile GCC on an SGI running IRIX 4, the "c.hdr.lib" +option must be installed from the CD-ROM supplied from Silicon Graphics. +This is found on the 2nd CD in release 4.0.1. + +In order to compile GCC on an SGI running IRIX 5, the "compiler_dev.hdr" +subsystem must be installed from the IDO CD-ROM supplied by Silicon +Graphics. + +@code{make compare} may fail on version 5 of IRIX unless you add +@samp{-save-temps} to @code{CFLAGS}. On these systems, the name of the +assembler input file is stored in the object file, and that makes +comparison fail if it differs between the @code{stage1} and +@code{stage2} compilations. The option @samp{-save-temps} forces a +fixed name to be used for the assembler input file, instead of a +randomly chosen name in @file{/tmp}. Do not add @samp{-save-temps} +unless the comparisons fail without that option. If you do you +@samp{-save-temps}, you will have to manually delete the @samp{.i} and +@samp{.s} files after each series of compilations. + +The MIPS C compiler needs to be told to increase its table size +for switch statements with the @samp{-Wf,-XNg1500} option in +order to compile @file{cp/parse.c}. If you use the @samp{-O2} +optimization option, you also need to use @samp{-Olimit 3000}. +Both of these options are automatically generated in the +@file{Makefile} that the shell script @file{configure} builds. +If you override the @code{CC} make variable and use the MIPS +compilers, you may need to add @samp{-Wf,-XNg1500 -Olimit 3000}. + +On Irix version 4.0.5F, and perhaps on some other versions as well, +there is an assembler bug that reorders instructions incorrectly. To +work around it, specify the target configuration +@samp{mips-sgi-irix4loser}. This configuration inhibits assembler +optimization. + +In a compiler configured with target @samp{mips-sgi-irix4}, you can turn +off assembler optimization by using the @samp{-noasmopt} option. This +compiler option passes the option @samp{-O0} to the assembler, to +inhibit reordering. + +The @samp{-noasmopt} option can be useful for testing whether a problem +is due to erroneous assembler reordering. Even if a problem does not go +away with @samp{-noasmopt}, it may still be due to assembler +reordering---perhaps GNU CC itself was miscompiled as a result. + +To enable debugging under Irix 5, you must use GNU as 2.5 or later, +and use the @samp{--with-gnu-as} configure option when configuring gcc. +GNU as is distributed as part of the binutils package. + +@item mips-sony-sysv +Sony MIPS NEWS. This works in NEWSOS 5.0.1, but not in 5.0.2 (which +uses ELF instead of COFF). Support for 5.0.2 will probably be provided +soon by volunteers. In particular, the linker does not like the +code generated by GCC when shared libraries are linked in. + +@item ns32k-encore +Encore ns32000 system. Encore systems are supported only under BSD. + +@item ns32k-*-genix +National Semiconductor ns32000 system. Genix has bugs in @code{alloca} +and @code{malloc}; you must get the compiled versions of these from GNU +Emacs. + +@item ns32k-sequent +Go to the Berkeley universe before compiling. In addition, you probably +need to create a file named @file{string.h} containing just one line: +@samp{#include }. + +@item ns32k-utek +UTEK ns32000 system (``merlin''). The C compiler that comes with this +system cannot compile GNU CC; contact @samp{tektronix!reed!mason} to get +binaries of GNU CC for bootstrapping. + +@item romp-*-aos +@itemx romp-*-mach +The only operating systems supported for the IBM RT PC are AOS and +MACH. GNU CC does not support AIX running on the RT. We recommend you +compile GNU CC with an earlier version of itself; if you compile GNU CC +with @code{hc}, the Metaware compiler, it will work, but you will get +mismatches between the stage 2 and stage 3 compilers in various files. +These errors are minor differences in some floating-point constants and +can be safely ignored; the stage 3 compiler is correct. + +@item rs6000-*-aix +@itemx powerpc-*-aix +Various early versions of each release of the IBM XLC compiler will not +bootstrap GNU CC. Symptoms include differences between the stage2 and +stage3 object files, and errors when compiling @file{libgcc.a} or +@file{enquire}. Known problematic releases include: xlc-1.2.1.8, +xlc-1.3.0.0 (distributed with AIX 3.2.5), and xlc-1.3.0.19. Both +xlc-1.2.1.28 and xlc-1.3.0.24 (PTF 432238) are known to produce working +versions of GNU CC, but most other recent releases correctly bootstrap +GNU CC. Also, releases of AIX prior to AIX 3.2.4 include a version of +the IBM assembler which does not accept debugging directives: assembler +updates are available as PTFs. Also, if you are using AIX 3.2.5 or +greater and the GNU assembler, you must have a version modified after +October 16th, 1995 in order for the GNU C compiler to build. See the +file @file{README.RS6000} for more details on of these problems. + +GNU CC does not yet support the 64-bit PowerPC instructions. + +Objective C does not work on this architecture because it makes assumptions +that are incompatible with the calling conventions. + +AIX on the RS/6000 provides support (NLS) for environments outside of +the United States. Compilers and assemblers use NLS to support +locale-specific representations of various objects including +floating-point numbers ("." vs "," for separating decimal fractions). +There have been problems reported where the library linked with GNU CC +does not produce the same floating-point formats that the assembler +accepts. If you have this problem, set the LANG environment variable to +"C" or "En_US". + +Due to changes in the way that GNU CC invokes the binder (linker) for AIX +4.1, you may now receive warnings of duplicate symbols from the link step +that were not reported before. The assembly files generated by GNU CC for +AIX have always included multiple symbol definitions for certain global +variable and function declarations in the original program. The warnings +should not prevent the linker from producing a correct library or runnable +executable. + +By default, AIX 4.1 produces code that can be used on either Power or +PowerPC processors. + +You can specify a default version for the @samp{-mcpu=}@var{cpu_type} +switch by using the configure option @samp{--with-cpu-}@var{cpu_type}. + +@item powerpc-*-elf +@itemx powerpc-*-sysv4 +PowerPC system in big endian mode, running System V.4. + +You can specify a default version for the @samp{-mcpu=}@var{cpu_type} +switch by using the configure option @samp{--with-cpu-}@var{cpu_type}. + +@item powerpc-*-linux +PowerPC system in big endian mode, running Linux. + +You can specify a default version for the @samp{-mcpu=}@var{cpu_type} +switch by using the configure option @samp{--with-cpu-}@var{cpu_type}. + +@item powerpc-*-eabiaix +Embedded PowerPC system in big endian mode with -mcall-aix selected as +the default. + +You can specify a default version for the @samp{-mcpu=}@var{cpu_type} +switch by using the configure option @samp{--with-cpu-}@var{cpu_type}. + +@item powerpc-*-eabisim +Embedded PowerPC system in big endian mode for use in running under the +PSIM simulator. + +You can specify a default version for the @samp{-mcpu=}@var{cpu_type} +switch by using the configure option @samp{--with-cpu-}@var{cpu_type}. + +@item powerpc-*-eabi +Embedded PowerPC system in big endian mode. + +You can specify a default version for the @samp{-mcpu=}@var{cpu_type} +switch by using the configure option @samp{--with-cpu-}@var{cpu_type}. + +@item powerpcle-*-elf +@itemx powerpcle-*-sysv4 +PowerPC system in little endian mode, running System V.4. + +You can specify a default version for the @samp{-mcpu=}@var{cpu_type} +switch by using the configure option @samp{--with-cpu-}@var{cpu_type}. + +@item powerpcle-*-solaris2* +PowerPC system in little endian mode, running Solaris 2.5.1 or higher. + +You can specify a default version for the @samp{-mcpu=}@var{cpu_type} +switch by using the configure option @samp{--with-cpu-}@var{cpu_type}. +Beta versions of the Sun 4.0 compiler do not seem to be able to build +GNU CC correctly. There are also problems with the host assembler and +linker that are fixed by using the GNU versions of these tools. + +@item powerpcle-*-eabisim +Embedded PowerPC system in little endian mode for use in running under +the PSIM simulator. + +@itemx powerpcle-*-eabi +Embedded PowerPC system in little endian mode. + +You can specify a default version for the @samp{-mcpu=}@var{cpu_type} +switch by using the configure option @samp{--with-cpu-}@var{cpu_type}. + +@item powerpcle-*-winnt +@itemx powerpcle-*-pe +PowerPC system in little endian mode running Windows NT. + +You can specify a default version for the @samp{-mcpu=}@var{cpu_type} +switch by using the configure option @samp{--with-cpu-}@var{cpu_type}. + +@item vax-dec-ultrix +Don't try compiling with Vax C (@code{vcc}). It produces incorrect code +in some cases (for example, when @code{alloca} is used). + +Meanwhile, compiling @file{cp/parse.c} with pcc does not work because of +an internal table size limitation in that compiler. To avoid this +problem, compile just the GNU C compiler first, and use it to recompile +building all the languages that you want to run. + +@item sparc-sun-* +@item sparc64-sun-* +See @ref{Sun Install}, for information on installing GNU CC on Sun +systems. + +@item vax-dec-vms +See @ref{VMS Install}, for details on how to install GNU CC on VMS. + +@item we32k-*-* +These computers are also known as the 3b2, 3b5, 3b20 and other similar +names. (However, the 3b1 is actually a 68000; see +@ref{Configurations}.) + +Don't use @samp{-g} when compiling with the system's compiler. The +system's linker seems to be unable to handle such a large program with +debugging information. + +The system's compiler runs out of capacity when compiling @file{stmt.c} +in GNU CC. You can work around this by building @file{cpp} in GNU CC +first, then use that instead of the system's preprocessor with the +system's C compiler to compile @file{stmt.c}. Here is how: + +@smallexample +mv /lib/cpp /lib/cpp.att +cp cpp /lib/cpp.gnu +echo '/lib/cpp.gnu -traditional $@{1+"$@@"@}' > /lib/cpp +chmod +x /lib/cpp +@end smallexample + +The system's compiler produces bad code for some of the GNU CC +optimization files. So you must build the stage 2 compiler without +optimization. Then build a stage 3 compiler with optimization. +That executable should work. Here are the necessary commands: + +@smallexample +make LANGUAGES=c CC=stage1/xgcc CFLAGS="-Bstage1/ -g" +make stage2 +make CC=stage2/xgcc CFLAGS="-Bstage2/ -g -O" +@end smallexample + +You may need to raise the ULIMIT setting to build a C++ compiler, +as the file @file{cc1plus} is larger than one megabyte. +@end table + +@node Other Dir +@section Compilation in a Separate Directory +@cindex other directory, compilation in +@cindex compilation in a separate directory +@cindex separate directory, compilation in + +If you wish to build the object files and executables in a directory +other than the one containing the source files, here is what you must +do differently: + +@enumerate +@item +Make sure you have a version of Make that supports the @code{VPATH} +feature. (GNU Make supports it, as do Make versions on most BSD +systems.) + +@item +If you have ever run @file{configure} in the source directory, you must undo +the configuration. Do this by running: + +@example +make distclean +@end example + +@item +Go to the directory in which you want to build the compiler before +running @file{configure}: + +@example +mkdir gcc-sun3 +cd gcc-sun3 +@end example + +On systems that do not support symbolic links, this directory must be +on the same file system as the source code directory. + +@item +Specify where to find @file{configure} when you run it: + +@example +../gcc/configure @dots{} +@end example + +This also tells @code{configure} where to find the compiler sources; +@code{configure} takes the directory from the file name that was used to +invoke it. But if you want to be sure, you can specify the source +directory with the @samp{--srcdir} option, like this: + +@example +../gcc/configure --srcdir=../gcc @var{other options} +@end example + +The directory you specify with @samp{--srcdir} need not be the same +as the one that @code{configure} is found in. +@end enumerate + +Now, you can run @code{make} in that directory. You need not repeat the +configuration steps shown above, when ordinary source files change. You +must, however, run @code{configure} again when the configuration files +change, if your system does not support symbolic links. + +@node Cross-Compiler +@section Building and Installing a Cross-Compiler +@cindex cross-compiler, installation + +GNU CC can function as a cross-compiler for many machines, but not all. + +@itemize @bullet +@item +Cross-compilers for the Mips as target using the Mips assembler +currently do not work, because the auxiliary programs +@file{mips-tdump.c} and @file{mips-tfile.c} can't be compiled on +anything but a Mips. It does work to cross compile for a Mips +if you use the GNU assembler and linker. + +@item +Cross-compilers between machines with different floating point formats +have not all been made to work. GNU CC now has a floating point +emulator with which these can work, but each target machine description +needs to be updated to take advantage of it. + +@item +Cross-compilation between machines of different word sizes is +somewhat problematic and sometimes does not work. +@end itemize + +Since GNU CC generates assembler code, you probably need a +cross-assembler that GNU CC can run, in order to produce object files. +If you want to link on other than the target machine, you need a +cross-linker as well. You also need header files and libraries suitable +for the target machine that you can install on the host machine. + +@menu +* Steps of Cross:: Using a cross-compiler involves several steps + that may be carried out on different machines. +* Configure Cross:: Configuring a cross-compiler. +* Tools and Libraries:: Where to put the linker and assembler, and the C library. +* Cross Headers:: Finding and installing header files + for a cross-compiler. +* Cross Runtime:: Supplying arithmetic runtime routines (@file{libgcc1.a}). +* Build Cross:: Actually compiling the cross-compiler. +@end menu + +@node Steps of Cross +@subsection Steps of Cross-Compilation + +To compile and run a program using a cross-compiler involves several +steps: + +@itemize @bullet +@item +Run the cross-compiler on the host machine to produce assembler files +for the target machine. This requires header files for the target +machine. + +@item +Assemble the files produced by the cross-compiler. You can do this +either with an assembler on the target machine, or with a +cross-assembler on the host machine. + +@item +Link those files to make an executable. You can do this either with a +linker on the target machine, or with a cross-linker on the host +machine. Whichever machine you use, you need libraries and certain +startup files (typically @file{crt@dots{}.o}) for the target machine. +@end itemize + +It is most convenient to do all of these steps on the same host machine, +since then you can do it all with a single invocation of GNU CC. This +requires a suitable cross-assembler and cross-linker. For some targets, +the GNU assembler and linker are available. + +@node Configure Cross +@subsection Configuring a Cross-Compiler + +To build GNU CC as a cross-compiler, you start out by running +@file{configure}. Use the @samp{--target=@var{target}} to specify the +target type. If @file{configure} was unable to correctly identify the +system you are running on, also specify the @samp{--build=@var{build}} +option. For example, here is how to configure for a cross-compiler that +produces code for an HP 68030 system running BSD on a system that +@file{configure} can correctly identify: + +@smallexample +./configure --target=m68k-hp-bsd4.3 +@end smallexample + +@node Tools and Libraries +@subsection Tools and Libraries for a Cross-Compiler + +If you have a cross-assembler and cross-linker available, you should +install them now. Put them in the directory +@file{/usr/local/@var{target}/bin}. Here is a table of the tools +you should put in this directory: + +@table @file +@item as +This should be the cross-assembler. + +@item ld +This should be the cross-linker. + +@item ar +This should be the cross-archiver: a program which can manipulate +archive files (linker libraries) in the target machine's format. + +@item ranlib +This should be a program to construct a symbol table in an archive file. +@end table + +The installation of GNU CC will find these programs in that directory, +and copy or link them to the proper place to for the cross-compiler to +find them when run later. + +The easiest way to provide these files is to build the Binutils package +and GAS. Configure them with the same @samp{--host} and @samp{--target} +options that you use for configuring GNU CC, then build and install +them. They install their executables automatically into the proper +directory. Alas, they do not support all the targets that GNU CC +supports. + +If you want to install libraries to use with the cross-compiler, such as +a standard C library, put them in the directory +@file{/usr/local/@var{target}/lib}; installation of GNU CC copies +all the files in that subdirectory into the proper place for GNU CC to +find them and link with them. Here's an example of copying some +libraries from a target machine: + +@example +ftp @var{target-machine} +lcd /usr/local/@var{target}/lib +cd /lib +get libc.a +cd /usr/lib +get libg.a +get libm.a +quit +@end example + +@noindent +The precise set of libraries you'll need, and their locations on +the target machine, vary depending on its operating system. + +@cindex start files +Many targets require ``start files'' such as @file{crt0.o} and +@file{crtn.o} which are linked into each executable; these too should be +placed in @file{/usr/local/@var{target}/lib}. There may be several +alternatives for @file{crt0.o}, for use with profiling or other +compilation options. Check your target's definition of +@code{STARTFILE_SPEC} to find out what start files it uses. +Here's an example of copying these files from a target machine: + +@example +ftp @var{target-machine} +lcd /usr/local/@var{target}/lib +prompt +cd /lib +mget *crt*.o +cd /usr/lib +mget *crt*.o +quit +@end example + +@node Cross Runtime +@subsection @file{libgcc.a} and Cross-Compilers + +Code compiled by GNU CC uses certain runtime support functions +implicitly. Some of these functions can be compiled successfully with +GNU CC itself, but a few cannot be. These problem functions are in the +source file @file{libgcc1.c}; the library made from them is called +@file{libgcc1.a}. + +When you build a native compiler, these functions are compiled with some +other compiler--the one that you use for bootstrapping GNU CC. +Presumably it knows how to open code these operations, or else knows how +to call the run-time emulation facilities that the machine comes with. +But this approach doesn't work for building a cross-compiler. The +compiler that you use for building knows about the host system, not the +target system. + +So, when you build a cross-compiler you have to supply a suitable +library @file{libgcc1.a} that does the job it is expected to do. + +To compile @file{libgcc1.c} with the cross-compiler itself does not +work. The functions in this file are supposed to implement arithmetic +operations that GNU CC does not know how to open code for your target +machine. If these functions are compiled with GNU CC itself, they +will compile into infinite recursion. + +On any given target, most of these functions are not needed. If GNU CC +can open code an arithmetic operation, it will not call these functions +to perform the operation. It is possible that on your target machine, +none of these functions is needed. If so, you can supply an empty +library as @file{libgcc1.a}. + +Many targets need library support only for multiplication and division. +If you are linking with a library that contains functions for +multiplication and division, you can tell GNU CC to call them directly +by defining the macros @code{MULSI3_LIBCALL}, and the like. These +macros need to be defined in the target description macro file. For +some targets, they are defined already. This may be sufficient to +avoid the need for libgcc1.a; if so, you can supply an empty library. + +Some targets do not have floating point instructions; they need other +functions in @file{libgcc1.a}, which do floating arithmetic. +Recent versions of GNU CC have a file which emulates floating point. +With a certain amount of work, you should be able to construct a +floating point emulator that can be used as @file{libgcc1.a}. Perhaps +future versions will contain code to do this automatically and +conveniently. That depends on whether someone wants to implement it. + +Some embedded targets come with all the necessary @file{libgcc1.a} +routines written in C or assembler. These targets build +@file{libgcc1.a} automatically and you do not need to do anything +special for them. Other embedded targets do not need any +@file{libgcc1.a} routines since all the necessary operations are +supported by the hardware. + +If your target system has another C compiler, you can configure GNU CC +as a native compiler on that machine, build just @file{libgcc1.a} with +@samp{make libgcc1.a} on that machine, and use the resulting file with +the cross-compiler. To do this, execute the following on the target +machine: + +@example +cd @var{target-build-dir} +./configure --host=sparc --target=sun3 +make libgcc1.a +@end example + +@noindent +And then this on the host machine: + +@example +ftp @var{target-machine} +binary +cd @var{target-build-dir} +get libgcc1.a +quit +@end example + +Another way to provide the functions you need in @file{libgcc1.a} is to +define the appropriate @code{perform_@dots{}} macros for those +functions. If these definitions do not use the C arithmetic operators +that they are meant to implement, you should be able to compile them +with the cross-compiler you are building. (If these definitions already +exist for your target file, then you are all set.) + +To build @file{libgcc1.a} using the perform macros, use +@samp{LIBGCC1=libgcc1.a OLDCC=./xgcc} when building the compiler. +Otherwise, you should place your replacement library under the name +@file{libgcc1.a} in the directory in which you will build the +cross-compiler, before you run @code{make}. + +@node Cross Headers +@subsection Cross-Compilers and Header Files + +If you are cross-compiling a standalone program or a program for an +embedded system, then you may not need any header files except the few +that are part of GNU CC (and those of your program). However, if you +intend to link your program with a standard C library such as +@file{libc.a}, then you probably need to compile with the header files +that go with the library you use. + +The GNU C compiler does not come with these files, because (1) they are +system-specific, and (2) they belong in a C library, not in a compiler. + +If the GNU C library supports your target machine, then you can get the +header files from there (assuming you actually use the GNU library when +you link your program). + +If your target machine comes with a C compiler, it probably comes with +suitable header files also. If you make these files accessible from the host +machine, the cross-compiler can use them also. + +Otherwise, you're on your own in finding header files to use when +cross-compiling. + +When you have found suitable header files, put them in the directory +@file{/usr/local/@var{target}/include}, before building the cross +compiler. Then installation will run fixincludes properly and install +the corrected versions of the header files where the compiler will use +them. + +Provide the header files before you build the cross-compiler, because +the build stage actually runs the cross-compiler to produce parts of +@file{libgcc.a}. (These are the parts that @emph{can} be compiled with +GNU CC.) Some of them need suitable header files. + +Here's an example showing how to copy the header files from a target +machine. On the target machine, do this: + +@example +(cd /usr/include; tar cf - .) > tarfile +@end example + +Then, on the host machine, do this: + +@example +ftp @var{target-machine} +lcd /usr/local/@var{target}/include +get tarfile +quit +tar xf tarfile +@end example + +@node Build Cross +@subsection Actually Building the Cross-Compiler + +Now you can proceed just as for compiling a single-machine compiler +through the step of building stage 1. If you have not provided some +sort of @file{libgcc1.a}, then compilation will give up at the point +where it needs that file, printing a suitable error message. If you +do provide @file{libgcc1.a}, then building the compiler will automatically +compile and link a test program called @file{libgcc1-test}; if you get +errors in the linking, it means that not all of the necessary routines +in @file{libgcc1.a} are available. + +You must provide the header file @file{float.h}. One way to do this is +to compile @file{enquire} and run it on your target machine. The job of +@file{enquire} is to run on the target machine and figure out by +experiment the nature of its floating point representation. +@file{enquire} records its findings in the header file @file{float.h}. +If you can't produce this file by running @file{enquire} on the target +machine, then you will need to come up with a suitable @file{float.h} in +some other way (or else, avoid using it in your programs). + +Do not try to build stage 2 for a cross-compiler. It doesn't work to +rebuild GNU CC as a cross-compiler using the cross-compiler, because +that would produce a program that runs on the target machine, not on the +host. For example, if you compile a 386-to-68030 cross-compiler with +itself, the result will not be right either for the 386 (because it was +compiled into 68030 code) or for the 68030 (because it was configured +for a 386 as the host). If you want to compile GNU CC into 68030 code, +whether you compile it on a 68030 or with a cross-compiler on a 386, you +must specify a 68030 as the host when you configure it. + +To install the cross-compiler, use @samp{make install}, as usual. + +@node Sun Install +@section Installing GNU CC on the Sun +@cindex Sun installation +@cindex installing GNU CC on the Sun + +On Solaris (version 2.1), do not use the linker or other tools in +@file{/usr/ucb} to build GNU CC. Use @code{/usr/ccs/bin}. + +Make sure the environment variable @code{FLOAT_OPTION} is not set when +you compile @file{libgcc.a}. If this option were set to @code{f68881} +when @file{libgcc.a} is compiled, the resulting code would demand to be +linked with a special startup file and would not link properly without +special pains. + +@cindex @code{alloca}, for SunOS +There is a bug in @code{alloca} in certain versions of the Sun library. +To avoid this bug, install the binaries of GNU CC that were compiled by +GNU CC. They use @code{alloca} as a built-in function and never the one +in the library. + +Some versions of the Sun compiler crash when compiling GNU CC. The +problem is a segmentation fault in cpp. This problem seems to be due to +the bulk of data in the environment variables. You may be able to avoid +it by using the following command to compile GNU CC with Sun CC: + +@example +make CC="TERMCAP=x OBJS=x LIBFUNCS=x STAGESTUFF=x cc" +@end example + +SunOS 4.1.3 and 4.1.3_U1 have bugs that can cause intermittent core +dumps when compiling GNU CC. A common symptom is an +internal compiler error which does not recur if you run it again. +To fix the problem, install Sun recommended patch 100726 (for SunOS 4.1.3) +or 101508 (for SunOS 4.1.3_U1), or upgrade to a later SunOS release. + +@node VMS Install +@section Installing GNU CC on VMS +@cindex VMS installation +@cindex installing GNU CC on VMS + +The VMS version of GNU CC is distributed in a backup saveset containing +both source code and precompiled binaries. + +To install the @file{gcc} command so you can use the compiler easily, in +the same manner as you use the VMS C compiler, you must install the VMS CLD +file for GNU CC as follows: + +@enumerate +@item +Define the VMS logical names @samp{GNU_CC} and @samp{GNU_CC_INCLUDE} +to point to the directories where the GNU CC executables +(@file{gcc-cpp.exe}, @file{gcc-cc1.exe}, etc.) and the C include files are +kept respectively. This should be done with the commands:@refill + +@smallexample +$ assign /system /translation=concealed - + disk:[gcc.] gnu_cc +$ assign /system /translation=concealed - + disk:[gcc.include.] gnu_cc_include +@end smallexample + +@noindent +with the appropriate disk and directory names. These commands can be +placed in your system startup file so they will be executed whenever +the machine is rebooted. You may, if you choose, do this via the +@file{GCC_INSTALL.COM} script in the @file{[GCC]} directory. + +@item +Install the @file{GCC} command with the command line: + +@smallexample +$ set command /table=sys$common:[syslib]dcltables - + /output=sys$common:[syslib]dcltables gnu_cc:[000000]gcc +$ install replace sys$common:[syslib]dcltables +@end smallexample + +@item +To install the help file, do the following: + +@smallexample +$ library/help sys$library:helplib.hlb gcc.hlp +@end smallexample + +@noindent +Now you can invoke the compiler with a command like @samp{gcc /verbose +file.c}, which is equivalent to the command @samp{gcc -v -c file.c} in +Unix. +@end enumerate + +If you wish to use GNU C++ you must first install GNU CC, and then +perform the following steps: + +@enumerate +@item +Define the VMS logical name @samp{GNU_GXX_INCLUDE} to point to the +directory where the preprocessor will search for the C++ header files. +This can be done with the command:@refill + +@smallexample +$ assign /system /translation=concealed - + disk:[gcc.gxx_include.] gnu_gxx_include +@end smallexample + +@noindent +with the appropriate disk and directory name. If you are going to be +using libg++, this is where the libg++ install procedure will install +the libg++ header files. + +@item +Obtain the file @file{gcc-cc1plus.exe}, and place this in the same +directory that @file{gcc-cc1.exe} is kept. + +The GNU C++ compiler can be invoked with a command like @samp{gcc /plus +/verbose file.cc}, which is equivalent to the command @samp{g++ -v -c +file.cc} in Unix. +@end enumerate + +We try to put corresponding binaries and sources on the VMS distribution +tape. But sometimes the binaries will be from an older version than the +sources, because we don't always have time to update them. (Use the +@samp{/version} option to determine the version number of the binaries and +compare it with the source file @file{version.c} to tell whether this is +so.) In this case, you should use the binaries you get to recompile the +sources. If you must recompile, here is how: + +@enumerate +@item +Execute the command procedure @file{vmsconfig.com} to set up the files +@file{tm.h}, @file{config.h}, @file{aux-output.c}, and @file{md.}, and +to create files @file{tconfig.h} and @file{hconfig.h}. This procedure +also creates several linker option files used by @file{make-cc1.com} and +a data file used by @file{make-l2.com}.@refill + +@smallexample +$ @@vmsconfig.com +@end smallexample + +@item +Setup the logical names and command tables as defined above. In +addition, define the VMS logical name @samp{GNU_BISON} to point at the +to the directories where the Bison executable is kept. This should be +done with the command:@refill + +@smallexample +$ assign /system /translation=concealed - + disk:[bison.] gnu_bison +@end smallexample + +You may, if you choose, use the @file{INSTALL_BISON.COM} script in the +@file{[BISON]} directory. + +@item +Install the @samp{BISON} command with the command line:@refill + +@smallexample +$ set command /table=sys$common:[syslib]dcltables - + /output=sys$common:[syslib]dcltables - + gnu_bison:[000000]bison +$ install replace sys$common:[syslib]dcltables +@end smallexample + +@item +Type @samp{@@make-gcc} to recompile everything (alternatively, submit +the file @file{make-gcc.com} to a batch queue). If you wish to build +the GNU C++ compiler as well as the GNU CC compiler, you must first edit +@file{make-gcc.com} and follow the instructions that appear in the +comments.@refill + +@item +In order to use GCC, you need a library of functions which GCC compiled code +will call to perform certain tasks, and these functions are defined in the +file @file{libgcc2.c}. To compile this you should use the command procedure +@file{make-l2.com}, which will generate the library @file{libgcc2.olb}. +@file{libgcc2.olb} should be built using the compiler built from +the same distribution that @file{libgcc2.c} came from, and +@file{make-gcc.com} will automatically do all of this for you. + +To install the library, use the following commands:@refill + +@smallexample +$ library gnu_cc:[000000]gcclib/delete=(new,eprintf) +$ library gnu_cc:[000000]gcclib/delete=L_* +$ library libgcc2/extract=*/output=libgcc2.obj +$ library gnu_cc:[000000]gcclib libgcc2.obj +@end smallexample + +The first command simply removes old modules that will be replaced with +modules from @file{libgcc2} under different module names. The modules +@code{new} and @code{eprintf} may not actually be present in your +@file{gcclib.olb}---if the VMS librarian complains about those modules +not being present, simply ignore the message and continue on with the +next command. The second command removes the modules that came from the +previous version of the library @file{libgcc2.c}. + +Whenever you update the compiler on your system, you should also update the +library with the above procedure. + +@item +You may wish to build GCC in such a way that no files are written to the +directory where the source files reside. An example would be the when +the source files are on a read-only disk. In these cases, execute the +following DCL commands (substituting your actual path names): + +@smallexample +$ assign dua0:[gcc.build_dir.]/translation=concealed, - + dua1:[gcc.source_dir.]/translation=concealed gcc_build +$ set default gcc_build:[000000] +@end smallexample + +@noindent +where the directory @file{dua1:[gcc.source_dir]} contains the source +code, and the directory @file{dua0:[gcc.build_dir]} is meant to contain +all of the generated object files and executables. Once you have done +this, you can proceed building GCC as described above. (Keep in mind +that @file{gcc_build} is a rooted logical name, and thus the device +names in each element of the search list must be an actual physical +device name rather than another rooted logical name). + +@item +@strong{If you are building GNU CC with a previous version of GNU CC, +you also should check to see that you have the newest version of the +assembler}. In particular, GNU CC version 2 treats global constant +variables slightly differently from GNU CC version 1, and GAS version +1.38.1 does not have the patches required to work with GCC version 2. +If you use GAS 1.38.1, then @code{extern const} variables will not have +the read-only bit set, and the linker will generate warning messages +about mismatched psect attributes for these variables. These warning +messages are merely a nuisance, and can safely be ignored. + +If you are compiling with a version of GNU CC older than 1.33, specify +@samp{/DEFINE=("inline=")} as an option in all the compilations. This +requires editing all the @code{gcc} commands in @file{make-cc1.com}. +(The older versions had problems supporting @code{inline}.) Once you +have a working 1.33 or newer GNU CC, you can change this file back. + +@item +If you want to build GNU CC with the VAX C compiler, you will need to +make minor changes in @file{make-cccp.com} and @file{make-cc1.com} +to choose alternate definitions of @code{CC}, @code{CFLAGS}, and +@code{LIBS}. See comments in those files. However, you must +also have a working version of the GNU assembler (GNU as, aka GAS) as +it is used as the back-end for GNU CC to produce binary object modules +and is not included in the GNU CC sources. GAS is also needed to +compile @file{libgcc2} in order to build @file{gcclib} (see above); +@file{make-l2.com} expects to be able to find it operational in +@file{gnu_cc:[000000]gnu-as.exe}. + +To use GNU CC on VMS, you need the VMS driver programs +@file{gcc.exe}, @file{gcc.com}, and @file{gcc.cld}. They are +distributed with the VMS binaries (@file{gcc-vms}) rather than the +GNU CC sources. GAS is also included in @file{gcc-vms}, as is Bison. + +Once you have successfully built GNU CC with VAX C, you should use the +resulting compiler to rebuild itself. Before doing this, be sure to +restore the @code{CC}, @code{CFLAGS}, and @code{LIBS} definitions in +@file{make-cccp.com} and @file{make-cc1.com}. The second generation +compiler will be able to take advantage of many optimizations that must +be suppressed when building with other compilers. +@end enumerate + +Under previous versions of GNU CC, the generated code would occasionally +give strange results when linked with the sharable @file{VAXCRTL} library. +Now this should work. + +Even with this version, however, GNU CC itself should not be linked with +the sharable @file{VAXCRTL}. The version of @code{qsort} in +@file{VAXCRTL} has a bug (known to be present in VMS versions V4.6 +through V5.5) which causes the compiler to fail. + +The executables are generated by @file{make-cc1.com} and +@file{make-cccp.com} use the object library version of @file{VAXCRTL} in +order to make use of the @code{qsort} routine in @file{gcclib.olb}. If +you wish to link the compiler executables with the shareable image +version of @file{VAXCRTL}, you should edit the file @file{tm.h} (created +by @file{vmsconfig.com}) to define the macro @code{QSORT_WORKAROUND}. + +@code{QSORT_WORKAROUND} is always defined when GNU CC is compiled with +VAX C, to avoid a problem in case @file{gcclib.olb} is not yet +available. + +@node Collect2 +@section @code{collect2} + +Many target systems do not have support in the assembler and linker for +``constructors''---initialization functions to be called before the +official ``start'' of @code{main}. On such systems, GNU CC uses a +utility called @code{collect2} to arrange to call these functions at +start time. + +The program @code{collect2} works by linking the program once and +looking through the linker output file for symbols with particular names +indicating they are constructor functions. If it finds any, it +creates a new temporary @samp{.c} file containing a table of them, +compiles it, and links the program a second time including that file. + +@findex __main +@cindex constructors, automatic calls +The actual calls to the constructors are carried out by a subroutine +called @code{__main}, which is called (automatically) at the beginning +of the body of @code{main} (provided @code{main} was compiled with GNU +CC). Calling @code{__main} is necessary, even when compiling C code, to +allow linking C and C++ object code together. (If you use +@samp{-nostdlib}, you get an unresolved reference to @code{__main}, +since it's defined in the standard GCC library. Include @samp{-lgcc} at +the end of your compiler command line to resolve this reference.) + +The program @code{collect2} is installed as @code{ld} in the directory +where the passes of the compiler are installed. When @code{collect2} +needs to find the @emph{real} @code{ld}, it tries the following file +names: + +@itemize @bullet +@item +@file{real-ld} in the directories listed in the compiler's search +directories. + +@item +@file{real-ld} in the directories listed in the environment variable +@code{PATH}. + +@item +The file specified in the @code{REAL_LD_FILE_NAME} configuration macro, +if specified. + +@item +@file{ld} in the compiler's search directories, except that +@code{collect2} will not execute itself recursively. + +@item +@file{ld} in @code{PATH}. +@end itemize + +``The compiler's search directories'' means all the directories where +@code{gcc} searches for passes of the compiler. This includes +directories that you specify with @samp{-B}. + +Cross-compilers search a little differently: + +@itemize @bullet +@item +@file{real-ld} in the compiler's search directories. + +@item +@file{@var{target}-real-ld} in @code{PATH}. + +@item +The file specified in the @code{REAL_LD_FILE_NAME} configuration macro, +if specified. + +@item +@file{ld} in the compiler's search directories. + +@item +@file{@var{target}-ld} in @code{PATH}. +@end itemize + +@code{collect2} explicitly avoids running @code{ld} using the file name +under which @code{collect2} itself was invoked. In fact, it remembers +up a list of such names---in case one copy of @code{collect2} finds +another copy (or version) of @code{collect2} installed as @code{ld} in a +second place in the search path. + +@code{collect2} searches for the utilities @code{nm} and @code{strip} +using the same algorithm as above for @code{ld}. + +@node Header Dirs +@section Standard Header File Directories + +@code{GCC_INCLUDE_DIR} means the same thing for native and cross. It is +where GNU CC stores its private include files, and also where GNU CC +stores the fixed include files. A cross compiled GNU CC runs +@code{fixincludes} on the header files in @file{$(tooldir)/include}. +(If the cross compilation header files need to be fixed, they must be +installed before GNU CC is built. If the cross compilation header files +are already suitable for ANSI C and GNU CC, nothing special need be +done). + +@code{GPLUS_INCLUDE_DIR} means the same thing for native and cross. It +is where @code{g++} looks first for header files. @code{libg++} +installs only target independent header files in that directory. + +@code{LOCAL_INCLUDE_DIR} is used only for a native compiler. It is +normally @file{/usr/local/include}. GNU CC searches this directory so +that users can install header files in @file{/usr/local/include}. + +@code{CROSS_INCLUDE_DIR} is used only for a cross compiler. GNU CC +doesn't install anything there. + +@code{TOOL_INCLUDE_DIR} is used for both native and cross compilers. It +is the place for other packages to install header files that GNU CC will +use. For a cross-compiler, this is the equivalent of +@file{/usr/include}. When you build a cross-compiler, +@code{fixincludes} processes any header files in this directory. -- 2.11.0