1// Copyright (c) 2006-2009 The Chromium Authors. All rights reserved. 2// Use of this source code is governed by a BSD-style license that can be 3// found in the LICENSE file. 4 5// This is the file that should be included by any file which declares 6// or defines a command line flag or wants to parse command line flags 7// or print a program usage message (which will include information about 8// flags). Executive summary, in the form of an example foo.cc file: 9// 10// #include "foo.h" // foo.h has a line "DECLARE_int32(start);" 11// 12// DEFINE_int32(end, 1000, "The last record to read"); 13// DECLARE_bool(verbose); // some other file has a DEFINE_bool(verbose, ...) 14// 15// void MyFunc() { 16// if (FLAGS_verbose) printf("Records %d-%d\n", FLAGS_start, FLAGS_end); 17// } 18// 19// Then, at the command-line: 20// ./foo --noverbose --start=5 --end=100 21 22#ifndef BASE_COMMANDLINEFLAGS_H_ 23#define BASE_COMMANDLINEFLAGS_H_ 24 25#include <assert.h> 26#include <string> 27#include <vector> 28#include "base/basictypes.h" 29#include "base/port.h" 30#include "base/stl_decl_msvc.h" 31#include "base/global_strip_options.h" 32 33// -------------------------------------------------------------------- 34// To actually define a flag in a file, use DEFINE_bool, 35// DEFINE_string, etc. at the bottom of this file. You may also find 36// it useful to register a validator with the flag. This ensures that 37// when the flag is parsed from the commandline, or is later set via 38// SetCommandLineOption, we call the validation function. 39// 40// The validation function should return true if the flag value is valid, and 41// false otherwise. If the function returns false for the new setting of the 42// flag, the flag will retain its current value. If it returns false for the 43// default value, InitGoogle will die. 44// 45// This function is safe to call at global construct time (as in the 46// example below). 47// 48// Example use: 49// static bool ValidatePort(const char* flagname, int32 value) { 50// if (value > 0 && value < 32768) // value is ok 51// return true; 52// printf("Invalid value for --%s: %d\n", flagname, (int)value); 53// return false; 54// } 55// DEFINE_int32(port, 0, "What port to listen on"); 56// static bool dummy = RegisterFlagValidator(&FLAGS_port, &ValidatePort); 57 58// Returns true if successfully registered, false if not (because the 59// first argument doesn't point to a command-line flag, or because a 60// validator is already registered for this flag). 61bool RegisterFlagValidator(const bool* flag, 62 bool (*validate_fn)(const char*, bool)); 63bool RegisterFlagValidator(const int32* flag, 64 bool (*validate_fn)(const char*, int32)); 65bool RegisterFlagValidator(const int64* flag, 66 bool (*validate_fn)(const char*, int64)); 67bool RegisterFlagValidator(const uint64* flag, 68 bool (*validate_fn)(const char*, uint64)); 69bool RegisterFlagValidator(const double* flag, 70 bool (*validate_fn)(const char*, double)); 71bool RegisterFlagValidator(const string* flag, 72 bool (*validate_fn)(const char*, const string&)); 73 74 75// -------------------------------------------------------------------- 76// These methods are the best way to get access to info about the 77// list of commandline flags. Note that these routines are pretty slow. 78// GetAllFlags: mostly-complete info about the list, sorted by file. 79// ShowUsageWithFlags: pretty-prints the list to stdout (what --help does) 80// ShowUsageWithFlagsRestrict: limit to filenames with restrict as a substr 81// 82// In addition to accessing flags, you can also access argv[0] (the program 83// name) and argv (the entire commandline), which we sock away a copy of. 84// These variables are static, so you should only set them once. 85 86struct CommandLineFlagInfo { 87 string name; // the name of the flag 88 string type; // the type of the flag: int32, etc 89 string description; // the "help text" associated with the flag 90 string current_value; // the current value, as a string 91 string default_value; // the default value, as a string 92 string filename; // 'cleaned' version of filename holding the flag 93 bool is_default; // true if the flag has default value 94 bool has_validator_fn; // true if RegisterFlagValidator called on this flag 95}; 96 97extern void GetAllFlags(vector<CommandLineFlagInfo>* OUTPUT); 98// These two are actually defined in commandlineflags_reporting.cc. 99extern void ShowUsageWithFlags(const char *argv0); // what --help does 100extern void ShowUsageWithFlagsRestrict(const char *argv0, const char *restrict); 101 102// Create a descriptive string for a flag. 103// Goes to some trouble to make pretty line breaks. 104extern string DescribeOneFlag(const CommandLineFlagInfo& flag); 105 106// Thread-hostile; meant to be called before any threads are spawned. 107extern void SetArgv(int argc, const char** argv); 108// The following functions are thread-safe as long as SetArgv() is 109// only called before any threads start. 110extern const vector<string>& GetArgvs(); // all of argv = vector of strings 111extern const char* GetArgv(); // all of argv as a string 112extern const char* GetArgv0(); // only argv0 113extern uint32 GetArgvSum(); // simple checksum of argv 114extern const char* ProgramInvocationName(); // argv0, or "UNKNOWN" if not set 115extern const char* ProgramInvocationShortName(); // basename(argv0) 116// ProgramUsage() is thread-safe as long as SetUsageMessage() is only 117// called before any threads start. 118extern const char* ProgramUsage(); // string set by SetUsageMessage() 119 120 121// -------------------------------------------------------------------- 122// Normally you access commandline flags by just saying "if (FLAGS_foo)" 123// or whatever, and set them by calling "FLAGS_foo = bar" (or, more 124// commonly, via the DEFINE_foo macro). But if you need a bit more 125// control, we have programmatic ways to get/set the flags as well. 126// These programmatic ways to access flags are thread-safe, but direct 127// access is only thread-compatible. 128 129// Return true iff the flagname was found. 130// OUTPUT is set to the flag's value, or unchanged if we return false. 131extern bool GetCommandLineOption(const char* name, string* OUTPUT); 132 133// Return true iff the flagname was found. OUTPUT is set to the flag's 134// CommandLineFlagInfo or unchanged if we return false. 135extern bool GetCommandLineFlagInfo(const char* name, 136 CommandLineFlagInfo* OUTPUT); 137 138// Return the CommandLineFlagInfo of the flagname. exit() if name not found. 139// Example usage, to check if a flag's value is currently the default value: 140// if (GetCommandLineFlagInfoOrDie("foo").is_default) ... 141extern CommandLineFlagInfo GetCommandLineFlagInfoOrDie(const char* name); 142 143enum FlagSettingMode { 144 // update the flag's value (can call this multiple times). 145 SET_FLAGS_VALUE, 146 // update the flag's value, but *only if* it has not yet been updated 147 // with SET_FLAGS_VALUE, SET_FLAG_IF_DEFAULT, or "FLAGS_xxx = nondef". 148 SET_FLAG_IF_DEFAULT, 149 // set the flag's default value to this. If the flag has not yet updated 150 // yet (via SET_FLAGS_VALUE, SET_FLAG_IF_DEFAULT, or "FLAGS_xxx = nondef") 151 // change the flag's current value to the new default value as well. 152 SET_FLAGS_DEFAULT 153}; 154 155// Set a particular flag ("command line option"). Returns a string 156// describing the new value that the option has been set to. The 157// return value API is not well-specified, so basically just depend on 158// it to be empty if the setting failed for some reason -- the name is 159// not a valid flag name, or the value is not a valid value -- and 160// non-empty else. 161 162// SetCommandLineOption uses set_mode == SET_FLAGS_VALUE (the common case) 163extern string SetCommandLineOption(const char* name, const char* value); 164extern string SetCommandLineOptionWithMode(const char* name, const char* value, 165 FlagSettingMode set_mode); 166 167 168// -------------------------------------------------------------------- 169// Saves the states (value, default value, whether the user has set 170// the flag, registered validators, etc) of all flags, and restores 171// them when the FlagSaver is destroyed. This is very useful in 172// tests, say, when you want to let your tests change the flags, but 173// make sure that they get reverted to the original states when your 174// test is complete. 175// 176// Example usage: 177// void TestFoo() { 178// FlagSaver s1; 179// FLAG_foo = false; 180// FLAG_bar = "some value"; 181// 182// // test happens here. You can return at any time 183// // without worrying about restoring the FLAG values. 184// } 185// 186// Note: This class is marked with ATTRIBUTE_UNUSED because all the 187// work is done in the constructor and destructor, so in the standard 188// usage example above, the compiler would complain that it's an 189// unused variable. 190// 191// This class is thread-safe. 192/* 193class FlagSaver { 194 public: 195 FlagSaver(); 196 ~FlagSaver(); 197 198 private: 199 class FlagSaverImpl* impl_; // we use pimpl here to keep API steady 200 201 FlagSaver(const FlagSaver&); // no copying! 202 void operator=(const FlagSaver&); 203} 204#ifndef SWIG // swig seems to have trouble with this for some reason 205ATTRIBUTE_UNUSED 206#endif 207; 208*/ 209// -------------------------------------------------------------------- 210// Some deprecated or hopefully-soon-to-be-deprecated functions. 211 212// This is often used for logging. TODO(csilvers): figure out a better way 213extern string CommandlineFlagsIntoString(); 214// Usually where this is used, a FlagSaver should be used instead. 215extern bool ReadFlagsFromString(const string& flagfilecontents, 216 const char* prog_name, 217 bool errors_are_fatal); // uses SET_FLAGS_VALUE 218 219// These let you manually implement --flagfile functionality. 220// DEPRECATED. 221extern bool AppendFlagsIntoFile(const string& filename, const char* prog_name); 222extern bool SaveCommandFlags(); // actually defined in google.cc ! 223extern bool ReadFromFlagsFile(const string& filename, const char* prog_name, 224 bool errors_are_fatal); // uses SET_FLAGS_VALUE 225 226 227// -------------------------------------------------------------------- 228// Useful routines for initializing flags from the environment. 229// In each case, if 'varname' does not exist in the environment 230// return defval. If 'varname' does exist but is not valid 231// (e.g., not a number for an int32 flag), abort with an error. 232// Otherwise, return the value. NOTE: for booleans, for true use 233// 't' or 'T' or 'true' or '1', for false 'f' or 'F' or 'false' or '0'. 234 235extern bool BoolFromEnv(const char *varname, bool defval); 236extern int32 Int32FromEnv(const char *varname, int32 defval); 237extern int64 Int64FromEnv(const char *varname, int64 defval); 238extern uint64 Uint64FromEnv(const char *varname, uint64 defval); 239extern double DoubleFromEnv(const char *varname, double defval); 240extern const char *StringFromEnv(const char *varname, const char *defval); 241 242 243// -------------------------------------------------------------------- 244// The next two functions parse commandlineflags from main(): 245 246// Set the "usage" message for this program. For example: 247// string usage("This program does nothing. Sample usage:\n"); 248// usage += argv[0] + " <uselessarg1> <uselessarg2>"; 249// SetUsageMessage(usage); 250// Do not include commandline flags in the usage: we do that for you! 251// Thread-hostile; meant to be called before any threads are spawned. 252extern void SetUsageMessage(const string& usage); 253 254// Looks for flags in argv and parses them. Rearranges argv to put 255// flags first, or removes them entirely if remove_flags is true. 256// If a flag is defined more than once in the command line or flag 257// file, the last definition is used. 258// See top-of-file for more details on this function. 259#ifndef SWIG // In swig, use ParseCommandLineFlagsScript() instead. 260extern uint32 ParseCommandLineFlags(int *argc, char*** argv, 261 bool remove_flags); 262#endif 263 264 265// Calls to ParseCommandLineNonHelpFlags and then to 266// HandleCommandLineHelpFlags can be used instead of a call to 267// ParseCommandLineFlags during initialization, in order to allow for 268// changing default values for some FLAGS (via 269// e.g. SetCommandLineOptionWithMode calls) between the time of 270// command line parsing and the time of dumping help information for 271// the flags as a result of command line parsing. 272// If a flag is defined more than once in the command line or flag 273// file, the last definition is used. 274extern uint32 ParseCommandLineNonHelpFlags(int *argc, char*** argv, 275 bool remove_flags); 276// This is actually defined in commandlineflags_reporting.cc. 277// This function is misnamed (it also handles --version, etc.), but 278// it's too late to change that now. :-( 279extern void HandleCommandLineHelpFlags(); // in commandlineflags_reporting.cc 280 281// Allow command line reparsing. Disables the error normally 282// generated when an unknown flag is found, since it may be found in a 283// later parse. Thread-hostile; meant to be called before any threads 284// are spawned. 285extern void AllowCommandLineReparsing(); 286 287// Reparse the flags that have not yet been recognized. 288// Only flags registered since the last parse will be recognized. 289// Any flag value must be provided as part of the argument using "=", 290// not as a separate command line argument that follows the flag argument. 291// Intended for handling flags from dynamically loaded libraries, 292// since their flags are not registered until they are loaded. 293extern uint32 ReparseCommandLineNonHelpFlags(); 294 295 296// -------------------------------------------------------------------- 297// Now come the command line flag declaration/definition macros that 298// will actually be used. They're kind of hairy. A major reason 299// for this is initialization: we want people to be able to access 300// variables in global constructors and have that not crash, even if 301// their global constructor runs before the global constructor here. 302// (Obviously, we can't guarantee the flags will have the correct 303// default value in that case, but at least accessing them is safe.) 304// The only way to do that is have flags point to a static buffer. 305// So we make one, using a union to ensure proper alignment, and 306// then use placement-new to actually set up the flag with the 307// correct default value. In the same vein, we have to worry about 308// flag access in global destructors, so FlagRegisterer has to be 309// careful never to destroy the flag-values it constructs. 310// 311// Note that when we define a flag variable FLAGS_<name>, we also 312// preemptively define a junk variable, FLAGS_no<name>. This is to 313// cause a link-time error if someone tries to define 2 flags with 314// names like "logging" and "nologging". We do this because a bool 315// flag FLAG can be set from the command line to true with a "-FLAG" 316// argument, and to false with a "-noFLAG" argument, and so this can 317// potentially avert confusion. 318// 319// We also put flags into their own namespace. It is purposefully 320// named in an opaque way that people should have trouble typing 321// directly. The idea is that DEFINE puts the flag in the weird 322// namespace, and DECLARE imports the flag from there into the current 323// namespace. The net result is to force people to use DECLARE to get 324// access to a flag, rather than saying "extern bool FLAGS_whatever;" 325// or some such instead. We want this so we can put extra 326// functionality (like sanity-checking) in DECLARE if we want, and 327// make sure it is picked up everywhere. 328// 329// We also put the type of the variable in the namespace, so that 330// people can't DECLARE_int32 something that they DEFINE_bool'd 331// elsewhere. 332 333class FlagRegisterer { 334 public: 335 FlagRegisterer(const char* name, const char* type, 336 const char* help, const char* filename, 337 void* current_storage, void* defvalue_storage); 338}; 339 340#ifndef SWIG // In swig, ignore the main flag declarations 341 342// If STRIP_FLAG_HELP is defined and is non-zero, we remove the help 343// message from the binary file. This is useful for security reasons 344// when shipping a binary outside of Google (if the user cannot see 345// the usage message by executing the program, they shouldn't be able 346// to see it by running "strings binary_file"). 347 348extern const char kStrippedFlagHelp[]; 349 350#if STRIP_FLAG_HELP > 0 351// Need this construct to avoid the 'defined but not used' warning. 352#define MAYBE_STRIPPED_HELP(txt) (false ? (txt) : kStrippedFlagHelp) 353#else 354#define MAYBE_STRIPPED_HELP(txt) txt 355#endif 356 357// Each command-line flag has two variables associated with it: one 358// with the current value, and one with the default value. However, 359// we have a third variable, which is where value is assigned; it's a 360// constant. This guarantees that FLAG_##value is initialized at 361// static initialization time (e.g. before program-start) rather than 362// than global construction time (which is after program-start but 363// before main), at least when 'value' is a compile-time constant. We 364// use a small trick for the "default value" variable, and call it 365// FLAGS_no<name>. This serves the second purpose of assuring a 366// compile error if someone tries to define a flag named no<name> 367// which is illegal (--foo and --nofoo both affect the "foo" flag). 368#define DEFINE_VARIABLE(type, shorttype, name, value, help) \ 369 namespace fL##shorttype { \ 370 static const type FLAGS_nono##name = value; \ 371 type FLAGS_##name = FLAGS_nono##name; \ 372 type FLAGS_no##name = FLAGS_nono##name; \ 373 static FlagRegisterer o_##name( \ 374 #name, #type, MAYBE_STRIPPED_HELP(help), __FILE__, \ 375 &FLAGS_##name, &FLAGS_no##name); \ 376 } \ 377 using fL##shorttype::FLAGS_##name 378 379#define DECLARE_VARIABLE(type, shorttype, name) \ 380 namespace fL##shorttype { \ 381 extern type FLAGS_##name; \ 382 } \ 383 using fL##shorttype::FLAGS_##name 384 385// For boolean flags, we want to do the extra check that the passed-in 386// value is actually a bool, and not a string or something that can be 387// coerced to a bool. These declarations (no definition needed!) will 388// help us do that, and never evaluate from, which is important. 389// We'll use 'sizeof(IsBool(val))' to distinguish. 390namespace fLB { 391template<typename From> double IsBoolFlag(const From& from); 392bool IsBoolFlag(bool from); 393} 394extern bool FlagsTypeWarn(const char *name); 395 396#define DECLARE_bool(name) DECLARE_VARIABLE(bool,B, name) 397// We have extra code here to make sure 'val' is actually a boolean. 398#define DEFINE_bool(name,val,txt) namespace fLB { \ 399 const bool FLAGS_nonono##name = \ 400 (sizeof(::fLB::IsBoolFlag(val)) \ 401 == sizeof(double)) \ 402 ? FlagsTypeWarn(#name) : true; \ 403 } \ 404 DEFINE_VARIABLE(bool,B, name, val, txt) 405#define DECLARE_int32(name) DECLARE_VARIABLE(int32,I, name) 406#define DEFINE_int32(name,val,txt) DEFINE_VARIABLE(int32,I, name, val, txt) 407 408#define DECLARE_int64(name) DECLARE_VARIABLE(int64,I64, name) 409#define DEFINE_int64(name,val,txt) DEFINE_VARIABLE(int64,I64, name, val, txt) 410 411#define DECLARE_uint64(name) DECLARE_VARIABLE(uint64,U64, name) 412#define DEFINE_uint64(name,val,txt) DEFINE_VARIABLE(uint64,U64, name, val, txt) 413 414#define DECLARE_double(name) DECLARE_VARIABLE(double,D, name) 415#define DEFINE_double(name,val,txt) DEFINE_VARIABLE(double,D, name, val, txt) 416 417// Strings are trickier, because they're not a POD, so we can't 418// construct them at static-initialization time (instead they get 419// constructed at global-constructor time, which is much later). To 420// try to avoid crashes in that case, we use a char buffer to store 421// the string, which we can static-initialize, and then placement-new 422// into it later. It's not perfect, but the best we can do. 423#define DECLARE_string(name) namespace fLS { extern string& FLAGS_##name; } \ 424 using fLS::FLAGS_##name 425 426// We need to define a var named FLAGS_no##name so people don't define 427// --string and --nostring. And we need a temporary place to put val 428// so we don't have to evaluate it twice. Two great needs that go 429// great together! 430#define DEFINE_string(name, val, txt) \ 431 namespace fLS { \ 432 static union { void* align; char s[sizeof(string)]; } s_##name[2]; \ 433 const string* const FLAGS_no##name = new (s_##name[0].s) string(val); \ 434 static FlagRegisterer o_##name( \ 435 #name, "string", MAYBE_STRIPPED_HELP(txt), __FILE__, \ 436 s_##name[0].s, new (s_##name[1].s) string(*FLAGS_no##name)); \ 437 string& FLAGS_##name = *(reinterpret_cast<string*>(s_##name[0].s)); \ 438 } \ 439 using fLS::FLAGS_##name 440 441#endif // SWIG 442 443#endif // BASE_COMMANDLINEFLAGS_H_ 444