projcet url:

usage:

commandline flags processing

DEFINE: Defining Flags In Program

DEFINE_bool: boolean

DEFINE_int32: 32-bit integer

DEFINE_int64: 64-bit integer

DEFINE_uint64: unsigned 64-bit integer

DEFINE_double: double

DEFINE_string: C++ string

DECLARE: Using the Flag in a Different File

If the flag does span multiple files, DECLARE it in theassociated .h file, and make others #include that .h file if they want to access the flag. The #include will make explicit the dependency between the two files. This causes the flag to be a global variable.

RegisterFlagValidator: Sanity-checking Flag Values

Here is an example use of this functionality:

static bool ValidatePort(const char* flagname, int32 value) {

   if (value > 0 && value < 32768)   // value is ok

     return true;

   printf("Invalid value for --%s: %d\n", flagname, (int)value);

   return false;

}

DEFINE_int32(port, 0, "What port to listen on");

static const bool port_dummy = RegisterFlagValidator(&FLAGS_port, &ValidatePort);

By doing the registration at global initialization time (right after the DEFINE), we ensure that the registration happens before the commandline is parsed at the beginning of main().

Putting It Together: How to Set Up Flags

gflags::ParseCommandLineFlags(&argc, &argv, true);

The last argument is called "remove_flags". If true, then ParseCommandLineFlags removes the flags and their arguments from argv, and modifies argc appropriately. In this case, after the function call, argv will hold only commandline arguments, and not commandline flags.

If, on the other hand, remove_flags is false, then ParseCommandLineFlags will leave argc unchanged, butwill rearrange the arguments in argv so that the flags are all at the beginning.

Setting Flags on the Command Line

Here's an example of all the ways to specify the "languages" flag:

app_containing_foo --languages="chinese,japanese,korean"

app_containing_foo -languages="chinese,japanese,korean"

app_containing_foo --languages "chinese,japanese,korean"

app_containing_foo -languages "chinese,japanese,korean"

For boolean flags, the possibilities are slightly different:

app_containing_foo --big_menu

app_containing_foo --nobig_menu

app_containing_foo --big_menu=true

app_containing_foo --big_menu=false

Changing the Default Flag Value

It's simple to do this: just assign a new value to the flag in main(), before calling ParseCommandLineFlags():

   DECLARE_bool(lib_verbose);   // mylib has a lib_verbose flag, default is false

   int main(int argc, char** argv) {

     FLAGS_lib_verbose = true;  // in my app, I want a verbose lib by default

     ParseCommandLineFlags(...);

   }

For this application, users can still set the flag value on the commandline, but if they do not, the flag's value will default to true.

Special Flags

--help

shows all flags from all files, sorted by file and then by name; shows the flagname, its default value, and its help string

--helpfull

same as -help, but unambiguously asks for all flags (in case -help changes in the future)

--helpshort

shows only flags for the file with the same name as the executable (usually the one containing main())

--helpxml

like --help, but output is in xml for easier parsing

--helpon=FILE  

shows only flags defined in FILE.*

--helpmatch=S

shows only flags defined in *S*.*

--helppackage

shows flags defined in files in same directory as main()

--version

prints version info for the executable

--fromenv

--fromenv=foo,bar says to read the values for the foo and bar flags from the environment.

--tryfromenv

--tryfromenv is exactly like --fromenv, except it is not a fatal error to say --tryfromenv=foo if FLAGS_foo is not actually defined in the environment.

--flagfile

--flagfile=f tells the commandlineflags module to read the file f, and to run all the flag-assignments found in that file as if these flags had been specified on the commandline.

The API

For more information about these routines, and other useful helper methods such asgflags::SetUsageMessage() andgflags::SetVersionString, seegflags.h.

Miscellaneous Notes

If your application has code like this:

   #define STRIP_FLAG_HELP 1    // this must go before the #include!

   #include <gflags/gflags.h>

we will remove the help messages from the compiled source. This canreduce the size of the resulting binary somewhat, and mayalso be useful for security reasons.