gcc/doc/gccint/target-makefile-fragments.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:: target makefile fragment, t-target
   7
   8 .. _target-fragment:
   9
  10 Target Makefile Fragments
  11 *************************
  12
  13 Target makefile fragments can set these Makefile variables.
  14
  15 .. index:: LIBGCC2_CFLAGS
  16
  17 ``LIBGCC2_CFLAGS``
  18   Compiler flags to use when compiling :samp:`libgcc2.c`.
  19
  20   .. index:: LIB2FUNCS_EXTRA
  21
  22 ``LIB2FUNCS_EXTRA``
  23   A list of source file names to be compiled or assembled and inserted
  24   into :samp:`libgcc.a`.
  25
  26   .. index:: CRTSTUFF_T_CFLAGS
  27
  28 .. envvar:: CRTSTUFF_T_CFLAGS
  29
  30   Special flags used when compiling :samp:`crtstuff.c`.
  31   See :ref:`initialization`.
  32
  33 .. envvar:: CRTSTUFF_T_CFLAGS_S
  34
  35   Special flags used when compiling :samp:`crtstuff.c` for shared
  36   linking.  Used if you use :samp:`crtbeginS.o` and :samp:`crtendS.o`
  37   in ``EXTRA-PARTS``.
  38   See :ref:`initialization`.
  39
  40 .. envvar:: MULTILIB_OPTIONS
  41
  42   For some targets, invoking GCC in different ways produces objects
  43   that cannot be linked together.  For example, for some targets GCC
  44   produces both big and little endian code.  For these targets, you must
  45   arrange for multiple versions of :samp:`libgcc.a` to be compiled, one for
  46   each set of incompatible options.  When GCC invokes the linker, it
  47   arranges to link in the right version of :samp:`libgcc.a`, based on
  48   the command line options used.
  49
  50   The ``MULTILIB_OPTIONS`` macro lists the set of options for which
  51   special versions of :samp:`libgcc.a` must be built.  Write options that
  52   are mutually incompatible side by side, separated by a slash.  Write
  53   options that may be used together separated by a space.  The build
  54   procedure will build all combinations of compatible options.
  55
  56   For example, if you set ``MULTILIB_OPTIONS`` to :samp:`m68000/m68020
  57   msoft-float`, :samp:`Makefile` will build special versions of
  58   :samp:`libgcc.a` using the following sets of options:  :option:`-m68000`,
  59   :option:`-m68020`, :option:`-msoft-float`, :samp:`-m68000 -msoft-float`, and
  60   :samp:`-m68020 -msoft-float`.
  61
  62 .. envvar:: MULTILIB_DIRNAMES
  63
  64   If ``MULTILIB_OPTIONS`` is used, this variable specifies the
  65   directory names that should be used to hold the various libraries.
  66   Write one element in ``MULTILIB_DIRNAMES`` for each element in
  67   ``MULTILIB_OPTIONS``.  If ``MULTILIB_DIRNAMES`` is not used, the
  68   default value will be ``MULTILIB_OPTIONS``, with all slashes treated
  69   as spaces.
  70
  71   ``MULTILIB_DIRNAMES`` describes the multilib directories using GCC
  72   conventions and is applied to directories that are part of the GCC
  73   installation.  When multilib-enabled, the compiler will add a
  74   subdirectory of the form :samp:`{prefix}` / :samp:`{multilib}` before each
  75   directory in the search path for libraries and crt files.
  76
  77   For example, if ``MULTILIB_OPTIONS`` is set to :samp:`m68000/m68020
  78   msoft-float`, then the default value of ``MULTILIB_DIRNAMES`` is
  79   :samp:`m68000 m68020 msoft-float`.  You may specify a different value if
  80   you desire a different set of directory names.
  81
  82 .. envvar:: MULTILIB_MATCHES
  83
  84   Sometimes the same option may be written in two different ways.  If an
  85   option is listed in ``MULTILIB_OPTIONS``, GCC needs to know about
  86   any synonyms.  In that case, set ``MULTILIB_MATCHES`` to a list of
  87   items of the form :samp:`option=option` to describe all relevant
  88   synonyms.  For example, :samp:`m68000=mc68000 m68020=mc68020`.
  89
  90 .. envvar:: MULTILIB_EXCEPTIONS
  91
  92   Sometimes when there are multiple sets of ``MULTILIB_OPTIONS`` being
  93   specified, there are combinations that should not be built.  In that
  94   case, set ``MULTILIB_EXCEPTIONS`` to be all of the switch exceptions
  95   in shell case syntax that should not be built.
  96
  97   For example the ARM processor cannot execute both hardware floating
  98   point instructions and the reduced size THUMB instructions at the same
  99   time, so there is no need to build libraries with both of these
 100   options enabled.  Therefore ``MULTILIB_EXCEPTIONS`` is set to:
 101
 102   .. code-block:: c++
 103
 104     *mthumb/*mhard-float*
 105
 106 .. envvar:: MULTILIB_REQUIRED
 107
 108   Sometimes when there are only a few combinations are required, it would
 109   be a big effort to come up with a ``MULTILIB_EXCEPTIONS`` list to
 110   cover all undesired ones.  In such a case, just listing all the required
 111   combinations in ``MULTILIB_REQUIRED`` would be more straightforward.
 112
 113   The way to specify the entries in ``MULTILIB_REQUIRED`` is same with
 114   the way used for ``MULTILIB_EXCEPTIONS``, only this time what are
 115   required will be specified.  Suppose there are multiple sets of
 116   ``MULTILIB_OPTIONS`` and only two combinations are required, one
 117   for ARMv7-M and one for ARMv7-R with hard floating-point ABI and FPU, the
 118   ``MULTILIB_REQUIRED`` can be set to:
 119
 120   .. code-block:: c++
 121
 122     MULTILIB_REQUIRED =  mthumb/march=armv7-m
 123     MULTILIB_REQUIRED += march=armv7-r/mfloat-abi=hard/mfpu=vfpv3-d16
 124
 125   The ``MULTILIB_REQUIRED`` can be used together with
 126   ``MULTILIB_EXCEPTIONS``.  The option combinations generated from
 127   ``MULTILIB_OPTIONS`` will be filtered by ``MULTILIB_EXCEPTIONS``
 128   and then by ``MULTILIB_REQUIRED``.
 129
 130 .. envvar:: MULTILIB_REUSE
 131
 132   Sometimes it is desirable to reuse one existing multilib for different
 133   sets of options.  Such kind of reuse can minimize the number of multilib
 134   variants.  And for some targets it is better to reuse an existing multilib
 135   than to fall back to default multilib when there is no corresponding multilib.
 136   This can be done by adding reuse rules to ``MULTILIB_REUSE``.
 137
 138   A reuse rule is comprised of two parts connected by equality sign.  The left
 139   part is the option set used to build multilib and the right part is the option
 140   set that will reuse this multilib.  Both parts should only use options
 141   specified in ``MULTILIB_OPTIONS`` and the equality signs found in options
 142   name should be replaced with periods.  An explicit period in the rule can be
 143   escaped by preceding it with a backslash.  The order of options in the left
 144   part matters and should be same with those specified in
 145   ``MULTILIB_REQUIRED`` or aligned with the order in ``MULTILIB_OPTIONS``.
 146   There is no such limitation for options in the right part as we don't build
 147   multilib from them.
 148
 149   ``MULTILIB_REUSE`` is different from ``MULTILIB_MATCHES`` in that it
 150   sets up relations between two option sets rather than two options.  Here is an
 151   example to demo how we reuse libraries built in Thumb mode for applications built
 152   in ARM mode:
 153
 154   .. code-block:: c++
 155
 156     MULTILIB_REUSE = mthumb/march.armv7-r=marm/march.armv7-r
 157
 158   Before the advent of ``MULTILIB_REUSE``, GCC select multilib by comparing command
 159   line options with options used to build multilib.  The ``MULTILIB_REUSE`` is
 160   complementary to that way.  Only when the original comparison matches nothing it will
 161   work to see if it is OK to reuse some existing multilib.
 162
 163 .. envvar:: MULTILIB_EXTRA_OPTS
 164
 165   Sometimes it is desirable that when building multiple versions of
 166   :samp:`libgcc.a` certain options should always be passed on to the
 167   compiler.  In that case, set ``MULTILIB_EXTRA_OPTS`` to be the list
 168   of options to be used for all builds.  If you set this, you should
 169   probably set ``CRTSTUFF_T_CFLAGS`` to a dash followed by it.
 170
 171 .. envvar:: MULTILIB_OSDIRNAMES
 172
 173   If ``MULTILIB_OPTIONS`` is used, this variable specifies
 174   a list of subdirectory names, that are used to modify the search
 175   path depending on the chosen multilib.  Unlike ``MULTILIB_DIRNAMES``,
 176   ``MULTILIB_OSDIRNAMES`` describes the multilib directories using
 177   operating systems conventions, and is applied to the directories such as
 178   ``lib`` or those in the :envvar:`LIBRARY_PATH` environment variable.
 179   The format is either the same as of
 180   ``MULTILIB_DIRNAMES``, or a set of mappings.  When it is the same
 181   as ``MULTILIB_DIRNAMES``, it describes the multilib directories
 182   using operating system conventions, rather than GCC conventions.  When it is a set
 183   of mappings of the form :samp:`{gccdir}` = :samp:`{osdir}`, the left side gives
 184   the GCC convention and the right gives the equivalent OS defined
 185   location.  If the :samp:`{osdir}` part begins with a :samp:`!`,
 186   GCC will not search in the non-multilib directory and use
 187   exclusively the multilib directory.  Otherwise, the compiler will
 188   examine the search path for libraries and crt files twice; the first
 189   time it will add :samp:`{multilib}` to each directory in the search path,
 190   the second it will not.
 191
 192   For configurations that support both multilib and multiarch,
 193   ``MULTILIB_OSDIRNAMES`` also encodes the multiarch name, thus
 194   subsuming ``MULTIARCH_DIRNAME``.  The multiarch name is appended to
 195   each directory name, separated by a colon (e.g.
 196   :samp:`../lib32:i386-linux-gnu`).
 197
 198   Each multiarch subdirectory will be searched before the corresponding OS
 199   multilib directory, for example :samp:`/lib/i386-linux-gnu` before
 200   :samp:`/lib/../lib32`.  The multiarch name will also be used to modify the
 201   system header search path, as explained for ``MULTIARCH_DIRNAME``.
 202
 203 .. envvar:: MULTIARCH_DIRNAME
 204
 205   This variable specifies the multiarch name for configurations that are
 206   multiarch-enabled but not multilibbed configurations.
 207
 208   The multiarch name is used to augment the search path for libraries, crt
 209   files and system header files with additional locations.  The compiler
 210   will add a multiarch subdirectory of the form
 211   :samp:`{prefix}` / :samp:`{multiarch}` before each directory in the library and
 212   crt search path.  It will also add two directories
 213   ``LOCAL_INCLUDE_DIR`` / :samp:`{multiarch}` and
 214   ``NATIVE_SYSTEM_HEADER_DIR`` / :samp:`{multiarch}`) to the system header
 215   search path, respectively before ``LOCAL_INCLUDE_DIR`` and
 216   ``NATIVE_SYSTEM_HEADER_DIR``.
 217
 218   ``MULTIARCH_DIRNAME`` is not used for configurations that support
 219   both multilib and multiarch.  In that case, multiarch names are encoded
 220   in ``MULTILIB_OSDIRNAMES`` instead.
 221
 222   More documentation about multiarch can be found at
 223   https://wiki.debian.org/Multiarch.
 224
 225 .. envvar:: SPECS
 226
 227   Unfortunately, setting ``MULTILIB_EXTRA_OPTS`` is not enough, since
 228   it does not affect the build of target libraries, at least not the
 229   build of the default multilib.  One possible work-around is to use
 230   ``DRIVER_SELF_SPECS`` to bring options from the :samp:`specs` file
 231   as if they had been passed in the compiler driver command line.
 232   However, you don't want to be adding these options after the toolchain
 233   is installed, so you can instead tweak the :samp:`specs` file that will
 234   be used during the toolchain build, while you still install the
 235   original, built-in :samp:`specs`.  The trick is to set ``SPECS`` to
 236   some other filename (say :samp:`specs.install`), that will then be
 237   created out of the built-in specs, and introduce a :samp:`Makefile`
 238   rule to generate the :samp:`specs` file that's going to be used at
 239   build time out of your :samp:`specs.install`.
 240
 241 .. envvar:: T_CFLAGS
 242
 243   These are extra flags to pass to the C compiler.  They are used both
 244   when building GCC, and when compiling things with the just-built GCC.
 245   This variable is deprecated and should not be used.