<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>
</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>
<!-- *********************************************************************** -->
<div class="doc_section">
- Introduction
+ <a name="introduction">Introduction</a>
</div>
<!-- *********************************************************************** -->
to specify where to put the output. With the CommandLine library, this is
represented like this:</p>
-<p><tt>
-<a name="value_desc_example">
-<a href="#cl::opt">cl::opt</a><string> OutputFilename("<i>o</i>", <a href="#cl::desc">cl::desc</a>("<i>Specify output filename</i>"), <a href="#cl::value_desc">cl::value_desc</a>("<i>filename</i>"));</a>
-</tt></p>
+<a name="value_desc_example"></a>
+<pre>
+<a href="#cl::opt">cl::opt</a><string> OutputFilename("<i>o</i>", <a href="#cl::desc">cl::desc</a>("<i>Specify output filename</i>"), <a href="#cl::value_desc">cl::value_desc</a>("<i>filename</i>"));
+</pre>
<p>This declares a global variable "<tt>OutputFilename</tt>" that is used to
capture the result of the "<tt>o</tt>" argument (first parameter). We specify
<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
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>
<p>There are several limitations to when <tt>cl::ConsumeAfter</tt> options can
be specified. For example, only one <tt>cl::ConsumeAfter</tt> can be specified
per program, there must be at least one <a href="#positional">positional
-argument</a> specified, and the <tt>cl::ConsumeAfter</tt> option should be a <a
+argument</a> specified, there must not be any <a href="#cl::list">cl::list</a>
+positional arguments, and the <tt>cl::ConsumeAfter</tt> option should be a <a
href="#cl::list">cl::list</a> option.</p>
</div>
<!-- ======================================================================= -->
-<div class="subsection">
+<div class="doc_subsection">
<a name="storage">Internal vs External Storage</a>
</div>
<pre>
bool DebugFlag; <i>// the actual value</i>
static <a href="#cl::opt">cl::opt</a><bool, true> <i>// The parser</i>
-Debug("<i>debug</i>", <a href="#cl::desc">cl::desc</a>("<i>Enable debug output</i>")
</a>, <a href="#cl::Hidden">cl::Hidden</a>,
+Debug("<i>debug</i>", <a href="#cl::desc">cl::desc</a>("<i>Enable debug output</i>"), <a href="#cl::Hidden">cl::Hidden</a>,
<a href="#cl::location">cl::location</a>(DebugFlag));
</pre>
<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:
strategy basically looks like this:</p>
<p><tt>parse(string OrigInput) {</tt>
+
<ol>
<li><tt>string input = OrigInput;</tt>
<li><tt>if (isOption(input)) return getOption(input).parse();</tt> <i>// Normal option</i>
input = OrigInput;<br>
while (!isOption(input) && !input.empty()) input.pop_back();<br>
}</tt>
-<li><tt>if (!OrigInput.empty()) error();</tt>
-</tt>
+<li><tt>if (!OrigInput.empty()) error();</tt></li>
</ol>
-<tt>}</tt></p>
+
+<p><tt>}</tt></p>
</div>
makes sense to be used in a case where the option is allowed to accept one or
more values (i.e. it is a <a href="#cl::list">cl::list</a> option).</li>
+<li><a name="cl::PositionalEatsArgs">The
+<b><tt>cl::PositionalEatsArgs</tt></b></a> modifier (which only applies to
+positional arguments, and only makes sense for lists) indicates that positional
+argument should consume any strings after it (including strings that start with
+a "-") up until another recognized positional argument. For example, if you
+have two "eating" positional arguments "<tt>pos1</tt>" and "<tt>pos2</tt>" the
+string "<tt>-pos1 -foo -bar baz -pos2 -bork</tt>" would cause the "<tt>-foo -bar
+-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>
+
</ul>
-<p>So far, the only miscellaneous option modifier is the
-<tt>cl::CommaSeparated</tt> modifier.</p>
+<p>So far, these are the only two miscellaneous option modifiers.</p>
</div>
</div>
<div class="doc_text">
+ <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: fill in this section</p>
+<p>TODO: complete this section</p>
</div>
<!-- *********************************************************************** -->
<hr>
-<div class="doc_footer">
- <address><a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
- <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a>
- <br>
+<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>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
+
+ <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
+ <a href="http://llvm.cs.uiuc.edu">LLVM Compiler Infrastructure</a><br>
Last modified: $Date$
-</div>
+</address>
</body>
</html>
projects / oota-llvm.git / blobdiff