"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>CommandLine 2.0 Library Manual</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<li><a href="#positional">Positional Arguments</a>
<ul>
<li><a href="#--">Specifying positional options with hyphens</a></li>
+ <li><a href="#getPosition">Determining absolute position with
+ getPosition</a></li>
<li><a href="#cl::ConsumeAfter">The <tt>cl::ConsumeAfter</tt>
modifier</a></li>
</ul></li>
<li><a href="#cl::opt">The <tt>cl::opt</tt> class</a></li>
<li><a href="#cl::list">The <tt>cl::list</tt> class</a></li>
<li><a href="#cl::alias">The <tt>cl::alias</tt> class</a></li>
+ <li><a href="#cl::extrahelp">The <tt>cl::extrahelp</tt> class</a></li>
</ul></li>
<li><a href="#builtinparsers">Builtin parsers</a>
</ol></li>
</ol>
-<div class="doc_text">
- <p><b>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a></b></p>
+<div class="doc_author">
+ <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a></p>
</div>
<!-- *********************************************************************** -->
<p>The answer is that it uses a table driven generic parser (unless you specify
your own parser, as described in the <a href="#extensionguide">Extension
-Guide</a>). This parser maps literal strings to whatever type is required, are
+Guide</a>). This parser maps literal strings to whatever type is required, and
requires you to tell it what this mapping should be.</p>
-<p>Lets say that we would like to add four optimizations levels to our
+<p>Lets say that we would like to add four optimization levels to our
optimizer, using the standard flags "<tt>-g</tt>", "<tt>-O0</tt>",
"<tt>-O1</tt>", and "<tt>-O2</tt>". We could easily implement this with boolean
options like above, but there are several problems with this strategy:</p>
clEnumVal(O1, "<i>Enable trivial optimizations</i>"),
clEnumVal(O2, "<i>Enable default optimizations</i>"),
clEnumVal(O3, "<i>Enable expensive optimizations</i>"),
- 0));
+ clEnumValEnd));
...
if (OptimizationLevel >= O2) doPartialRedundancyElimination(...);
<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>0</tt>" argument!). The CommandLine library enforces
+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
command line arguments matched the enum values. With this option added, our
clEnumVal(O1 , "<i>Enable trivial optimizations</i>"),
clEnumVal(O2 , "<i>Enable default optimizations</i>"),
clEnumVal(O3 , "<i>Enable expensive optimizations</i>"),
- 0));
+ clEnumValEnd));
...
if (OptimizationLevel == Debug) outputDebugInfo(...);
clEnumValN(nodebuginfo, "none", "<i>disable debug information</i>"),
clEnumVal(quick, "<i>enable quick debug information</i>"),
clEnumVal(detailed, "<i>enable detailed debug information</i>"),
- 0));
+ clEnumValEnd));
</pre>
<p>This definition defines an enumerated command line variable of type "<tt>enum
</pre>
<p>Again, the only structural difference between the debug level declaration and
-the optimiation level declaration is that the debug level declaration includes
+the optimization level declaration is that the debug level declaration includes
an option name (<tt>"debug_level"</tt>), which automatically changes how the
library processes the argument. The CommandLine library supports both forms so
that you can choose the form most appropriate for your application.</p>
clEnumVal(constprop , "<i>Constant Propagation</i>"),
clEnumValN(inlining, "<i>inline</i>", "<i>Procedure Integration</i>"),
clEnumVal(strip , "<i>Strip Symbols</i>"),
- 0));
+ clEnumValEnd));
</pre>
<p>This defines a variable that is conceptually of the type
<p>Positional arguments are sorted by their order of construction. This means
that command line options will be ordered according to how they are listed in a
-.cpp file, but will not have an ordering defined if they positional arguments
+.cpp file, but will not have an ordering defined if the positional arguments
are defined in multiple .cpp files. The fix for this problem is simply to
define all of your positional arguments in one .cpp file.</p>
</div>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="getPosition">Determining absolute position with getPosition()</a>
+</div>
+<div class="doc_text">
+ <p>Sometimes an option can affect or modify the meaning of another option. For
+ 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
+ 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
+ <tt>cl::list::getPosition(optnum)</tt> method. This method returns 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:<pre><tt>
+ static cl::list<std::string> Files(cl::Positional, cl::OneOrMore);
+ static cl::listlt;std::string> Libraries("l", cl::ZeroOrMore);
+
+ int main(int argc, char**argv) {
+ // ...
+ std::vector<std::string>::iterator fileIt = Files.begin();
+ std::vector<std::string>::iterator libIt = Libraries.begin();
+ unsigned libPos = 0, filePos = 0;
+ while ( 1 ) {
+ if ( libIt != Libraries.end() )
+ libPos = Libraries.getPosition( libIt - Libraries.begin() );
+ else
+ libPos = 0;
+ if ( fileIt != Files.end() )
+ filePos = Files.getPosition( fileIt - Files.begin() );
+ else
+ filePos = 0;
+
+ if ( filePos != 0 && (libPos == 0 || filePos < libPos) ) {
+ // Source File Is next
+ ++fileIt;
+ }
+ else if ( libPos != 0 && (filePos == 0 || libPos < filePos) ) {
+ // Library is next
+ ++libIt;
+ }
+ else
+ break; // we're done with the list
+ }
+ }
+ </tt></pre></p>
+ <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
+ <tt>cl::opt</tt> and a <tt>cl::list</tt> option as you can with two lists.</p>
+</div>
+
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
<a name="cl::ConsumeAfter">The <tt>cl::ConsumeAfter</tt> modifier</a>
<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>null terminated</b> list of (option, value, description) triplets that
+<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
frequently with enum values, two macros are often useful:
specifies that this option is used to capture "interpreter style" arguments. See <a href="#cl::ConsumeAfter">this section for more information</a>.</li>
<li><a name="cl::Prefix">The <b><tt>cl::Prefix</tt></b></a> modifier specifies
-that this option prefixes its value. With 'Prefix' options, there is no equal
-sign that separates the value from the option name specified. This is useful
-for processing odd arguments like '<tt>-lmalloc -L/usr/lib'</tt> in a linker
-tool. Here, the '<tt>l</tt>' and '<tt>L</tt>' options are normal string (list)
-options, that have the <a href="#cl::Prefix">cl::Prefix</a> modifier added to
-allow the CommandLine library to recognize them. Note that <a
-href="#cl::Prefix">cl::Prefix</a> options must not have the <a
+that this option prefixes its value. With 'Prefix' options, the equal sign does
+not separate the value from the option name specified. Instead, the value is
+everything after the prefix, including any equal sign if present. This is useful
+for processing odd arguments like <tt>-lmalloc</tt> and <tt>-L/usr/lib</tt> in a
+linker tool or <tt>-DNAME=value</tt> in a compiler tool. Here, the
+'<tt>l</tt>', '<tt>D</tt>' and '<tt>L</tt>' options are normal string (or list)
+options, that have the <a href="#cl::Prefix">cl::Prefix</a> modifier added to
+allow the CommandLine library to recognize them. Note that
+<a href="#cl::Prefix">cl::Prefix</a> options must not have the <a
href="#cl::ValueDisallowed">cl::ValueDisallowed</a> modifier specified.</li>
<li><a name="cl::Grouping">The <b><tt>cl::Grouping</tt></b></a> modifier is used
</div>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="cl::extrahelp">The <tt>cl::extrahelp</tt> class</a>
+</div>
+
+<div class="doc_text">
+
+<p>The <tt>cl::extrahelp</tt> class is a nontemplated class that allows extra
+help text to be printed out for the <tt>--help</tt> option.</p>
+
+<pre>
+<b>namespace</b> cl {
+ <b>struct</b> extrahelp;
+}
+</pre>
+
+<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
+your tool needs to print additional help information, put all that help into a
+single <tt>cl::extrahelp</tt> instance.</p>
+<p>For example:</p>
+<pre>
+ cl::extrahelp("\nADDITIONAL HELP:\n\n This is the extra help\n");
+</pre>
+</div>
+
<!-- ======================================================================= -->
<div class="doc_subsection">
<a name="builtinparsers">Builtin parsers</a>
</div>
<div class="doc_text">
-
-<p>TODO: fill in this section</p>
+ <p>Several of the LLVM libraries define static <tt>cl::opt</tt> instances that
+ will automatically be included in any program that links with that library.
+ This is a feature. However, sometimes it is necessary to know the value of the
+ command line option outside of the library. In these cases the library does or
+ should provide an external storage location that is accessible to users of the
+ library. Examples of this include the <tt>llvm::DebugFlag</tt> exported by the
+ <tt>lib/Support/Debug.cpp</tt> file and the <tt>llvm::TimePassesIsEnabled</tt>
+ flag exported by the <tt>lib/VMCore/Pass.cpp</tt> file.</p>
+
+<p>TODO: complete this section</p>
</div>
projects / oota-llvm.git / blobdiff