]>
Commit | Line | Data |
---|---|---|
c63539ff ML |
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 | |
3ed1b4ce | 175 | configurations and yet the masks always need to be defined. |