"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="#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>
</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>
else
break; // we're done with the list
}
- }</tt></pre></p>
+ }
+ </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
<p>To do this, set up your .h file with your option, like this for example:</p>
+<div class="doc_code">
<pre>
<i>// DebugFlag.h - Get access to the '-debug' command line option
//
// debug build, then the code specified as the option to the macro will be
// executed. Otherwise it will not be. Example:
//
-// DEBUG(cerr << "Bitset contains: " << Bitset << "\n");
+// DEBUG(std::cerr << "Bitset contains: " << Bitset << "\n");
//</i>
-<span class="doc_red">#ifdef NDEBUG
+<span class="doc_hilite">#ifdef NDEBUG
#define DEBUG(X)
#else
-#define DEBUG(X)</span> \
- do { if (DebugFlag) { X; } } while (0)
-<span class="doc_red">#endif</span>
+#define DEBUG(X)</span> do { if (DebugFlag) { X; } } while (0)
+<span class="doc_hilite">#endif</span>
</pre>
+</div>
<p>This allows clients to blissfully use the <tt>DEBUG()</tt> macro, or the
<tt>DebugFlag</tt> explicitly if they want to. Now we just need to be able to
where to fill in with the <a href="#cl::location">cl::location</a>
attribute:</p>
+<div class="doc_code">
<pre>
-bool DebugFlag; <i>// the actual value</i>
+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 href="#cl::Hidden">cl::Hidden</a>,
- <a href="#cl::location">cl::location</a>(DebugFlag));
+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>
+</div>
<p>In the above example, we specify "<tt>true</tt>" as the second argument to
-the <a href="#cl::opt">cl::opt</a> template, indicating that the template should
-not maintain a copy of the value itself. In addition to this, we specify the <a
-href="#cl::location">cl::location</a> attribute, so that <tt>DebugFlag</tt> is
-automatically set.</p>
+the <tt><a href="#cl::opt">cl::opt</a></tt> template, indicating that the
+template should not maintain a copy of the value itself. In addition to this,
+we specify the <tt><a href="#cl::location">cl::location</a></tt> attribute, so
+that <tt>DebugFlag</tt> is automatically set.</p>
</div>
information.</li>
<li><a name="cl::aliasopt">The <b><tt>cl::aliasopt</tt></b></a> attribute
-specifies which option a <a href="#cl::alias">cl::alias</a> option is an alias
-for.</li>
+specifies which option a <tt><a href="#cl::alias">cl::alias</a></tt> option is
+an alias for.</li>
<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
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