<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1988-2015 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.2, 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="prev" 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> &nbsp; [<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 &lsquo;<samp>Language</samp>&rsquo; 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 &lsquo;<samp>TargetSave</samp>&rsquo;, 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
&lsquo;<samp>Variable</samp>&rsquo;, and a declaration of the type and name of the
variable, optionally with an initializer (but without any trailing
&lsquo;<samp>;</samp>&rsquo;).  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
&lsquo;<samp>TargetVariable</samp>&rsquo;, and a declaration of the type and name of the
variable, optionally with an initializer (but without any trailing
&lsquo;<samp>;</samp>&rsquo;).  &lsquo;<samp>TargetVariable</samp>&rsquo; is a combination of &lsquo;<samp>Variable</samp>&rsquo;
and &lsquo;<samp>TargetSave</samp>&rsquo; 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 &lsquo;<samp>HeaderInclude</samp>&rsquo; and the
name of the include file.

</li><li> A variable record to record any additional files that the
<samp>options.c</samp> or <samp>options-save.c</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 &lsquo;<samp>SourceInclude</samp>&rsquo; 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 &lsquo;<samp>Enum</samp>&rsquo;, 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
&lsquo;<samp>%qs</samp>&rsquo; 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 &lsquo;<samp>Enum</samp>&rsquo; record.  These records have two fields: the
string &lsquo;<samp>EnumValue</samp>&rsquo; 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 &lsquo;<samp>Enum</samp>&rsquo; record
this &lsquo;<samp>EnumValue</samp>&rsquo; 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
&lsquo;<samp>gcc -v</samp>&rsquo; shows how the options chosen depended on the system on
which the compiler was run.
</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 &ldquo;-&rdquo; 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 &ldquo;f&rdquo;, &ldquo;W&rdquo; or &ldquo;m&rdquo; are
implicitly assumed to take a &ldquo;no-&rdquo; form.  This form should not be
listed separately.  If an option beginning with one of these letters
does not have a &ldquo;no-&rdquo; 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&rsquo;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>
</li><li> A target mask record.  These records have one field of the form
&lsquo;<samp>Mask(<var>x</var>)</samp>&rsquo;.  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> &nbsp; [<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>