<li><a href="#modifiers">Option Modifiers</a>
<ul>
- <li><a href="#hiding">Hiding an option from <tt>--help</tt>
+ <li><a href="#hiding">Hiding an option from <tt>--help</tt>
output</a></li>
<li><a href="#numoccurrences">Controlling the number of occurrences
required and allowed</a></li>
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>
<ul>
- <li><a href="#cl::ParseCommandLineOptions">The
+ <li><a href="#cl::ParseCommandLineOptions">The
<tt>cl::ParseCommandLineOptions</tt> function</a></li>
- <li><a href="#cl::ParseEnvironmentOptions">The
+ <li><a href="#cl::ParseEnvironmentOptions">The
<tt>cl::ParseEnvironmentOptions</tt> function</a></li>
<li><a href="#cl::SetVersionPrinter">The <tt>cl::SetVersionPrinter</tt>
function</a></li>
<ol>
<li><a href="#customparser">Writing a custom parser</a></li>
<li><a href="#explotingexternal">Exploiting external storage</a></li>
- <li><a href="#dynamicopts">Dynamically adding command line
+ <li><a href="#dynamicopts">Dynamically adding command line
options</a></li>
</ol></li>
</ol>
<div class="doc_code"><pre>
...
- ofstream Output(OutputFilename.c_str());
- if (Out.good()) ...
+ std::ofstream Output(OutputFilename.c_str());
+ if (Output.good()) ...
...
</pre></div>
<p>This declaration defines a variable "<tt>OptimizationLevel</tt>" of the
"<tt>OptLevel</tt>" enum type. This variable can be assigned any of the values
that are listed in the declaration (Note that the declaration list must be
-terminated with the "<tt>clEnumValEnd</tt>" argument!). The CommandLine
+terminated with the "<tt>clEnumValEnd</tt>" argument!). The CommandLine
library enforces
that the user can only specify one of the options, and it ensure that only valid
enum values can be specified. The "<tt>clEnumVal</tt>" macros ensure that the
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
- 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
+ <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
a dash.</p>
<p>So, generally, the problem is that you have two <tt>cl::list</tt> variables
that interact in some way. To ensure the correct interaction, you can use the
absolute position (as found on the command line) of the <tt>optnum</tt>
item in the <tt>cl::list</tt>.</p>
<p>The idiom for usage is like this:</p>
-
+
<div class="doc_code"><pre>
static cl::list<std::string> Files(cl::Positional, cl::OneOrMore);
static cl::list<std::string> Libraries("l", cl::ZeroOrMore);
<p>Note that, for compatibility reasons, the <tt>cl::opt</tt> also supports an
<tt>unsigned getPosition()</tt> option that will provide the absolute position
- of that option. You can apply the same approach as above with a
+ of that option. You can apply the same approach as above with a
<tt>cl::opt</tt> and a <tt>cl::list</tt> option as you can with two lists.</p>
</div>
<li><a name="cl::values">The <b><tt>cl::values</tt></b></a> attribute specifies
the string-to-value mapping to be used by the generic parser. It takes a
-<b>clEnumValEnd terminated</b> list of (option, value, description) triplets
+<b>clEnumValEnd terminated</b> list of (option, value, description) triplets
that
specify the option name, the value mapped to, and the description shown in the
<tt>--help</tt> for the tool. Because the generic parser is used most
-baz</tt>" strings to be applied to the "<tt>-pos1</tt>" option and the
"<tt>-bork</tt>" string to be applied to the "<tt>-pos2</tt>" option.</li>
+<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
+unrecognized option strings to it as values instead of signaling an
+error. As with <b><tt>cl::CommaSeparated</tt></b></a>, this modifier
+only makes sense with a <a href="#cl::list">cl::list</a> option.</li>
+
+
</ul>
-<p>So far, these are the only two miscellaneous option modifiers.</p>
+<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">reponse 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
}
</pre></div>
-<p>To use the extrahelp, simply construct one with a <tt>const char*</tt>
+<p>To use the extrahelp, simply construct one with a <tt>const char*</tt>
parameter to the constructor. The text passed to the constructor will be printed
at the bottom of the help message, verbatim. Note that multiple
<tt>cl::extrahelp</tt> <b>can</b> be used, but this practice is discouraged. If
<b>const</b> std::string &Arg, <b>unsigned</b> &Val) {
<b>const char</b> *ArgStart = Arg.c_str();
<b>char</b> *End;
-
+
<i>// Parse integer part, leaving 'End' pointing to the first non-integer char</i>
Val = (unsigned)strtol(ArgStart, &End, 0);
projects / oota-llvm.git / blobdiff