gcc/doc/install/prerequisites.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. index:: Prerequisites
   7
   8 .. _prerequisites:
   9
  10 Prerequisites
  11 -------------
  12
  13 GCC requires that various tools and packages be available for use in the
  14 build procedure.  Modifying GCC sources requires additional tools
  15 described below.
  16
  17 Tools/packages necessary for building GCC
  18 *****************************************
  19
  20 * ISO C++11 compiler
  21
  22   Necessary to bootstrap GCC.
  23
  24   Versions of GCC prior to 11 also allow bootstrapping with an ISO C++98
  25   compiler, versions of GCC prior to 4.8 also allow bootstrapping with a
  26   ISO C89 compiler, and versions of GCC prior to 3.4 also allow
  27   bootstrapping with a traditional (K&R) C compiler.
  28
  29   To build all languages in a cross-compiler or other configuration where
  30   3-stage bootstrap is not performed, you need to start with an existing
  31   GCC binary (version 4.8 or later) because source code for language
  32   frontends other than C might use GCC extensions.
  33
  34 * C standard library and headers
  35
  36   In order to build GCC, the C standard library and headers must be present
  37   for all target variants for which target libraries will be built (and not
  38   only the variant of the host C++ compiler).
  39
  40   This affects the popular :samp:`x86_64-pc-linux-gnu` platform (among
  41   other multilib targets), for which 64-bit (:samp:`x86_64`) and 32-bit
  42   (:samp:`i386`) libc headers are usually packaged separately. If you do a
  43   build of a native compiler on :samp:`x86_64-pc-linux-gnu`, make sure you
  44   either have the 32-bit libc developer package properly installed (the exact
  45   name of the package depends on your distro) or you must build GCC as a
  46   64-bit only compiler by configuring with the option
  47   :option:`--disable-multilib`.  Otherwise, you may encounter an error such as
  48   :samp:`fatal error: gnu/stubs-32.h: No such file`
  49
  50 .. _gnat-prerequisite:
  51
  52 * GNAT
  53
  54   In order to build GNAT, the Ada compiler, you need a working GNAT
  55   compiler (GCC version 5.1 or later).
  56
  57   This includes GNAT tools such as :command:`gnatmake` and
  58   :command:`gnatlink`, since the Ada front end is written in Ada and
  59   uses some GNAT-specific extensions.
  60
  61   In order to build a cross compiler, it is strongly recommended to install
  62   the new compiler as native first, and then use it to build the cross
  63   compiler. Other native compiler versions may work but this is not guaranteed and
  64   will typically fail with hard to understand compilation errors during the
  65   build.
  66
  67   Similarly, it is strongly recommended to use an older version of GNAT to build
  68   GNAT. More recent versions of GNAT than the version built are not guaranteed
  69   to work and will often fail during the build with compilation errors.
  70
  71   Note that :command:`configure` does not test whether the GNAT installation works
  72   and has a sufficiently recent version; if too old a GNAT version is
  73   installed and :option:`--enable-languages=ada` is used, the build will fail.
  74
  75   :envvar:`ADA_INCLUDE_PATH` and :envvar:`ADA_OBJECT_PATH` environment variables
  76   must not be set when building the Ada compiler, the Ada tools, or the
  77   Ada runtime libraries. You can check that your build environment is clean
  78   by verifying that :samp:`gnatls -v` lists only one explicit path in each
  79   section.
  80
  81 .. _gdc-prerequisite:
  82
  83 * GDC
  84
  85   In order to build GDC, the D compiler, you need a working GDC
  86   compiler (GCC version 9.1 or later) and D runtime library,
  87   :samp:`libphobos`, as the D front end is written in D.
  88
  89   Versions of GDC prior to 12 can be built with an ISO C++11 compiler, which can
  90   then be installed and used to bootstrap newer versions of the D front end.
  91
  92   It is strongly recommended to use an older version of GDC to build GDC. More
  93   recent versions of GDC than the version built are not guaranteed to work and
  94   will often fail during the build with compilation errors relating to
  95   deprecations or removed features.
  96
  97   Note that :command:`configure` does not test whether the GDC installation works
  98   and has a sufficiently recent version.  Though the implementation of the D
  99   front end does not make use of any GDC-specific extensions, or novel features
 100   of the D language, if too old a GDC version is installed and
 101   :option:`--enable-languages=d` is used, the build will fail.
 102
 103   On some targets, :samp:`libphobos` isn't enabled by default, but compiles
 104   and works if :option:`--enable-libphobos` is used.  Specifics are
 105   documented for affected targets.
 106
 107 * A 'working' POSIX compatible shell, or GNU bash
 108
 109   Necessary when running :command:`configure` because some
 110   :command:`/bin/sh` shells have bugs and may crash when configuring the
 111   target libraries.  In other cases, :command:`/bin/sh` or :command:`ksh`
 112   have disastrous corner-case performance problems.  This
 113   can cause target :command:`configure` runs to literally take days to
 114   complete in some cases.
 115
 116   So on some platforms :command:`/bin/ksh` is sufficient, on others it
 117   isn't.  See the host/target specific instructions for your platform, or
 118   use :command:`bash` to be sure.  Then set :envvar:`CONFIG_SHELL` in your
 119   environment to your 'good' shell prior to running
 120   :command:`configure`/:command:`make`.
 121
 122   :command:`zsh` is not a fully compliant POSIX shell and will not
 123   work when configuring GCC.
 124
 125 * A POSIX or SVR4 awk
 126
 127   Necessary for creating some of the generated source files for GCC.
 128   If in doubt, use a recent GNU awk version, as some of the older ones
 129   are broken.  GNU awk version 3.1.5 is known to work.
 130
 131 * GNU binutils
 132
 133   Necessary in some circumstances, optional in others.  See the
 134   host/target specific instructions for your platform for the exact
 135   requirements.
 136
 137   Note binutils 2.35 or newer is required for LTO to work correctly
 138   with GNU libtool that includes doing a bootstrap with LTO enabled.
 139
 140 * gzip version 1.2.4 (or later) or
 141 * bzip2 version 1.0.2 (or later)
 142
 143   Necessary to uncompress GCC :command:`tar` files when source code is
 144   obtained via HTTPS mirror sites.
 145
 146 * GNU make version 3.80 (or later)
 147
 148   You must have GNU make installed to build GCC.
 149
 150 * GNU tar version 1.14 (or later)
 151
 152   Necessary (only on some platforms) to untar the source code.  Many
 153   systems' :command:`tar` programs will also work, only try GNU
 154   :command:`tar` if you have problems.
 155
 156 * Perl version between 5.6.1 and 5.6.24
 157
 158   Necessary when targeting Darwin, building :samp:`libstdc++`,
 159   and not using :option:`--disable-symvers`.
 160   Necessary when targeting Solaris 2 with Solaris :command:`ld` and not using
 161   :option:`--disable-symvers`.
 162
 163   Necessary when regenerating :samp:`Makefile` dependencies in libiberty.
 164   Used by various scripts to generate some files included in the source
 165   repository (mainly Unicode-related and rarely changing) from source
 166   tables.
 167
 168   Used by :command:`automake`.
 169
 170 Several support libraries are necessary to build GCC, some are required,
 171 others optional.  While any sufficiently new version of required tools
 172 usually work, library requirements are generally stricter.  Newer
 173 versions may work in some cases, but it's safer to use the exact
 174 versions documented.  We appreciate bug reports about problems with
 175 newer versions, though.  If your OS vendor provides packages for the
 176 support libraries then using those packages may be the simplest way to
 177 install the libraries.
 178
 179 * GNU Multiple Precision Library (GMP) version 4.3.2 (or later)
 180
 181   Necessary to build GCC.  If a GMP source distribution is found in a
 182   subdirectory of your GCC sources named :samp:`gmp`, it will be built
 183   together with GCC.  Alternatively, if GMP is already installed but it
 184   is not in your library search path, you will have to configure with the
 185   :option:`--with-gmp` configure option.  See also :option:`--with-gmp-lib`
 186   and :option:`--with-gmp-include`.
 187   The in-tree build is only supported with the GMP version that
 188   :command:`download_prerequisites` installs.
 189
 190 * MPFR Library version 3.1.0 (or later)
 191
 192   Necessary to build GCC.  It can be downloaded from
 193   https://www.mpfr.org.  If an MPFR source distribution is found
 194   in a subdirectory of your GCC sources named :samp:`mpfr`, it will be
 195   built together with GCC.  Alternatively, if MPFR is already installed
 196   but it is not in your default library search path, the
 197   :option:`--with-mpfr` configure option should be used.  See also
 198   :option:`--with-mpfr-lib` and :option:`--with-mpfr-include`.
 199   The in-tree build is only supported with the MPFR version that
 200   :command:`download_prerequisites` installs.
 201
 202 * MPC Library version 1.0.1 (or later)
 203
 204   Necessary to build GCC.  It can be downloaded from
 205   https://www.multiprecision.org/mpc/.  If an MPC source distribution
 206   is found in a subdirectory of your GCC sources named :samp:`mpc`, it
 207   will be built together with GCC.  Alternatively, if MPC is already
 208   installed but it is not in your default library search path, the
 209   :option:`--with-mpc` configure option should be used.  See also
 210   :option:`--with-mpc-lib` and :option:`--with-mpc-include`.
 211   The in-tree build is only supported with the MPC version that
 212   :command:`download_prerequisites` installs.
 213
 214 * isl Library version 0.15 or later.
 215
 216   Necessary to build GCC with the Graphite loop optimizations.
 217   It can be downloaded from https://gcc.gnu.org/pub/gcc/infrastructure/.
 218   If an isl source distribution is found
 219   in a subdirectory of your GCC sources named :samp:`isl`, it will be
 220   built together with GCC.  Alternatively, the :option:`--with-isl` configure
 221   option should be used if isl is not installed in your default library
 222   search path.
 223
 224 * zstd Library.
 225
 226   Necessary to build GCC with zstd compression used for LTO bytecode.
 227   The library is searched in your default library patch search.
 228   Alternatively, the :option:`--with-zstd` configure option should be used.
 229
 230 Tools/packages necessary for modifying GCC
 231 ******************************************
 232
 233 * autoconf version 2.69
 234 * GNU m4 version 1.4.6 (or later)
 235
 236   Necessary when modifying :samp:`configure.ac`, :samp:`aclocal.m4`, etc.
 237   to regenerate :samp:`configure` and :samp:`config.in` files.
 238
 239 * automake version 1.15.1
 240
 241   Necessary when modifying a :samp:`Makefile.am` file to regenerate its
 242   associated :samp:`Makefile.in`.
 243
 244   Much of GCC does not use automake, so directly edit the :samp:`Makefile.in`
 245   file.  Specifically this applies to the :samp:`gcc`, :samp:`intl`,
 246   :samp:`libcpp`, :samp:`libiberty`, :samp:`libobjc` directories as well
 247   as any of their subdirectories.
 248
 249   For directories that use automake, GCC requires the latest release in
 250   the 1.15 series, which is currently 1.15.1.  When regenerating a directory
 251   to a newer version, please update all the directories using an older 1.15
 252   to the latest released version.
 253
 254 * gettext version 0.14.5 (or later)
 255
 256   Needed to regenerate :samp:`gcc.pot`.
 257
 258 * gperf version 2.7.2 (or later)
 259
 260   Necessary when modifying :command:`gperf` input files, e.g.
 261   :samp:`gcc/cp/cfns.gperf` to regenerate its associated header file, e.g.
 262   :samp:`gcc/cp/cfns.h`.
 263
 264 * DejaGnu version 1.5.3 (or later)
 265 * Expect
 266 * Tcl
 267
 268   Necessary to run the GCC testsuite; see the section on testing for
 269   details.
 270
 271   .. Once Tcl 8.5 or higher is required, remove any obsolete
 272      compatibility workarounds:
 273          git grep 'compatibility with earlier Tcl releases'
 274
 275 * autogen version 5.5.4 (or later)
 276 * guile version 1.4.1 (or later)
 277
 278   Necessary to regenerate :samp:`fixinc/fixincl.x` from
 279   :samp:`fixinc/inclhack.def` and :samp:`fixinc/*.tpl`.
 280
 281   Necessary to run :samp:`make check` for :samp:`fixinc`.
 282
 283   Necessary to regenerate the top level :samp:`Makefile.in` file from
 284   :samp:`Makefile.tpl` and :samp:`Makefile.def`.
 285
 286 * Flex version 2.5.4 (or later)
 287
 288   Necessary when modifying :samp:`*.l` files.
 289
 290   Necessary to build GCC during development because the generated output
 291   files are not included in the version-controlled source repository.
 292   They are included in releases.
 293
 294 * Sphinx version |needs_sphinx| (or later)
 295
 296   Necessary to build HTML, PDF or EPUB documentation. See more in
 297   :ref:`gccint:building_documentation`.
 298
 299   Necessary for running :command:`make html` or :command:`make pdf` to
 300   create printable documentation in HTML or PDF format.
 301
 302   Necessary to build GCC documentation during development because the
 303   generated output files are not included in the repository.  They are
 304   included in releases.
 305
 306 * git (any version)
 307 * SSH (any version)
 308
 309   Necessary to access the source repository.  Public releases and weekly
 310   snapshots of the development sources are also available via HTTPS.
 311
 312 * GNU diffutils version 2.7 (or later)
 313
 314   Useful when submitting patches for the GCC source code.
 315
 316 * patch version 2.5.4 (or later)
 317
 318   Necessary when applying patches, created with :command:`diff`, to one's
 319   own sources.