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