1// Copyright (c) 2006, Google Inc. 2// All rights reserved. 3// 4// Redistribution and use in source and binary forms, with or without 5// modification, are permitted provided that the following conditions are 6// met: 7// 8// * Redistributions of source code must retain the above copyright 9// notice, this list of conditions and the following disclaimer. 10// * Redistributions in binary form must reproduce the above 11// copyright notice, this list of conditions and the following disclaimer 12// in the documentation and/or other materials provided with the 13// distribution. 14// * Neither the name of Google Inc. nor the names of its 15// contributors may be used to endorse or promote products derived from 16// this software without specific prior written permission. 17// 18// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 21// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 22// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 23// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 24// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 30// --- 31// Author: Ray Sidney 32// Revamped and reorganized by Craig Silverstein 33// 34// This is the file that should be included by any file which declares 35// or defines a command line flag or wants to parse command line flags 36// or print a program usage message (which will include information about 37// flags). Executive summary, in the form of an example foo.cc file: 38// 39// #include "foo.h" // foo.h has a line "DECLARE_int32(start);" 40// 41// DEFINE_int32(end, 1000, "The last record to read"); 42// DECLARE_bool(verbose); // some other file has a DEFINE_bool(verbose, ...) 43// 44// void MyFunc() { 45// if (FLAGS_verbose) printf("Records %d-%d\n", FLAGS_start, FLAGS_end); 46// } 47// 48// Then, at the command-line: 49// ./foo --noverbose --start=5 --end=100 50// 51// For more details, see 52// doc/gflags.html 53// 54// --- A note about thread-safety: 55// 56// We describe many functions in this routine as being thread-hostile, 57// thread-compatible, or thread-safe. Here are the meanings we use: 58// 59// thread-safe: it is safe for multiple threads to call this routine 60// (or, when referring to a class, methods of this class) 61// concurrently. 62// thread-hostile: it is not safe for multiple threads to call this 63// routine (or methods of this class) concurrently. In gflags, 64// most thread-hostile routines are intended to be called early in, 65// or even before, main() -- that is, before threads are spawned. 66// thread-compatible: it is safe for multiple threads to read from 67// this variable (when applied to variables), or to call const 68// methods of this class (when applied to classes), as long as no 69// other thread is writing to the variable or calling non-const 70// methods of this class. 71 72#ifndef GOOGLE_GFLAGS_H_ 73#define GOOGLE_GFLAGS_H_ 74 75#include <string> 76#include <vector> 77 78// We care a lot about number of bits things take up. Unfortunately, 79// systems define their bit-specific ints in a lot of different ways. 80// We use our own way, and have a typedef to get there. 81// Note: these commands below may look like "#if 1" or "#if 0", but 82// that's because they were constructed that way at ./configure time. 83// Look at gflags.h.in to see how they're calculated (based on your config). 84#if 1 85#include <stdint.h> // the normal place uint16_t is defined 86#endif 87#if 1 88#include <sys/types.h> // the normal place u_int16_t is defined 89#endif 90#if 1 91#include <inttypes.h> // a third place for uint16_t or u_int16_t 92#endif 93 94namespace google { 95 96#if 1 // the C99 format 97typedef int32_t int32; 98typedef uint32_t uint32; 99typedef int64_t int64; 100typedef uint64_t uint64; 101#elif 1 // the BSD format 102typedef int32_t int32; 103typedef u_int32_t uint32; 104typedef int64_t int64; 105typedef u_int64_t uint64; 106#elif 0 // the windows (vc7) format 107typedef __int32 int32; 108typedef unsigned __int32 uint32; 109typedef __int64 int64; 110typedef unsigned __int64 uint64; 111#else 112#error Do not know how to define a 32-bit integer quantity on your system 113#endif 114 115// -------------------------------------------------------------------- 116// To actually define a flag in a file, use DEFINE_bool, 117// DEFINE_string, etc. at the bottom of this file. You may also find 118// it useful to register a validator with the flag. This ensures that 119// when the flag is parsed from the commandline, or is later set via 120// SetCommandLineOption, we call the validation function. 121// 122// The validation function should return true if the flag value is valid, and 123// false otherwise. If the function returns false for the new setting of the 124// flag, the flag will retain its current value. If it returns false for the 125// default value, InitGoogle will die. 126// 127// This function is safe to call at global construct time (as in the 128// example below). 129// 130// Example use: 131// static bool ValidatePort(const char* flagname, int32 value) { 132// if (value > 0 && value < 32768) // value is ok 133// return true; 134// printf("Invalid value for --%s: %d\n", flagname, (int)value); 135// return false; 136// } 137// DEFINE_int32(port, 0, "What port to listen on"); 138// static bool dummy = RegisterFlagValidator(&FLAGS_port, &ValidatePort); 139 140// Returns true if successfully registered, false if not (because the 141// first argument doesn't point to a command-line flag, or because a 142// validator is already registered for this flag). 143bool RegisterFlagValidator(const bool* flag, 144 bool (*validate_fn)(const char*, bool)); 145bool RegisterFlagValidator(const int32* flag, 146 bool (*validate_fn)(const char*, int32)); 147bool RegisterFlagValidator(const int64* flag, 148 bool (*validate_fn)(const char*, int64)); 149bool RegisterFlagValidator(const uint64* flag, 150 bool (*validate_fn)(const char*, uint64)); 151bool RegisterFlagValidator(const double* flag, 152 bool (*validate_fn)(const char*, double)); 153bool RegisterFlagValidator(const std::string* flag, 154 bool (*validate_fn)(const char*, const std::string&)); 155 156 157// -------------------------------------------------------------------- 158// These methods are the best way to get access to info about the 159// list of commandline flags. Note that these routines are pretty slow. 160// GetAllFlags: mostly-complete info about the list, sorted by file. 161// ShowUsageWithFlags: pretty-prints the list to stdout (what --help does) 162// ShowUsageWithFlagsRestrict: limit to filenames with restrict as a substr 163// 164// In addition to accessing flags, you can also access argv[0] (the program 165// name) and argv (the entire commandline), which we sock away a copy of. 166// These variables are static, so you should only set them once. 167 168struct CommandLineFlagInfo { 169 std::string name; // the name of the flag 170 std::string type; // the type of the flag: int32, etc 171 std::string description; // the "help text" associated with the flag 172 std::string current_value; // the current value, as a string 173 std::string default_value; // the default value, as a string 174 std::string filename; // 'cleaned' version of filename holding the flag 175 bool has_validator_fn; // true if RegisterFlagValidator called on flag 176 bool is_default; // true if the flag has default value 177}; 178 179// Using this inside of a validator is a recipe for a deadlock. 180// TODO(wojtekm) Fix locking when validators are running, to make it safe to 181// call validators during ParseAllFlags. 182// Also make sure then to uncomment the corresponding unit test in 183// commandlineflags_unittest.sh 184extern void GetAllFlags(std::vector<CommandLineFlagInfo>* OUTPUT); 185// These two are actually defined in commandlineflags_reporting.cc. 186extern void ShowUsageWithFlags(const char *argv0); // what --help does 187extern void ShowUsageWithFlagsRestrict(const char *argv0, const char *restrict); 188 189// Create a descriptive string for a flag. 190// Goes to some trouble to make pretty line breaks. 191extern std::string DescribeOneFlag(const CommandLineFlagInfo& flag); 192 193// Thread-hostile; meant to be called before any threads are spawned. 194extern void SetArgv(int argc, const char** argv); 195// The following functions are thread-safe as long as SetArgv() is 196// only called before any threads start. 197extern const std::vector<std::string>& GetArgvs(); // all of argv as a vector 198extern const char* GetArgv(); // all of argv as a string 199extern const char* GetArgv0(); // only argv0 200extern uint32 GetArgvSum(); // simple checksum of argv 201extern const char* ProgramInvocationName(); // argv0, or "UNKNOWN" if not set 202extern const char* ProgramInvocationShortName(); // basename(argv0) 203// ProgramUsage() is thread-safe as long as SetUsageMessage() is only 204// called before any threads start. 205extern const char* ProgramUsage(); // string set by SetUsageMessage() 206 207 208// -------------------------------------------------------------------- 209// Normally you access commandline flags by just saying "if (FLAGS_foo)" 210// or whatever, and set them by calling "FLAGS_foo = bar" (or, more 211// commonly, via the DEFINE_foo macro). But if you need a bit more 212// control, we have programmatic ways to get/set the flags as well. 213// These programmatic ways to access flags are thread-safe, but direct 214// access is only thread-compatible. 215 216// Return true iff the flagname was found. 217// OUTPUT is set to the flag's value, or unchanged if we return false. 218extern bool GetCommandLineOption(const char* name, std::string* OUTPUT); 219 220// Return true iff the flagname was found. OUTPUT is set to the flag's 221// CommandLineFlagInfo or unchanged if we return false. 222extern bool GetCommandLineFlagInfo(const char* name, 223 CommandLineFlagInfo* OUTPUT); 224 225// Return the CommandLineFlagInfo of the flagname. exit() if name not found. 226// Example usage, to check if a flag's value is currently the default value: 227// if (GetCommandLineFlagInfoOrDie("foo").is_default) ... 228extern CommandLineFlagInfo GetCommandLineFlagInfoOrDie(const char* name); 229 230enum FlagSettingMode { 231 // update the flag's value (can call this multiple times). 232 SET_FLAGS_VALUE, 233 // update the flag's value, but *only if* it has not yet been updated 234 // with SET_FLAGS_VALUE, SET_FLAG_IF_DEFAULT, or "FLAGS_xxx = nondef". 235 SET_FLAG_IF_DEFAULT, 236 // set the flag's default value to this. If the flag has not yet updated 237 // yet (via SET_FLAGS_VALUE, SET_FLAG_IF_DEFAULT, or "FLAGS_xxx = nondef") 238 // change the flag's current value to the new default value as well. 239 SET_FLAGS_DEFAULT 240}; 241 242// Set a particular flag ("command line option"). Returns a string 243// describing the new value that the option has been set to. The 244// return value API is not well-specified, so basically just depend on 245// it to be empty if the setting failed for some reason -- the name is 246// not a valid flag name, or the value is not a valid value -- and 247// non-empty else. 248 249// SetCommandLineOption uses set_mode == SET_FLAGS_VALUE (the common case) 250extern std::string SetCommandLineOption(const char* name, const char* value); 251extern std::string SetCommandLineOptionWithMode(const char* name, const char* value, 252 FlagSettingMode set_mode); 253 254 255// -------------------------------------------------------------------- 256// Saves the states (value, default value, whether the user has set 257// the flag, registered validators, etc) of all flags, and restores 258// them when the FlagSaver is destroyed. This is very useful in 259// tests, say, when you want to let your tests change the flags, but 260// make sure that they get reverted to the original states when your 261// test is complete. 262// 263// Example usage: 264// void TestFoo() { 265// FlagSaver s1; 266// FLAG_foo = false; 267// FLAG_bar = "some value"; 268// 269// // test happens here. You can return at any time 270// // without worrying about restoring the FLAG values. 271// } 272// 273// Note: This class is marked with __attribute__((unused)) because all the 274// work is done in the constructor and destructor, so in the standard 275// usage example above, the compiler would complain that it's an 276// unused variable. 277// 278// This class is thread-safe. 279 280class FlagSaver { 281 public: 282 FlagSaver(); 283 ~FlagSaver(); 284 285 private: 286 class FlagSaverImpl* impl_; // we use pimpl here to keep API steady 287 288 FlagSaver(const FlagSaver&); // no copying! 289 void operator=(const FlagSaver&); 290} __attribute__ ((unused)); 291 292// -------------------------------------------------------------------- 293// Some deprecated or hopefully-soon-to-be-deprecated functions. 294 295// This is often used for logging. TODO(csilvers): figure out a better way 296extern std::string CommandlineFlagsIntoString(); 297// Usually where this is used, a FlagSaver should be used instead. 298extern bool ReadFlagsFromString(const std::string& flagfilecontents, 299 const char* prog_name, 300 bool errors_are_fatal); // uses SET_FLAGS_VALUE 301 302// These let you manually implement --flagfile functionality. 303// DEPRECATED. 304extern bool AppendFlagsIntoFile(const std::string& filename, const char* prog_name); 305extern bool SaveCommandFlags(); // actually defined in google.cc ! 306extern bool ReadFromFlagsFile(const std::string& filename, const char* prog_name, 307 bool errors_are_fatal); // uses SET_FLAGS_VALUE 308 309 310// -------------------------------------------------------------------- 311// Useful routines for initializing flags from the environment. 312// In each case, if 'varname' does not exist in the environment 313// return defval. If 'varname' does exist but is not valid 314// (e.g., not a number for an int32 flag), abort with an error. 315// Otherwise, return the value. NOTE: for booleans, for true use 316// 't' or 'T' or 'true' or '1', for false 'f' or 'F' or 'false' or '0'. 317 318extern bool BoolFromEnv(const char *varname, bool defval); 319extern int32 Int32FromEnv(const char *varname, int32 defval); 320extern int64 Int64FromEnv(const char *varname, int64 defval); 321extern uint64 Uint64FromEnv(const char *varname, uint64 defval); 322extern double DoubleFromEnv(const char *varname, double defval); 323extern const char *StringFromEnv(const char *varname, const char *defval); 324 325 326// -------------------------------------------------------------------- 327// The next two functions parse commandlineflags from main(): 328 329// Set the "usage" message for this program. For example: 330// string usage("This program does nothing. Sample usage:\n"); 331// usage += argv[0] + " <uselessarg1> <uselessarg2>"; 332// SetUsageMessage(usage); 333// Do not include commandline flags in the usage: we do that for you! 334// Thread-hostile; meant to be called before any threads are spawned. 335extern void SetUsageMessage(const std::string& usage); 336 337// Looks for flags in argv and parses them. Rearranges argv to put 338// flags first, or removes them entirely if remove_flags is true. 339// If a flag is defined more than once in the command line or flag 340// file, the last definition is used. 341// See top-of-file for more details on this function. 342#ifndef SWIG // In swig, use ParseCommandLineFlagsScript() instead. 343extern uint32 ParseCommandLineFlags(int *argc, char*** argv, 344 bool remove_flags); 345#endif 346 347 348// Calls to ParseCommandLineNonHelpFlags and then to 349// HandleCommandLineHelpFlags can be used instead of a call to 350// ParseCommandLineFlags during initialization, in order to allow for 351// changing default values for some FLAGS (via 352// e.g. SetCommandLineOptionWithMode calls) between the time of 353// command line parsing and the time of dumping help information for 354// the flags as a result of command line parsing. 355// If a flag is defined more than once in the command line or flag 356// file, the last definition is used. 357extern uint32 ParseCommandLineNonHelpFlags(int *argc, char*** argv, 358 bool remove_flags); 359// This is actually defined in commandlineflags_reporting.cc. 360// This function is misnamed (it also handles --version, etc.), but 361// it's too late to change that now. :-( 362extern void HandleCommandLineHelpFlags(); // in commandlineflags_reporting.cc 363 364// Allow command line reparsing. Disables the error normally 365// generated when an unknown flag is found, since it may be found in a 366// later parse. Thread-hostile; meant to be called before any threads 367// are spawned. 368extern void AllowCommandLineReparsing(); 369 370// Reparse the flags that have not yet been recognized. 371// Only flags registered since the last parse will be recognized. 372// Any flag value must be provided as part of the argument using "=", 373// not as a separate command line argument that follows the flag argument. 374// Intended for handling flags from dynamically loaded libraries, 375// since their flags are not registered until they are loaded. 376extern uint32 ReparseCommandLineNonHelpFlags(); 377 378 379// -------------------------------------------------------------------- 380// Now come the command line flag declaration/definition macros that 381// will actually be used. They're kind of hairy. A major reason 382// for this is initialization: we want people to be able to access 383// variables in global constructors and have that not crash, even if 384// their global constructor runs before the global constructor here. 385// (Obviously, we can't guarantee the flags will have the correct 386// default value in that case, but at least accessing them is safe.) 387// The only way to do that is have flags point to a static buffer. 388// So we make one, using a union to ensure proper alignment, and 389// then use placement-new to actually set up the flag with the 390// correct default value. In the same vein, we have to worry about 391// flag access in global destructors, so FlagRegisterer has to be 392// careful never to destroy the flag-values it constructs. 393// 394// Note that when we define a flag variable FLAGS_<name>, we also 395// preemptively define a junk variable, FLAGS_no<name>. This is to 396// cause a link-time error if someone tries to define 2 flags with 397// names like "logging" and "nologging". We do this because a bool 398// flag FLAG can be set from the command line to true with a "-FLAG" 399// argument, and to false with a "-noFLAG" argument, and so this can 400// potentially avert confusion. 401// 402// We also put flags into their own namespace. It is purposefully 403// named in an opaque way that people should have trouble typing 404// directly. The idea is that DEFINE puts the flag in the weird 405// namespace, and DECLARE imports the flag from there into the current 406// namespace. The net result is to force people to use DECLARE to get 407// access to a flag, rather than saying "extern bool FLAGS_whatever;" 408// or some such instead. We want this so we can put extra 409// functionality (like sanity-checking) in DECLARE if we want, and 410// make sure it is picked up everywhere. 411// 412// We also put the type of the variable in the namespace, so that 413// people can't DECLARE_int32 something that they DEFINE_bool'd 414// elsewhere. 415 416class FlagRegisterer { 417 public: 418 FlagRegisterer(const char* name, const char* type, 419 const char* help, const char* filename, 420 void* current_storage, void* defvalue_storage); 421}; 422 423extern bool FlagsTypeWarn(const char *name); 424 425// If your application #defines STRIP_FLAG_HELP to a non-zero value 426// before #including this file, we remove the help message from the 427// binary file. This can reduce the size of the resulting binary 428// somewhat, and may also be useful for security reasons. 429 430extern const char kStrippedFlagHelp[]; 431 432} 433 434#ifndef SWIG // In swig, ignore the main flag declarations 435 436#if defined(STRIP_FLAG_HELP) && STRIP_FLAG_HELP > 0 437// Need this construct to avoid the 'defined but not used' warning. 438#define MAYBE_STRIPPED_HELP(txt) (false ? (txt) : kStrippedFlagHelp) 439#else 440#define MAYBE_STRIPPED_HELP(txt) txt 441#endif 442 443// Each command-line flag has two variables associated with it: one 444// with the current value, and one with the default value. However, 445// we have a third variable, which is where value is assigned; it's a 446// constant. This guarantees that FLAG_##value is initialized at 447// static initialization time (e.g. before program-start) rather than 448// than global construction time (which is after program-start but 449// before main), at least when 'value' is a compile-time constant. We 450// use a small trick for the "default value" variable, and call it 451// FLAGS_no<name>. This serves the second purpose of assuring a 452// compile error if someone tries to define a flag named no<name> 453// which is illegal (--foo and --nofoo both affect the "foo" flag). 454#define DEFINE_VARIABLE(type, shorttype, name, value, help) \ 455 namespace fL##shorttype { \ 456 static const type FLAGS_nono##name = value; \ 457 type FLAGS_##name = FLAGS_nono##name; \ 458 type FLAGS_no##name = FLAGS_nono##name; \ 459 static ::google::FlagRegisterer o_##name( \ 460 #name, #type, MAYBE_STRIPPED_HELP(help), __FILE__, \ 461 &FLAGS_##name, &FLAGS_no##name); \ 462 } \ 463 using fL##shorttype::FLAGS_##name 464 465#define DECLARE_VARIABLE(type, shorttype, name) \ 466 namespace fL##shorttype { \ 467 extern type FLAGS_##name; \ 468 } \ 469 using fL##shorttype::FLAGS_##name 470 471// For DEFINE_bool, we want to do the extra check that the passed-in 472// value is actually a bool, and not a string or something that can be 473// coerced to a bool. These declarations (no definition needed!) will 474// help us do that, and never evaluate From, which is important. 475// We'll use 'sizeof(IsBool(val))' to distinguish. This code requires 476// that the compiler have different sizes for bool & double. Since 477// this is not guaranteed by the standard, we check it with a 478// compile-time assert (msg[-1] will give a compile-time error). 479namespace fLB { 480struct CompileAssert {}; 481typedef CompileAssert expected_sizeof_double_neq_sizeof_bool[ 482 (sizeof(double) != sizeof(bool)) ? 1 : -1]; 483template<typename From> double IsBoolFlag(const From& from); 484bool IsBoolFlag(bool from); 485} // namespace fLB 486 487#define DECLARE_bool(name) DECLARE_VARIABLE(bool, B, name) 488#define DEFINE_bool(name, val, txt) \ 489 namespace fLB { \ 490 typedef CompileAssert FLAG_##name##_value_is_not_a_bool[ \ 491 (sizeof(::fLB::IsBoolFlag(val)) != sizeof(double)) ? 1 : -1]; \ 492 } \ 493 DEFINE_VARIABLE(bool, B, name, val, txt) 494 495#define DECLARE_int32(name) DECLARE_VARIABLE(::google::int32, I, name) 496#define DEFINE_int32(name,val,txt) DEFINE_VARIABLE(::google::int32, I, name, val, txt) 497 498#define DECLARE_int64(name) DECLARE_VARIABLE(::google::int64, I64, name) 499#define DEFINE_int64(name,val,txt) DEFINE_VARIABLE(::google::int64, I64, name, val, txt) 500 501#define DECLARE_uint64(name) DECLARE_VARIABLE(::google::uint64, U64, name) 502#define DEFINE_uint64(name,val,txt) DEFINE_VARIABLE(::google::uint64, U64, name, val, txt) 503 504#define DECLARE_double(name) DECLARE_VARIABLE(double, D, name) 505#define DEFINE_double(name, val, txt) DEFINE_VARIABLE(double, D, name, val, txt) 506 507// Strings are trickier, because they're not a POD, so we can't 508// construct them at static-initialization time (instead they get 509// constructed at global-constructor time, which is much later). To 510// try to avoid crashes in that case, we use a char buffer to store 511// the string, which we can static-initialize, and then placement-new 512// into it later. It's not perfect, but the best we can do. 513#define DECLARE_string(name) namespace fLS { extern std::string& FLAGS_##name; } \ 514 using fLS::FLAGS_##name 515 516// We need to define a var named FLAGS_no##name so people don't define 517// --string and --nostring. And we need a temporary place to put val 518// so we don't have to evaluate it twice. Two great needs that go 519// great together! 520// The weird 'using' + 'extern' inside the fLS namespace is to work around 521// an unknown compiler bug/issue with the gcc 4.2.1 on SUSE 10. See 522// http://code.google.com/p/google-gflags/issues/detail?id=20 523#define DEFINE_string(name, val, txt) \ 524 namespace fLS { \ 525 static union { void* align; char s[sizeof(std::string)]; } s_##name[2]; \ 526 const std::string* const FLAGS_no##name = new (s_##name[0].s) std::string(val); \ 527 static ::google::FlagRegisterer o_##name( \ 528 #name, "string", MAYBE_STRIPPED_HELP(txt), __FILE__, \ 529 s_##name[0].s, new (s_##name[1].s) std::string(*FLAGS_no##name)); \ 530 extern std::string& FLAGS_##name; \ 531 using fLS::FLAGS_##name; \ 532 std::string& FLAGS_##name = *(reinterpret_cast<std::string*>(s_##name[0].s)); \ 533 } \ 534 using fLS::FLAGS_##name 535 536#endif // SWIG 537 538#endif // GOOGLE_GFLAGS_H_ 539