| Index: tools/nixysa/third_party/gflags-1.0/doc/gflags.html
|
| ===================================================================
|
| --- tools/nixysa/third_party/gflags-1.0/doc/gflags.html (revision 0)
|
| +++ tools/nixysa/third_party/gflags-1.0/doc/gflags.html (revision 0)
|
| @@ -0,0 +1,495 @@
|
| +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
| +
|
| +<html>
|
| +<head>
|
| +<title>How To Use Google Commandline Flags</title>
|
| +
|
| +<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
| +<link href="http://www.google.com/favicon.ico" type="image/x-icon"
|
| + rel="shortcut icon">
|
| +<link href="designstyle.css" type="text/css" rel="stylesheet">
|
| +<style type="text/css">
|
| +<!--
|
| + ol.bluelist li {
|
| + color: #3366ff;
|
| + font-family: sans-serif;
|
| + }
|
| + ol.bluelist li p {
|
| + color: #000;
|
| + font-family: "Times Roman", times, serif;
|
| + }
|
| + ul.blacklist li {
|
| + color: #000;
|
| + font-family: "Times Roman", times, serif;
|
| + }
|
| +//-->
|
| +</style>
|
| +</head>
|
| +
|
| +<body>
|
| +
|
| +<h1>How To Use Google Commandline Flags (gflags)</h1>
|
| +<small>(as of
|
| +<script type=text/javascript>
|
| + var lm = new Date(document.lastModified);
|
| + document.write(lm.toDateString());
|
| +</script>)
|
| +</small>
|
| +<br>
|
| +
|
| +
|
| +<h2> <A NAME=intro>Introduction, and Comparison to Other Commandline
|
| + Flags Libraries</A> </h2>
|
| +
|
| +<p><b>Commandline flags</b> are flags that users specify on the
|
| +command line when they run an executable. In the command</p>
|
| +<pre>
|
| + fgrep -l -f /var/tmp/foo johannes brahms
|
| +</pre>
|
| +<p><code>-l</code> and <code>-f /var/tmp/foo</code> are the two
|
| +commandline flags. (<code>johannes</code> and <code>brahms</code>,
|
| +which don't start with a dash, are <b>commandline arguments</b>.)</p>
|
| +
|
| +<p>Typically, an application lists what flags the user is allowed to
|
| +pass in, and what arguments they take -- in this example,
|
| +<code>-l</code> takes no argument, and <code>-f</code> takes a
|
| +string (in particular, a filename) as an argument. Users can use a
|
| +library to help parse the commandline and store the flags in some data
|
| +structure.</p>
|
| +
|
| +<p>Google's commandline flags library differs from other libraries,
|
| +such as <code>getopt()</code>, in that flag definitions can be
|
| +scattered around the source code, and not just listed in one place
|
| +such as <code>main()</code>. In practice, this means that a single
|
| +source-code file will define and use flags that are meaningful to that
|
| +file. Any application that links in that file will get the flags, and
|
| +the google commandline flags library will automatically handle that
|
| +flag appropriately.</p>
|
| +
|
| +<p>There's significant gain in flexibility, and ease of code reuse,
|
| +due to this technique. However, there is a danger that two files will
|
| +define the same flag, and then give an error when they're linked
|
| +together.</p>
|
| +
|
| +<p>The rest of this document describes how to use the commandlineflag
|
| +library. It's a C++ library, so examples are in C++. However, there
|
| +is a Python port with the same functionality, and this discussion
|
| +translates directly to Python.</p>
|
| +
|
| +
|
| +<h2> <A name=define>DEFINE: Defining Flags In Program</A> </h2>
|
| +
|
| +<p> Defining a flag is easy: just use the appropriate macro for the
|
| +type you want the flag to be, as defined at the bottom of
|
| +<code>gflags/gflags.h</code>. Here's an example file,
|
| +<code>foo.cc</code>:</p>
|
| +
|
| +<pre>
|
| + #include <gflags/gflags.h>
|
| +
|
| + DEFINE_bool(big_menu, true, "Include 'advanced' options in the menu listing");
|
| + DEFINE_string(languages, "english,french,german",
|
| + "comma-separated list of languages to offer in the 'lang' menu");
|
| +</pre>
|
| +
|
| +<p><code>DEFINE_bool</code> defines a boolean flag. Here are the
|
| +types supported:</p>
|
| +<ul>
|
| + <li> <code>DEFINE_bool</code>: boolean
|
| + <li> <code>DEFINE_int32</code>: 32-bit integer
|
| + <li> <code>DEFINE_int64</code>: 64-bit integer
|
| + <li> <code>DEFINE_uint64</code>: unsigned 64-bit integer
|
| + <li> <code>DEFINE_double</code>: double
|
| + <li> <code>DEFINE_string</code>: C++ string
|
| +</ul>
|
| +
|
| +<p>Note that there are no 'complex' types like lists: the "languages"
|
| +flag in our example is a list of strings, but is defined of type
|
| +"string", not "list_of_string" or similar. This is by design. We'd
|
| +rather use only simple types for the flags, and allow for complex,
|
| +arbitrary parsing routines to parse them, then to try to put the logic
|
| +inside the flags library proper.</p>
|
| +
|
| +<p>All DEFINE macros take the same three arguments: the name of the
|
| +flag, its default value, and a 'help' string that describes its use.
|
| +The 'help' string is displayed when the user runs the application with
|
| +the <A HREF="#special"><code>--help</code> flag</A>.</p>
|
| +
|
| +<p>You can define a flag in any source-code file in your executable.
|
| +Only define a flag once! If you want to access a flag in more than
|
| +one source file, DEFINE it in one file, and <A
|
| +HREF="#declare">DECLARE</A> it in the others. Even better, DEFINE it
|
| +in <code>foo.cc</code> and DECLARE it in <code>foo.h</code>; then
|
| +everyone who <code>#includes foo.h</code> can use the flag.</p>
|
| +
|
| +<p>Note that while most functions in this library are defined in the
|
| +<code>google</code> namespace, <code>DEFINE_foo</code> (and
|
| +<code>DECLARE_foo</code>, <A HREF="#declare">below</A>), should always
|
| +be in the global namespace.</p>
|
| +
|
| +
|
| +<h2> <A name=using>Accessing the Flag</A> </h2>
|
| +
|
| +<p>All defined flags are available to the program as just a normal
|
| +variable, with the prefix <code>FLAGS_</code> prepended. In the above
|
| +example, the macros define two variables, <code>FLAGS_big_menu</code>
|
| +(a bool), and <code>FLAGS_languages</code> (a C++ string).</p>
|
| +
|
| +<p>You can read and write to the flag just like any other
|
| +variable:</p>
|
| +<pre>
|
| + if (FLAGS_consider_made_up_languages)
|
| + FLAGS_languages += ",klingon"; // implied by --consider_made_up_languages
|
| + if (FLAGS_languages.find("finnish") != string::npos)
|
| + HandleFinnish();
|
| +</pre>
|
| +
|
| +<p>You can also get and set flag values via special functions in
|
| +<code>gflags.h</code>. That's a rarer use case, though.</p>
|
| +
|
| +
|
| +<h2> <A name=declare>DECLARE: Using the Flag in a Different File</A> </h2>
|
| +
|
| +<p>Accessing a flag in the manner of the previous section only works
|
| +if the flag was <code>DEFINE</code>-ed at the top of the file. If it
|
| +wasn't, you'll get an 'unknown variable' error.</p>
|
| +
|
| +<p>The <code>DECLARE_type</code> macro is available when you want to
|
| +use a flag that's defined in another file. For instance, if I were
|
| +writing <code>bar.cc</code> but wanted to access the big_menu, flag, I
|
| +would put this near the top of <code>bar.cc</code>:</p>
|
| +<pre>
|
| + DECLARE_bool(big_menu);
|
| +</pre>
|
| +
|
| +<p>This is functionally equivalent to saying <code>extern
|
| +FLAGS_big_menu</code>.</p>
|
| +
|
| +<p>Note that such an extern declaration introduces a dependency
|
| +between your file and the file that defines the <code>big_menu</code>
|
| +flag: <code>foo.cc</code>, in this case. Such implicit dependencies
|
| +can be difficult to manage in large projects. For that reason we
|
| +recommend the following guideline:</p>
|
| +
|
| +<blockquote>
|
| +If you DEFINE a flag in <code>foo.cc</code>, either don't DECLARE it
|
| +at all, only DECLARE it in tightly related tests, or only DECLARE
|
| +it in <code>foo.h</code>.
|
| +</blockquote>
|
| +
|
| +<p>You should go the do-not-DECLARE route when the flag is only needed
|
| +by <code>foo.cc</code>, and not in any other file. If you want to
|
| +modify the value of the flag in the related test file to see if it is
|
| +functioning as expected, DECLARE it in the <code>foo_test.cc</code>
|
| +file.
|
| +
|
| +<p>If the flag does span multiple files, DECLARE it in the associated
|
| +<code>.h</code> file, and make others <code>#include</code> that
|
| +<code>.h</code> file if they want to access the flag. The
|
| +<code>#include</code> will make explicit the dependency between the
|
| +two files. This causes the flag to be a global variable.</p>
|
| +
|
| +
|
| +<h2> <A name=validate>RegisterFlagValidator: Sanity-checking Flag Values</A> </h2>
|
| +
|
| +<p>After DEFINE-ing a flag, you may optionally register a validator
|
| +function with the flag. If you do this, after the flag is parsed from
|
| +the commandline, and whenever its value is changes via a call to
|
| +<code>SetCommandLineOption()</code>, the validator function is called
|
| +with the new value as an argument. The validator function should
|
| +return 'true' if the flag value is valid, and false otherwise.
|
| +
|
| +<p>Here is an example use of this functionality:</p>
|
| +<pre>
|
| +static bool ValidatePort(const char* flagname, int32 value) {
|
| + if (value > 0 && value < 32768) // value is ok
|
| + return true;
|
| + printf("Invalid value for --%s: %d\n", flagname, (int)value);
|
| + return false;
|
| +}
|
| +DEFINE_int32(port, 0, "What port to listen on");
|
| +static const bool port_dummy = RegisterFlagValidator(&FLAGS_port, &ValidatePort);
|
| +</pre>
|
| +
|
| +<p>By doing the registration at global initialization time (right
|
| +after the DEFINE), we ensure that the registration happens before
|
| +the commandline is parsed at the beginning of <code>main()</code>.</p>
|
| +
|
| +<p><code>RegisterFlagValidator()</code> returns true if the
|
| +registration is successful. It return false if the registration fails
|
| +because a) the first argument does not refer to a commandline flag, or
|
| +b) a different validator has already been registered for this flag.</p>
|
| +
|
| +
|
| +<h2> <A name=together>Putting It Together: How to Set Up Flags</A> </h2>
|
| +
|
| +<p>The final piece is the one that tells the executable to process the
|
| +commandline flags, and set the <code>FLAGS_*</code> variables to the
|
| +appropriate, non-default value based on what is seen on the
|
| +commandline. This is equivalent to the <code>getopt()</code> call in
|
| +the getopt library, but has much less overhead to use. In fact, it's
|
| +just a single function call:</p>
|
| +
|
| +<pre>
|
| + google::ParseCommandLineFlags(&argc, &argv, true);
|
| +</pre>
|
| +
|
| +<p>Usually, this code is at the beginning of <code>main()</code>.
|
| +<code>argc</code> and <code>argv</code> are exactly as passed in to
|
| +<code>main()</code>. This routine might modify them, which is why
|
| +pointers to them are passed in.</p>
|
| +
|
| +<p>The last argument is called "remove_flags". If true, then
|
| +<code>ParseCommandLineFlags</code> removes the flags and their
|
| +arguments from <code>argv</code>, and modifies <code>argc</code>
|
| +appropriately. In this case, after the function call,
|
| +<code>argv</code> will hold only commandline arguments, and not
|
| +commandline flags.</p>
|
| +
|
| +<p>If, on the other hand, <code>remove_flags</code> is false, then
|
| +<code>ParseCommandLineFlags</code> will leave argc unchanged, but will
|
| +rearrange the arguments in argv so that the flags are all at the
|
| +beginning. For example, if the input is <code>"/bin/foo" "arg1" "-q"
|
| +"arg2"</code> (which is legal but weird), the function will rearrange
|
| +<code>argv</code> so it reads <code>"/bin/foo", "-q", "arg1",
|
| +"arg2"</code>. In this case, <code>ParseCommandLineFlags</code>
|
| +returns the index into argv that holds the first commandline argument:
|
| +that is, the index past the last flag. (In this example, it would
|
| +return 2, since <code>argv[2]</code> points to <code>arg1</code>.)</p>
|
| +
|
| +<p>In either case, the <code>FLAGS_*</code> variables are modified
|
| +based on what was <A HREF="#commandline">passed in on the
|
| +commandline</A>.</p>
|
| +
|
| +
|
| +<h2> <A name=commandline>Setting Flags on the Command Line</A> </h2>
|
| +
|
| +<p>The reason you make something a flag instead of a compile-time
|
| +constant, is so users can specify a non-default value on the
|
| +commandline. Here's how they might do it for an application that
|
| +links in <code>foo.cc</code>:</p>
|
| +<pre>
|
| + app_containing_foo --nobig_menu -languages="chinese,japanese,korean" ...
|
| +</pre>
|
| +
|
| +<p>This sets <code>FLAGS_big_menu = false;</code> and
|
| +<code>FLAGS_languages = "chinese,japanese,korean"</code>, when
|
| +<code>ParseCommandLineFlags</code> is run.</p>
|
| +
|
| +<p>Note the atypical syntax for setting a boolean flag to false:
|
| +putting "no" in front of its name. There's a fair bit of flexibility
|
| +to how flags may be specified. Here's an example of all the ways to
|
| +specify the "languages" flag:</p>
|
| +<ul>
|
| + <li> <code>app_containing_foo --languages="chinese,japanese,korean"</code>
|
| + <li> <code>app_containing_foo -languages="chinese,japanese,korean"</code>
|
| + <li> <code>app_containing_foo --languages "chinese,japanese,korean"</code>
|
| + <li> <code>app_containing_foo -languages "chinese,japanese,korean"</code>
|
| +</ul>
|
| +
|
| +<p>For boolean flags, the possibilities are slightly different:</p>
|
| +<ul>
|
| + <li> <code>app_containing_foo --big_menu</code>
|
| + <li> <code>app_containing_foo --nobig_menu</code>
|
| + <li> <code>app_containing_foo --big_menu=true</code>
|
| + <li> <code>app_containing_foo --big_menu=false</code>
|
| +</ul>
|
| +<p>(as well as the single-dash variant on all of these).</p>
|
| +
|
| +<p>Despite this flexibility, we recommend using only a single form:
|
| +<code>--variable=value</code> for non-boolean flags, and
|
| +<code>--variable/--novariable</code> for boolean flags. This
|
| +consistency will make your code more readable, and is also the format
|
| +required for certain special-use cases like <A
|
| +HREF="#flagfiles">flagfiles</A>.</p>
|
| +
|
| +<p>It is a fatal error to specify a flag on the commandline that has
|
| +not been DEFINED somewhere in the executable. If you need that
|
| +functionality for some reason -- say you want to use the same set of
|
| +flags for several executables, but not all of them DEFINE every flag
|
| +in your list -- you can specify <A
|
| +HREF="#special"><code>--undefok</code></A> to suppress the error.</p>
|
| +
|
| +<p>As in getopt(), <code>--</code> by itself will terminate flags
|
| +processing. So in <code>foo -f1 1 -- -f2 2</code>, <code>f1</code> is
|
| +considered a flag, but <code>-f2</code> is not.</p>
|
| +
|
| +<p>Note that flags do not have single-letter synonyms, like they do in
|
| +the getopt library, nor do we allow "combining" flags behind a
|
| +single dash, as in <code>ls -la</code>.</p>
|
| +
|
| +
|
| +<h2> <A name="special">Special Flags</code> </h2>
|
| +
|
| +<p>There are a few flags defined by the commandlineflags module
|
| +itself, and are available to all applications. These fall into three
|
| +categories. First are the 'reporting' flags that, when found, cause
|
| +the application to print some information about itself and exit.</p>
|
| +
|
| +<table><tr valign=top>
|
| + <td><code>--help</code></td>
|
| + <td>shows all flags from all files, sorted by file and then by name;
|
| + shows the flagname, its default value, and its help string</td>
|
| +</tr><tr valign=top>
|
| + <td><code>--helpfull</code></td>
|
| + <td>same as -help, but unambiguously asks for all flags
|
| + (in case -help changes in the future)</td>
|
| +</tr><tr valign=top>
|
| + <td><code>--helpshort</code></td>
|
| + <td>shows only flags for the file that includes <code>main()</code></td>
|
| +</tr><tr valign=top>
|
| + <td><code>--helpxml</code></td>
|
| + <td>like --help, but output is in xml for easier parsing</td>
|
| +</tr><tr valign=top>
|
| + <td><code>--helpon=FILE </code></td>
|
| + <td>shows only flags defined in FILE.*</td>
|
| +</tr><tr valign=top>
|
| + <td><code>--helpmatch=S</code></td>
|
| + <td>shows only flags defined in *S*.*</td>
|
| +</tr><tr valign=top>
|
| + <td><code>--helppackage</code></td>
|
| + <td>shows flags defined in files in same directory as <code>main()</code></td>
|
| +</tr><tr valign=top>
|
| + <td><code>--version</code></td>
|
| + <td>prints version info for the executable</td>
|
| +</tr></table>
|
| +
|
| +<p>Second are the flags that affect how other flags are parsed.</p>
|
| +
|
| +<table><tr valign=top>
|
| + <td><code>--undefok=flagname,flagname,...</code></td>
|
| + <td>for those names listed as the argument to <code>--undefok</code>,
|
| + suppress the normal error-exit that occurs when
|
| + <code>--name</code> is seen on the commandline, but
|
| + <code>name</code> has not been DEFINED anywhere in the
|
| + application
|
| +</table>
|
| +
|
| +<p>Third are the 'recursive' flags, that cause other flag values to be
|
| +set: <code>--fromenv</code>, <code>--tryfromenv</code>,
|
| +<code>--flagfile</code>. These are described below in more
|
| +detail.</p>
|
| +
|
| +<h3> <code>--fromenv</code> </h3>
|
| +
|
| +<p><code>--fromenv=foo,bar</code> says to read the values for the
|
| +<code>foo</code> and <code>bar</code> flags from the environment.
|
| +In concert with this flag, you must actually set the values in the
|
| +environment, via a line like one of the two below:</p>
|
| +<pre>
|
| + export FLAGS_foo=xxx; export FLAGS_bar=yyy # sh
|
| + setenv FLAGS_foo xxx; setenv FLAGS_bar yyy # tcsh
|
| +</pre>
|
| +<p>This is equivalent to specifying <code>--foo=xxx</code>,
|
| +<code>--bar=yyy</code> on the commandline.</p>
|
| +
|
| +<p>Note it is a fatal error to say <code>--fromenv=foo</code> if
|
| +<code>foo</code> is not DEFINED somewhere in the application. (Though
|
| +you can suppress this error via <code>--undefok=foo</code>, just like
|
| +for any other flag.)</p>
|
| +
|
| +<p>It is also a fatal error to say <code>--fromenv=foo</code> if
|
| +<code>FLAGS_foo</code> is not actually defined in the environment.</p>
|
| +
|
| +<h3> <code>--tryfromenv</code> </h3>
|
| +
|
| +<p><code>--tryfromenv</code> is exactly like <code>--fromenv</code>,
|
| +except it is <b>not</b> a fatal error to say
|
| +<code>--tryfromenv=foo</code> if <code>FLAGS_foo</code> is not
|
| +actually defined in the environment. Instead, in such cases,
|
| +<code>FLAGS_foo</code> just keeps its default value as specified in
|
| +the application.</p>
|
| +
|
| +<p>Note it is still an error to say <code>--tryfromenv=foo</code> if
|
| +<code>foo</code> is not DEFINED somewhere in the application.</p>
|
| +
|
| +<h3> <code>--flagfile</code> </h3>
|
| +
|
| +<p><code>--flagfile=f</code> tells the commandlineflags module to read
|
| +the file <code>f</code>, and to run all the flag-assignments found in
|
| +that file as if these flags had been specified on the commandline.</p>
|
| +
|
| +<p>In its simplest form, <code>f</code> should just be a list of flag
|
| +assignments, one per line. Unlike on the commandline, the equals sign
|
| +separating a flagname from its argument is <i>required</i> for
|
| +flagfiles. An example flagfile, <code>/tmp/myflags</code>:</p>
|
| +<pre>
|
| +--nobig_menus
|
| +--languages=english,french
|
| +</pre>
|
| +
|
| +<p>With this flagfile, the following two lines are equivalent:<p>
|
| +<pre>
|
| + ./myapp --foo --nobig_menus --languages=english,french --bar
|
| + ./myapp --foo --flagfile=/tmp/myflags --bar
|
| +</pre>
|
| +
|
| +<p>Note that many errors are silently suppressed in flagfiles. In
|
| +particular, unrecognized flagnames are silently ignored, as are flags
|
| +that are missing a required value (e.g., a flagfile that just says
|
| +<code>--languages</code>).</p>
|
| +
|
| +<p>The general format of a flagfile is a bit more complicated than the
|
| +simple, common case above. It is: a sequence of filenames, one per
|
| +line, followed by a sequence of flags, one per line, repeated as many
|
| +times as desired. Filenames in a flagfile can use wildcards
|
| +(<code>*</code> and <code>?</code>), and the sequence of flags located
|
| +after a sequence of filenames is processed only if the current
|
| +executable's name matches one of the filenames. It is possible to
|
| +start the flagfile with a sequence of flags instead of a sequence of
|
| +filenames; if such a sequence of flags is present, these flags are
|
| +applied to the current executable no matter what it is.</p>
|
| +
|
| +<p>Lines that start with a <code>#</code> are ignored as comments.
|
| +Leading whitespace is also ignored in flagfiles, as are blank
|
| +lines.</p>
|
| +
|
| +<p>It is possible for a flagfile to use the <code>--flagfile</code>
|
| +flag to include another flagfile.</p>
|
| +
|
| +<p>Flags are always processed in the expected order. That is,
|
| +processing begins by examining the flags specified directly on the
|
| +command line. If a flagfile is specified, its contents are processed,
|
| +and then processing continues with remaining flags from the command
|
| +line.</p>
|
| +
|
| +
|
| +<h2> <A name="api">The API</code> </h2>
|
| +
|
| +<p>In addition to accessing <code>FLAGS_foo</code> directly, it is
|
| +possible to access the flags programmatically, through an API. It is
|
| +also possible to access information about a flag, such as its default
|
| +value and help-string. A <code>FlagSaver</code> makes it easy to
|
| +modify flags and then automatically undo the modifications later.
|
| +Finally, there are somewhat unrelated, but useful, routines to easily
|
| +access parts of <code>argv</code> outside main, including the program
|
| +name (<code>argv[0]</code>).</p>
|
| +
|
| +<p>For more information about these routines, and other useful helper
|
| +methods such as <code>google::SetUsageMessage</code>, see
|
| +<code>gflags.h</code>.</p>
|
| +
|
| +
|
| +<h2> <A name="misc">Miscellaneous Notes</code> </h2>
|
| +
|
| +<p>If your application has code like this:</p>
|
| +<pre>
|
| + #define STRIP_FLAG_HELP 1 // this must go before the #include!
|
| + #include <gflags/gflags.h>
|
| +</pre>
|
| +<p>we will remove the help messages from the compiled source. This can
|
| +reduce the size of the resulting binary somewhat, and may also be
|
| +useful for security reasons.</p>
|
| +
|
| +
|
| +<hr>
|
| +<address>
|
| +Craig Silverstein<br>
|
| +<script type=text/javascript>
|
| + var lm = new Date(document.lastModified);
|
| + document.write(lm.toDateString());
|
| +</script>
|
| +</address>
|
| +
|
| +</body>
|
| +</html>
|
|
|
| Property changes on: tools/nixysa/third_party/gflags-1.0/doc/gflags.html
|
| ___________________________________________________________________
|
| Added: svn:eol-style
|
| + LF
|
|
|
|
|
Chromium Code Reviews
