specified</a></li>
<li><a href="#formatting">Controlling other formatting options</a></li>
<li><a href="#misc">Miscellaneous option modifiers</a></li>
+ <li><a href="#response">Response files</a></li>
</ul></li>
<li><a href="#toplevel">Top-Level Classes and Functions</a>
<div class="doc_code"><pre>
...
- ofstream Output(OutputFilename.c_str());
- if (Out.good()) ...
+ std::ofstream Output(OutputFilename.c_str());
+ if (Output.good()) ...
...
</pre></div>
<div class="doc_text">
<p>In addition to input and output filenames, we would like the compiler example
-to support three boolean flags: "<tt>-f</tt>" to force overwriting of the output
-file, "<tt>--quiet</tt>" to enable quiet mode, and "<tt>-q</tt>" for backwards
-compatibility with some of our users. We can support these by declaring options
-of boolean type like this:</p>
+to support three boolean flags: "<tt>-f</tt>" to force writing binary output to
+a terminal, "<tt>--quiet</tt>" to enable quiet mode, and "<tt>-q</tt>" for
+backwards compatibility with some of our users. We can support these by
+declaring options of boolean type like this:</p>
<div class="doc_code"><pre>
-<a href="#cl::opt">cl::opt</a><bool> Force ("<i>f</i>", <a href="#cl::desc">cl::desc</a>("<i>Overwrite output files</i>"));
+<a href="#cl::opt">cl::opt</a><bool> Force ("<i>f</i>", <a href="#cl::desc">cl::desc</a>("<i>Enable binary output on terminals</i>"));
<a href="#cl::opt">cl::opt</a><bool> Quiet ("<i>quiet</i>", <a href="#cl::desc">cl::desc</a>("<i>Don't print informational messages</i>"));
<a href="#cl::opt">cl::opt</a><bool> Quiet2("<i>q</i>", <a href="#cl::desc">cl::desc</a>("<i>Don't print informational messages</i>"), <a href="#cl::Hidden">cl::Hidden</a>);
</pre></div>
USAGE: compiler [options] <input file>
OPTIONS:
- <b>-f - Overwrite output files</b>
+ <b>-f - Enable binary output on terminals</b>
-o - Override output filename
<b>-quiet - Don't print informational messages</b>
-help - display available options (--help-hidden for more)
USAGE: compiler [options] <input file>
OPTIONS:
- -f - Overwrite output files
+ -f - Enable binary output on terminals
-o - Override output filename
<b>-q - Don't print informational messages</b>
-quiet - Don't print informational messages
-O1 - Enable trivial optimizations
-O2 - Enable default optimizations
-O3 - Enable expensive optimizations</b>
- -f - Overwrite output files
+ -f - Enable binary output on terminals
-help - display available options (--help-hidden for more)
-o <filename> - Specify output filename
-quiet - Don't print informational messages
=none - disable debug information
=quick - enable quick debug information
=detailed - enable detailed debug information</b>
- -f - Overwrite output files
+ -f - Enable binary output on terminals
-help - display available options (--help-hidden for more)
-o <filename> - Specify output filename
-quiet - Don't print informational messages
example, consider <tt>gcc</tt>'s <tt>-x LANG</tt> option. This tells
<tt>gcc</tt> to ignore the suffix of subsequent positional arguments and force
the file to be interpreted as if it contained source code in language
- <tt>LANG</tt>. In order to handle this properly , you need to know the
+ <tt>LANG</tt>. In order to handle this properly, you need to know the
absolute position of each argument, especially those in lists, so their
interaction(s) can be applied correctly. This is also useful for options like
<tt>-llibname</tt> which is actually a positional argument that starts with
code from the storage of the value parsed. For example, lets say that we have a
'<tt>-debug</tt>' option that we would like to use to enable debug information
across the entire body of our program. In this case, the boolean value
-controlling the debug code should be globally accessable (in a header file, for
+controlling the debug code should be globally accessible (in a header file, for
example) yet the command line option processing code should not be exposed to
all of these clients (requiring lots of .cpp files to #include
<tt>CommandLine.h</tt>).</p>
example.</li>
<li><a name="cl::init">The <b><tt>cl::init</tt></b></a> attribute specifies an
-inital value for a <a href="#cl::opt">scalar</a> option. If this attribute is
+init
ial value for a <a href="#cl::opt">scalar</a> option. If this attribute is
not specified then the command line option value defaults to the value created
by the default constructor for the type. <b>Warning</b>: If you specify both
<b><tt>cl::init</tt></b> and <b><tt>cl::location</tt></b> for an option,
initial value. (You will get an error at runtime if you don't put them in
the right order.)</li>
-<li><a name="cl::location">The <b><tt>cl::location</tt></b></a> attribute where to
-store the value for a parsed command line option if using external storage. See
-the section on <a href="#storage">Internal vs External Storage</a> for more
+<li><a name="cl::location">The <b><tt>cl::location</tt></b></a> attribute where
+to store the value for a parsed command line option if using external storage.
+
See the section on <a href="#storage">Internal vs External Storage</a> for more
information.</li>
<li><a name="cl::aliasopt">The <b><tt>cl::aliasopt</tt></b></a> attribute
You will get a compile time error if you try to use cl::values with a parser
that does not support it.</li>
+<li><a name="cl::multi_val">The <b><tt>cl::multi_val</tt></b></a>
+attribute specifies that this option takes has multiple values
+(example: <tt>-sectalign segname sectname sectvalue</tt>). This
+attribute takes one unsigned argument - the number of values for the
+option. This attribute is valid only on <tt>cl::list</tt> options (and
+will fail with compile error if you try to use it with other option
+types). It is allowed to use all of the usual modifiers on
+multi-valued options (besides <tt>cl::ValueDisallowed</tt>,
+obviously).</li>
+
</ul>
</div>
tweak how options are parsed and how <tt>--help</tt> output is generated to fit
your application well.</p>
-<p>These options fall into five main catagories:</p>
+<p>These options fall into five main categories:</p>
<ol>
<li><a href="#hiding">Hiding an option from <tt>--help</tt> output</a></li>
<li><a href="#misc">Miscellaneous option modifiers</a></li>
</ol>
-<p>It is not possible to specify two options from the same catagory (you'll get
+<p>It is not possible to specify two options from the same category (you'll get
a runtime error) to a single option, except for options in the miscellaneous
-catagory. The CommandLine library specifies defaults for all of these settings
+category. The CommandLine library specifies defaults for all of these settings
that are the most useful in practice and the most common, which mean that you
usually shouldn't have to worry about these.</p>
<li><a name="cl::Sink">The <b><tt>cl::Sink</tt></b></a> modifier is
used to handle unknown options. If there is at least one option with
-<b><tt>cl::Sink</tt></b></a> modifier specified, the parser passes
+<tt>cl::Sink</tt> modifier specified, the parser passes
unrecognized option strings to it as values instead of signaling an
-error. As with <b><tt>cl::CommaSeparated</tt></b></a>, this modifier
+error. As with <tt>cl::CommaSeparated</tt>, this modifier
only makes sense with a <a href="#cl::list">cl::list</a> option.</li>
-
</ul>
<p>So far, these are the only three miscellaneous option modifiers.</p>
</div>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="response">Response files</a>
+</div>
+
+<div class="doc_text">
+
+<p>Some systems, such as certain variants of Microsoft Windows and
+some older Unices have a relatively low limit on command-line
+length. It is therefore customary to use the so-called 'response
+files' to circumvent this restriction. These files are mentioned on
+the command-line (using the "@file") syntax. The program reads these
+files and inserts the contents into argv, thereby working around the
+command-line length limits. Response files are enabled by an optional
+fourth argument to
+<a href="#cl::ParseEnvironmentOptions"><tt>cl::ParseEnvironmentOptions</tt></a>
+and
+<a href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>.
+</p>
+
+</div>
+
+
<!-- ======================================================================= -->
<div class="doc_subsection">
<a name="toplevel">Top-Level Classes and Functions</a>
<p>The <tt>cl::ParseCommandLineOptions</tt> function requires two parameters
(<tt>argc</tt> and <tt>argv</tt>), but may also take an optional third parameter
which holds <a href="#description">additional extra text</a> to emit when the
-<tt>--help</tt> option is invoked.</p>
+<tt>--help</tt> option is invoked, and a fourth boolean parameter that enables
+<a href="#response">response files</a>.</p>
</div>
href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>
does.</p>
-<p>It takes three parameters: the name of the program (since <tt>argv</tt> may
+<p>It takes four parameters: the name of the program (since <tt>argv</tt> may
not be available, it can't just look in <tt>argv[0]</tt>), the name of the
-environment variable to examine, and the optional
+environment variable to examine, the optional
<a href="#description">additional extra text</a> to emit when the
-<tt>--help</tt> option is invoked.</p>
+<tt>--help</tt> option is invoked, and the boolean
+switch that controls whether <a href="#response">response files</a>
+should be read.</p>
<p><tt>cl::ParseEnvironmentOptions</tt> will break the environment
variable's value up into words and then process them using
default:
<i>// Print an error message if unrecognized character!</i>
- <b>return</b> O.error(": '" + Arg + "' value invalid for file size argument!");
+ <b>return</b> O.error("'" + Arg + "' value invalid for file size argument!");
}
}
}
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
- src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
- src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
<a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
projects / oota-llvm.git / blobdiff