install.texi

\input texinfo.tex    @c -*-texinfo-*-
@c @ifnothtml
@c %**start of header
@setfilename gccinstall.info
@setchapternewpage odd
@c %**end of header
@c @end ifnothtml

@include gcc-common.texi

@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 prerequisiteshtml
@settitle Prerequisites 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
@ifset gfdlhtml
@settitle Installing GCC: GNU Free Documentation License
@end ifset

@c Copyright (C) 1988-2025 Free Software Foundation, Inc.
@c *** Converted to texinfo by Dean Wakerley, dean@wakerley.com

@c IMPORTANT: whenever you modify this file, run `install.texi2html' to
@c test the generation of HTML documents for the gcc.gnu.org web pages.
@c
@c Do not use @footnote{} in this file as it breaks install.texi2html!

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

@c Part 2 Summary Description and Copyright
@copying
Copyright @copyright{} 1988-2025 Free Software Foundation, Inc.
@sp 1
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, the Front-Cover texts being (a) (see below), and
with the Back-Cover Texts being (b) (see below).  A copy of the
license is included in the section entitled ``@uref{./gfdl.html,,GNU
Free Documentation License}''.

(a) The FSF's Front-Cover Text is:

     A GNU Manual

(b) The FSF's Back-Cover Text is:

     You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development.
@end copying
@ifinfo
@insertcopying
@end ifinfo
@dircategory Software development
@direntry
* gccinstall: (gccinstall).    Installing the GNU Compiler Collection.
@end direntry

@c Part 3 Titlepage and Copyright
@titlepage
@title Installing GCC
@versionsubtitle

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@c Part 4 Top node, Master Menu, and/or Table of Contents
@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.

* GNU Free Documentation License:: How you can copy and share this manual.
* Concept Index::   This index has two entries.
@end menu
@end ifinfo

@iftex
@contents
@end iftex

@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
@ifnothtml
@chapter Installing GCC
@end ifnothtml

The latest version of this document is always available at
@uref{https://gcc.gnu.org/install/,,https://gcc.gnu.org/install/}.
It refers to the current development sources, instructions for
specific released versions are included with the sources.

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.

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

The installation procedure itself is broken into five steps.

@ifinfo
@menu
* Prerequisites::
* Downloading the source::
* Configuration::
* Building::
* Testing:: (optional)
* Final install::
@end menu
@end ifinfo
@ifhtml
@enumerate
@item
@uref{prerequisites.html,,Prerequisites}
@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 ifhtml

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, and, if shared libraries are installed there as well, no
more binaries exist that use them.

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

@insertcopying
@end ifhtml
@end ifset

@c ***Prerequisites**************************************************
@ifnothtml
@comment node-name,     next,          previous, up
@node    Prerequisites, Downloading the source, , Installing GCC
@end ifnothtml
@ifset prerequisiteshtml
@ifnothtml
@chapter Prerequisites
@end ifnothtml
@cindex Prerequisites

GCC requires that various tools and packages be available for use in the
build procedure.  Modifying GCC sources requires additional tools
described below.

@heading Tools/packages necessary for building GCC
@table @asis
@item ISO C++14 compiler
Necessary to bootstrap GCC.  GCC 5.4 or newer has sufficient support
for used C++14 features.

Versions of GCC prior to 15 allow bootstrapping with an ISO C++11
compiler, versions prior to 10.5 allow bootstrapping with an ISO C++98
compiler, and versions prior to 4.8 allow bootstrapping with an ISO
C89 compiler.

If you need to build an intermediate version of GCC in order to
bootstrap current GCC, consider GCC 9.5: it can build the current Ada
and D compilers, and was also the version that declared C++17 support
stable.

To build all languages in a cross-compiler or other configuration where
3-stage bootstrap is not performed, you need to start with an existing
GCC binary (of a new enough version) because source code for language
frontends other than C might use GCC extensions.

@item C standard library and headers

In order to build GCC, the C standard library and headers must be present
for all target variants for which target libraries will be built (and not
only the variant of the host C++ compiler).

This affects the popular @samp{x86_64-pc-linux-gnu} platform (among
other multilib targets), for which 64-bit (@samp{x86_64}) and 32-bit
(@samp{i386}) libc headers are usually packaged separately. If you do a
build of a native compiler on @samp{x86_64-pc-linux-gnu}, make sure you
either have the 32-bit libc developer package properly installed (the exact
name of the package depends on your distro) or you must build GCC as a
64-bit only compiler by configuring with the option
@option{--disable-multilib}.  Otherwise, you may encounter an error such as
@samp{fatal error: gnu/stubs-32.h: No such file}

@item Python
If you configure a RISC-V compiler with the option @option{--with-arch} and
the specified architecture string is non-canonical, then you will need
@command{python} installed on the build system.

@item @anchor{GNAT-prerequisite}GNAT

In order to build GNAT, the Ada compiler, you need a working GNAT
compiler (GCC version 5.1 or later).

This includes GNAT tools such as @command{gnatmake} and
@command{gnatlink}, since the Ada front end is written in Ada and
uses some GNAT-specific extensions.

In order to build a cross compiler, it is strongly recommended to install
the new compiler as native first, and then use it to build the cross
compiler. Other native compiler versions may work but this is not guaranteed and
will typically fail with hard to understand compilation errors during the
build.

Similarly, it is strongly recommended to use an older version of GNAT to build
GNAT. More recent versions of GNAT than the version built are not guaranteed
to work and will often fail during the build with compilation errors.

Note that @command{configure} does not test whether the GNAT installation works
and has a sufficiently recent version; if too old a GNAT version is
installed and @option{--enable-languages=ada} is used, the build will fail.

@env{ADA_INCLUDE_PATH} and @env{ADA_OBJECT_PATH} environment variables
must not be set when building the Ada compiler, the Ada tools, or the
Ada runtime libraries. You can check that your build environment is clean
by verifying that @samp{gnatls -v} lists only one explicit path in each
section.

@item @anchor{GDC-prerequisite}GDC

In order to build GDC, the D compiler, you need a working GDC
compiler (GCC version 9.4 or later) and D runtime library,
@samp{libphobos}, as the D front end is written in D.

Versions of GDC prior to 12 can be built with an ISO C++11 compiler, which can
then be installed and used to bootstrap newer versions of the D front end.

It is strongly recommended to use an older version of GDC to build GDC. More
recent versions of GDC than the version built are not guaranteed to work and
will often fail during the build with compilation errors relating to
deprecations or removed features.

Note that @command{configure} does not test whether the GDC installation works
and has a sufficiently recent version.  Though the implementation of the D
front end does not make use of any GDC-specific extensions, or novel features
of the D language, if too old a GDC version is installed and
@option{--enable-languages=d} is used, the build will fail.

On some targets, @samp{libphobos} isn't enabled by default, but compiles
and works if @option{--enable-libphobos} is used.  Specifics are
documented for affected targets.

@item @anchor{GM2-prerequisite}GM2

Python3 is required if you want to build the complete Modula-2
documentation including the target @code{SYSTEM} definition module.
If Python3 is unavailable Modula-2 documentation will include a target
independent version of the SYSTEM modules.

@item A ``working'' POSIX compatible shell, or GNU bash

Necessary when running @command{configure} because some
@command{/bin/sh} shells have bugs and may crash when configuring the
target libraries.  In other cases, @command{/bin/sh} or @command{ksh}
have disastrous corner-case performance problems.  This
can cause target @command{configure} runs to literally take days to
complete in some cases.

So on some platforms @command{/bin/ksh} is sufficient, on others it
isn't.  See the host/target specific instructions for your platform, or
use @command{bash} to be sure.  Then set @env{CONFIG_SHELL} in your
environment to your ``good'' shell prior to running
@command{configure}/@command{make}.

@command{zsh} is not a fully compliant POSIX shell and will not
work when configuring GCC@.

@item GNU flex

Necessary to build the lexical analysis module.

@item A POSIX or SVR4 awk

Necessary for creating some of the generated source files for GCC@.
If in doubt, use a recent GNU awk version.

@item GNU binutils

Necessary in some circumstances, optional in others.  See the
host/target specific instructions for your platform for the exact
requirements.

Note binutils 2.35 or newer is required for LTO to work correctly
with GNU libtool that includes doing a bootstrap with LTO enabled.

@item gzip version 1.2.4 (or later) or
@itemx bzip2 version 1.0.2 (or later)

Necessary to uncompress GCC @command{tar} files when source code is
obtained via HTTPS mirror sites.

@item GNU make version 3.80 (or later)

You must have GNU make installed to build GCC@.

@item GNU tar version 1.14 (or later)

Necessary (only on some platforms) to untar the source code.  Many
systems' @command{tar} programs will also work, only try GNU
@command{tar} if you have problems.

@item Perl version 5.6.1 (or later)

Necessary when targeting Darwin, building @samp{libstdc++},
and not using @option{--disable-symvers}.
Necessary when targeting Solaris with Solaris @command{ld} and not using
@option{--disable-symvers}.

Necessary when regenerating @file{Makefile} dependencies in libiberty.
Necessary when regenerating @file{libiberty/functions.texi}.
Necessary when generating manpages from Texinfo manuals.
Used by various scripts to generate some files included in the source
repository (mainly Unicode-related and rarely changing) from source
tables.

Used by @command{automake}.

If available, enables parallel testing of @samp{libgomp} in case that
@command{flock} is not available.

@end table

Several support libraries are necessary to build GCC, some are required,
others optional.  While any sufficiently new version of required tools
usually work, library requirements are generally stricter.  Newer
versions may work in some cases, but it's safer to use the exact
versions documented.  We appreciate bug reports about problems with
newer versions, though.  If your OS vendor provides packages for the
support libraries then using those packages may be the simplest way to
install the libraries.

@table @asis
@item GNU Multiple Precision Library (GMP) version 4.3.2 (or later)

Necessary to build GCC@.  It can be downloaded from
@uref{https://gmplib.org/}.  If a GMP source distribution is found in a
subdirectory of your GCC sources named @file{gmp}, it will be built
together with GCC.  Alternatively, if GMP is already installed but it
is not in your library search path, you will have to configure with the
@option{--with-gmp} configure option.  See also @option{--with-gmp-lib}
and @option{--with-gmp-include}.
The in-tree build is only supported with the GMP version that
download_prerequisites installs.

@item MPFR Library version 3.1.0 (or later)

Necessary to build GCC@.  It can be downloaded from
@uref{https://www.mpfr.org}.  If an MPFR source distribution is found
in a subdirectory of your GCC sources named @file{mpfr}, it will be
built together with GCC.  Alternatively, if MPFR is already installed
but it is not in your default library search path, the
@option{--with-mpfr} configure option should be used.  See also
@option{--with-mpfr-lib} and @option{--with-mpfr-include}.
The in-tree build is only supported with the MPFR version that
download_prerequisites installs.

@item MPC Library version 1.0.1 (or later)

Necessary to build GCC@.  It can be downloaded from
@uref{https://www.multiprecision.org/mpc/}.  If an MPC source distribution
is found in a subdirectory of your GCC sources named @file{mpc}, it
will be built together with GCC.  Alternatively, if MPC is already
installed but it is not in your default library search path, the
@option{--with-mpc} configure option should be used.  See also
@option{--with-mpc-lib} and @option{--with-mpc-include}.
The in-tree build is only supported with the MPC version that
download_prerequisites installs.

@item isl Library version 0.15 or later.

Necessary to build GCC with the Graphite loop optimizations.
It can be downloaded from @uref{https://gcc.gnu.org/pub/gcc/infrastructure/}.
If an isl source distribution is found
in a subdirectory of your GCC sources named @file{isl}, it will be
built together with GCC.  Alternatively, the @option{--with-isl} configure
option should be used if isl is not installed in your default library
search path.

@item zstd Library.

Necessary to build GCC with zstd compression used for LTO bytecode.
The library is searched in your default library patch search.
Alternatively, the @option{--with-zstd} configure option should be used.

@item Python3 modules

The complete list of Python3 modules broken down by GCC subcomponent
is shown below:

@table @asis
@item internal debugging in gdbhooks
@code{gdb}, @code{gdb.printing}, @code{gdb.types},
@code{os.path}, @code{re}, @code{sys} and @code{tempfile},

@item g++ testsuite
@code{gcov}, @code{gzip}, @code{json}, @code{os} and @code{pytest}.

@item SARIF testsuite
Tests of SARIF output will use the @code{check-jsonschema} program from
the @code{check-jsonschema} module (if available) to validate generated
.sarif files.  If this tool is not found, the validation parts of those
tests are skipped.

@item c++ cxx api generation
@code{csv}, @code{os}, @code{sys} and @code{time}.

@item modula-2 documentation
@code{argparse}, @code{os}, @code{pathlib}, @code{shutil} and
@code{sys}.

@item git developer tools
@code{os} and @code{sys}.

@item ada documentation
@code{latex_elements}, @code{os}, @code{pygments}, @code{re},
@code{sys} and @code{time}.
@end table

@item GNU gettext

Necessary to build GCC with internationalization support via
@option{--enable-nls}.  It can be downloaded from
@uref{https://www.gnu.org/software/gettext/}. If a GNU gettext distribution
is found in a subdirectory of your GCC sources named @file{gettext}, it
will be built together with GCC, unless present in the system (either in
libc or as a stand-alone library).

The in-tree configuration requires GNU gettext version 0.22 or later.

@end table

@heading Tools/packages necessary for modifying GCC
@table @asis
@item autoconf version 2.69
@itemx GNU m4 version 1.4.6 (or later)

Necessary when modifying @file{configure.ac}, @file{aclocal.m4}, etc.@:
to regenerate @file{configure} and @file{config.in} files.

@item automake version 1.15.1

Necessary when modifying a @file{Makefile.am} file to regenerate its
associated @file{Makefile.in}.

Much of GCC does not use automake, so directly edit the @file{Makefile.in}
file.  Specifically this applies to the @file{gcc}, @file{intl},
@file{libcpp}, @file{libiberty}, @file{libobjc} directories as well
as any of their subdirectories.

For directories that use automake, GCC requires the latest release in
the 1.15 series, which is currently 1.15.1.  When regenerating a directory
to a newer version, please update all the directories using an older 1.15
to the latest released version.

@item gettext version 0.14.5 (or later)

Needed to regenerate @file{gcc.pot}.

@item gperf version 2.7.2 (or later)

Necessary when modifying @command{gperf} input files, e.g.@:
@file{gcc/cp/cfns.gperf} to regenerate its associated header file, e.g.@:
@file{gcc/cp/cfns.h}.

@item DejaGnu version 1.5.3 (or later)
@itemx Expect
@itemx Tcl
@c Once Tcl 8.5 or higher is required, remove any obsolete
@c compatibility workarounds:
@c     git grep 'compatibility with earlier Tcl releases'

Necessary to run the GCC testsuite; see the section on testing for
details.

@item autogen version 5.5.4 (or later) and
@itemx guile version 1.4.1 (or later)

Necessary to regenerate @file{fixinc/fixincl.x} from
@file{fixinc/inclhack.def} and @file{fixinc/*.tpl}.

Necessary to run @samp{make check} for @file{fixinc}.

Necessary to regenerate the top level @file{Makefile.in} file from
@file{Makefile.tpl} and @file{Makefile.def}.

Necessary to regenerate the @file{bits/version.h} header for libstdc++.

@item Flex version 2.5.4 (or later)

Necessary when modifying @file{*.l} files.

Necessary to build GCC during development because the generated output
files are not included in the version-controlled source repository.
They are included in releases.

@item Texinfo version 4.7 (or later)

Necessary for running @command{makeinfo} when modifying @file{*.texi}
files to test your changes.

Necessary for running @command{make dvi}, @command{make pdf},
or @command{make html} to create formatted documentation.  Texinfo version
4.8 or later is required for @command{make pdf}.

Necessary to build GCC documentation in info format during development
because the generated output files are not included in the repository.
(They are included in release tarballs.)

Note that the minimum requirement is for a very old version of
Texinfo, but recent versions of Texinfo produce better-quality output,
especially for HTML format.  The version of Texinfo packaged with any
current operating system distribution is likely to be adequate for
building the documentation without error, but you may still want to
install a newer release to get the best appearance and usability of
the generated manuals.

@item @TeX{} (any working version)

Necessary for running @command{texi2dvi} and @command{texi2pdf}, which
are used when running @command{make dvi} or @command{make pdf} to create
DVI or PDF files, respectively.

@item Sphinx version 1.0 (or later)

Necessary to regenerate @file{jit/docs/_build/texinfo} from the @file{.rst}
files in the directories below @file{jit/docs}.

@item git (any version)
@itemx SSH (any version)

Necessary to access the source repository.  Public releases and weekly
snapshots of the development sources are also available via HTTPS@.

@item GNU diffutils version 2.7 (or later)

Useful when submitting patches for the GCC source code.

@item patch version 2.5.4 (or later)

Necessary when applying patches, created with @command{diff}, to one's
own sources.

@end table

@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, Prerequisites, Installing GCC
@end ifnothtml
@ifset downloadhtml
@ifnothtml
@chapter Downloading GCC
@end ifnothtml
@cindex Downloading GCC
@cindex Downloading the Source

GCC is distributed via @uref{https://gcc.gnu.org/git.html,,git} and via
HTTPS as tarballs compressed with @command{gzip} or @command{bzip2}.

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

The source distribution includes the Ada, C, C++, Objective-C, D (GCC 9
and later), Fortran, Go, and Modula-2 (GCC 13 and later) compilers, as
well as runtime libraries for C++, Objective-C, and Fortran.
For previous versions these were downloadable as separate components such
as the core GCC distribution, which included the C language front end and
shared components, and language-specific distributions including the
language front end and the language runtime (where appropriate).

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.

Likewise the GMP, MPFR, MPC and Gettext libraries can be automatically
built together with GCC.  You may simply run the
@command{contrib/download_prerequisites} script in the GCC source directory
to set up everything.
Otherwise unpack the GMP, MPFR, MPC and/or Gettext source
distributions in the directory containing the GCC sources and rename
their directories to @file{gmp}, @file{mpfr}, @file{mpc} and
@file{gettext}, respectively (or use symbolic links with the same name).

@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
@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 by cloning the repository, @var{srcdir}
must refer to the top @file{gcc} directory, the one where the
@file{MAINTAINERS} file can be found, and not its @file{gcc}
subdirectory, otherwise the build will fail.

If either @var{srcdir} or @var{objdir} is located on an automounted NFS
file system, the shell's built-in @command{pwd} command will return
temporary pathnames.  Using these can lead to various sorts of build
problems.  To avoid this issue, set the @env{PWDCMD} environment
variable to an automounter-aware @command{pwd} command, e.g.,
@command{pawd} or @samp{amq -w}, during the configuration and build
phases.

First, we @strong{highly} recommend that GCC be built into a
separate directory from the sources which does @strong{not} reside
within the source tree.  This is how we generally build GCC; building
where @var{objdir} is a subdirectory of @var{srcdir} should work as well;
building where @var{objdir} == @var{srcdir} is unsupported.

If you have previously built GCC 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
or issues a message like ``don't know how to make distclean'' 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.

@ignore
Note that the bootstrap compiler and the resulting GCC must be link
compatible, else the bootstrap will fail with linker errors about
incompatible object file formats.  Several multilibed targets are
affected by this requirement, see
@ifnothtml
@ref{Specific, host/target specific installation notes}.
@end ifnothtml
@ifhtml
@uref{specific.html,,host/target specific installation notes}.
@end ifhtml
@end ignore

To configure GCC:

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

@heading Distributor options

If you will be distributing binary versions of GCC, with modifications
to the source code, you should use the options described in this
section to make clear that your version contains modifications.

@table @code
@item --with-pkgversion=@var{version}
Specify a string that identifies your package.  You may wish
to include a build number or build date.  This version string will be
included in the output of @command{gcc --version}.  This suffix does
not replace the default version string, only the @samp{GCC} part.

The default value is @samp{GCC}.

@item --with-bugurl=@var{url}
Specify the URL that users should visit if they wish to report a bug.
You are of course welcome to forward bugs reported to you to the FSF,
if you determine that they are not bugs in your modifications.

The default value refers to the FSF's GCC bug tracker.

@item --with-documentation-root-url=@var{url}
Specify the URL root that contains GCC option documentation.  The @var{url}
should end with a @code{/} character.

The default value is @uref{https://gcc.gnu.org/onlinedocs/,,https://gcc.gnu.org/onlinedocs/}
on the GCC main development trunk.  On release branches, the default
is @code{https://gcc.gnu.org/onlinedocs/gcc-@var{major}.@var{minor}.0/}.

@item --with-changes-root-url=@var{url}
Specify the URL root that contains information about changes in GCC
releases like @code{gcc-@var{version}/changes.html}.
The @var{url} should end with a @code{/} character.

The default value is @uref{https://gcc.gnu.org/,,https://gcc.gnu.org/}.

@end table

@heading Host, Build and Target specification

Specify the host, build and target machine configurations.  You do this
when you run the @file{configure} script.

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 @option{--host} option; the host and target will default to be
the same as the host machine.

Here is an example:

@smallexample
./configure --host=x86_64-pc-linux-gnu
@end smallexample

A configuration name may be canonical or it may be more or less
abbreviated (@file{config.sub} script produces canonical versions).

A canonical configuration name has three parts, separated by dashes.
It looks like this: @samp{@var{cpu}-@var{company}-@var{system}}.

Here are the possible CPU types:

@quotation
aarch64, aarch64_be, alpha, alpha64, amdgcn, arc, arceb, arm, armeb, avr, bfin,
bpf, cris, csky, epiphany, fido, fr30, frv, ft32, h8300, hppa, hppa2.0,
hppa64, i486, i686, ia64, iq2000, lm32, loongarch64, m32c, m32r, m32rle, m68k,
mcore, microblaze, microblazeel, mips, mips64, mips64el, mips64octeon,
mips64orion, mips64vr, mipsel, mipsisa32, mipsisa32r2, mipsisa64, mipsisa64r2,
mipsisa64r2el, mipsisa64sb1, mipsisa64sr71k, mipstx39, mmix, mn10300, moxie,
msp430, nds32be, nds32le, nvptx, or1k, pdp11, powerpc, powerpc64,
powerpc64le, powerpcle, pru, riscv32, riscv32be, riscv64, riscv64be, rl78, rx,
s390, s390x, sh, shle, sparc, sparc64, tic6x, v850,
v850e, v850e1, vax, visium, x86_64, xstormy16, xtensa
@end quotation

Here is a list of system types:

@quotation
aix@var{version}, amdhsa, aout, cygwin, darwin@var{version},
eabi, eabialtivec, eabisim, eabisimaltivec, elf, elf32,
elfbare, elfoabi, freebsd@var{version}, gnu, hpux, hpux@var{version},
kfreebsd-gnu, kopensolaris-gnu, linux-androideabi, linux-gnu,
linux-gnu_altivec, linux-musl, linux-uclibc, lynxos, mingw32, mingw32crt,
mmixware, msdosdjgpp, netbsd, netbsdelf@var{version}, nto-qnx, openbsd,
rtems, solaris@var{version}, symbianelf, tpf, uclinux, uclinux_eabi, vms,
vxworks, vxworksae, vxworksmils
@end quotation

@heading Options specification

Use @var{options} to override several configure time options for
GCC@.  A list of supported @var{options} follows; @samp{configure
--help} may list other options, but those not listed below may not
work and should not normally be used.

Note that each @option{--enable} option has a corresponding
@option{--disable} option and that each @option{--with} option has a
corresponding @option{--without} option.

@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.  If specifying a directory
beneath a user's home directory tree, some shells will not expand
@var{dirname} correctly if it contains the @samp{~} metacharacter; use
@env{$HOME} instead.

The following standard @command{autoconf} options are supported.  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 data files of GCC@.  The default is @file{@var{exec-prefix}/lib}.

@item --libexecdir=@var{dirname}
Specify the installation directory for internal executables of GCC@.
The default is @file{@var{exec-prefix}/libexec}.

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

@item --datarootdir=@var{dirname}
Specify the root of the directory tree for read-only architecture-independent
data files referenced by GCC@.  The default is @file{@var{prefix}/share}.

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

@item --datadir=@var{dirname}
Specify the installation directory for some architecture-independent
data files referenced by GCC@.  The default is @file{@var{datarootdir}}.

@item --docdir=@var{dirname}
Specify the installation directory for documentation files (other
than Info) for GCC@.  The default is @file{@var{datarootdir}/doc}.

@item --htmldir=@var{dirname}
Specify the installation directory for HTML documentation files.
The default is @file{@var{docdir}}.

@item --pdfdir=@var{dirname}
Specify the installation directory for PDF documentation files.
The default is @file{@var{docdir}}.

@item --mandir=@var{dirname}
Specify the installation directory for manual pages.  The default is
@file{@var{datarootdir}/man}.  (Note that the manual pages are only extracts
from the full GCC manuals, which are provided in Texinfo format.  The manpages
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 depends
on other configuration options, and differs between cross and native
configurations.

@item --with-specs=@var{specs}
Specify additional command line driver SPECS.
This can be useful if you need to turn on a non-standard feature by
default without modifying the compiler's source code, for instance
@option{--with-specs=%@{!fcommon:%@{!fno-common:-fno-common@}@}}.
@ifnothtml
@xref{Spec Files,, Specifying subprocesses and the switches to pass to them,
gcc, Using the GNU Compiler Collection (GCC)},
@end ifnothtml
@ifhtml
See ``Spec Files'' in the main manual
@end ifhtml

@end table

@item --program-prefix=@var{prefix}
GCC supports some transformations of the names of its programs when
installing them.  This option prepends @var{prefix} to the names of
programs to install in @var{bindir} (see above).  For example, specifying
@option{--program-prefix=foo-} would result in @samp{gcc}
being installed as @file{/usr/local/bin/foo-gcc}.

@item --program-suffix=@var{suffix}
Appends @var{suffix} to the names of programs to install in @var{bindir}
(see above).  For example, specifying @option{--program-suffix=-3.1}
would result in @samp{gcc} being installed as
@file{/usr/local/bin/gcc-3.1}.

@item --program-transform-name=@var{pattern}
Applies the @samp{sed} script @var{pattern} to be applied to the names
of programs to install in @var{bindir} (see above).  @var{pattern} has to
consist of one or more basic @samp{sed} editing commands, separated by
semicolons.  For example, if you want the @samp{gcc} program name to be
transformed to the installed program @file{/usr/local/bin/myowngcc} and
the @samp{g++} program name to be transformed to
@file{/usr/local/bin/gspecial++} without changing other program names,
you could use the pattern
@option{--program-transform-name='s/^gcc$/myowngcc/; s/^g++$/gspecial++/'}
to achieve this effect.

All three options can be combined and used together, resulting in more
complex conversion patterns.  As a basic rule, @var{prefix} (and
@var{suffix}) are prepended (appended) before further transformations
can happen with a special transformation script @var{pattern}.

As currently implemented, this option only takes effect for native
builds; cross compiler binaries' names are not transformed even when a
transformation is explicitly asked for by one of these options.

For native builds, some of the installed programs are also installed
with the target alias in front of their name, as in
@samp{i686-pc-linux-gnu-gcc}.  All of the above transformations happen
before the target alias is prepended to the name---so, specifying
@option{--program-prefix=foo-} and @option{program-suffix=-3.1}, the
resulting binary would be installed as
@file{/usr/local/bin/i686-pc-linux-gnu-foo-gcc-3.1}.

As a last shortcoming, none of the installed Ada programs are
transformed yet, which will be fixed in some time.

@item --with-local-prefix=@var{dirname}