2001-07-23 23:03:12 +00:00
|
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
2002-07-25 19:27:01 +00:00
|
|
|
<html><head><title>CommandLine 2.0 Library Manual</title></head>
|
2001-07-23 23:03:12 +00:00
|
|
|
<body bgcolor=white>
|
|
|
|
|
|
|
|
|
|
<table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
|
2002-07-25 19:27:01 +00:00
|
|
|
<tr><td> <font size=+4 color="#EEEEFF" face="Georgia,Palatino,Times,Roman"><b>CommandLine 2.0 Library Manual</b></font></td>
|
2001-07-23 23:03:12 +00:00
|
|
|
</tr></table>
|
|
|
|
|
|
|
|
|
|
<ol>
|
|
|
|
|
<li><a href="#introduction">Introduction</a>
|
|
|
|
|
<li><a href="#quickstart">Quick Start Guide</a>
|
|
|
|
|
<ol>
|
2002-07-25 19:27:01 +00:00
|
|
|
<li><a href="#bool">Boolean Arguments</a>
|
|
|
|
|
<li><a href="#alias">Argument Aliases</a>
|
|
|
|
|
<li><a href="#onealternative">Selecting an alternative from a set of possibilities</a>
|
2001-07-23 23:03:12 +00:00
|
|
|
<li><a href="#namedalternatives">Named alternatives</a>
|
2002-07-25 19:27:01 +00:00
|
|
|
<li><a href="#list">Parsing a list of options</a>
|
2001-07-23 23:03:12 +00:00
|
|
|
</ol>
|
|
|
|
|
<li><a href="#referenceguide">Reference Guide</a>
|
2002-07-25 19:27:01 +00:00
|
|
|
<ol>
|
|
|
|
|
<li>Option Modifiers:
|
|
|
|
|
<ul>
|
|
|
|
|
<li>Controlling whether or not the option is shown by <tt>--help</tt>
|
|
|
|
|
<li>Controlling the number of occurances required and allowed
|
|
|
|
|
<li>Controlling whether or not a value must be specified
|
|
|
|
|
<li>Controlling other formatting options
|
|
|
|
|
</ul>
|
|
|
|
|
<li>Positional Arguments
|
|
|
|
|
<li>Internal vs External Storage
|
|
|
|
|
<li>The option classes
|
|
|
|
|
<ul>
|
|
|
|
|
<li>The <tt>opt<></tt> class
|
|
|
|
|
<li>The <tt>list<></tt> class
|
|
|
|
|
<li>The <tt>alias</tt> class
|
|
|
|
|
</ul>
|
|
|
|
|
</ol>
|
2001-07-23 23:03:12 +00:00
|
|
|
<li><a href="#extensionguide">Extension Guide</a>
|
2002-07-25 19:27:01 +00:00
|
|
|
<ol>
|
|
|
|
|
<li>Writing a custom parser
|
|
|
|
|
<li>Exploiting external storage
|
|
|
|
|
<li>Dynamically adding command line options
|
|
|
|
|
</ol>
|
2001-07-23 23:03:12 +00:00
|
|
|
</ol><p>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
|
|
|
|
|
<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
|
|
|
|
|
<a name="introduction">Introduction
|
|
|
|
|
</b></font></td></tr></table><ul>
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
This document describes the CommandLine argument processing library. It will
|
|
|
|
|
show you how to use it, and what it can do.<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
Although there are a <b>lot</b> of command line argument parsing libraries out
|
|
|
|
|
there in many different languages, none of them fit well with what I needed. By
|
|
|
|
|
looking at the features and problems of other libraries, I designed the
|
|
|
|
|
CommandLine library to have the following features:<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<ol>
|
2002-07-25 19:27:01 +00:00
|
|
|
<li>Speed: The CommandLine library is very quick and uses little resources. The
|
|
|
|
|
parsing time of the library is directly proportional to the number of arguments
|
|
|
|
|
parsed, not the the number of options recognized. Additionally, command line
|
|
|
|
|
argument values are captured transparently into user defined variables, which
|
|
|
|
|
can be accessed like any other variable (and with the same performance).<p>
|
|
|
|
|
|
|
|
|
|
<li>Type Safe: As a user of CommandLine, you don't have to worry about
|
|
|
|
|
remembering the type of arguments that you want (is it an int? a string? a
|
|
|
|
|
bool? an enum?) and keep casting it around. Not only does this help prevent
|
|
|
|
|
error prone constructs, it also leads to dramatically cleaner source code.<p>
|
|
|
|
|
|
|
|
|
|
<li>No subclasses required: To use CommandLine, you instantiate variables that
|
|
|
|
|
correspond to the arguments that you would like to capture, you don't subclass a
|
|
|
|
|
parser. This leads to much less boilerplate code.<p>
|
|
|
|
|
|
|
|
|
|
<li>Globally accessible: Libraries can specify command line arguments that are
|
|
|
|
|
automatically enabled in any tool that links to the library. This is possible
|
|
|
|
|
because the application doesn't have to keep a "list" of arguments to pass to
|
|
|
|
|
the parser.<p>
|
|
|
|
|
|
|
|
|
|
<li>More Clean: CommandLine supports enum types directly, meaning that there is
|
|
|
|
|
less error and more security built into the library. You don't have to worry
|
|
|
|
|
about whether your integral command line argument accidentally got assigned a
|
|
|
|
|
value that is not valid for your enum type.<p>
|
|
|
|
|
|
|
|
|
|
<li>Powerful: The CommandLine library supports many different types of
|
|
|
|
|
arguments, from simple boolean flags to scalars arguments (strings, integers,
|
|
|
|
|
enums, doubles), to lists of arguments. This is possible because CommandLine
|
|
|
|
|
is...<p>
|
|
|
|
|
|
|
|
|
|
<li>Extensible: It is very simple to add a new argument type to CommandLine.
|
|
|
|
|
Simply specify the parser that you want to use with the command line option when
|
|
|
|
|
you declare it. Custom parsers are no problem.<p>
|
|
|
|
|
|
|
|
|
|
<li>Labor Saving: The CommandLine library cuts down on the amount of grunt work
|
|
|
|
|
that you, the user, have to do. For example, it automatically provides a --help
|
|
|
|
|
option that shows the available command line options for your tool.<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
</ol>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
This document will hopefully let you jump in and start using CommandLine in your
|
|
|
|
|
utility quickly and painlessly. Additionally it should be a simple reference
|
|
|
|
|
manual to figure out how stuff works. If it is failing in some area, nag the
|
|
|
|
|
author, <a href="mailto:sabre@nondot.org">Chris Lattner</a>.<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0><tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
|
|
|
|
|
<a name="quickstart">Quick Start Guide
|
|
|
|
|
</b></font></td></tr></table><ul>
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
This section of the manual runs through a simple CommandLine'ification of a
|
|
|
|
|
basic compiler tool. This is intended to show you how to jump into using the
|
|
|
|
|
CommandLine library in your own program, and show you some of the cool things it
|
|
|
|
|
can do.<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
To start out, you need to include the CommandLine header file into your
|
|
|
|
|
program:<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<pre>
|
2002-07-25 19:27:01 +00:00
|
|
|
#include "Support/CommandLine.h"
|
2001-07-23 23:03:12 +00:00
|
|
|
</pre><p>
|
|
|
|
|
|
|
|
|
|
Additionally, you need to add this as the first line of your main program:<p>
|
|
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
int main(int argc, char **argv) {
|
|
|
|
|
cl::ParseCommandLineOptions(argc, argv);
|
|
|
|
|
...
|
|
|
|
|
}
|
|
|
|
|
</pre><p>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
... which actually parses the arguments and fills in the variable
|
|
|
|
|
declarations.<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
Now that you are ready to support command line arguments, we need to tell the
|
|
|
|
|
system which ones we want, and what type of argument they are. The CommandLine
|
|
|
|
|
library uses a declarative syntax to model cammand line arguments with the
|
|
|
|
|
variable declarations that capture the parsed values. This means that for every
|
|
|
|
|
command line option that you would like to support, there should be a variable
|
|
|
|
|
declaration to capture the result. For example, in a compiler, we would like to
|
|
|
|
|
support the unix standard '<tt>-o <filename></tt>' option to specify where
|
|
|
|
|
to put the output. With the CommandLine library, this is represented like
|
|
|
|
|
this:<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<pre>
|
2002-07-25 19:27:01 +00:00
|
|
|
cl::opt<string> OutputFilename("<i>o</i>", cl::desc("<i>Specify output filename</i>"), cl::value_desc("<i>filename</i>"));
|
2001-07-23 23:03:12 +00:00
|
|
|
</pre><p>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
This declares a variable "<tt>OutputFilename</tt>" that is used to capture the
|
|
|
|
|
result of the "<tt>o</tt>" argument (first parameter). We specify that this is
|
|
|
|
|
a simple scalar option by using the "<tt>opt<></tt>" template (as opposed
|
|
|
|
|
to the <a href="#list">"<tt>list<></tt> template</a>), and tell the
|
|
|
|
|
CommandLine library that the data type that we are parsing is a string.<p>
|
|
|
|
|
|
|
|
|
|
The second and third parameters (which are optional) are used to specify what to
|
|
|
|
|
output for the "<tt>--help</tt>" option. In this case, we get a line that looks
|
|
|
|
|
like this:<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<pre>
|
2002-07-25 19:27:01 +00:00
|
|
|
USAGE: compiler [options]
|
2001-07-23 23:03:12 +00:00
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
OPTIONS:
|
|
|
|
|
-help - display available options (--help-hidden for more)
|
|
|
|
|
-o <filename> - Specify output filename
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
Because we specified that the command line option should parse using the
|
|
|
|
|
<tt>string</tt> data type, the variable declared is automatically usable as a
|
|
|
|
|
real string in all contexts that a normal C++ string object may be used. For
|
|
|
|
|
example:<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
...
|
|
|
|
|
ofstream Output(OutputFilename.c_str());
|
|
|
|
|
if (Out.good()) ...
|
|
|
|
|
...
|
|
|
|
|
</pre><p>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
There are many different options that you can use to customize the command line
|
|
|
|
|
option handling library, but the above example shows the general interface to
|
|
|
|
|
these options. The options can be specified in any order, and are specified
|
|
|
|
|
with helper functions like <tt>cl::desc(...)</tt>, so there are no positional
|
|
|
|
|
dependencies to have to remember. We will discuss the options you can use later
|
|
|
|
|
in this document. Also note that if your compiler supports Koenig lookup (gcc
|
|
|
|
|
2.95.x doesn't), that you don't have to specify as many <tt>cl::</tt> namespace
|
|
|
|
|
qualifiers to use the library.<p>
|
|
|
|
|
|
|
|
|
|
Continuing the example, we would like to have our compiler take an input
|
|
|
|
|
filename as well as an output filename, but we do not want the input filename to
|
|
|
|
|
be specified with a hyphen (ie, not <tt>-filename.c</tt>). To support this
|
|
|
|
|
style of argument, the CommandLine library allows for positional arguments to be
|
|
|
|
|
specified for the program. These positional arguments are filled with command
|
|
|
|
|
line parameters that are not in option form. We use this feature like this:<p>
|
|
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
cl::opt<string> InputFilename(cl::Positional, cl::desc("<i><input file></i>"), cl::init("<i>-</i>"));
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
This declaration indicates that the first positional argument should be treated
|
|
|
|
|
as the input filename. Here we use the <tt>cl::init</tt> option to specify an
|
|
|
|
|
initial value for the command line option, which is used if the option is not
|
|
|
|
|
specified (if you do not specify a <tt>cl::init</tt> modifier for an option,
|
|
|
|
|
then the default constructor for the data type is used to initialize the value).
|
|
|
|
|
Command line options default to being optional, so if we would like to require
|
|
|
|
|
that the user always specify an input filename, we would add the
|
|
|
|
|
<tt>cl::Required</tt> flag, and we could eliminate the <tt>cl::init</tt>
|
|
|
|
|
modifier, like this:<p>
|
|
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
cl::opt<string> InputFilename(cl::Positional, cl::desc("<i><input file></i>"), <b>cl::Required</b>);
|
|
|
|
|
</pre>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
Again, the CommandLine library does not require the options to be specified in
|
|
|
|
|
any particular order, so the above declaration is equivalent to:<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<pre>
|
2002-07-25 19:27:01 +00:00
|
|
|
cl::opt<string> InputFilename(cl::Positional, cl::Required, cl::desc("<i><input file></i>"));
|
2001-07-23 23:03:12 +00:00
|
|
|
</pre>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
By simply adding the <tt>cl::Required</tt> flag, the CommandLine library will
|
|
|
|
|
automatically issue an error if the argument is not specified, which shifts all
|
|
|
|
|
of the command line option verification code out of your application into the
|
|
|
|
|
library. This is just one example of how using flags can alter the default
|
|
|
|
|
behaviour of the library, on a per-option basis. By adding one of the
|
|
|
|
|
declarations above, the <tt>--help</tt> option synopsis is now extended to:<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<pre>
|
2002-07-25 19:27:01 +00:00
|
|
|
USAGE: compiler [options] <input file>
|
|
|
|
|
|
|
|
|
|
OPTIONS:
|
|
|
|
|
-help - display available options (--help-hidden for more)
|
|
|
|
|
-o <filename> - Specify output filename
|
2001-07-23 23:03:12 +00:00
|
|
|
</pre>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
... indicating that an input filename is expected.<p>
|
|
|
|
|
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<!-- ======================================================================= -->
|
|
|
|
|
</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%"> <font color="#EEEEFF" face="Georgia,Palatino"><b>
|
2002-07-25 19:27:01 +00:00
|
|
|
<a name="bool">Boolean Arguments
|
2001-07-23 23:03:12 +00:00
|
|
|
</b></font></td></tr></table><ul>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
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>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<pre>
|
2002-07-25 19:27:01 +00:00
|
|
|
cl::opt<bool> Force ("<i>f</i>", cl::desc("<i>Overwrite output files</i>"));
|
|
|
|
|
cl::opt<bool> Quiet ("<i>quiet</i>", cl::desc("<i>Don't print informational messages</i>"));
|
|
|
|
|
cl::opt<bool> Quiet2("<i>q</i>", cl::desc("<i>Don't print informational messages</i>"), cl::Hidden);
|
2001-07-23 23:03:12 +00:00
|
|
|
</pre><p>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
This does what you would expect: it declares three boolean variables
|
|
|
|
|
("<tt>Force</tt>", "<tt>Quiet</tt>", and "<tt>Quiet2</tt>") to recognize these
|
|
|
|
|
options. Note that the "<tt>-q</tt>" option is specified with the
|
|
|
|
|
"<tt>cl::Hidden</tt>" flag. This modifier prevents it from being shown by the
|
|
|
|
|
standard "<tt>--help</tt>" output (note that it is still shown in the
|
|
|
|
|
"<tt>--help-hidden</tt>" output).<p>
|
|
|
|
|
|
|
|
|
|
The CommandLine library uses a different parser for different data types. For
|
|
|
|
|
example, in the string case, the argument passed to the option is copied
|
|
|
|
|
literally into the content of the string variable... we obviously cannot do that
|
|
|
|
|
in the boolean case, however, so we must use a smarter parser. In the case of
|
|
|
|
|
the boolean parser, it allows no options (in which case it assigns the value of
|
|
|
|
|
true to the variable), or it allows the values "<tt>true</tt>" or
|
|
|
|
|
"<tt>false</tt>" to be specified, allowing any of the following inputs:<p>
|
|
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
compiler -f # No value, 'Force' == true
|
|
|
|
|
compiler -f=true # Value specified, 'Force' == true
|
|
|
|
|
compiler -f=TRUE # Value specified, 'Force' == true
|
|
|
|
|
compiler -f=FALSE # Value specified, 'Force' == false
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
... you get the idea. The bool parser just turns the string values into boolean
|
|
|
|
|
values, and rejects things like '<tt>compiler -f=foo</tt>'. Similarly, the
|
|
|
|
|
float, double, and int parsers work like you would expect, using the
|
|
|
|
|
'<tt>strtol</tt>' and '<tt>strtod</tt>' C library calls to parse the string
|
|
|
|
|
value into the specified data type.<p>
|
|
|
|
|
|
|
|
|
|
With the declarations above, "<tt>compiler --help</tt>" emits this:<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<pre>
|
2002-07-25 19:27:01 +00:00
|
|
|
USAGE: compiler [options] <input file>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
OPTIONS:
|
|
|
|
|
-f - Overwrite output files
|
|
|
|
|
-o - Override output filename
|
|
|
|
|
-quiet - Don't print informational messages
|
|
|
|
|
-help - display available options (--help-hidden for more)
|
|
|
|
|
</pre><p>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
and "<tt>opt --help-hidden</tt>" prints this:<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<pre>
|
2002-07-25 19:27:01 +00:00
|
|
|
USAGE: opt [options] <input file>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
OPTIONS:
|
|
|
|
|
-f - Overwrite output files
|
|
|
|
|
-o - Override output filename
|
|
|
|
|
-q - Don't print informational messages
|
|
|
|
|
-quiet - Don't print informational messages
|
|
|
|
|
-help - display available options (--help-hidden for more)
|
|
|
|
|
</pre><p>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
This brief example has shown you how to use the '<tt>opt<></tt>' class to
|
|
|
|
|
parse simple scalar command line arguments. In addition to simple scalar
|
|
|
|
|
arguments, the CommandLine library also provides primitives to support
|
|
|
|
|
CommandLine option <a href="#alias">aliases</a>, and <a href="#list">lists</a>
|
|
|
|
|
of options.<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ======================================================================= -->
|
|
|
|
|
</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%"> <font color="#EEEEFF" face="Georgia,Palatino"><b>
|
2002-07-25 19:27:01 +00:00
|
|
|
<a name="alias">Argument Aliases
|
2001-07-23 23:03:12 +00:00
|
|
|
</b></font></td></tr></table><ul>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
So far, the example works well, except for the fact that we need to check the
|
|
|
|
|
quiet condition like this now:<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
...
|
|
|
|
|
if (!Quiet && !Quiet2) printInformationalMessage(...);
|
|
|
|
|
...
|
|
|
|
|
</pre><p>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
... which is a real pain! Instead of defining two values for the same
|
|
|
|
|
condition, we can use the "<tt>cl::alias</tt>" class to make the "<tt>-q</tt>"
|
|
|
|
|
option an <b>alias</b> for the "<tt>-quiet</tt>" option, instead of providing
|
|
|
|
|
a value itself:<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<pre>
|
2002-07-25 19:27:01 +00:00
|
|
|
cl::opt<bool> Force ("<i>f</i>", cl::desc("<i>Overwrite output files</i>"));
|
|
|
|
|
cl::opt<bool> Quiet ("<i>quiet</i>", cl::desc("<i>Don't print informational messages</i>"));
|
|
|
|
|
cl::alias QuietA("<i>q</i>", cl::desc("<i>Alias for -quiet</i>"), cl::aliasopt(Quiet));
|
2001-07-23 23:03:12 +00:00
|
|
|
</pre><p>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
The third line (which is the only one we modified from above) defines a
|
|
|
|
|
"<tt>-q</tt> alias that updates the "<tt>Quiet</tt>" variable (as specified by
|
|
|
|
|
the <tt>cl::aliasopt</tt> modifier) whenever it is specified. Because aliases
|
|
|
|
|
do not hold state, the only thing the program has to query is the <tt>Quiet</tt>
|
|
|
|
|
variable now. Another nice feature of aliases is that they automatically hide
|
|
|
|
|
themselves from the <tt>-help</tt> output (although, again, they are still
|
|
|
|
|
visible in the <tt>--help-hidden output</tt>).<p>
|
|
|
|
|
|
|
|
|
|
Now the application code can simply use:<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
...
|
|
|
|
|
if (!Quiet) printInformationalMessage(...);
|
|
|
|
|
...
|
|
|
|
|
</pre><p>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
... which is much nicer! The "<tt>cl::alias</tt>" can be used to specify an
|
|
|
|
|
alternative name for any variable type, and has many uses.<p>
|
|
|
|
|
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ======================================================================= -->
|
|
|
|
|
</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%"> <font color="#EEEEFF" face="Georgia,Palatino"><b>
|
2002-07-25 19:27:01 +00:00
|
|
|
<a name="onealternative">Selecting an alternative from a set of possibilities
|
2001-07-23 23:03:12 +00:00
|
|
|
</b></font></td></tr></table><ul>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
So far, we have seen how the CommandLine library handles builtin types like
|
|
|
|
|
<tt>std::string</tt>, <tt>bool</tt> and <tt>int</tt>, but how does it handle
|
|
|
|
|
things it doesn't know about, like enums or '<tt>int*</tt>'s?<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
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
|
|
|
|
|
requires you to tell it what this mapping should be.<p>
|
|
|
|
|
|
|
|
|
|
Lets say that we would like to add four optimizations 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>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<ol>
|
2002-07-25 19:27:01 +00:00
|
|
|
<li>A user could specify more than one of the options at a time, for example,
|
|
|
|
|
"<tt>opt -O3 -O2</tt>". The CommandLine library would not be able to catch this
|
|
|
|
|
erroneous input for us.
|
|
|
|
|
|
2001-07-23 23:03:12 +00:00
|
|
|
<li>We would have to test 4 different variables to see which ones are set.
|
2002-07-25 19:27:01 +00:00
|
|
|
|
|
|
|
|
<li>This doesn't map to the numeric levels that we want... so we cannot easily
|
|
|
|
|
see if some level >= "<tt>-O1</tt>" is enabled.
|
|
|
|
|
|
2001-07-23 23:03:12 +00:00
|
|
|
</ol><p>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
To cope with these problems, we can use an enum value, and have the CommandLine
|
|
|
|
|
library fill it in with the appropriate level directly, which is used like
|
|
|
|
|
this:<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
enum OptLevel {
|
|
|
|
|
g, O1, O2, O3
|
|
|
|
|
};
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
cl::opt<OptLevel> OptimizationLevel(cl::desc("<i>Choose optimization level:</i>"),
|
|
|
|
|
cl::values(
|
|
|
|
|
clEnumVal(g , "<i>No optimizations, enable debugging</i>"),
|
|
|
|
|
clEnumVal(O1, "<i>Enable trivial optimizations</i>"),
|
|
|
|
|
clEnumVal(O2, "<i>Enable default optimizations</i>"),
|
|
|
|
|
clEnumVal(O3, "<i>Enable expensive optimizations</i>"),
|
|
|
|
|
0));
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
...
|
2002-07-25 19:27:01 +00:00
|
|
|
if (OptimizationLevel >= O2) doPartialRedundancyElimination(...);
|
2001-07-23 23:03:12 +00:00
|
|
|
...
|
|
|
|
|
</pre><p>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
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
|
|
|
|
|
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 matche the enum values. With this option added, our help
|
|
|
|
|
output now is:<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
<pre>
|
|
|
|
|
USAGE: compiler [options] <input file>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
OPTIONS:
|
|
|
|
|
Choose optimization level:
|
|
|
|
|
-g - No optimizations, enable debugging
|
|
|
|
|
-O1 - Enable trivial optimizations
|
|
|
|
|
-O2 - Enable default optimizations
|
|
|
|
|
-O3 - Enable expensive optimizations
|
|
|
|
|
-f - Overwrite output files
|
|
|
|
|
-help - display available options (--help-hidden for more)
|
|
|
|
|
-o <filename> - Specify output filename
|
|
|
|
|
-quiet - Don't print informational messages
|
|
|
|
|
</pre>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
In this case, it is sort of awkward that flag names correspond directly to enum
|
|
|
|
|
names, because we probably don't want a enum definition named "<tt>g</tt>" in
|
|
|
|
|
our program. Because of this, we can alternatively write this example like
|
|
|
|
|
this:<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
enum OptLevel {
|
|
|
|
|
Debug, O1, O2, O3
|
|
|
|
|
};
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
cl::opt<OptLevel> OptimizationLevel(cl::desc("<i>Choose optimization level:</i>"),
|
|
|
|
|
cl::values(
|
|
|
|
|
clEnumValN(Debug, "g", "<i>No optimizations, enable debugging</i>"),
|
|
|
|
|
clEnumVal(O1 , "<i>Enable trivial optimizations</i>"),
|
|
|
|
|
clEnumVal(O2 , "<i>Enable default optimizations</i>"),
|
|
|
|
|
clEnumVal(O3 , "<i>Enable expensive optimizations</i>"),
|
|
|
|
|
0));
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
...
|
|
|
|
|
if (OptimizationLevel == Debug) outputDebugInfo(...);
|
|
|
|
|
...
|
|
|
|
|
</pre><p>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
By using the "<tt>clEnumValN</tt>" macro instead of "<tt>clEnumVal</tt>", we can
|
|
|
|
|
directly specify the name that the flag should get. In general a direct mapping
|
|
|
|
|
is nice, but sometimes you can't or don't want to preserve the mapping, which is
|
|
|
|
|
when you would use it.<p>
|
|
|
|
|
|
|
|
|
|
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<!-- ======================================================================= -->
|
|
|
|
|
</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%"> <font color="#EEEEFF" face="Georgia,Palatino"><b>
|
|
|
|
|
<a name="namedalternatives">Named Alternatives
|
|
|
|
|
</b></font></td></tr></table><ul>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
Another useful argument form is a named alternative style. We shall use this
|
|
|
|
|
style in our compiler to specify different debug levels that can be used.
|
|
|
|
|
Instead of each debug level being its own switch, we want to support the
|
|
|
|
|
following options, of which only one can be specified at a time:
|
|
|
|
|
"<tt>--debug-level=none</tt>", "<tt>--debug-level=quick</tt>",
|
|
|
|
|
"<tt>--debug-level=detailed</tt>". To do this, we use the exact same format as
|
|
|
|
|
our optimization level flags, but we also specify an option name. For this
|
|
|
|
|
case, the code looks like this:<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
enum DebugLev {
|
|
|
|
|
nodebuginfo, quick, detailed
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
// Enable Debug Options to be specified on the command line
|
2002-07-25 19:27:01 +00:00
|
|
|
cl::opt<DebugLev> DebugLevel("<i>debug_level</i>", cl::desc("<i>Set the debugging level:</i>"),
|
|
|
|
|
cl::values(
|
|
|
|
|
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));
|
2001-07-23 23:03:12 +00:00
|
|
|
</pre>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
This definition defines an enumerated command line variable of type "<tt>enum
|
|
|
|
|
DebugLev</tt>", which works exactly the same way as before. The difference here
|
|
|
|
|
is just the interface exposed to the user of your program and the help output by
|
|
|
|
|
the "<tt>--help</tt>" option:<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<pre>
|
2002-07-25 19:27:01 +00:00
|
|
|
USAGE: compiler [options] <input file>
|
|
|
|
|
|
2001-07-23 23:03:12 +00:00
|
|
|
OPTIONS:
|
2002-07-25 19:27:01 +00:00
|
|
|
Choose optimization level:
|
|
|
|
|
-g - No optimizations, enable debugging
|
|
|
|
|
-O1 - Enable trivial optimizations
|
|
|
|
|
-O2 - Enable default optimizations
|
|
|
|
|
-O3 - Enable expensive optimizations
|
|
|
|
|
-debug_level - Set the debugging level:
|
|
|
|
|
=none - disable debug information
|
|
|
|
|
=quick - enable quick debug information
|
|
|
|
|
=detailed - enable detailed debug information
|
|
|
|
|
-f - Overwrite output files
|
|
|
|
|
-help - display available options (--help-hidden for more)
|
|
|
|
|
-o <filename> - Specify output filename
|
|
|
|
|
-quiet - Don't print informational messages
|
2001-07-23 23:03:12 +00:00
|
|
|
</pre><p>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
Again, the only structural difference between the debug level declaration and
|
|
|
|
|
the optimiation 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>
|
|
|
|
|
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ======================================================================= -->
|
|
|
|
|
</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%"> <font color="#EEEEFF" face="Georgia,Palatino"><b>
|
2002-07-25 19:27:01 +00:00
|
|
|
<a name="list">Parsing a list of options
|
2001-07-23 23:03:12 +00:00
|
|
|
</b></font></td></tr></table><ul>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
Now that we have the standard run of the mill argument types out of the way,
|
|
|
|
|
lets get a little wild and crazy. Lets say that we want our optimizer to accept
|
|
|
|
|
a <b>list</b> of optimizations to perform, allowing duplicates. For example, we
|
|
|
|
|
might want to run: "<tt>compiler -dce -constprop -inline -dce -strip</tt>". In
|
|
|
|
|
this case, the order of the arguments and the number of appearances is very
|
|
|
|
|
important. This is what the "<tt>cl::list</tt>" template is for. First,
|
|
|
|
|
start by defining an enum of the optimizations that you would like to
|
|
|
|
|
perform:<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
enum Opts {
|
2002-07-25 19:27:01 +00:00
|
|
|
// 'inline' is a C++ keyword, so name it 'inlining'
|
2001-07-23 23:03:12 +00:00
|
|
|
dce, constprop, inlining, strip
|
2002-07-25 19:27:01 +00:00
|
|
|
};
|
2001-07-23 23:03:12 +00:00
|
|
|
</pre><p>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
Then define your "<tt>cl::list</tt>" variable:<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<pre>
|
2002-07-25 19:27:01 +00:00
|
|
|
cl::list<Opts> OptimizationList(cl::desc("<i>Available Optimizations:</i>"),
|
|
|
|
|
cl::values(
|
|
|
|
|
clEnumVal(dce , "<i>Dead Code Elimination</i>"),
|
|
|
|
|
clEnumVal(constprop , "<i>Constant Propogation</i>"),
|
|
|
|
|
clEnumValN(inlining, "<i>inline</i>", "<i>Procedure Integration</i>"),
|
|
|
|
|
clEnumVal(strip , "<i>Strip Symbols</i>"),
|
|
|
|
|
0));
|
2001-07-23 23:03:12 +00:00
|
|
|
</pre><p>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
This defines a variable that is conceptually of the type
|
|
|
|
|
"<tt>std::vector<enum Opts></tt>". Thus, you can access it with standard
|
|
|
|
|
vector methods:<p>
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
<pre>
|
2002-07-25 19:27:01 +00:00
|
|
|
for (unsigned i = 0; i != OptimizationList.size(); ++i)
|
2001-07-23 23:03:12 +00:00
|
|
|
switch (OptimizationList[i])
|
|
|
|
|
...
|
|
|
|
|
</pre>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
... to iterate through the list of options specified.<p>
|
2002-04-13 18:35:59 +00:00
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
Note that the "<tt>cl::list</tt>" template is completely general and may be used
|
|
|
|
|
with any data types or other arguments that you can use with the
|
|
|
|
|
"<tt>cl::opt</tt>" template. One especially useful way to use a list is to
|
|
|
|
|
capture all of the positional arguments together if there may be more than one
|
|
|
|
|
specified. In the case of a linker, for example, the linker takes several
|
|
|
|
|
'<tt>.o</tt>' files, and needs to capture them into a list. This is naturally
|
|
|
|
|
specified as:<p>
|
2002-04-13 18:35:59 +00:00
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
...
|
2002-07-25 19:27:01 +00:00
|
|
|
cl::list<std::string> InputFilenames(cl::Positional, cl::desc("<Input files>"), cl::OneOrMore);
|
2002-04-13 18:35:59 +00:00
|
|
|
...
|
|
|
|
|
</pre><p>
|
|
|
|
|
|
2002-07-25 19:27:01 +00:00
|
|
|
This variable works just like a "<tt>vector<string></tt>" object. As
|
|
|
|
|
such, accessing the list is simple, just like above. In this example, we used
|
|
|
|
|
the <tt>cl::OneOrMore</tt> modifier to inform the CommandLine library that it is
|
|
|
|
|
an error if the user does not specify any <tt>.o</tt> files on our command line.
|
|
|
|
|
Again, this just reduces the amount of checking we have to do.<p>
|
2002-04-13 18:35:59 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2001-07-23 23:03:12 +00:00
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0><tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
|
|
|
|
|
<a name="referenceguide">Reference Guide
|
|
|
|
|
</b></font></td></tr></table><ul>
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
Reference Guide: TODO
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0><tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
|
|
|
|
|
<a name="extensionguide">Extension Guide
|
|
|
|
|
</b></font></td></tr></table><ul>
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
|
2002-04-13 18:35:59 +00:00
|
|
|
Look at the examples classes provided. This section is a TODO.
|
2001-07-23 23:03:12 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
</ul>
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
<hr>
|
|
|
|
|
<font size=-1>
|
|
|
|
|
<address><a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
|
|
|
|
|
<!-- Created: Tue Jan 23 15:19:28 CST 2001 -->
|
|
|
|
|
<!-- hhmts start -->
|
2002-07-25 19:27:01 +00:00
|
|
|
Last modified: Thu Jul 25 14:25:50 CDT 2002
|
2001-07-23 23:03:12 +00:00
|
|
|
<!-- hhmts end -->
|
|
|
|
|
</font>
|
|
|
|
|
</body></html>
|
