github.com/jlmucb/cloudproxy@v0.0.0-20170830161738-b5aa0b619bc4/src/third_party/gflags/doc/.svn/text-base/gflags.html.svn-base (about) 1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> 2 3 <html> 4 <head> 5 <title>How To Use Gflags (formerly Google Commandline Flags)</title> 6 7 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 8 <link href="designstyle.css" type="text/css" rel="stylesheet"> 9 <style type="text/css"> 10 <!-- 11 ol.bluelist li { 12 color: #3366ff; 13 font-family: sans-serif; 14 } 15 ol.bluelist li p { 16 color: #000; 17 font-family: "Times Roman", times, serif; 18 } 19 ul.blacklist li { 20 color: #000; 21 font-family: "Times Roman", times, serif; 22 } 23 //--> 24 </style> 25 </head> 26 27 <body> 28 29 <h1>How To Use Gflags (formerly Google Commandline Flags)</h1> 30 <small>(as of 31 <script type=text/javascript> 32 var lm = new Date(document.lastModified); 33 document.write(lm.toDateString()); 34 </script>) 35 </small> 36 <br> 37 38 <blockquote><dl> 39 <dt> Table of contents </dt> 40 <dd> <a href="#intro">Introduction</a> </dd> 41 <dd> <a href="#define">DEFINE: Defining Flags In Program</A> </dd> 42 <dd> <a href="#using">Accessing the Flag</A> </dd> 43 <dd> <a href="#declare">DECLARE: Using the Flag in a Different File</a> </dd> 44 <dd> <a href="#validate">RegisterFlagValidator: Sanity-checking Flag Values</a> </dd> 45 <dd> <a href="#together">Putting It Together: How to Set Up Flags</a> </dd> 46 <dd> <a href="#commandline">Setting Flags on the Command Line</a> </dd> 47 <dd> <a href="#varz">Setting Flags at Runtime</a> </dd> 48 <dd> <a href="#default">Changing the Default Flag Value</a> </dd> 49 <dd> <a href="#special">Special Flags</a> </dd> 50 <dd> <a href="#api">The API</a> </dd> 51 <dd> <br/> </dd> 52 </dl></blockquote> 53 54 <h2> <A NAME=intro>Introduction, and Comparison to Other Commandline 55 Flags Libraries</A> </h2> 56 57 <p><b>Commandline flags</b> are flags that users specify on the 58 command line when they run an executable. In the command</p> 59 <pre> 60 fgrep -l -f /var/tmp/foo johannes brahms 61 </pre> 62 <p><code>-l</code> and <code>-f /var/tmp/foo</code> are the two 63 commandline flags. (<code>johannes</code> and <code>brahms</code>, 64 which don't start with a dash, are <b>commandline arguments</b>.)</p> 65 66 <p>Typically, an application lists what flags the user is allowed to 67 pass in, and what arguments they take -- in this example, 68 <code>-l</code> takes no argument, and <code>-f</code> takes a 69 string (in particular, a filename) as an argument. Users can use a 70 library to help parse the commandline and store the flags in some data 71 structure.</p> 72 73 <p>Gflags, the commandline flags library used within Google, 74 differs from other libraries, 75 such as <code>getopt()</code>, in that flag definitions can be 76 scattered around the source code, and not just listed in one place 77 such as <code>main()</code>. In practice, this means that a single 78 source-code file will define and use flags that are meaningful to that 79 file. Any application that links in that file will get the flags, and 80 the gflags library will automatically handle that 81 flag appropriately.</p> 82 83 <p>There's significant gain in flexibility, and ease of code reuse, 84 due to this technique. However, there is a danger that two files will 85 define the same flag, and then give an error when they're linked 86 together.</p> 87 88 <p>The rest of this document describes how to use the commandlineflag 89 library. It's a C++ library, so examples are in C++. However, there 90 is a Python port with the same functionality, and this discussion 91 translates directly to Python.</p> 92 93 94 <h2> <A name=define>DEFINE: Defining Flags In Program</A> </h2> 95 96 <p> Defining a flag is easy: just use the appropriate macro for the 97 type you want the flag to be, as defined at the bottom of 98 <code>gflags/gflags.h</code>. Here's an example file, 99 <code>foo.cc</code>:</p> 100 101 <pre> 102 #include <gflags/gflags.h> 103 104 DEFINE_bool(big_menu, true, "Include 'advanced' options in the menu listing"); 105 DEFINE_string(languages, "english,french,german", 106 "comma-separated list of languages to offer in the 'lang' menu"); 107 </pre> 108 109 <p><code>DEFINE_bool</code> defines a boolean flag. Here are the 110 types supported:</p> 111 <ul> 112 <li> <code>DEFINE_bool</code>: boolean 113 <li> <code>DEFINE_int32</code>: 32-bit integer 114 <li> <code>DEFINE_int64</code>: 64-bit integer 115 <li> <code>DEFINE_uint64</code>: unsigned 64-bit integer 116 <li> <code>DEFINE_double</code>: double 117 <li> <code>DEFINE_string</code>: C++ string 118 </ul> 119 120 <p>Note that there are no 'complex' types like lists: the "languages" 121 flag in our example is a list of strings, but is defined of type 122 "string", not "list_of_string" or similar. This is by design. We'd 123 rather use only simple types for the flags, and allow for complex, 124 arbitrary parsing routines to parse them, than to try to put the logic 125 inside the flags library proper.</p> 126 127 <p>All DEFINE macros take the same three arguments: the name of the 128 flag, its default value, and a 'help' string that describes its use. 129 The 'help' string is displayed when the user runs the application with 130 the <A HREF="#special"><code>--help</code> flag</A>.</p> 131 132 <p>You can define a flag in any source-code file in your executable. 133 Only define a flag once! If you want to access a flag in more than 134 one source file, DEFINE it in one file, and <A 135 HREF="#declare">DECLARE</A> it in the others. Even better, DEFINE it 136 in <code>foo.cc</code> and DECLARE it in <code>foo.h</code>; then 137 everyone who <code>#includes foo.h</code> can use the flag.</p> 138 139 <p> 140 Defining flags in libraries rather than in main() is powerful, but 141 does have some costs. One is that a library might not have a good 142 default value for its flags, for example if the flag holds a 143 filename that might not exist in some environments. To mitigate such problems, 144 you can use <a href="#validate">flag validators</a> to ensure prompt 145 notification (in the form of a crash) of an invalid flag value. 146 </p> 147 148 <p>Note that while most functions in this library are defined in the 149 <code>google</code> namespace, <code>DEFINE_foo</code> (and 150 <code>DECLARE_foo</code>, <A HREF="#declare">below</A>), should always 151 be in the global namespace.</p> 152 153 154 <h2> <A name=using>Accessing the Flag</A> </h2> 155 156 <p>All defined flags are available to the program as just a normal 157 variable, with the prefix <code>FLAGS_</code> prepended. In the above 158 example, the macros define two variables, <code>FLAGS_big_menu</code> 159 (a bool), and <code>FLAGS_languages</code> (a C++ string).</p> 160 161 <p>You can read and write to the flag just like any other 162 variable:</p> 163 <pre> 164 if (FLAGS_consider_made_up_languages) 165 FLAGS_languages += ",klingon"; // implied by --consider_made_up_languages 166 if (FLAGS_languages.find("finnish") != string::npos) 167 HandleFinnish(); 168 </pre> 169 170 <p>You can also get and set flag values via special functions in 171 <code>gflags.h</code>. That's a rarer use case, though.</p> 172 173 174 <h2> <A name=declare>DECLARE: Using the Flag in a Different File</A> </h2> 175 176 <p>Accessing a flag in the manner of the previous section only works 177 if the flag was <code>DEFINE</code>-ed at the top of the file. If it 178 wasn't, you'll get an 'unknown variable' error.</p> 179 180 <p>The <code>DECLARE_type</code> macro is available when you want to 181 use a flag that's defined in another file. For instance, if I were 182 writing <code>bar.cc</code> but wanted to access the big_menu, flag, I 183 would put this near the top of <code>bar.cc</code>:</p> 184 <pre> 185 DECLARE_bool(big_menu); 186 </pre> 187 188 <p>This is functionally equivalent to saying <code>extern 189 FLAGS_big_menu</code>.</p> 190 191 <p>Note that such an extern declaration introduces a dependency 192 between your file and the file that defines the <code>big_menu</code> 193 flag: <code>foo.cc</code>, in this case. Such implicit dependencies 194 can be difficult to manage in large projects. For that reason we 195 recommend the following guideline:</p> 196 197 <blockquote> 198 If you DEFINE a flag in <code>foo.cc</code>, either don't DECLARE it 199 at all, only DECLARE it in tightly related tests, or only DECLARE 200 it in <code>foo.h</code>. 201 </blockquote> 202 203 <p>You should go the do-not-DECLARE route when the flag is only needed 204 by <code>foo.cc</code>, and not in any other file. If you want to 205 modify the value of the flag in the related test file to see if it is 206 functioning as expected, DECLARE it in the <code>foo_test.cc</code> 207 file. 208 209 <p>If the flag does span multiple files, DECLARE it in the associated 210 <code>.h</code> file, and make others <code>#include</code> that 211 <code>.h</code> file if they want to access the flag. The 212 <code>#include</code> will make explicit the dependency between the 213 two files. This causes the flag to be a global variable.</p> 214 215 216 <h2> <A name=validate>RegisterFlagValidator: Sanity-checking Flag Values</A> </h2> 217 218 <p>After DEFINE-ing a flag, you may optionally register a validator 219 function with the flag. If you do this, after the flag is parsed from 220 the commandline, and whenever its value is changed via a call to 221 <code>SetCommandLineOption()</code>, the validator function is called 222 with the new value as an argument. The validator function should 223 return 'true' if the flag value is valid, and false otherwise. 224 If the function returns false for the new setting of the 225 flag, the flag will retain its current value. If it returns false for the 226 default value, ParseCommandLineFlags will die. 227 228 <p>Here is an example use of this functionality:</p> 229 <pre> 230 static bool ValidatePort(const char* flagname, int32 value) { 231 if (value > 0 && value < 32768) // value is ok 232 return true; 233 printf("Invalid value for --%s: %d\n", flagname, (int)value); 234 return false; 235 } 236 DEFINE_int32(port, 0, "What port to listen on"); 237 static const bool port_dummy = RegisterFlagValidator(&FLAGS_port, &ValidatePort); 238 </pre> 239 240 <p>By doing the registration at global initialization time (right 241 after the DEFINE), we ensure that the registration happens before 242 the commandline is parsed at the beginning of <code>main()</code>.</p> 243 244 <p><code>RegisterFlagValidator()</code> returns true if the 245 registration is successful. It return false if the registration fails 246 because a) the first argument does not refer to a commandline flag, or 247 b) a different validator has already been registered for this flag.</p> 248 249 250 <h2> <A name=together>Putting It Together: How to Set Up Flags</A> </h2> 251 252 <p>The final piece is the one that tells the executable to process the 253 commandline flags, and set the <code>FLAGS_*</code> variables to the 254 appropriate, non-default value based on what is seen on the 255 commandline. This is equivalent to the <code>getopt()</code> call in 256 the getopt library, but has much less overhead to use. In fact, it's 257 just a single function call:</p> 258 259 <pre> 260 google::ParseCommandLineFlags(&argc, &argv, true); 261 </pre> 262 263 <p>Usually, this code is at the beginning of <code>main()</code>. 264 <code>argc</code> and <code>argv</code> are exactly as passed in to 265 <code>main()</code>. This routine might modify them, which is why 266 pointers to them are passed in.</p> 267 268 <p>The last argument is called "remove_flags". If true, then 269 <code>ParseCommandLineFlags</code> removes the flags and their 270 arguments from <code>argv</code>, and modifies <code>argc</code> 271 appropriately. In this case, after the function call, 272 <code>argv</code> will hold only commandline arguments, and not 273 commandline flags.</p> 274 275 <p>If, on the other hand, <code>remove_flags</code> is false, then 276 <code>ParseCommandLineFlags</code> will leave argc unchanged, but will 277 rearrange the arguments in argv so that the flags are all at the 278 beginning. For example, if the input is <code>"/bin/foo" "arg1" "-q" 279 "arg2"</code> (which is legal but weird), the function will rearrange 280 <code>argv</code> so it reads <code>"/bin/foo", "-q", "arg1", 281 "arg2"</code>. In this case, <code>ParseCommandLineFlags</code> 282 returns the index into argv that holds the first commandline argument: 283 that is, the index past the last flag. (In this example, it would 284 return 2, since <code>argv[2]</code> points to <code>arg1</code>.)</p> 285 286 <p>In either case, the <code>FLAGS_*</code> variables are modified 287 based on what was <A HREF="#commandline">passed in on the 288 commandline</A>.</p> 289 290 291 <h2> <A name=commandline>Setting Flags on the Command Line</A> </h2> 292 293 <p>The reason you make something a flag instead of a compile-time 294 constant, is so users can specify a non-default value on the 295 commandline. Here's how they might do it for an application that 296 links in <code>foo.cc</code>:</p> 297 <pre> 298 app_containing_foo --nobig_menu -languages="chinese,japanese,korean" ... 299 </pre> 300 301 <p>This sets <code>FLAGS_big_menu = false;</code> and 302 <code>FLAGS_languages = "chinese,japanese,korean"</code>, when 303 <code>ParseCommandLineFlags</code> is run.</p> 304 305 <p>Note the atypical syntax for setting a boolean flag to false: 306 putting "no" in front of its name. There's a fair bit of flexibility 307 to how flags may be specified. Here's an example of all the ways to 308 specify the "languages" flag:</p> 309 <ul> 310 <li> <code>app_containing_foo --languages="chinese,japanese,korean"</code> 311 <li> <code>app_containing_foo -languages="chinese,japanese,korean"</code> 312 <li> <code>app_containing_foo --languages "chinese,japanese,korean"</code> 313 <li> <code>app_containing_foo -languages "chinese,japanese,korean"</code> 314 </ul> 315 316 <p>For boolean flags, the possibilities are slightly different:</p> 317 <ul> 318 <li> <code>app_containing_foo --big_menu</code> 319 <li> <code>app_containing_foo --nobig_menu</code> 320 <li> <code>app_containing_foo --big_menu=true</code> 321 <li> <code>app_containing_foo --big_menu=false</code> 322 </ul> 323 <p>(as well as the single-dash variant on all of these).</p> 324 325 <p>Despite this flexibility, we recommend using only a single form: 326 <code>--variable=value</code> for non-boolean flags, and 327 <code>--variable/--novariable</code> for boolean flags. This 328 consistency will make your code more readable, and is also the format 329 required for certain special-use cases like <A 330 HREF="#flagfiles">flagfiles</A>.</p> 331 332 <p>It is a fatal error to specify a flag on the commandline that has 333 not been DEFINED somewhere in the executable. If you need that 334 functionality for some reason -- say you want to use the same set of 335 flags for several executables, but not all of them DEFINE every flag 336 in your list -- you can specify <A 337 HREF="#special"><code>--undefok</code></A> to suppress the error.</p> 338 339 <p>As in getopt(), <code>--</code> by itself will terminate flags 340 processing. So in <code>foo -f1 1 -- -f2 2</code>, <code>f1</code> is 341 considered a flag, but <code>-f2</code> is not.</p> 342 343 <p>If a flag is specified more than once, only the last specification 344 is used; the others are ignored.</p> 345 346 <p>Note that flags do not have single-letter synonyms, like they do in 347 the getopt library, nor do we allow "combining" flags behind a 348 single dash, as in <code>ls -la</code>.</p> 349 350 351 352 <h2> <A name=default>Changing the Default Flag Value</A> </h2> 353 354 <p>Sometimes a flag is defined in a library, and you want to change 355 its default value in one application but not others. It's simple to 356 do this: just assign a new value to the flag in <code>main()</code>, 357 before calling <code>ParseCommandLineFlags()</code>:</p> 358 <pre> 359 DECLARE_bool(lib_verbose); // mylib has a lib_verbose flag, default is false 360 int main(int argc, char** argv) { 361 FLAGS_lib_verbose = true; // in my app, I want a verbose lib by default 362 ParseCommandLineFlags(...); 363 } 364 </pre> 365 366 <p>For this application, users can still set the flag value on the 367 commandline, but if they do not, the flag's value will default to 368 true.</p> 369 370 371 <h2> <A name="special">Special Flags</a> </h2> 372 373 <p>There are a few flags defined by the commandlineflags module 374 itself, and are available to all applications that use 375 commandlineflags. These fall into 376 three categories. First are the 'reporting' flags that, when found, cause 377 the application to print some information about itself and exit.</p> 378 379 <table><tr valign=top> 380 <td><code>--help</code></td> 381 <td>shows all flags from all files, sorted by file and then by name; 382 shows the flagname, its default value, and its help string</td> 383 </tr><tr valign=top> 384 <td><code>--helpfull</code></td> 385 <td>same as -help, but unambiguously asks for all flags 386 (in case -help changes in the future)</td> 387 </tr><tr valign=top> 388 <td><code>--helpshort</code></td> 389 <td>shows only flags for the file with the same name as the executable 390 (usually the one containing <code>main()</code>)</td> 391 </tr><tr valign=top> 392 <td><code>--helpxml</code></td> 393 <td>like --help, but output is in xml for easier parsing</td> 394 </tr><tr valign=top> 395 <td><code>--helpon=FILE </code></td> 396 <td>shows only flags defined in FILE.*</td> 397 </tr><tr valign=top> 398 <td><code>--helpmatch=S</code></td> 399 <td>shows only flags defined in *S*.*</td> 400 </tr><tr valign=top> 401 <td><code>--helppackage</code></td> 402 <td>shows flags defined in files in same directory as <code>main()</code></td> 403 </tr><tr valign=top> 404 <td><code>--version</code></td> 405 <td>prints version info for the executable</td> 406 </tr></table> 407 408 <p>Second are the flags that affect how other flags are parsed.</p> 409 410 <table><tr valign=top> 411 <td><code>--undefok=flagname,flagname,...</code></td> 412 <td>for those names listed as the argument to <code>--undefok</code>, 413 suppress the normal error-exit that occurs when 414 <code>--name</code> is seen on the commandline, but 415 <code>name</code> has not been DEFINED anywhere in the 416 application 417 </table> 418 419 <p>Third are the 'recursive' flags, that cause other flag values to be 420 set: <code>--fromenv</code>, <code>--tryfromenv</code>, 421 <code>--flagfile</code>. These are described below in more 422 detail.</p> 423 424 <h3> <code>--fromenv</code> </h3> 425 426 <p><code>--fromenv=foo,bar</code> says to read the values for the 427 <code>foo</code> and <code>bar</code> flags from the environment. 428 In concert with this flag, you must actually set the values in the 429 environment, via a line like one of the two below:</p> 430 <pre> 431 export FLAGS_foo=xxx; export FLAGS_bar=yyy # sh 432 setenv FLAGS_foo xxx; setenv FLAGS_bar yyy # tcsh 433 </pre> 434 <p>This is equivalent to specifying <code>--foo=xxx</code>, 435 <code>--bar=yyy</code> on the commandline.</p> 436 437 <p>Note it is a fatal error to say <code>--fromenv=foo</code> if 438 <code>foo</code> is not DEFINED somewhere in the application. (Though 439 you can suppress this error via <code>--undefok=foo</code>, just like 440 for any other flag.)</p> 441 442 <p>It is also a fatal error to say <code>--fromenv=foo</code> if 443 <code>FLAGS_foo</code> is not actually defined in the environment.</p> 444 445 <h3> <code>--tryfromenv</code> </h3> 446 447 <p><code>--tryfromenv</code> is exactly like <code>--fromenv</code>, 448 except it is <b>not</b> a fatal error to say 449 <code>--tryfromenv=foo</code> if <code>FLAGS_foo</code> is not 450 actually defined in the environment. Instead, in such cases, 451 <code>FLAGS_foo</code> just keeps its default value as specified in 452 the application.</p> 453 454 <p>Note it is still an error to say <code>--tryfromenv=foo</code> if 455 <code>foo</code> is not DEFINED somewhere in the application.</p> 456 457 <h3> <code>--flagfile</code> </h3> 458 459 <p><code>--flagfile=f</code> tells the commandlineflags module to read 460 the file <code>f</code>, and to run all the flag-assignments found in 461 that file as if these flags had been specified on the commandline.</p> 462 463 <p>In its simplest form, <code>f</code> should just be a list of flag 464 assignments, one per line. Unlike on the commandline, the equals sign 465 separating a flagname from its argument is <i>required</i> for 466 flagfiles. An example flagfile, <code>/tmp/myflags</code>:</p> 467 <pre> 468 --nobig_menus 469 --languages=english,french 470 </pre> 471 472 <p>With this flagfile, the following two lines are equivalent:<p> 473 <pre> 474 ./myapp --foo --nobig_menus --languages=english,french --bar 475 ./myapp --foo --flagfile=/tmp/myflags --bar 476 </pre> 477 478 <p>Note that many errors are silently suppressed in flagfiles. In 479 particular, unrecognized flagnames are silently ignored, as are flags 480 that are missing a required value (e.g., a flagfile that just says 481 <code>--languages</code>).</p> 482 483 <p>The general format of a flagfile is a bit more complicated than the 484 simple, common case above. It is: a sequence of filenames, one per 485 line, followed by a sequence of flags, one per line, repeated as many 486 times as desired. Filenames in a flagfile can use wildcards 487 (<code>*</code> and <code>?</code>), and the sequence of flags located 488 after a sequence of filenames is processed only if the current 489 executable's name matches one of the filenames. It is possible to 490 start the flagfile with a sequence of flags instead of a sequence of 491 filenames; if such a sequence of flags is present, these flags are 492 applied to the current executable no matter what it is.</p> 493 494 <p>Lines that start with a <code>#</code> are ignored as comments. 495 Leading whitespace is also ignored in flagfiles, as are blank 496 lines.</p> 497 498 <p>It is possible for a flagfile to use the <code>--flagfile</code> 499 flag to include another flagfile.</p> 500 501 <p>Flags are always processed in the expected order. That is, 502 processing begins by examining the flags specified directly on the 503 command line. If a flagfile is specified, its contents are processed, 504 and then processing continues with remaining flags from the command 505 line.</p> 506 507 508 <h2> <A name="api">The API</a> </h2> 509 510 <p>In addition to accessing <code>FLAGS_foo</code> directly, it is 511 possible to access the flags programmatically, through an API. It is 512 also possible to access information about a flag, such as its default 513 value and help-string. A <code>FlagSaver</code> makes it easy to 514 modify flags and then automatically undo the modifications later. 515 Finally, there are somewhat unrelated, but useful, routines to easily 516 access parts of <code>argv</code> outside main, including the program 517 name (<code>argv[0]</code>).</p> 518 519 <p>For more information about these routines, and other useful helper 520 methods such as <code>google::SetUsageMessage()</code> and 521 <code>google::SetVersionString</code>, see <code>gflags.h</code>.</p> 522 523 524 <h2> <A name="misc">Miscellaneous Notes</code> </h2> 525 526 <p>If your application has code like this:</p> 527 <pre> 528 #define STRIP_FLAG_HELP 1 // this must go before the #include! 529 #include <gflags/gflags.h> 530 </pre> 531 <p>we will remove the help messages from the compiled source. This can 532 reduce the size of the resulting binary somewhat, and may also be 533 useful for security reasons.</p> 534 535 536 <hr> 537 <address> 538 Craig Silverstein<br> 539 <script type=text/javascript> 540 var lm = new Date(document.lastModified); 541 document.write(lm.toDateString()); 542 </script> 543 </address> 544 545 </body> 546 </html>