gcc/doc/gccint/option-file-format.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 .. _option-file-format:
   7
   8 Option file format
   9 ******************
  10
  11 Option files are a simple list of records in which each field occupies
  12 its own line and in which the records themselves are separated by
  13 blank lines.  Comments may appear on their own line anywhere within
  14 the file and are preceded by semicolons.  Whitespace is allowed before
  15 the semicolon.
  16
  17 The files can contain the following types of record:
  18
  19 * A language definition record.  These records have two fields: the
  20   string :samp:`Language` and the name of the language.  Once a language
  21   has been declared in this way, it can be used as an option property.
  22   See :ref:`option-properties`.
  23
  24 * A target specific save record to save additional information. These
  25   records have two fields: the string :samp:`TargetSave`, and a
  26   declaration type to go in the ``cl_target_option`` structure.
  27
  28 * A variable record to define a variable used to store option
  29   information.  These records have two fields: the string
  30   :samp:`Variable`, and a declaration of the type and name of the
  31   variable, optionally with an initializer (but without any trailing
  32   :samp:`;`).  These records may be used for variables used for many
  33   options where declaring the initializer in a single option definition
  34   record, or duplicating it in many records, would be inappropriate, or
  35   for variables set in option handlers rather than referenced by
  36   ``Var`` properties.
  37
  38 * A variable record to define a variable used to store option
  39   information.  These records have two fields: the string
  40   :samp:`TargetVariable`, and a declaration of the type and name of the
  41   variable, optionally with an initializer (but without any trailing
  42   :samp:`;`).  :samp:`TargetVariable` is a combination of :samp:`Variable`
  43   and :samp:`TargetSave` records in that the variable is defined in the
  44   ``gcc_options`` structure, but these variables are also stored in
  45   the ``cl_target_option`` structure.  The variables are saved in the
  46   target save code and restored in the target restore code.
  47
  48 * A variable record to record any additional files that the
  49   :samp:`options.h` file should include.  This is useful to provide
  50   enumeration or structure definitions needed for target variables.
  51   These records have two fields: the string :samp:`HeaderInclude` and the
  52   name of the include file.
  53
  54 * A variable record to record any additional files that the
  55   :samp:`options.cc` or :samp:`options-save.cc` file should include.  This
  56   is useful to provide
  57   inline functions needed for target variables and/or ``#ifdef``
  58   sequences to properly set up the initialization.  These records have
  59   two fields: the string :samp:`SourceInclude` and the name of the
  60   include file.
  61
  62 * An enumeration record to define a set of strings that may be used as
  63   arguments to an option or options.  These records have three fields:
  64   the string :samp:`Enum`, a space-separated list of properties and help
  65   text used to describe the set of strings in :option:`--help` output.
  66   Properties use the same format as option properties; the following are
  67   valid:
  68
  69   :samp:`Name({name})`
  70     This property is required; :samp:`{name}` must be a name (suitable for use
  71     in C identifiers) used to identify the set of strings in ``Enum``
  72     option properties.
  73
  74   :samp:`Type({type})`
  75     This property is required; :samp:`{type}` is the C type for variables set
  76     by options using this enumeration together with ``Var``.
  77
  78   :samp:`UnknownError({message})`
  79     The message :samp:`{message}` will be used as an error message if the
  80     argument is invalid; for enumerations without ``UnknownError``, a
  81     generic error message is used.  :samp:`{message}` should contain a single
  82     :samp:`%qs` format, which will be used to format the invalid argument.
  83
  84 * An enumeration value record to define one of the strings in a set
  85   given in an :samp:`Enum` record.  These records have two fields: the
  86   string :samp:`EnumValue` and a space-separated list of properties.
  87   Properties use the same format as option properties; the following are
  88   valid:
  89
  90   :samp:`Enum({name})`
  91     This property is required; :samp:`{name}` says which :samp:`Enum` record
  92     this :samp:`EnumValue` record corresponds to.
  93
  94   :samp:`String({string})`
  95     This property is required; :samp:`{string}` is the string option argument
  96     being described by this record.
  97
  98   :samp:`Value({value})`
  99     This property is required; it says what value (representable as
 100     ``int``) should be used for the given string.
 101
 102   ``Canonical``
 103     This property is optional.  If present, it says the present string is
 104     the canonical one among all those with the given value.  Other strings
 105     yielding that value will be mapped to this one so specs do not need to
 106     handle them.
 107
 108   ``DriverOnly``
 109     This property is optional.  If present, the present string will only
 110     be accepted by the driver.  This is used for cases such as
 111     :option:`-march=native` that are processed by the driver so that
 112     :samp:`gcc -v` shows how the options chosen depended on the system on
 113     which the compiler was run.
 114
 115   :samp:`Set({number})`
 116     This property is optional, required for enumerations used in
 117     ``EnumSet`` options.  :samp:`{number}` should be decimal number between
 118     1 and 64 inclusive and divides the enumeration into a set of
 119     sets of mutually exclusive arguments.  Arguments with the same
 120     :samp:`{number}` can't be specified together in the same option, but
 121     arguments with different :samp:`{number}` can.  :samp:`{value}` needs to be
 122     chosen such that a mask of all :samp:`{value}` values from the same set
 123     :samp:`{number}` bitwise ored doesn't overlap with masks for other sets.
 124     When ``-foption=arg_from_set1,arg_from_set4`` and
 125     ``-fno-option=arg_from_set3`` are used, the effect is that previous
 126     value of the ``Var`` will get bits from set 1 and 4 masks cleared,
 127     ored ``Value`` of ``arg_from_set1`` and ``arg_from_set4``
 128     and then will get bits from set 3 mask cleared.
 129
 130 * An option definition record.  These records have the following fields:
 131
 132   * the name of the option, with the leading '-' removed
 133
 134   * a space-separated list of option properties (see :ref:`option-properties`)
 135
 136   * the help text to use for :option:`--help` (omitted if the second field
 137     contains the ``Undocumented`` property).
 138
 139   By default, all options beginning with 'f', 'W' or 'm' are
 140   implicitly assumed to take a 'no-' form.  This form should not be
 141   listed separately.  If an option beginning with one of these letters
 142   does not have a 'no-' form, you can use the ``RejectNegative``
 143   property to reject it.
 144
 145   The help text is automatically line-wrapped before being displayed.
 146   Normally the name of the option is printed on the left-hand side of
 147   the output and the help text is printed on the right.  However, if the
 148   help text contains a tab character, the text to the left of the tab is
 149   used instead of the option's name and the text to the right of the
 150   tab forms the help text.  This allows you to elaborate on what type
 151   of argument the option takes.
 152
 153   There is no support for different help texts for different languages.
 154   If an option is supported for multiple languages, use a generic
 155   description that is correct for all of them.
 156
 157   If an option has multiple option definition records (in different
 158   front ends' :samp:`*.opt` files, and/or :samp:`gcc/common.opt`, for
 159   example), convention is to not duplicate the help text for each of
 160   them, but instead put a comment like ``; documented in common.opt``
 161   in place of the help text for all but one of the multiple option
 162   definition records.
 163
 164 * A target mask record.  These records have one field of the form
 165   :samp:`Mask({x})`.  The options-processing script will automatically
 166   allocate a bit in ``target_flags`` (see :ref:`run-time-target`) for
 167   each mask name :samp:`{x}` and set the macro ``MASK_x`` to the
 168   appropriate bitmask.  It will also declare a ``TARGET_x``
 169   macro that has the value 1 when bit ``MASK_x`` is set and
 170   0 otherwise.
 171
 172   They are primarily intended to declare target masks that are not
 173   associated with user options, either because these masks represent
 174   internal switches or because the options are not available on all
 175   configurations and yet the masks always need to be defined.