install.texi

GCC

\input texinfo.tex    @c -*-texinfo-*-
@c @ifnothtml
@c %**start of header
@setfilename install.info
@settitle Installing GCC
@setchapternewpage odd
@c %**end of header
@c @end ifnothtml

@c Specify title for specific html page
@ifset indexhtml
@settitle Installing GCC
@end ifset
@ifset specifichtml
@settitle Host/Target specific installation notes for GCC
@end ifset
@ifset downloadhtml
@settitle Downloading GCC
@end ifset
@ifset configurehtml
@settitle Installing GCC: Configuration
@end ifset
@ifset buildhtml
@settitle Installing GCC: Building
@end ifset
@ifset testhtml
@settitle Installing GCC: Testing
@end ifset
@ifset finalinstallhtml
@settitle Installing GCC: Final installation
@end ifset
@ifset binarieshtml
@settitle Installing GCC: Binaries
@end ifset

@comment $Id: install.texi,v 1.1.2.27 2001/06/15 19:39:05 aj Exp $
@c Copyright (C) 2001 Free Software Foundation, Inc.
@c *** Converted to texinfo by Dean Wakerley, [e-mail]

@c Include everything if we're not making html
@ifnothtml
@set indexhtml
@set specifichtml
@set downloadhtml
@set configurehtml
@set buildhtml
@set testhtml
@set finalinstallhtml
@set binarieshtml
@end ifnothtml

@c Part 2 Summary Description and Copyright
@ifinfo

Copyright @copyright{} 2001 Free Software Foundation, Inc.
@end ifinfo

@c Part 3 Titlepage and Copyright
@titlepage
@sp 10
@comment The title is printed in a large font.
@center @titlefont{Installing GCC}

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2001 Free Software Foundation, Inc.
@end titlepage

@c Part 4 Top node and Master Menu
@ifinfo
@node    Top, , , (dir)
@comment node-name, next,          Previous, up

@menu
* Installing GCC::  This document describes the generic installation
                    procedure for GCC as well as detailing some target
                    specific installation instructions. 

* Specific::        Host/target specific installation notes for GCC.
* Binaries::        Where to get pre-compiled binaries.

* Concept Index::   This index has two entries.
@end menu
@end ifinfo

@c Part 5 The Body of the Document
@c ***Installing GCC**********************************************************
@ifnothtml
@comment node-name,     next,          previous, up
@node    Installing GCC, Binaries, , Top
@end ifnothtml
@ifset indexhtml
@html
<h1 align="center">Installing GCC</h1>
@end html
@ifnothtml
@chapter Installing GCC
@end ifnothtml

The latest version of this document is always available at
@uref{http://gcc.gnu.org/install/,,http://gcc.gnu.org/install/}. 

This document describes the generic installation procedure for GCC as well
as detailing some target specific installation instructions. 

GCC includes several components that previously were separate distributions 
with their own installation instructions. This document supersedes all 
package specific installation instructions. We provide the component 
specific installation information in the source distribution for historical 
reference purposes only. 

@emph{Before} starting the build/install procedure please check the 
@ifnothtml
@xref{Specific, host/target specific installation notes}.
@end ifnothtml
@ifnotinfo
@uref{specific.html,,host/target specific installation notes}. 
@end ifnotinfo
We recommend you browse the entire generic installation instructions before 
you proceed.

The installation procedure itself is broken into five steps. 

@ifinfo
@menu
* Downloading the source::
* Configuration::
* Building::
* Testing:: (optional)
* Final install::
@end menu
@end ifinfo
@ifnotinfo
@enumerate
@item 
@uref{download.html,,Downloading the source}
@item 
@uref{configure.html,,Configuration} 
@item
@uref{build.html,,Building} 
@item 
@uref{test.html,,Testing} (optional) 
@item
@uref{finalinstall.html,,Final install}
@end enumerate
@end ifnotinfo

Please note that GCC does not support @samp{make uninstall} and probably
won't do so in the near future as this would open a can of worms. Instead, 
we suggest that you install GCC into a directory of its own and simply
remove that directory when you do not need that specific version of GCC
any longer. 

@html
<hr>
<p>
@end html
@ifhtml
@uref{./index.html,,Return to the GCC Installation page}
@end ifhtml
@end ifset

@c ***Downloading the source**************************************************
@ifnothtml
@comment node-name,     next,          previous, up
@node    Downloading the source, Configuration, , Installing GCC
@end ifnothtml
@ifset downloadhtml
@html
<h1 align="center">Downloading GCC</h1>
@end html
@ifnothtml
@chapter Downloading GCC
@end ifnothtml
@cindex Downloading GCC
@cindex Downloading the Source

GCC is distributed via CVS and FTP tarballs compressed with @command{gzip} or
@command{bzip2}.  It is possible to download a full distribution or specific
components.

Please refer to our @uref{http://gcc.gnu.org/releases.html,,releases web page}
for information on how to obtain GCC.

The full distribution includes the C, C++, Objective-C, Fortran, Java,
and Chill compilers.  The full distribution also includes runtime libraries
for C++, Objective-C, Fortran, Java and Chill.  (GCC 3.0 does not
include Chill.  Releases before 3.0 do not include the Java runtime
library.)  In GCC 3.0 and later versions, GNU compiler testsuites
are also included in the full distribution.

If you choose to download specific components, you must download the core
gcc distribution plus any language specific distributions you wish to
use.  The core distribution includes the C language front-end as well as the
shared components. Each language has a tarball which includes the language
front-end as well as the language runtime (when appropriate).

Unpack the core distribution as well as any language specific
distributions in the same directory.

If you also intend to build binutils (either to upgrade an existing
installation or for use in place of the corresponding tools of your
OS), unpack the binutils distribution either in the same directory or
a separate one.  In the latter case, add symbolic links to any
components of the binutils you intend to build alongside the compiler
(@file{bfd}, @file{binutils}, @file{gas}, @file{gprof}, @file{ld},
@file{opcodes}, @dots{}) to the directory containing the GCC sources.

@html
<hr>
<p>
@end html
@ifhtml
@uref{./index.html,,Return to the GCC Installation page}
@end ifhtml
@end ifset

@c ***Configuration***********************************************************
@ifnothtml
@comment node-name,     next,          previous, up
@node    Configuration, Building, Downloading the source, Installing GCC
@end ifnothtml
@ifset configurehtml
@html
<h1 align="center">Installing GCC: Configuration</h1>
@end html
@ifnothtml
@chapter Installing GCC: Configuration
@end ifnothtml
@cindex Configuration
@cindex Installing GCC: Configuration

Like most GNU software, GCC must be configured before it can be built.
This document describes the recommended configuration procedure
for both native and cross targets.

We use @var{srcdir} to refer to the toplevel source directory for
GCC; we use @var{objdir} to refer to the toplevel build/object directory.

If you obtained the sources via CVS, @var{srcdir} must refer to the top
@file{gcc} directory, the one where the @file{MAINTAINERS} can be found,
and not its @file{gcc} subdirectory, otherwise the build will fail.

First, we @strong{highly} recommend that GCC be built into a
separate directory than the sources which does @strong{not} reside
within the source tree.  This is how we generally build GCC; building
where @var{srcdir} == @var{objdir} should still work, but doesn't
get extensive testing; building where @var{objdir} is a subdirectory
of @var{srcdir} is unsupported.

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.  However, with the recommended method of building in a separate
@var{objdir}, you should simply use a different @var{objdir} for each
target.

Second, when configuring a native system, either @command{cc} or
@command{gcc} must be in your path or you must set @env{CC} in
your environment before running configure.  Otherwise the configuration
scripts may fail.

To configure GCC:

@example
   % mkdir @var{objdir}
   % cd @var{objdir}
   % @var{srcdir}/configure [@var{target}] [@var{options}]
@end example


@heading Target specification
@itemize @bullet
@item
GCC has code to correctly determine the correct value for @var{target}
for nearly all native systems.  Therefore, we highly recommend you not 
provide a configure target when configuring a native compiler.

@item
@var{target} must be specified as @option{--target=@var{target}}
when configuring a cross compiler; examples of valid targets would be 
i960-rtems, m68k-coff, sh-elf, etc.

@item
Specifying just @var{target} instead of @option{--target=@var{target}}
implies that the host defaults to @var{target}.
@end itemize


@heading Options specification

Use @var{options} to override several configure time options for
GCC.  A partial list of supported @var{options}:

@table @code
@item --prefix=@var{dirname}
Specify the toplevel installation
directory.  This is the recommended way to install the tools into a directory
other than the default.  The toplevel installation directory defaults to
@file{/usr/local}.

We @strong{highly} recommend against @var{dirname} being the same or a
subdirectory of @var{objdir} or vice versa.

These additional options control where certain parts of the distribution
are installed.  Normally you should not need to use these options.
@table @code

@item --exec-prefix=@var{dirname}
Specify the toplevel installation directory for architecture-dependent
files.  The default is @file{@var{prefix}}.

@item --bindir=@var{dirname}
Specify the installation directory for the executables called by users
(such as @command{gcc} and @command{g++}).  The default is
@file{@var{exec-prefix}/bin}.

@item --libdir=@var{dirname}
Specify the installation directory for object code libraries and
internal parts of GCC.  The default is @file{@var{exec-prefix}/lib}.

@item --with-slibdir=@var{dirname}
Specify the installation directory for the shared libgcc library.  The
default is @file{@var{libdir}}.

@item --infodir=@var{dirname}
Specify the installation directory for documentation in info format.
The default is @file{@var{prefix}/info}.

@item --mandir=@var{dirname}
Specify the installation directory for manual pages.  The default is
@file{@var{prefix}/man}.  (Note that the manual pages are only extracts from
the full GCC manuals, which are provided in Texinfo format.  The
@command{g77} manpage is unmaintained and may be out of date; the others
are derived by an automatic conversion process from parts of the full
manual.)

@item --with-gxx-include-dir=@var{dirname}
Specify
the installation directory for g++ header files.  The default is
@file{@var{prefix}/include/g++-v3}.

@end table

@item --with-local-prefix=@var{dirname}
Specify the
installation directory for local include files.  The default is
@file{/usr/local}.  Specify this option if you want the compiler to
search directory @file{@var{dirname}/include} for locally installed
header files @emph{instead} of @file{/usr/local/include}.

You should specify @option{--with-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 @option{--with-local-prefix} is @file{/usr/local}
regardless of the value of @option{--prefix}.  Specifying
@option{--prefix} has no effect on which directory GCC searches for
local header files.  This may seem counterintuitive, but actually it is
logical.

The purpose of @option{--prefix} is to specify where to @emph{install
GCC}.  The local header files in @file{/usr/local/include}---if you put
any in that directory---are not part of GCC.  They are part of other
programs---perhaps many others.  (GCC installs its own header files in
another directory which is based on the @option{--prefix} value.)

@strong{Do not} specify @file{/usr} as the @option{--with-local-prefix}!
The directory you use for @option{--with-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