diff options
Diffstat (limited to 'share/doc/gccint/Option-file-format.html')
| -rw-r--r-- | share/doc/gccint/Option-file-format.html | 267 |
1 files changed, 267 insertions, 0 deletions
diff --git a/share/doc/gccint/Option-file-format.html b/share/doc/gccint/Option-file-format.html new file mode 100644 index 0000000..7d23247 --- /dev/null +++ b/share/doc/gccint/Option-file-format.html @@ -0,0 +1,267 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1988-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Funding Free Software", the Front-Cover +Texts being (a) (see below), and with the Back-Cover Texts being (b) +(see below). A copy of the license is included in the section entitled +"GNU Free Documentation License". + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>GNU Compiler Collection (GCC) Internals: Option file format</title> + +<meta name="description" content="GNU Compiler Collection (GCC) Internals: Option file format"> +<meta name="keywords" content="GNU Compiler Collection (GCC) Internals: Option file format"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Option-Index.html#Option-Index" rel="index" title="Option Index"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Options.html#Options" rel="up" title="Options"> +<link href="Option-properties.html#Option-properties" rel="next" title="Option properties"> +<link href="Options.html#Options" rel="previous" title="Options"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Option-file-format"></a> +<div class="header"> +<p> +Next: <a href="Option-properties.html#Option-properties" accesskey="n" rel="next">Option properties</a>, Up: <a href="Options.html#Options" accesskey="u" rel="up">Options</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Option-file-format-1"></a> +<h3 class="section">8.1 Option file format</h3> + +<p>Option files are a simple list of records in which each field occupies +its own line and in which the records themselves are separated by +blank lines. Comments may appear on their own line anywhere within +the file and are preceded by semicolons. Whitespace is allowed before +the semicolon. +</p> +<p>The files can contain the following types of record: +</p> +<ul> +<li> A language definition record. These records have two fields: the +string ‘<samp>Language</samp>’ and the name of the language. Once a language +has been declared in this way, it can be used as an option property. +See <a href="Option-properties.html#Option-properties">Option properties</a>. + +</li><li> A target specific save record to save additional information. These +records have two fields: the string ‘<samp>TargetSave</samp>’, and a +declaration type to go in the <code>cl_target_option</code> structure. + +</li><li> A variable record to define a variable used to store option +information. These records have two fields: the string +‘<samp>Variable</samp>’, and a declaration of the type and name of the +variable, optionally with an initializer (but without any trailing +‘<samp>;</samp>’). These records may be used for variables used for many +options where declaring the initializer in a single option definition +record, or duplicating it in many records, would be inappropriate, or +for variables set in option handlers rather than referenced by +<code>Var</code> properties. + +</li><li> A variable record to define a variable used to store option +information. These records have two fields: the string +‘<samp>TargetVariable</samp>’, and a declaration of the type and name of the +variable, optionally with an initializer (but without any trailing +‘<samp>;</samp>’). ‘<samp>TargetVariable</samp>’ is a combination of ‘<samp>Variable</samp>’ +and ‘<samp>TargetSave</samp>’ records in that the variable is defined in the +<code>gcc_options</code> structure, but these variables are also stored in +the <code>cl_target_option</code> structure. The variables are saved in the +target save code and restored in the target restore code. + +</li><li> A variable record to record any additional files that the +<samp>options.h</samp> file should include. This is useful to provide +enumeration or structure definitions needed for target variables. +These records have two fields: the string ‘<samp>HeaderInclude</samp>’ and the +name of the include file. + +</li><li> A variable record to record any additional files that the +<samp>options.cc</samp> or <samp>options-save.cc</samp> file should include. This +is useful to provide +inline functions needed for target variables and/or <code>#ifdef</code> +sequences to properly set up the initialization. These records have +two fields: the string ‘<samp>SourceInclude</samp>’ and the name of the +include file. + +</li><li> An enumeration record to define a set of strings that may be used as +arguments to an option or options. These records have three fields: +the string ‘<samp>Enum</samp>’, a space-separated list of properties and help +text used to describe the set of strings in <samp>--help</samp> output. +Properties use the same format as option properties; the following are +valid: +<dl compact="compact"> +<dt><code>Name(<var>name</var>)</code></dt> +<dd><p>This property is required; <var>name</var> must be a name (suitable for use +in C identifiers) used to identify the set of strings in <code>Enum</code> +option properties. +</p> +</dd> +<dt><code>Type(<var>type</var>)</code></dt> +<dd><p>This property is required; <var>type</var> is the C type for variables set +by options using this enumeration together with <code>Var</code>. +</p> +</dd> +<dt><code>UnknownError(<var>message</var>)</code></dt> +<dd><p>The message <var>message</var> will be used as an error message if the +argument is invalid; for enumerations without <code>UnknownError</code>, a +generic error message is used. <var>message</var> should contain a single +‘<samp>%qs</samp>’ format, which will be used to format the invalid argument. +</p></dd> +</dl> + +</li><li> An enumeration value record to define one of the strings in a set +given in an ‘<samp>Enum</samp>’ record. These records have two fields: the +string ‘<samp>EnumValue</samp>’ and a space-separated list of properties. +Properties use the same format as option properties; the following are +valid: +<dl compact="compact"> +<dt><code>Enum(<var>name</var>)</code></dt> +<dd><p>This property is required; <var>name</var> says which ‘<samp>Enum</samp>’ record +this ‘<samp>EnumValue</samp>’ record corresponds to. +</p> +</dd> +<dt><code>String(<var>string</var>)</code></dt> +<dd><p>This property is required; <var>string</var> is the string option argument +being described by this record. +</p> +</dd> +<dt><code>Value(<var>value</var>)</code></dt> +<dd><p>This property is required; it says what value (representable as +<code>int</code>) should be used for the given string. +</p> +</dd> +<dt><code>Canonical</code></dt> +<dd><p>This property is optional. If present, it says the present string is +the canonical one among all those with the given value. Other strings +yielding that value will be mapped to this one so specs do not need to +handle them. +</p> +</dd> +<dt><code>DriverOnly</code></dt> +<dd><p>This property is optional. If present, the present string will only +be accepted by the driver. This is used for cases such as +<samp>-march=native</samp> that are processed by the driver so that +‘<samp>gcc -v</samp>’ shows how the options chosen depended on the system on +which the compiler was run. +</p> +</dd> +<dt><code>Set(<var>number</var>)</code></dt> +<dd><p>This property is optional, required for enumerations used in +<code>EnumSet</code> options. <var>number</var> should be decimal number between +1 and 64 inclusive and divides the enumeration into a set of +sets of mutually exclusive arguments. Arguments with the same +<var>number</var> can’t be specified together in the same option, but +arguments with different <var>number</var> can. <var>value</var> needs to be +chosen such that a mask of all <var>value</var> values from the same set +<var>number</var> bitwise ored doesn’t overlap with masks for other sets. +When <code>-foption=arg_from_set1,arg_from_set4</code> and +<code>-fno-option=arg_from_set3</code> are used, the effect is that previous +value of the <code>Var</code> will get bits from set 1 and 4 masks cleared, +ored <code>Value</code> of <code>arg_from_set1</code> and <code>arg_from_set4</code> +and then will get bits from set 3 mask cleared. +</p></dd> +</dl> + +</li><li> An option definition record. These records have the following fields: +<ol> +<li> the name of the option, with the leading “-” removed +</li><li> a space-separated list of option properties (see <a href="Option-properties.html#Option-properties">Option properties</a>) +</li><li> the help text to use for <samp>--help</samp> (omitted if the second field +contains the <code>Undocumented</code> property). +</li></ol> + +<p>By default, all options beginning with “f”, “g”, “W” or “m” are +implicitly assumed to take a “no-” form. This form should not be +listed separately. If an option beginning with one of these letters +does not have a “no-” form, you can use the <code>RejectNegative</code> +property to reject it. +</p> +<p>The help text is automatically line-wrapped before being displayed. +Normally the name of the option is printed on the left-hand side of +the output and the help text is printed on the right. However, if the +help text contains a tab character, the text to the left of the tab is +used instead of the option’s name and the text to the right of the +tab forms the help text. This allows you to elaborate on what type +of argument the option takes. +</p> +<p>There is no support for different help texts for different languages. +If an option is supported for multiple languages, use a generic +description that is correct for all of them. +</p> +<p>If an option has multiple option definition records (in different +front ends’ <samp>*.opt</samp> files, and/or <samp>gcc/common.opt</samp>, for +example), convention is to not duplicate the help text for each of +them, but instead put a comment like <code>; documented in common.opt</code> +in place of the help text for all but one of the multiple option +definition records. +</p> +</li><li> A target mask record. These records have one field of the form +‘<samp>Mask(<var>x</var>)</samp>’. The options-processing script will automatically +allocate a bit in <code>target_flags</code> (see <a href="Run_002dtime-Target.html#Run_002dtime-Target">Run-time Target</a>) for +each mask name <var>x</var> and set the macro <code>MASK_<var>x</var></code> to the +appropriate bitmask. It will also declare a <code>TARGET_<var>x</var></code> +macro that has the value 1 when bit <code>MASK_<var>x</var></code> is set and +0 otherwise. + +<p>They are primarily intended to declare target masks that are not +associated with user options, either because these masks represent +internal switches or because the options are not available on all +configurations and yet the masks always need to be defined. +</p></li></ul> + +<hr> +<div class="header"> +<p> +Next: <a href="Option-properties.html#Option-properties" accesskey="n" rel="next">Option properties</a>, Up: <a href="Options.html#Options" accesskey="u" rel="up">Options</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> |