home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / gnu / gcc-2.5.8-bin.lha / info / gcc.info-5 (.txt) < prev    next >
GNU Info File  |  1994-02-21  |  50KB  |  867 lines
  1. This is Info file gcc.info, produced by Makeinfo-1.55 from the input
  2. file gcc.texi.
  3.    This file documents the use and the internals of the GNU compiler.
  4.    Published by the Free Software Foundation 675 Massachusetts Avenue
  5. Cambridge, MA 02139 USA
  6.    Copyright (C) 1988, 1989, 1992, 1993 Free Software Foundation, Inc.
  7.    Permission is granted to make and distribute verbatim copies of this
  8. manual provided the copyright notice and this permission notice are
  9. preserved on all copies.
  10.    Permission is granted to copy and distribute modified versions of
  11. this manual under the conditions for verbatim copying, provided also
  12. that the sections entitled "GNU General Public License" and "Protect
  13. Your Freedom--Fight `Look And Feel'" are included exactly as in the
  14. original, and provided that the entire resulting derived work is
  15. distributed under the terms of a permission notice identical to this
  16.    Permission is granted to copy and distribute translations of this
  17. manual into another language, under the above conditions for modified
  18. versions, except that the sections entitled "GNU General Public
  19. License" and "Protect Your Freedom--Fight `Look And Feel'", and this
  20. permission notice, may be included in translations approved by the Free
  21. Software Foundation instead of in the original English.
  22. File: gcc.info,  Node: Installation,  Next: C Extensions,  Prev: Invoking GCC,  Up: Top
  23. Installing GNU CC
  24. *****************
  25.    Here is the procedure for installing GNU CC on a Unix system.
  26. * Menu:
  27. * Other Dir::     Compiling in a separate directory (not where the source is).
  28. * Cross-Compiler::   Building and installing a cross-compiler.
  29. * PA Install::    See below for installation on the HP Precision Architecture.
  30. * Sun Install::   See below for installation on the Sun.
  31. * 3b1 Install::   See below for installation on the 3b1.
  32. * Unos Install::  See below for installation on Unos (from CRDS).
  33. * VMS Install::   See below for installation on VMS.
  34. * WE32K Install:: See below for installation on the 3b* aside from the 3b1.
  35. * MIPS Install::  See below for installation on the MIPS Architecture.
  36. * Collect2::      How `collect2' works; how it finds `ld'.
  37. * Header Dirs::   Understanding the standard header file directories.
  38.    You cannot install GNU C by itself on MSDOS; it will not compile
  39. under any MSDOS compiler except itself.  You need to get the complete
  40. compilation package DJGPP, which includes binaries as well as sources,
  41. and includes all the necessary compilation tools and libraries.
  42.   1. If you have built GNU CC previously in the same directory for a
  43.      different target machine, do `make distclean' to delete all files
  44.      that might be invalid.  One of the files this deletes is
  45.      `Makefile'; if `make distclean' complains that `Makefile' does not
  46.      exist, it probably means that the directory is already suitably
  47.      clean.
  48.   2. On a System V release 4 system, make sure `/usr/bin' precedes
  49.      `/usr/ucb' in `PATH'.  The `cc' command in `/usr/ucb' uses
  50.      libraries which have bugs.
  51.   3. Specify the host and target machine configurations.  You do this by
  52.      running the file `configure' with appropriate arguments.
  53.      If you are building a compiler to produce code for the machine it
  54.      runs on, specify just one machine type, with the `--target'
  55.      option; the host type will default to be the same as the target.
  56.      (For information on building a cross-compiler, see *Note
  57.      Cross-Compiler::.)  Here is an example:
  58.           configure --target=sparc-sun-sunos4.1
  59.      If you run `configure' without specifying configuration arguments,
  60.      `configure' tries to guess the type of host you are on, and uses
  61.      that configuration type for both host and target.  So you don't
  62.      need to specify a configuration, for building a native compiler,
  63.      unless `configure' cannot figure out what your configuration is.
  64.      A configuration name may be canonical or it may be more or less
  65.      abbreviated.
  66.      A canonical configuration name has three parts, separated by
  67.      dashes.  It looks like this: `CPU-COMPANY-SYSTEM'.  (The three
  68.      parts may themselves contain dashes; `configure' can figure out
  69.      which dashes serve which purpose.)  For example,
  70.      `m68k-sun-sunos4.1' specifies a Sun 3.
  71.      You can also replace parts of the configuration by nicknames or
  72.      aliases.  For example, `sun3' stands for `m68k-sun', so
  73.      `sun3-sunos4.1' is another way to specify a Sun 3.  You can also
  74.      use simply `sun3-sunos', since the version of SunOS is assumed by
  75.      default to be version 4.  `sun3-bsd' also works, since `configure'
  76.      knows that the only BSD variant on a Sun 3 is SunOS.
  77.      You can specify a version number after any of the system types,
  78.      and some of the CPU types.  In most cases, the version is
  79.      irrelevant, and will be ignored.  So you might as well specify the
  80.      version if you know it.
  81.      Here are the possible CPU types:
  82.           a29k, alpha, arm, cN, clipper, elxsi, h8300, hppa1.0, hppa1.1,
  83.           i370, i386, i486, i860, i960, m68000, m68k, m88k, mips,
  84.           ns32k, pyramid, romp, rs6000, sh, sparc, sparclite, vax,
  85.           we32k.
  86.      Here are the recognized company names.  As you can see, customary
  87.      abbreviations are used rather than the longer official names.
  88.           alliant, altos, apollo, att, bull, cbm, convergent, convex,
  89.           crds, dec, dg, dolphin, elxsi, encore, harris, hitachi, hp,
  90.           ibm, intergraph, isi, mips, motorola, ncr, next, ns, omron,
  91.           plexus, sequent, sgi, sony, sun, tti, unicom.
  92.      The company name is meaningful only to disambiguate when the rest
  93.      of the information supplied is insufficient.  You can omit it,
  94.      writing just `CPU-SYSTEM', if it is not needed.  For example,
  95.      `vax-ultrix4.2' is equivalent to `vax-dec-ultrix4.2'.
  96.      Here is a list of system types:
  97.           aix, acis, aos, bsd, clix, ctix, dgux, dynix, genix, hpux,
  98.           isc, linux, luna, lynxos, mach, minix, newsos, osf, osfrose,
  99.           riscos, sco, solaris, sunos, sysv, ultrix, unos, vms.
  100.      You can omit the system type; then `configure' guesses the
  101.      operating system from the CPU and company.
  102.      You can add a version number to the system type; this may or may
  103.      not make a difference.  For example, you can write `bsd4.3' or
  104.      `bsd4.4' to distinguish versions of BSD.  In practice, the version
  105.      number is most needed for `sysv3' and `sysv4', which are often
  106.      treated differently.
  107.      If you specify an impossible combination such as `i860-dg-vms',
  108.      then you may get an error message from `configure', or it may
  109.      ignore part of the information and do the best it can with the
  110.      rest.  `configure' always prints the canonical name for the
  111.      alternative that it used.
  112.      Often a particular model of machine has a name.  Many machine
  113.      names are recognized as aliases for CPU/company combinations.
  114.      Thus, the machine name `sun3', mentioned above, is an alias for
  115.      `m68k-sun'.  Sometimes we accept a company name as a machine name,
  116.      when the name is popularly used for a particular machine.  Here is
  117.      a table of the known machine names:
  118.           3300, 3b1, 3bN, 7300, altos3068, altos, apollo68, att-7300,
  119.           balance, convex-cN, crds, decstation-3100, decstation, delta,
  120.           encore, fx2800, gmicro, hp7NN, hp8NN, hp9k2NN, hp9k3NN,
  121.           hp9k7NN, hp9k8NN, iris4d, iris, isi68, m3230, magnum, merlin,
  122.           miniframe, mmax, news-3600, news800, news, next, pbd, pc532,
  123.           pmax, ps2, risc-news, rtpc, sun2, sun386i, sun386, sun3,
  124.           sun4, symmetry, tower-32, tower.
  125.      Remember that a machine name specifies both the cpu type and the
  126.      company name.
  127.      There are four additional options you can specify independently to
  128.      describe variant hardware and software configurations.  These are
  129.      `--with-gnu-as', `--with-gnu-ld', `--with-stabs' and `--nfp'.
  130.     `--with-gnu-as'
  131.           If you will use GNU CC with the GNU assembler (GAS), you
  132.           should declare this by using the `--with-gnu-as' option when
  133.           you run `configure'.
  134.           Using this option does not install GAS.  It only modifies the
  135.           output of GNU CC to work with GAS.  Building and installing
  136.           GAS is up to you.
  137.           Conversely, if you *do not* wish to use GAS and do not specify
  138.           `--with-gnu-as' when building GNU CC, it is up to you to make
  139.           sure that GAS is not installed.  GNU CC searches for a
  140.           program named `as' in various directories; if the program it
  141.           finds is GAS, then it runs GAS.  If you are not sure where
  142.           GNU CC finds the assembler it is using, try specifying `-v'
  143.           when you run it.
  144.           The systems where it makes a difference whether you use GAS
  145.           are
  146.           `hppa1.0-ANY-ANY', `hppa1.1-ANY-ANY', `i386-ANY-sysv',
  147.           `i386-ANY-isc',
  148.           `i860-ANY-bsd', `m68k-bull-sysv', `m68k-hp-hpux',
  149.           `m68k-sony-bsd',
  150.           `m68k-altos-sysv', `m68000-hp-hpux', `m68000-att-sysv', and
  151.           `mips-ANY').  On any other system, `--with-gnu-as' has no
  152.           effect.
  153.           On the systems listed above (except for the HP-PA and for ISC
  154.           on the 386), if you use GAS, you should also use the GNU
  155.           linker (and specify `--with-gnu-ld').
  156.     `--with-gnu-ld'
  157.           Specify the option `--with-gnu-ld' if you plan to use the GNU
  158.           linker with GNU CC.
  159.           This option does not cause the GNU linker to be installed; it
  160.           just modifies the behavior of GNU CC to work with the GNU
  161.           linker.  Specifically, it inhibits the installation of
  162.           `collect2', a program which otherwise serves as a front-end
  163.           for the system's linker on most configurations.
  164.     `--with-stabs'
  165.           On MIPS based systems and on Alphas, you must specify whether
  166.           you want GNU CC to create the normal ECOFF debugging format,
  167.           or to use BSD-style stabs passed through the ECOFF symbol
  168.           table.  The normal ECOFF debug format cannot fully handle
  169.           languages other than C.  BSD stabs format can handle other
  170.           languages, but it only works with the GNU debugger GDB.
  171.           Normally, GNU CC uses the ECOFF debugging format by default;
  172.           if you prefer BSD stabs, specify `--with-stabs' when you
  173.           configure GNU CC.
  174.           No matter which default you choose when you configure GNU CC,
  175.           the user can use the `-gcoff' and `-gstabs+' options to
  176.           specify explicitly the debug format for a particular
  177.           compilation.
  178.           `--with-stabs' is meaningful on the ISC system on the 386,
  179.           also, if `--with-gas' is used.  It selects use of stabs
  180.           debugging information embedded in COFF output.  This kind of
  181.           debugging information supports C++ well; ordinary COFF
  182.           debugging information does not.
  183.     `--nfp'
  184.           On certain systems, you must specify whether the machine has
  185.           a floating point unit.  These systems include
  186.           `m68k-sun-sunosN' and `m68k-isi-bsd'.  On any other system,
  187.           `--nfp' currently has no effect, though perhaps there are
  188.           other systems where it could usefully make a difference.
  189.      If you want to install your own homemade configuration files, you
  190.      can use `local' as the company name to access them.  If you use
  191.      configuration `CPU-local', the configuration name without the cpu
  192.      prefix is used to form the configuration file names.
  193.      Thus, if you specify `m68k-local', configuration uses files
  194.      `local.md', `local.h', `local.c', `xm-local.h', `t-local', and
  195.      `x-local', all in the directory `config/m68k'.
  196.      Here is a list of configurations that have special treatment or
  197.      special things you must know:
  198.     `alpha-*-osf1'
  199.           Systems using processors that implement the DEC Alpha
  200.           architecture and are running the OSF/1 operating system, for
  201.           example the DEC Alpha AXP systems.  (VMS on the Alpha is not
  202.           currently supported by GNU CC.)
  203.           Objective C and C++ do not yet work on the Alpha.  We hope to
  204.           support C++ in version 2.6.
  205.           GNU CC writes a `.verstamp' directive to the assembler output
  206.           file unless it is built as a cross-compiler.  It gets the
  207.           version to use from the system header file
  208.           `/usr/include/stamp.h'.  If you install a new version of
  209.           OSF/1, you should rebuild GCC to pick up the new version
  210.           stamp.
  211.           Note that since the Alpha is a 64-bit architecture,
  212.           cross-compilers from 32-bit machines will not generate as
  213.           efficient code as that generated when the compiler is running
  214.           on a 64-bit machine because many optimizations that depend on
  215.           being able to represent a word on the target in an integral
  216.           value on the host cannot be performed.  Building
  217.           cross-compilers on the Alpha for 32-bit machines has only
  218.           been tested in a few cases and may not work properly.
  219.           `make compare' may fail on some versions of OSF/1 unless you
  220.           add `-save-temps' to `CFLAGS'.  The same problem occurs on
  221.           Irix version 5.1.1.  On these systems, the name of the
  222.           assembler input file is stored in the object file, and that
  223.           makes comparison fail if it differs between the `stage1' and
  224.           `stage2' compilations.  The option `-save-temps' forces a
  225.           fixed name to be used for the assembler input file, instead
  226.           of a randomly chosen name in `/tmp'.
  227.           GNU CC now supports both the native (ECOFF) debugging format
  228.           used by DBX and GDB and an encapsulated STABS format for use
  229.           only with GDB.  See the discussion of the `--with-stabs'
  230.           option of `configure' above for more information on these
  231.           formats and how to select them.
  232.           There is a bug in DEC's assembler that produces incorrect
  233.           line numbers for ECOFF format when the `.align' directive is
  234.           used.  To work around this problem, GNU CC will not emit such
  235.           alignment directives even if optimization is being performed
  236.           if it is writing ECOFF format debugging information.
  237.           Unfortunately, this has the very undesirable side-effect that
  238.           code addresses when `-O' is specified are different depending
  239.           on whether or not `-g' is also specified.
  240.           To avoid this behavior, specify `-gstabs+' and use GDB
  241.           instead of DBX.  DEC is now aware of this problem with the
  242.           assembler and hopes to provide a fix shortly.
  243.     `a29k'
  244.           AMD Am29k-family processors.  These are normally used in
  245.           embedded applications.  There are no standard Unix
  246.           configurations.  This configuration corresponds to AMD's
  247.           standard calling sequence and binary interface and is
  248.           compatible with other 29k tools.
  249.           You may need to make a variant of the file `a29k.h' for your
  250.           particular configuration.
  251.     `a29k-*-bsd'
  252.           AMD Am29050 used in a system running a variant of BSD Unix.
  253.     `elxsi-elxsi-bsd'
  254.           The Elxsi's C compiler has known limitations that prevent it
  255.           from compiling GNU C.  Please contact `mrs@cygnus.com' for
  256.           more details.
  257.     `hppa*-*-*'
  258.           Using GAS is highly recommended for all HP-PA configurations.
  259.           See *Note PA Install:: for the special procedures needed to
  260.           compile GNU CC for the HP-PA.
  261.     `i386-*-sco'
  262.           Compilation with RCC is recommended.  Also, it may be a good
  263.           idea to link with GNU malloc instead of the malloc that comes
  264.           with the system.
  265.     `i386-*-sco3.2.4'
  266.           Use this configuration for SCO release 3.2 version 4.
  267.     `i386-*-isc'
  268.           It may be good idea to link with GNU malloc instead of the
  269.           malloc that comes with the system.
  270.     `i386-*-esix'
  271.           It may be good idea to link with GNU malloc instead of the
  272.           malloc that comes with the system.
  273.     `i386-ibm-aix'
  274.           You need to use GAS version 2.1 or later, and and LD from GNU
  275.           binutils version 2.2 or later.
  276.     `i386-sequent'
  277.           Go to the Berkeley universe before compiling.  In addition,
  278.           you probably need to create a file named `string.h'
  279.           containing just one line: `#include <strings.h>'.
  280.     `i386-sun-sunos4'
  281.           You may find that you need another version of GNU CC to begin
  282.           bootstrapping with, since the current version when built with
  283.           the system's own compiler seems to get an infinite loop
  284.           compiling part of `libgcc2.c'.  GNU CC version 2 compiled
  285.           with GNU CC (any version) seems not to have this problem.
  286.     `i860-intel-osf1'
  287.           This is the Paragon.  If you have version 1.0 of the
  288.           operating system, see *Note Installation Problems::, for
  289.           special things you need to do to compensate for peculiarities
  290.           in the system.
  291.     `m68000-att'
  292.           AT&T 3b1, a.k.a. 7300 PC.  Special procedures are needed to
  293.           compile GNU CC with this machine's standard C compiler, due
  294.           to bugs in that compiler.  *Note 3b1 Install::.  You can
  295.           bootstrap it more easily with previous versions of GNU CC if
  296.           you have them.
  297.     `m68000-hp-bsd'
  298.           HP 9000 series 200 running BSD.  Note that the C compiler
  299.           that comes with this system cannot compile GNU CC; contact
  300.           `law@cs.utah.edu' to get binaries of GNU CC for bootstrapping.
  301.     `m68k-altos'
  302.           Altos 3068.  You must use the GNU assembler, linker and
  303.           debugger.  Also, you must fix a kernel bug.  Details in the
  304.           file `README.ALTOS'.
  305.     `m68k-bull-sysv'
  306.           Bull DPX/2 series 200 and 300 with BOS-2.00.45 up to
  307.           BOS-2.01. GNU CC works either with native assembler or GNU
  308.           assembler. You can use GNU assembler with native coff
  309.           generation by providing `--gas' to the configure script or
  310.           use GNU assembler with dbx-in-coff encapsulation by providing
  311.           `--gas --stabs'. For any problem with native assembler or for
  312.           availability of the DPX/2 port of GAS, contact
  313.           `F.Pierresteguy@frcl.bull.fr'.
  314.     `m68k-hp-hpux'
  315.           HP 9000 series 300 or 400 running HP-UX.  HP-UX version 8.0
  316.           has a bug in the assembler that prevents compilation of GNU
  317.           CC.  To fix it, get patch PHCO_0800 from HP.
  318.           In addition, `--gas' does not currently work with this
  319.           configuration.  Changes in HP-UX have broken the library
  320.           conversion tool and the linker.
  321.     `m68k-sun'
  322.           Sun 3.  We do not provide a configuration file to use the Sun
  323.           FPA by default, because programs that establish signal
  324.           handlers for floating point traps inherently cannot work with
  325.           the FPA.
  326.     `m88k-*-svr3'
  327.           Motorola m88k running the AT&T/Unisoft/Motorola V.3 reference
  328.           port.  These systems tend to use the Green Hills C, revision
  329.           1.8.5, as the standard C compiler.  There are apparently bugs
  330.           in this compiler that result in object files differences
  331.           between stage 2 and stage 3.  If this happens, make the stage
  332.           4 compiler and compare it to the stage 3 compiler.  If the
  333.           stage 3 and stage 4 object files are identical, this suggests
  334.           you encountered a problem with the standard C compiler; the
  335.           stage 3 and 4 compilers may be usable.
  336.           It is best, however, to use an older version of GNU CC for
  337.           bootstrapping if you have one.
  338.     `m88k-*-dgux'
  339.           Motorola m88k running DG/UX.  To build native or cross
  340.           compilers on DG/UX, you must first change to the 88open BCS
  341.           software development environment.  This is done by issuing
  342.           this command:
  343.                eval `sde-target m88kbcs`
  344.     `m88k-tektronix-sysv3'
  345.           Tektronix XD88 running UTekV 3.2e.  Do not turn on
  346.           optimization while building stage1 if you bootstrap with the
  347.           buggy Green Hills compiler.  Also, The bundled LAI System V
  348.           NFS is buggy so if you build in an NFS mounted directory,
  349.           start from a fresh reboot, or avoid NFS all together.
  350.           Otherwise you may have trouble getting clean comparisons
  351.           between stages.
  352.     `mips-mips-bsd'
  353.           MIPS machines running the MIPS operating system in BSD mode.
  354.           It's possible that some old versions of the system lack the
  355.           functions `memcpy', `memcmp', and `memset'.  If your system
  356.           lacks these, you must remove or undo the definition of
  357.           `TARGET_MEM_FUNCTIONS' in `mips-bsd.h'.
  358.     `mips-sgi-*'
  359.           Silicon Graphics MIPS machines running IRIX.  In order to
  360.           compile GCC on an SGI the "c.hdr.lib" option must be
  361.           installed from the CD-ROM supplied from Silicon Graphics.
  362.           This is found on the 2nd CD in release 4.0.1.
  363.     `mips-sony-sysv'
  364.           Sony MIPS NEWS.  This works in NEWSOS 5.0.1, but not in 5.0.2
  365.           (which uses ELF instead of COFF).  Support for 5.0.2 will
  366.           probably be provided soon by volunteers.  In particular, the
  367.           linker does not like the code generated by GCC when shared
  368.           libraries are linked in.
  369.     `ns32k-encore'
  370.           Encore ns32000 system.  Encore systems are supported only
  371.           under BSD.
  372.     `ns32k-*-genix'
  373.           National Semiconductor ns32000 system.  Genix has bugs in
  374.           `alloca' and `malloc'; you must get the compiled versions of
  375.           these from GNU Emacs.
  376.     `ns32k-sequent'
  377.           Go to the Berkeley universe before compiling.  In addition,
  378.           you probably need to create a file named `string.h'
  379.           containing just one line: `#include <strings.h>'.
  380.     `ns32k-utek'
  381.           UTEK ns32000 system ("merlin").  The C compiler that comes
  382.           with this system cannot compile GNU CC; contact
  383.           `tektronix!reed!mason' to get binaries of GNU CC for
  384.           bootstrapping.
  385.     `romp-*-aos'
  386.     `romp-*-mach'
  387.           The only operating systems supported for the IBM RT PC are
  388.           AOS and MACH.  GNU CC does not support AIX running on the RT.
  389.           We recommend you compile GNU CC with an earlier version of
  390.           itself; if you compile GNU CC with `hc', the Metaware
  391.           compiler, it will work, but you will get mismatches between
  392.           the stage 2 and stage 3 compilers in various files.  These
  393.           errors are minor differences in some floating-point constants
  394.           and can be safely ignored; the stage 3 compiler is correct.
  395.     `rs6000-*-aix'
  396.           *Read the file `README.RS6000' for information on how to get
  397.           a fix for problems in the IBM assembler that interfere with
  398.           GNU CC.* You must either obtain the new assembler or avoid
  399.           using the `-g' switch.  Note that `Makefile.in' uses `-g' by
  400.           default when compiling `libgcc2.c'.
  401.           The PowerPC and POWER2 architectures are now supported, but
  402.           have not been extensively tested due to lack of appropriate
  403.           systems.  Only AIX is supported on the PowerPC.
  404.           Objective C does not work on this architecture.
  405.           XLC version 1.3.0.0 will miscompile `jump.c'.  XLC version
  406.           1.3.0.1 or later fixes this problem.  We do not yet have a
  407.           PTF number for this fix.
  408.     `vax-dec-ultrix'
  409.           Don't try compiling with Vax C (`vcc').  It produces
  410.           incorrect code in some cases (for example, when `alloca' is
  411.           used).
  412.           Meanwhile, compiling `cp-parse.c' with pcc does not work
  413.           because of an internal table size limitation in that
  414.           compiler.  To avoid this problem, compile just the GNU C
  415.           compiler first, and use it to recompile building all the
  416.           languages that you want to run.
  417.      Here we spell out what files will be set up by `configure'.
  418.      Normally you need not be concerned with these files.
  419.         * A symbolic link named `config.h' is made to the top-level
  420.           config file for the machine you will run the compiler on
  421.           (*note Config::.).  This file is responsible for defining
  422.           information about the host machine.  It includes `tm.h'.
  423.           The top-level config file is located in the subdirectory
  424.           `config'.  Its name is always `xm-SOMETHING.h'; usually
  425.           `xm-MACHINE.h', but there are some exceptions.
  426.           If your system does not support symbolic links, you might
  427.           want to set up `config.h' to contain a `#include' command
  428.           which refers to the appropriate file.
  429.         * A symbolic link named `tconfig.h' is made to the top-level
  430.           config file for your target machine.  This is used for
  431.           compiling certain programs to run on that machine.
  432.         * A symbolic link named `tm.h' is made to the
  433.           machine-description macro file for your target machine.  It
  434.           should be in the subdirectory `config' and its name is often
  435.           `MACHINE.h'.
  436.         * A symbolic link named `md' will be made to the machine
  437.           description pattern file.  It should be in the `config'
  438.           subdirectory and its name should be `MACHINE.md'; but MACHINE
  439.           is often not the same as the name used in the `tm.h' file
  440.           because the `md' files are more general.
  441.         * A symbolic link named `aux-output.c' will be made to the
  442.           output subroutine file for your machine.  It should be in the
  443.           `config' subdirectory and its name should be `MACHINE.c'.
  444.         * The command file `configure' also constructs the file
  445.           `Makefile' by adding some text to the template file
  446.           `Makefile.in'.  The additional text comes from files in the
  447.           `config' directory, named `t-TARGET' and `x-HOST'.  If these
  448.           files do not exist, it means nothing needs to be added for a
  449.           given target or host.
  450.   4. The standard directory for installing GNU CC is `/gnu/lib'.  If
  451.      you want to install its files somewhere else, specify
  452.      `--prefix=DIR' when you run `configure'.  Here DIR is a directory
  453.      name to use instead of `/gnu' for all purposes with one exception:
  454.      the directory `/gnu/include' is searched for header files no
  455.      matter where you install the compiler.
  456.   5. Specify `--local-prefix=DIR' if you want the compiler to search
  457.      directory `DIR/include' for header files *instead* of
  458.      `/gnu/include'.  (This is for systems that have different
  459.      conventions for where to put site-specific things.)
  460.      Unless you have a convention other than `/gnu' for site-specific
  461.      files, it is a bad idea to specify `--local-prefix'.
  462.   6. Make sure the Bison parser generator is installed.  (This is
  463.      unnecessary if the Bison output files `c-parse.c' and `cexp.c' are
  464.      more recent than `c-parse.y' and `cexp.y' and you do not plan to
  465.      change the `.y' files.)
  466.      Bison versions older than Sept 8, 1988 will produce incorrect
  467.      output for `c-parse.c'.
  468.   7. If you have chosen a configuration for GNU CC which requires other
  469.      GNU tools (such as GAS or the GNU linker) instead of the standard
  470.      system tools, install the required tools in the build directory
  471.      under the names `as', `ld' or whatever is appropriate.  This will
  472.      enable the compiler to find the proper tools for compilation of
  473.      the program `enquire'.
  474.      Alternatively, you can do subsequent compilation using a value of
  475.      the `PATH' environment variable such that the necessary GNU tools
  476.      come before the standard system tools.
  477.   8. Build the compiler.  Just type `make LANGUAGES=c' in the compiler
  478.      directory.
  479.      `LANGUAGES=c' specifies that only the C compiler should be
  480.      compiled.  The makefile normally builds compilers for all the
  481.      supported languages; currently, C, C++ and Objective C.  However,
  482.      C is the only language that is sure to work when you build with
  483.      other non-GNU C compilers.  In addition, building anything but C
  484.      at this stage is a waste of time.
  485.      In general, you can specify the languages to build by typing the
  486.      argument `LANGUAGES="LIST"', where LIST is one or more words from
  487.      the list `c', `c++', and `objective-c'.
  488.      Ignore any warnings you may see about "statement not reached" in
  489.      `insn-emit.c'; they are normal.  Also, warnings about "unknown
  490.      escape sequence" are normal in `genopinit.c' and perhaps some
  491.      other files.  Any other compilation errors may represent bugs in
  492.      the port to your machine or operating system, and should be
  493.      investigated and reported (*note Bugs::.).
  494.      Some commercial compilers fail to compile GNU CC because they have
  495.      bugs or limitations.  For example, the Microsoft compiler is said
  496.      to run out of macro space.  Some Ultrix compilers run out of
  497.      expression space; then you need to break up the statement where
  498.      the problem happens.
  499.      If you are building with a previous GNU C compiler, do not use
  500.      `CC=gcc' on the make command or by editing the Makefile.  Instead,
  501.      use a full pathname to specify the compiler, such as
  502.      `CC=/gnu/bin/gcc'.  This is because make might execute the `gcc'
  503.      in the current directory before all of the compiler components
  504.      have been built.
  505.   9. If you are building a cross-compiler, stop here.  *Note
  506.      Cross-Compiler::.
  507.  10. Move the first-stage object files and executables into a
  508.      subdirectory with this command:
  509.           make stage1
  510.      The files are moved into a subdirectory named `stage1'.  Once
  511.      installation is complete, you may wish to delete these files with
  512.      `rm -r stage1'.
  513.  11. If you have chosen a configuration for GNU CC which requires other
  514.      GNU tools (such as GAS or the GNU linker) instead of the standard
  515.      system tools, install the required tools in the `stage1'
  516.      subdirectory under the names `as', `ld' or whatever is
  517.      appropriate.  This will enable the stage 1 compiler to find the
  518.      proper tools in the following stage.
  519.      Alternatively, you can do subsequent compilation using a value of
  520.      the `PATH' environment variable such that the necessary GNU tools
  521.      come before the standard system tools.
  522.  12. Recompile the compiler with itself, with this command:
  523.           make CC="stage1/xgcc -Bstage1/" CFLAGS="-g -O"
  524.      This is called making the stage 2 compiler.
  525.      The command shown above builds compilers for all the supported
  526.      languages.  If you don't want them all, you can specify the
  527.      languages to build by typing the argument `LANGUAGES="LIST"'.  LIST
  528.      should contain one or more words from the list `c', `c++',
  529.      `objective-c', and `proto'.  Separate the words with spaces.
  530.      `proto' stands for the programs `protoize' and `unprotoize'; they
  531.      are not a separate language, but you use `LANGUAGES' to enable or
  532.      disable their installation.
  533.      If you are going to build the stage 3 compiler, then you might
  534.      want to build only the C language in stage 2.
  535.      Once you have built the stage 2 compiler, if you are short of disk
  536.      space, you can delete the subdirectory `stage1'.
  537.      On a 68000 or 68020 system lacking floating point hardware, unless
  538.      you have selected a `tm.h' file that expects by default that there
  539.      is no such hardware, do this instead:
  540.           make CC="stage1/xgcc -Bstage1/" CFLAGS="-g -O -msoft-float"
  541.  13. If you wish to test the compiler by compiling it with itself one
  542.      more time, install any other necessary GNU tools (such as GAS or
  543.      the GNU linker) in the `stage2' subdirectory as you did in the
  544.      `stage1' subdirectory, then do this:
  545.           make stage2
  546.           make CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O"
  547.      This is called making the stage 3 compiler.  Aside from the `-B'
  548.      option, the compiler options should be the same as when you made
  549.      the stage 2 compiler.  But the `LANGUAGES' option need not be the
  550.      same.  The command shown above builds compilers for all the
  551.      supported languages; if you don't want them all, you can specify
  552.      the languages to build by typing the argument `LANGUAGES="LIST"',
  553.      as described above.
  554.      Then compare the latest object files with the stage 2 object
  555.      files--they ought to be identical, aside from time stamps (if any).
  556.      On some systems, meaningful comparison of object files is
  557.      impossible; they always appear "different."  This is currently
  558.      true on Solaris and probably on all systems that use ELF object
  559.      file format.  Some other systems where this is so are listed below.
  560.      Use this command to compare the files:
  561.           make compare
  562.      This will mention any object files that differ between stage 2 and
  563.      stage 3.  Any difference, no matter how innocuous, indicates that
  564.      the stage 2 compiler has compiled GNU CC incorrectly, and is
  565.      therefore a potentially serious bug which you should investigate
  566.      and report (*note Bugs::.).
  567.      If your system does not put time stamps in the object files, then
  568.      this is a faster way to compare them (using the Bourne shell):
  569.           for file in *.o; do
  570.           cmp $file stage2/$file
  571.           done
  572.      If you have built the compiler with the `-mno-mips-tfile' option on
  573.      MIPS machines, you will not be able to compare the files.
  574.      The Alpha stores file names of internal temporary files in the
  575.      object files and `make compare' does not know how to ignore them,
  576.      so normally you cannot compare on the Alpha.  However, if you use
  577.      the `-save-temps' option when compiling *both* stage 2 and stage
  578.      3, this causes the same file names to be used in both stages; then
  579.      you can do the comparison.
  580.  14. Build the Objective C library (if you have built the Objective C
  581.      compiler).  Here is the command to do this:
  582.           make objc-runtime CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O"
  583.  15. Install the compiler driver, the compiler's passes and run-time
  584.      support with `make install'.  Use the same value for `CC',
  585.      `CFLAGS' and `LANGUAGES' that you used when compiling the files
  586.      that are being installed.  One reason this is necessary is that
  587.      some versions of Make have bugs and recompile files gratuitously
  588.      when you do this step.  If you use the same variable values, those
  589.      files will be recompiled properly.
  590.      For example, if you have built the stage 2 compiler, you can use
  591.      the following command:
  592.           make install CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O" LANGUAGES="LIST"
  593.      This copies the files `cc1', `cpp' and `libgcc.a' to files `cc1',
  594.      `cpp' and `libgcc.a' in the directory
  595.      `/gnu/lib/gcc-lib/TARGET/VERSION', which is where the compiler
  596.      driver program looks for them.  Here TARGET is the target machine
  597.      type specified when you ran `configure', and VERSION is the
  598.      version number of GNU CC.  This naming scheme permits various
  599.      versions and/or cross-compilers to coexist.
  600.      This also copies the driver program `xgcc' into `/gnu/bin/gcc', so
  601.      that it appears in typical execution search paths.
  602.      On some systems, this command causes recompilation of some files.
  603.      This is usually due to bugs in `make'.  You should either ignore
  604.      this problem, or use GNU Make.
  605.      *Warning: there is a bug in `alloca' in the Sun library.  To avoid
  606.      this bug, be sure to install the executables of GNU CC that were
  607.      compiled by GNU CC.  (That is, the executables from stage 2 or 3,
  608.      not stage 1.)  They use `alloca' as a built-in function and never
  609.      the one in the library.*
  610.      (It is usually better to install GNU CC executables from stage 2
  611.      or 3, since they usually run faster than the ones compiled with
  612.      some other compiler.)
  613.  16. Install the Objective C library (if you are installing the
  614.      Objective C compiler).  Here is the command to do this:
  615.           make install-libobjc CC="stage2/xgcc -Bstage2/" CFLAGS="-g -O"
  616.  17. If you're going to use C++, it's likely that you need to also
  617.      install the libg++ distribution.  It should be available from the
  618.      same place where you got the GNU C distribution.  Just as GNU C
  619.      does not distribute a C runtime library, it also does not include
  620.      a C++ run-time library.  All I/O functionality, special class
  621.      libraries, etc., are available in the libg++ distribution.
  622. File: gcc.info,  Node: Other Dir,  Next: Cross-Compiler,  Up: Installation
  623. Compilation in a Separate Directory
  624. ===================================
  625.    If you wish to build the object files and executables in a directory
  626. other than the one containing the source files, here is what you must
  627. do differently:
  628.   1. Make sure you have a version of Make that supports the `VPATH'
  629.      feature.  (GNU Make supports it, as do Make versions on most BSD
  630.      systems.)
  631.   2. If you have ever run `configure' in the source directory, you must
  632.      undo the configuration.  Do this by running:
  633.           make distclean
  634.   3. Go to the directory in which you want to build the compiler before
  635.      running `configure':
  636.           mkdir gcc-sun3
  637.           cd gcc-sun3
  638.      On systems that do not support symbolic links, this directory must
  639.      be on the same file system as the source code directory.
  640.   4. Specify where to find `configure' when you run it:
  641.           ../gcc/configure ...
  642.      This also tells `configure' where to find the compiler sources;
  643.      `configure' takes the directory from the file name that was used to
  644.      invoke it.  But if you want to be sure, you can specify the source
  645.      directory with the `--srcdir' option, like this:
  646.           ../gcc/configure --srcdir=../gcc sun3
  647.      The directory you specify with `--srcdir' need not be the same as
  648.      the one that `configure' is found in.
  649.    Now, you can run `make' in that directory.  You need not repeat the
  650. configuration steps shown above, when ordinary source files change.  You
  651. must, however, run `configure' again when the configuration files
  652. change, if your system does not support symbolic links.
  653. File: gcc.info,  Node: Cross-Compiler,  Next: PA Install,  Prev: Other Dir,  Up: Installation
  654. Building and Installing a Cross-Compiler
  655. ========================================
  656.    GNU CC can function as a cross-compiler for many machines, but not
  657.    * Cross-compilers for the Mips as target using the Mips assembler
  658.      currently do not work, because the auxiliary programs
  659.      `mips-tdump.c' and `mips-tfile.c' can't be compiled on anything
  660.      but a Mips.  It does work to cross compile for a Mips if you use
  661.      the GNU assembler and linker.
  662.    * Cross-compilers between machines with different floating point
  663.      formats have not all been made to work.  GNU CC now has a floating
  664.      point emulator with which these can work, but each target machine
  665.      description needs to be updated to take advantage of it.
  666.    * Cross-compilation between machines of different word sizes has not
  667.      really been addressed yet.
  668.    Since GNU CC generates assembler code, you probably need a
  669. cross-assembler that GNU CC can run, in order to produce object files.
  670. If you want to link on other than the target machine, you need a
  671. cross-linker as well.  You also need header files and libraries suitable
  672. for the target machine that you can install on the host machine.
  673. * Menu:
  674. * Steps of Cross::      Using a cross-compiler involves several steps
  675.                           that may be carried out on different machines.
  676. * Configure Cross::     Configuring a cross-compiler.
  677. * Tools and Libraries:: Where to put the linker and assembler, and the C library.
  678. * Cross Headers::       Finding and installing header files
  679.                           for a cross-compiler.
  680. * Cross Runtime::       Supplying arithmetic runtime routines (`libgcc1.a').
  681. * Build Cross::         Actually compiling the cross-compiler.
  682. File: gcc.info,  Node: Steps of Cross,  Next: Configure Cross,  Up: Cross-Compiler
  683. Steps of Cross-Compilation
  684. --------------------------
  685.    To compile and run a program using a cross-compiler involves several
  686. steps:
  687.    * Run the cross-compiler on the host machine to produce assembler
  688.      files for the target machine.  This requires header files for the
  689.      target machine.
  690.    * Assemble the files produced by the cross-compiler.  You can do this
  691.      either with an assembler on the target machine, or with a
  692.      cross-assembler on the host machine.
  693.    * Link those files to make an executable.  You can do this either
  694.      with a linker on the target machine, or with a cross-linker on the
  695.      host machine.  Whichever machine you use, you need libraries and
  696.      certain startup files (typically `crt....o') for the target
  697.      machine.
  698.    It is most convenient to do all of these steps on the same host
  699. machine, since then you can do it all with a single invocation of GNU
  700. CC.  This requires a suitable cross-assembler and cross-linker.  For
  701. some targets, the GNU assembler and linker are available.
  702. File: gcc.info,  Node: Configure Cross,  Next: Tools and Libraries,  Prev: Steps of Cross,  Up: Cross-Compiler
  703. Configuring a Cross-Compiler
  704. ----------------------------
  705.    To build GNU CC as a cross-compiler, you start out by running
  706. `configure'.  You must specify two different configurations, the host
  707. and the target.  Use the `--host=HOST' option for the host and
  708. `--target=TARGET' to specify the target type.  For example, here is how
  709. to configure for a cross-compiler that runs on a hypothetical Intel 386
  710. system and produces code for an HP 68030 system running BSD:
  711.      configure --target=m68k-hp-bsd4.3 --host=i386-bozotheclone-bsd4.3
  712. File: gcc.info,  Node: Tools and Libraries,  Next: Cross Headers,  Prev: Configure Cross,  Up: Cross-Compiler
  713. Tools and Libraries for a Cross-Compiler
  714. ----------------------------------------
  715.    If you have a cross-assembler and cross-linker available, you should
  716. install them now.  Put them in the directory `/gnu/TARGET/bin'.  Here
  717. is a table of the tools you should put in this directory:
  718.      This should be the cross-assembler.
  719.      This should be the cross-linker.
  720.      This should be the cross-archiver: a program which can manipulate
  721.      archive files (linker libraries) in the target machine's format.
  722. `ranlib'
  723.      This should be a program to construct a symbol table in an archive
  724.      file.
  725.    The installation of GNU CC will find these programs in that
  726. directory, and copy or link them to the proper place to for the
  727. cross-compiler to find them when run later.
  728.    The easiest way to provide these files is to build the Binutils
  729. package and GAS.  Configure them with the same `--host' and `--target'
  730. options that you use for configuring GNU CC, then build and install
  731. them.  They install their executables automatically into the proper
  732. directory.  Alas, they do not support all the targets that GNU CC
  733. supports.
  734.    If you want to install libraries to use with the cross-compiler,
  735. such as a standard C library, put them in the directory
  736. `/gnu/TARGET/lib'; installation of GNU CC copies all all the files in
  737. that subdirectory into the proper place for GNU CC to find them and
  738. link with them.  Here's an example of copying some libraries from a
  739. target machine:
  740.      ftp TARGET-MACHINE
  741.      lcd /gnu/TARGET/lib
  742.      cd /lib
  743.      get libc.a
  744.      cd /usr/lib
  745.      get libg.a
  746.      get libm.a
  747.      quit
  748. The precise set of libraries you'll need, and their locations on the
  749. target machine, vary depending on its operating system.
  750.    Many targets require "start files" such as `crt0.o' and `crtn.o'
  751. which are linked into each executable; these too should be placed in
  752. `/gnu/TARGET/lib'.  There may be several alternatives for `crt0.o', for
  753. use with profiling or other compilation options.  Check your target's
  754. definition of `STARTFILE_SPEC' to find out what start files it uses.
  755. Here's an example of copying these files from a target machine:
  756.      ftp TARGET-MACHINE
  757.      lcd /gnu/TARGET/lib
  758.      prompt
  759.      cd /lib
  760.      mget *crt*.o
  761.      cd /usr/lib
  762.      mget *crt*.o
  763.      quit
  764. File: gcc.info,  Node: Cross Runtime,  Next: Build Cross,  Prev: Cross Headers,  Up: Cross-Compiler
  765. `libgcc.a' and Cross-Compilers
  766. ------------------------------
  767.    Code compiled by GNU CC uses certain runtime support functions
  768. implicitly.  Some of these functions can be compiled successfully with
  769. GNU CC itself, but a few cannot be.  These problem functions are in the
  770. source file `libgcc1.c'; the library made from them is called
  771. `libgcc1.a'.
  772.    When you build a native compiler, these functions are compiled with
  773. some other compiler-the one that you use for bootstrapping GNU CC.
  774. Presumably it knows how to open code these operations, or else knows how
  775. to call the run-time emulation facilities that the machine comes with.
  776. But this approach doesn't work for building a cross-compiler.  The
  777. compiler that you use for building knows about the host system, not the
  778. target system.
  779.    So, when you build a cross-compiler you have to supply a suitable
  780. library `libgcc1.a' that does the job it is expected to do.
  781.    To compile `libgcc1.c' with the cross-compiler itself does not work.
  782. The functions in this file are supposed to implement arithmetic
  783. operations that GNU CC does not know how to open code, for your target
  784. machine.  If these functions are compiled with GNU CC itself, they will
  785. compile into infinite recursion.
  786.    On any given target, most of these functions are not needed.  If GNU
  787. CC can open code an arithmetic operation, it will not call these
  788. functions to perform the operation.  It is possible that on your target
  789. machine, none of these functions is needed.  If so, you can supply an
  790. empty library as `libgcc1.a'.
  791.    Many targets need library support only for multiplication and
  792. division.  If you are linking with a library that contains functions for
  793. multiplication and division, you can tell GNU CC to call them directly
  794. by defining the macros `MULSI3_LIBCALL', and the like.  These macros
  795. need to be defined in the target description macro file.  For some
  796. targets, they are defined already.  This may be sufficient to avoid the
  797. need for libgcc1.a; if so, you can supply an empty library.
  798.    Some targets do not have floating point instructions; they need other
  799. functions in `libgcc1.a', which do floating arithmetic.  Recent
  800. versions of GNU CC have a file which emulates floating point.  With a
  801. certain amount of work, you should be able to construct a floating
  802. point emulator that can be used as `libgcc1.a'.  Perhaps future
  803. versions will contain code to do this automatically and conveniently.
  804. That depends on whether someone wants to implement it.
  805.    If your target system has another C compiler, you can configure GNU
  806. CC as a native compiler on that machine, build just `libgcc1.a' with
  807. `make libgcc1.a' on that machine, and use the resulting file with the
  808. cross-compiler.  To do this, execute the following on the target
  809. machine:
  810.      cd TARGET-BUILD-DIR
  811.      configure --host=sparc --target=sun3
  812.      make libgcc1.a
  813. And then this on the host machine:
  814.      ftp TARGET-MACHINE
  815.      binary
  816.      cd TARGET-BUILD-DIR
  817.      get libgcc1.a
  818.      quit
  819.    Another way to provide the functions you need in `libgcc1.a' is to
  820. define the appropriate `perform_...' macros for those functions.  If
  821. these definitions do not use the C arithmetic operators that they are
  822. meant to implement, you should be able to compile them with the
  823. cross-compiler you are building.  (If these definitions already exist
  824. for your target file, then you are all set.)
  825.    To build `libgcc1.a' using the perform macros, use
  826. `LIBGCC1=libgcc1.a OLDCC=./xgcc' when building the compiler.
  827. Otherwise, you should place your replacement library under the name
  828. `libgcc1.a' in the directory in which you will build the
  829. cross-compiler, before you run `make'.
  830. File: gcc.info,  Node: Cross Headers,  Next: Cross Runtime,  Prev: Tools and Libraries,  Up: Cross-Compiler
  831. Cross-Compilers and Header Files
  832. --------------------------------
  833.    If you are cross-compiling a standalone program or a program for an
  834. embedded system, then you may not need any header files except the few
  835. that are part of GNU CC (and those of your program).  However, if you
  836. intend to link your program with a standard C library such as `libc.a',
  837. then you probably need to compile with the header files that go with
  838. the library you use.
  839.    The GNU C compiler does not come with these files, because (1) they
  840. are system-specific, and (2) they belong in a C library, not in a
  841. compiler.
  842.    If the GNU C library supports your target machine, then you can get
  843. the header files from there (assuming you actually use the GNU library
  844. when you link your program).
  845.    If your target machine comes with a C compiler, it probably comes
  846. with suitable header files also.  If you make these files accessible
  847. from the host machine, the cross-compiler can use them also.
  848.    Otherwise, you're on your own in finding header files to use when
  849. cross-compiling.
  850.    When you have found suitable header files, put them in
  851. `/gnu/TARGET/include', before building the cross compiler.  Then
  852. installation will run fixincludes properly and install the corrected
  853. versions of the header files where the compiler will use them.
  854.    Provide the header files before you build the cross-compiler, because
  855. the build stage actually runs the cross-compiler to produce parts of
  856. `libgcc.a'.  (These are the parts that *can* be compiled with GNU CC.)
  857. Some of them need suitable header files.
  858.    Here's an example showing how to copy the header files from a target
  859. machine.  On the target machine, do this:
  860.      (cd /usr/include; tar cf - .) > tarfile
  861.    Then, on the host machine, do this:
  862.      ftp TARGET-MACHINE
  863.      lcd /gnu/TARGET/include
  864.      get tarfile
  865.      quit
  866.      tar xf tarfile
  867.