sphinx: add missing trailing newline

[thirdparty/gcc.git] / gcc / doc / gccint / source-tree-structure-and-build-system / the-gcc-subdirectory / configuration-in-the-gcc-directory.rst

..
  Copyright 1988-2022 Free Software Foundation, Inc.
  This is part of the GCC manual.
  For copying conditions, see the copyright.rst file.

.. _configuration:

Configuration in the gcc Directory
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The :samp:`gcc` directory is configured with an Autoconf-generated
script :samp:`configure`.  The :samp:`configure` script is generated
from :samp:`configure.ac` and :samp:`aclocal.m4`.  From the files
:samp:`configure.ac` and :samp:`acconfig.h`, Autoheader generates the
file :samp:`config.in`.  The file :samp:`cstamp-h.in` is used as a
timestamp.

.. toctree::
  :maxdepth: 2


.. _config-fragments:

Scripts Used by configure
~~~~~~~~~~~~~~~~~~~~~~~~~

:samp:`configure` uses some other scripts to help in its work:

* The standard GNU :samp:`config.sub` and :samp:`config.guess`
  files, kept in the top level directory, are used.

* The file :samp:`config.gcc` is used to handle configuration
  specific to the particular target machine.  The file
  :samp:`config.build` is used to handle configuration specific to the
  particular build machine.  The file :samp:`config.host` is used to handle
  configuration specific to the particular host machine.  (In general,
  these should only be used for features that cannot reasonably be tested in
  Autoconf feature tests.)
  See :ref:`system-config`, for details of the contents of these files.

* Each language subdirectory has a file
  :samp:`{language}/config-lang.in` that is used for
  front-end-specific configuration.  See :ref:`front-end-config`, for details of this file.

* A helper script :samp:`configure.frag` is used as part of
  creating the output of :samp:`configure`.

.. _system-config:

The config.build; config.host; and config.gcc Files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :samp:`config.build` file contains specific rules for particular systems
which GCC is built on.  This should be used as rarely as possible, as the
behavior of the build system can always be detected by autoconf.

The :samp:`config.host` file contains specific rules for particular systems
which GCC will run on.  This is rarely needed.

The :samp:`config.gcc` file contains specific rules for particular systems
which GCC will generate code for.  This is usually needed.

Each file has a list of the shell variables it sets, with descriptions, at the
top of the file.

.. todo:: document the contents of these files, and what variables should
  be set to control build, host and target configuration.

.. _configuration-files:

Files Created by configure
~~~~~~~~~~~~~~~~~~~~~~~~~~

Here we spell out what files will be set up by :samp:`configure` in the
:samp:`gcc` directory.  Some other files are created as temporary files
in the configuration process, and are not used in the subsequent
build; these are not documented.

* :samp:`Makefile` is constructed from :samp:`Makefile.in`, together with
  the host and target fragments (see :ref:`fragments`) :samp:`t-{target}` and :samp:`x-{host}` from
  :samp:`config`, if any, and language Makefile fragments
  :samp:`{language}/Make-lang.in`.

* :samp:`auto-host.h` contains information about the host machine
  determined by :samp:`configure`.  If the host machine is different from
  the build machine, then :samp:`auto-build.h` is also created,
  containing such information about the build machine.

* :samp:`config.status` is a script that may be run to recreate the
  current configuration.

* :samp:`configargs.h` is a header containing details of the arguments
  passed to :samp:`configure` to configure GCC, and of the thread model
  used.

* :samp:`cstamp-h` is used as a timestamp.

* If a language :samp:`config-lang.in` file (see :ref:`front-end-config`) sets ``outputs``, then
  the files listed in ``outputs`` there are also generated.

The following configuration headers are created from the Makefile,
using :samp:`mkconfig.sh`, rather than directly by :samp:`configure`.
:samp:`config.h`, :samp:`bconfig.h` and :samp:`tconfig.h` all contain the
:samp:`xm-{machine}.h` header, if any, appropriate to the host,
build and target machines respectively, the configuration headers for
the target, and some definitions; for the host and build machines,
these include the autoconfigured headers generated by
:samp:`configure`.  The other configuration headers are determined by
:samp:`config.gcc`.  They also contain the typedefs for ``rtx``,
``rtvec`` and ``tree``.

* :samp:`config.h`, for use in programs that run on the host machine.

* :samp:`bconfig.h`, for use in programs that run on the build machine.

* :samp:`tconfig.h`, for use in programs and libraries for the target
  machine.

* :samp:`tm_p.h`, which includes the header :samp:`{machine}-protos.h`
  that contains prototypes for functions in the target
  :samp:`{machine}.c` file.  The
  :samp:`{machine}-protos.h` header is included after the :samp:`rtl.h`
  and/or :samp:`tree.h` would have been included.
  The :samp:`tm_p.h` also
  includes the header :samp:`tm-preds.h` which is generated by
  :samp:`genpreds` program during the build to define the declarations
  and inline functions for the predicate functions.