Release v2.3.0 (#382)
Signed-off-by: Andreas Schuh <andreas.schuh.84@gmail.com>
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 1598eff..6c0b93c 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -91,7 +91,7 @@
# ----------------------------------------------------------------------------
# package information
set (PACKAGE_NAME "gflags")
-set (PACKAGE_VERSION "2.2.2")
+set (PACKAGE_VERSION "2.3.0")
set (PACKAGE_STRING "${PACKAGE_NAME} ${PACKAGE_VERSION}")
set (PACKAGE_TARNAME "${PACKAGE_NAME}-${PACKAGE_VERSION}")
set (PACKAGE_BUGREPORT "https://github.com/gflags/gflags/issues")
diff --git a/ChangeLog.txt b/ChangeLog.txt
index c7fd09b..bd009ee 100644
--- a/ChangeLog.txt
+++ b/ChangeLog.txt
@@ -1,24 +1,39 @@
+* Sat Dec 06 2025 - Andreas Schuh <andreas.schuh.84@gmail.com>
+
+- gflags: version 2.3.0
+- Fixed 377: Undefined behavior in ProcessOptionsFromStringLocked
+- Bazel: Merged 353: Support for Bzlmod (MODULE.bazel)
+- Bazel: Merged 381: Use includes instead of include_prefix in cc_library
+- Bazel: Fixed 321: Android linking issue
+- CMake: Merged 367: Support for CMake 4.0
+- CMake: Merged 364: Support for BlackBerry QNX
+- CMake: Merged 357: Export gflags_nothreads_static in subproject default
+- CMake: Merged 368: MinGW static library suffix and pkgconfig installation
+- CMake: Merged 385: Fix package version compatibility check and support ranges
+- CMake: Fixed 380: Fix patch version string parsing
+- CI: Merged 369/370: Migrate to GitHub Actions for testing
+
* Sun Nov 11 2018 - Andreas Schuh <andreas.schuh.84@gmail.com>
- gflags: version 2.2.2
-Fixed 267: Support build with GCC option "-fvisibility=hidden".
-Fixed 262: Declare FLAGS_no##name variables as static to avoid "previous extern" warning.
-Fixed 261: Declare FlagRegisterer c’tor explicit template instanations as extern in header
-Fixed 257: Build with _UNICODE support on Windows.
-Fixed 233/234/235: Move CMake defines that are unused by Bazel to separate header; makes config.h private again
-Fixed 228: Build with recent MinGW versions that define setenv.
-Fixed 226: Remove obsolete and unused CleanFileName code
-Merged 266: Various PVS Studio and GCC warnings.
-Merged 258: Fix build with some Clang variants that define "restrict" macro.
-Merged 252: Update documentation on how to use Bazel.
-Merged 249: Use "_debug" postfix for debug libraries.
-Merged 247: CMake "project" VERSION; no enable_testing(); "gflags::" import target prefix.
-Merged 246: Add Bazel-on-Windows support.
-Merged 239: Use GFLAGS_NAMESPACE instead of "gflags" in test executable.
-Merged 237: Removed unused functions; fixes compilation with -Werror compiler option.
-Merged 232: Fix typo in Bazel's BUILD definition
-Merged 230: Remove using ::fLS::clstring.
-Merged 221: Add convenience 'uninstall' target
+- Fixed 267: Support build with GCC option "-fvisibility=hidden".
+- Fixed 262: Declare FLAGS_no##name variables as static to avoid "previous extern" warning.
+- Fixed 261: Declare FlagRegisterer c’tor explicit template instanations as extern in header
+- Fixed 257: Build with _UNICODE support on Windows.
+- Fixed 233/234/235: Move CMake defines that are unused by Bazel to separate header; makes config.h private again
+- Fixed 228: Build with recent MinGW versions that define setenv.
+- Fixed 226: Remove obsolete and unused CleanFileName code
+- Merged 266: Various PVS Studio and GCC warnings.
+- Merged 258: Fix build with some Clang variants that define "restrict" macro.
+- Merged 252: Update documentation on how to use Bazel.
+- Merged 249: Use "_debug" postfix for debug libraries.
+- Merged 247: CMake "project" VERSION; no enable_testing(); "gflags::" import target prefix.
+- Merged 246: Add Bazel-on-Windows support.
+- Merged 239: Use GFLAGS_NAMESPACE instead of "gflags" in test executable.
+- Merged 237: Removed unused functions; fixes compilation with -Werror compiler option.
+- Merged 232: Fix typo in Bazel's BUILD definition
+- Merged 230: Remove using ::fLS::clstring.
+- Merged 221: Add convenience 'uninstall' target
* Tue Jul 11 2017 - Andreas Schuh <andreas.schuh.84@gmail.com>
diff --git a/INSTALL.md b/INSTALL.md
index 46b9124..aff34e3 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -15,18 +15,21 @@
# Compiling the source code with Bazel
-To use gflags in a [Bazel](http://bazel.io) project, map it in as an external
-dependency by editing your WORKSPACE file:
+To use gflags in a [Bazel](http://bazel.io) project using [Bzlmod](https://docs.bazel.build/versions/main/bzlmod.html),
+declare it as a dependency in your `MODULE.bazel` file:
- git_repository(
- name = "com_github_gflags_gflags",
- commit = "<INSERT COMMIT SHA HERE>",
+ bazel_dep(name = "gflags")
+
+To override the version of gflags used by your project, add the following after the `bazel_dep` call:
+
+ git_override(
+ module_name = "gflags",
+ commit = "3398b59cedbd3575e997470734f8e69c26a752f2",
remote = "https://github.com/gflags/gflags.git",
)
-You can then add `@com_github_gflags_gflags//:gflags` to the `deps` section of a
-`cc_binary` or `cc_library` rule, and `#include <gflags/gflags.h>` to include it
-in your source code.
+You can then add `@gflags//:gflags` to the `deps` section of a `cc_binary` or `cc_library` rule,
+and `#include <gflags/gflags.h>` to include it in your source code.
# Compiling the source code with vcpkg
diff --git a/README.md b/README.md
index a8cb4be..58aaf48 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,18 @@
The documentation of the gflags library is available online at https://gflags.github.io/gflags/.
+Please note that this is an open-source community project that was developed and originally released by Google, but is no longer maintained by Google. Since the initial open-source release of gflags, an internal fork of the library was re-released as part of Abseil. If you are using Abseil, we recommend using Abseil's [flags](https://abseil.io/docs/cpp/guides/flags) library instead. This open-source project will mainly receive minor maintenance releases. The addition of features is not currently planned, and depends on the open-source community to submit pull requests.
+
+
+06 December 2025
+----------------
+
+I've just released gflags 2.3.0.
+
+This maintenance release includes a number of build system improvements for both Bazel and CMake. It adds support for Bzlmod to prepares for Bazel 9. For CMake users, it adds support for CMake 4.0 and BlackBerry QNX. A few bugs in the library itself have also been fixed, including undefined behavior in option processing. The CI infrastructure has also been migrated to GitHub Actions.
+
+Please report any further issues with this release using the GitHub issue tracker.
+
11 November 2018
----------------
diff --git a/doc/index.html b/doc/index.html
index 17aa507..3ab332f 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -1,317 +1,334 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
-<head>
-<title>How To Use Gflags (formerly Google Commandline Flags)</title>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
-<link href="designstyle.css" type="text/css" rel="stylesheet">
-<style type="text/css">
-<!--
- ol.bluelist li {
- color: #3366ff;
- font-family: sans-serif;
- }
- ol.bluelist li p {
- color: #000;
- font-family: "Times Roman", times, serif;
- }
- ul.blacklist li {
- color: #000;
- font-family: "Times Roman", times, serif;
- }
-//-->
-</style>
+<head>
+ <title>How To Use Gflags (formerly Google Commandline Flags)</title>
+
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+ <link href="designstyle.css" type="text/css" rel="stylesheet">
+ <style type="text/css">
+ <!--
+ ol.bluelist li {
+ color: #3366ff;
+ font-family: sans-serif;
+ }
+
+ ol.bluelist li p {
+ color: #000;
+ font-family: "Times Roman", times, serif;
+ }
+
+ ul.blacklist li {
+ color: #000;
+ font-family: "Times Roman", times, serif;
+ }
+ -->
+ </style>
</head>
<body>
-<h1>How To Use gflags (formerly Google Commandline Flags)</h1>
-<small>(as of
-<script type=text/javascript>
+ <h1>How To Use gflags (formerly Google Commandline Flags)</h1>
+ <small>(as of
+ <script type=text/javascript>
var lm = new Date(document.lastModified);
document.write(lm.toDateString());
</script>)
-</small>
-<br>
+ </small>
+ <br>
-<blockquote><dl>
- <dt> Table of contents </dt>
- <dd> <a href="#intro">Introduction</a> </dd>
- <dd> <a href="#download">Download and Installation</a> </dd>
- <dd> <a href="#cmake">Declare dependency on gflags with CMake</a></dd>
- <dd> <a href="#bazel">Declare dependency on gflags with Bazel</a></dd>
- <dd> <a href="#define">DEFINE: Defining Flags In Program</A> </dd>
- <dd> <a href="#using">Accessing the Flag</A> </dd>
- <dd> <a href="#declare">DECLARE: Using the Flag in a Different File</a> </dd>
- <dd> <a href="#validate">RegisterFlagValidator: Sanity-checking Flag Values</a> </dd>
- <dd> <a href="#together">Putting It Together: How to Set Up Flags</a> </dd>
- <dd> <a href="#commandline">Setting Flags on the Command Line</a> </dd>
- <dd> <a href="#default">Changing the Default Flag Value</a> </dd>
- <dd> <a href="#special">Special Flags</a> </dd>
- <dd> <a href="#api">The API</a> </dd>
- <dd> <a href="#misc">Miscellaneous Notes</a> </dd>
- <dd> <a href="#issues">Issues and Feature Requests</a> </dd>
- <dd> <br/> </dd>
-</dl></blockquote>
+ <blockquote>
+ <dl>
+ <dt> Table of contents </dt>
+ <dd> <a href="#intro">Introduction</a> </dd>
+ <dd> <a href="#download">Download and Installation</a> </dd>
+ <dd> <a href="#cmake">Declare dependency on gflags with CMake</a></dd>
+ <dd> <a href="#bazel">Declare dependency on gflags with Bazel</a></dd>
+ <dd> <a href="#define">DEFINE: Defining Flags In Program</A> </dd>
+ <dd> <a href="#using">Accessing the Flag</A> </dd>
+ <dd> <a href="#declare">DECLARE: Using the Flag in a Different File</a> </dd>
+ <dd> <a href="#validate">RegisterFlagValidator: Sanity-checking Flag Values</a> </dd>
+ <dd> <a href="#together">Putting It Together: How to Set Up Flags</a> </dd>
+ <dd> <a href="#commandline">Setting Flags on the Command Line</a> </dd>
+ <dd> <a href="#default">Changing the Default Flag Value</a> </dd>
+ <dd> <a href="#special">Special Flags</a> </dd>
+ <dd> <a href="#api">The API</a> </dd>
+ <dd> <a href="#misc">Miscellaneous Notes</a> </dd>
+ <dd> <a href="#issues">Issues and Feature Requests</a> </dd>
+ <dd> <br /> </dd>
+ </dl>
+ </blockquote>
-<h2> <A NAME=intro>Introduction, and Comparison to Other Commandline
- Flags Libraries</A> </h2>
+ <h2> <A NAME=intro>Introduction, and Comparison to Other Commandline
+ Flags Libraries</A> </h2>
-<p><b>Commandline flags</b> are flags that users specify on the
-command line when they run an executable. In the command</p>
-<pre>
+ <p><b>Commandline flags</b> are flags that users specify on the
+ command line when they run an executable. In the command</p>
+ <pre>
fgrep -l -f /var/tmp/foo johannes brahms
</pre>
-<p><code>-l</code> and <code>-f /var/tmp/foo</code> are the two
-commandline flags. (<code>johannes</code> and <code>brahms</code>,
-which don't start with a dash, are <b>commandline arguments</b>.)</p>
+ <p><code>-l</code> and <code>-f /var/tmp/foo</code> are the two
+ commandline flags. (<code>johannes</code> and <code>brahms</code>,
+ which don't start with a dash, are <b>commandline arguments</b>.)</p>
-<p>Typically, an application lists what flags the user is allowed to
-pass in, and what arguments they take -- in this example,
-<code>-l</code> takes no argument, and <code>-f</code> takes a
-string (in particular, a filename) as an argument. Users can use a
-library to help parse the commandline and store the flags in some data
-structure.</p>
+ <p>Typically, an application lists what flags the user is allowed to
+ pass in, and what arguments they take -- in this example,
+ <code>-l</code> takes no argument, and <code>-f</code> takes a
+ string (in particular, a filename) as an argument. Users can use a
+ library to help parse the commandline and store the flags in some data
+ structure.
+ </p>
-<p>Gflags, the commandline flags library used within Google,
-differs from other libraries,
-such as <code>getopt()</code>, in that flag definitions can be
-scattered around the source code, and not just listed in one place
-such as <code>main()</code>. In practice, this means that a single
-source-code file will define and use flags that are meaningful to that
-file. Any application that links in that file will get the flags, and
-the gflags library will automatically handle that
-flag appropriately.</p>
+ <p>Gflags, the commandline flags library used within Google,
+ differs from other libraries,
+ such as <code>getopt()</code>, in that flag definitions can be
+ scattered around the source code, and not just listed in one place
+ such as <code>main()</code>. In practice, this means that a single
+ source-code file will define and use flags that are meaningful to that
+ file. Any application that links in that file will get the flags, and
+ the gflags library will automatically handle that
+ flag appropriately.</p>
-<p>There's significant gain in flexibility, and ease of code reuse,
-due to this technique. However, there is a danger that two files will
-define the same flag, and then give an error when they're linked
-together.</p>
+ <p>There's significant gain in flexibility, and ease of code reuse,
+ due to this technique. However, there is a danger that two files will
+ define the same flag, and then give an error when they're linked
+ together.</p>
-<p>The rest of this document describes how to use the commandlineflag
-library. It's a C++ library, so examples are in C++. However, there
-is a Python port with the same functionality, and this discussion
-translates directly to Python.</p>
+ <p>The rest of this document describes how to use the commandlineflag
+ library. It's a C++ library, so examples are in C++. However, there
+ is a Python port with the same functionality, and this discussion
+ translates directly to Python.</p>
-<h2> <A NAME=download>Download and Installation</A> </h2>
+ <h2> <A NAME=download>Download and Installation</A> </h2>
-<p>The gflags library can be downloaded from <A href="https://github.com/gflags/gflags">GitHub</A>.
-You can clone the project using the command:</p>
-<pre>
+ <p>The gflags library can be downloaded from <A href="https://github.com/gflags/gflags">GitHub</A>.
+ You can clone the project using the command:</p>
+ <pre>
git clone https://github.com/gflags/gflags.git
</pre>
-<p>Build and installation instructions are provided in the
-<A href="https://github.com/gflags/gflags/blob/master/INSTALL.md">INSTALL</A> file.
-The installation of the gflags package includes configuration files for popular build systems
-such as <A href="https://www.freedesktop.org/wiki/Software/pkg-config/">pkg-config</A>,
-<A href="#cmake">CMake</A>, and <A href="#bazel">Bazel</A>.</p>
+ <p>Build and installation instructions are provided in the
+ <A href="https://github.com/gflags/gflags/blob/master/INSTALL.md">INSTALL</A> file.
+ The installation of the gflags package includes configuration files for popular build systems
+ such as <A href="https://www.freedesktop.org/wiki/Software/pkg-config/">pkg-config</A>,
+ <A href="#cmake">CMake</A>, and <A href="#bazel">Bazel</A>.
+ </p>
-<h2> <A name=cmake>Declare dependency on gflags with CMake</A></h2>
+ <h2> <A name=cmake>Declare dependency on gflags with CMake</A></h2>
-<p>Using gflags within a project which uses <A href="http://www.cmake.org">CMake</A> for its build system is easy.
-You can either require an external installation of the gflags package and find it using CMake's find_package
-command, or include the gflags project as subtree or submodule within your project's source tree and add the directory
-using CMake's add_subdirectory command.
+ <p>Using gflags within a project which uses <A href="http://www.cmake.org">CMake</A> for its build system is easy.
+ You can either require an external installation of the gflags package and find it using CMake's find_package
+ command, or include the gflags project as subtree or submodule within your project's source tree and add the
+ directory
+ using CMake's add_subdirectory command.
-<p>To use an external gflags installation, add the following CMake code to your <code>CMakeLists.txt</code> file.</p>
+ <p>To use an external gflags installation, add the following CMake code to your <code>CMakeLists.txt</code> file.</p>
-<p>Find gflags installation. The <code>gflags_DIR</code> variable must be set to the <prefix>/lib/cmake/gflags directory
-containing the gflags-config.cmake file if <prefix> is a non-standard location. Otherwise, CMake should find
-the gflags installation automatically.</p>
-<pre>
+ <p>Find gflags installation. The <code>gflags_DIR</code> variable must be set to the <prefix>/lib/cmake/gflags
+ directory
+ containing the gflags-config.cmake file if <prefix> is a non-standard location. Otherwise, CMake should find
+ the gflags installation automatically.</p>
+ <pre>
find_package(gflags REQUIRED)
-</pre>
-<p>To request a particular imported gflags library target to link against, use the <code>COMPONENTS</code> option of
-the find_package command. For example, to force the use of the single-threaded static library, use the command</p>
-<pre>
+ </pre>
+ <p>To request a particular imported gflags library target to link against, use the <code>COMPONENTS</code> option of
+ the find_package command. For example, to force the use of the single-threaded static library, use the command</p>
+ <pre>
find_package(gflags COMPONENTS nothreads_static)
-</pre>
-<p>Note that this will raise a fatal error when the installed gflags package does not contain the requested library.
-It is therefore recommended to only specify the particular component to look for if a specific library must be used.
-Otherwise, the gflags-config.cmake module will choose a suitable and available library for you. By default, the
-multi-threaded gflags library with shared linkage is chosen if available.</p>
+ </pre>
+ <p>Note that this will raise a fatal error when the installed gflags package does not contain the requested library.
+ It is therefore recommended to only specify the particular component to look for if a specific library must be used.
+ Otherwise, the gflags-config.cmake module will choose a suitable and available library for you. By default, the
+ multi-threaded gflags library with shared linkage is chosen if available.</p>
-<p>When the source tree of the gflags project is included as subtree or submodule in the "gflags" directory of your project,
-replace the above find_package command by <code>add_subdirectory(gflags)</code>. See the top of the <code>gflags/CMakeLists.txt</code>
-file for a listing of available CMake variables that can be set before this command to configure the build of the
-gflags library. The default build settings are the build of a single-threaded static library which does not require
-any installation of the gflags subproject products.</p>
+ <p>When the source tree of the gflags project is included as subtree or submodule in the "gflags" directory of your
+ project,
+ replace the above find_package command by <code>add_subdirectory(gflags)</code>. See the top of the
+ <code>gflags/CMakeLists.txt</code>
+ file for a listing of available CMake variables that can be set before this command to configure the build of the
+ gflags library. The default build settings are the build of a single-threaded static library which does not require
+ any installation of the gflags subproject products.
+ </p>
-<p>Finally, add your executable build target which uses gflags to parse the command arguments with dependency on the
-imported gflags library target:</p>
-<pre>
+ <p>Finally, add your executable build target which uses gflags to parse the command arguments with dependency on the
+ imported gflags library target:</p>
+ <pre>
add_executable(foo main.cc)
target_link_libraries(foo gflags::gflags)
-</pre>
+ </pre>
-<h2> <A name=bazel>Declare dependency on gflags with Bazel</A></h2>
+ <h2> <A name=bazel>Declare dependency on gflags with Bazel</A></h2>
-<p>To use gflags within a project which uses <A href="https://bazel.build/">Bazel</A> as build tool,
-add the following lines to your <code>WORKSPACE</code> file
-(see also Bazel documentation of <A href="https://www.bazel.io/versions/master/docs/be/workspace.html#git_repository">git_repository</A>):
+ <p>To use gflags within a project which uses <A href="https://bazel.build/">Bazel</A> as build tool,
+ add the following lines to your <code>WORKSPACE</code> file
+ (see also Bazel documentation of <A
+ href="https://www.bazel.io/versions/master/docs/be/workspace.html#git_repository">git_repository</A>):
-<pre>
+ <pre>
git_repository(
name = "com_github_gflags_gflags",
remote = "https://github.com/gflags/gflags.git",
- tag = "v2.2.2"
+ tag = "v2.3.0"
)
-</pre>
+ </pre>
-<p>You can then add <code>@com_github_gflags_gflags//:gflags</code> to the <code>deps</code> section of a
-<code>cc_binary</code> or <code>cc_library</code> rule, and <code>#include "gflags/gflags.h"</code> to
-include it in your source code. This uses the shared gflags library with multi-threading enabled.
-In order to use the single-threaded shared gflags library, use the dependency
-<code>@com_github_gflags_gflags//:gflags_nothreads</code> instead.</p>
+ <p>You can then add <code>@com_github_gflags_gflags//:gflags</code> to the <code>deps</code> section of a
+ <code>cc_binary</code> or <code>cc_library</code> rule, and <code>#include "gflags/gflags.h"</code> to
+ include it in your source code. This uses the shared gflags library with multi-threading enabled.
+ In order to use the single-threaded shared gflags library, use the dependency
+ <code>@com_github_gflags_gflags//:gflags_nothreads</code> instead.
+ </p>
-<p>For example, see the following <code>BUILD</code> rule of the gflags/example project:</p>
+ <p>For example, see the following <code>BUILD</code> rule of the gflags/example project:</p>
-<pre>
+ <pre>
cc_binary(
name = "foo",
srcs = ["main.cc"],
deps = ["@com_github_gflags_gflags//:gflags"],
)
-</pre>
+ </pre>
-<h2> <A name=define>DEFINE: Defining Flags In Program</A> </h2>
+ <h2> <A name=define>DEFINE: Defining Flags In Program</A> </h2>
-<p> Defining a flag is easy: just use the appropriate macro for the
-type you want the flag to be, as defined at the bottom of
-<code>gflags/gflags.h</code>. Here's an example file,
-<code>foo.cc</code>:</p>
+ <p> Defining a flag is easy: just use the appropriate macro for the
+ type you want the flag to be, as defined at the bottom of
+ <code>gflags/gflags.h</code>. Here's an example file,
+ <code>foo.cc</code>:
+ </p>
-<pre>
+ <pre>
#include <gflags/gflags.h>
DEFINE_bool(big_menu, true, "Include 'advanced' options in the menu listing");
DEFINE_string(languages, "english,french,german",
"comma-separated list of languages to offer in the 'lang' menu");
-</pre>
+ </pre>
-<p><code>DEFINE_bool</code> defines a boolean flag. Here are the
-types supported:</p>
-<ul>
- <li> <code>DEFINE_bool</code>: boolean
- <li> <code>DEFINE_int32</code>: 32-bit integer
- <li> <code>DEFINE_int64</code>: 64-bit integer
- <li> <code>DEFINE_uint64</code>: unsigned 64-bit integer
- <li> <code>DEFINE_double</code>: double
- <li> <code>DEFINE_string</code>: C++ string
-</ul>
+ <p><code>DEFINE_bool</code> defines a boolean flag. Here are the
+ types supported:</p>
+ <ul>
+ <li> <code>DEFINE_bool</code>: boolean
+ <li> <code>DEFINE_int32</code>: 32-bit integer
+ <li> <code>DEFINE_int64</code>: 64-bit integer
+ <li> <code>DEFINE_uint64</code>: unsigned 64-bit integer
+ <li> <code>DEFINE_double</code>: double
+ <li> <code>DEFINE_string</code>: C++ string
+ </ul>
-<p>Note that there are no 'complex' types like lists: the "languages"
-flag in our example is a list of strings, but is defined of type
-"string", not "list_of_string" or similar. This is by design. We'd
-rather use only simple types for the flags, and allow for complex,
-arbitrary parsing routines to parse them, than to try to put the logic
-inside the flags library proper.</p>
+ <p>Note that there are no 'complex' types like lists: the "languages"
+ flag in our example is a list of strings, but is defined of type
+ "string", not "list_of_string" or similar. This is by design. We'd
+ rather use only simple types for the flags, and allow for complex,
+ arbitrary parsing routines to parse them, than to try to put the logic
+ inside the flags library proper.</p>
-<p>All DEFINE macros take the same three arguments: the name of the
-flag, its default value, and a 'help' string that describes its use.
-The 'help' string is displayed when the user runs the application with
-the <A HREF="#special"><code>--help</code> flag</A>.</p>
+ <p>All DEFINE macros take the same three arguments: the name of the
+ flag, its default value, and a 'help' string that describes its use.
+ The 'help' string is displayed when the user runs the application with
+ the <A HREF="#special"><code>--help</code> flag</A>.</p>
-<p>You can define a flag in any source-code file in your executable.
-Only define a flag once! If you want to access a flag in more than
-one source file, DEFINE it in one file, and <A
-HREF="#declare">DECLARE</A> it in the others. Even better, DEFINE it
-in <code>foo.cc</code> and DECLARE it in <code>foo.h</code>; then
-everyone who <code>#includes foo.h</code> can use the flag.</p>
+ <p>You can define a flag in any source-code file in your executable.
+ Only define a flag once! If you want to access a flag in more than
+ one source file, DEFINE it in one file, and <A HREF="#declare">DECLARE</A> it in the others. Even better, DEFINE it
+ in <code>foo.cc</code> and DECLARE it in <code>foo.h</code>; then
+ everyone who <code>#includes foo.h</code> can use the flag.</p>
-<p>
-Defining flags in libraries rather than in main() is powerful, but
-does have some costs. One is that a library might not have a good
-default value for its flags, for example if the flag holds a
-filename that might not exist in some environments. To mitigate such problems,
-you can use <a href="#validate">flag validators</a> to ensure prompt
-notification (in the form of a crash) of an invalid flag value.
-</p>
+ <p>
+ Defining flags in libraries rather than in main() is powerful, but
+ does have some costs. One is that a library might not have a good
+ default value for its flags, for example if the flag holds a
+ filename that might not exist in some environments. To mitigate such problems,
+ you can use <a href="#validate">flag validators</a> to ensure prompt
+ notification (in the form of a crash) of an invalid flag value.
+ </p>
-<p>Note that while most functions in this library are defined in the
-<code>google</code> namespace, <code>DEFINE_foo</code> (and
-<code>DECLARE_foo</code>, <A HREF="#declare">below</A>), should always
-be in the global namespace.</p>
+ <p>Note that while most functions in this library are defined in the
+ <code>google</code> namespace, <code>DEFINE_foo</code> (and
+ <code>DECLARE_foo</code>, <A HREF="#declare">below</A>), should always
+ be in the global namespace.
+ </p>
-<h2> <A name=using>Accessing the Flag</A> </h2>
+ <h2> <A name=using>Accessing the Flag</A> </h2>
-<p>All defined flags are available to the program as just a normal
-variable, with the prefix <code>FLAGS_</code> prepended. In the above
-example, the macros define two variables, <code>FLAGS_big_menu</code>
-(a bool), and <code>FLAGS_languages</code> (a C++ string).</p>
+ <p>All defined flags are available to the program as just a normal
+ variable, with the prefix <code>FLAGS_</code> prepended. In the above
+ example, the macros define two variables, <code>FLAGS_big_menu</code>
+ (a bool), and <code>FLAGS_languages</code> (a C++ string).</p>
-<p>You can read and write to the flag just like any other
-variable:</p>
-<pre>
+ <p>You can read and write to the flag just like any other
+ variable:</p>
+ <pre>
if (FLAGS_consider_made_up_languages)
FLAGS_languages += ",klingon"; // implied by --consider_made_up_languages
if (FLAGS_languages.find("finnish") != string::npos)
HandleFinnish();
-</pre>
+ </pre>
-<p>You can also get and set flag values via special functions in
-<code>gflags.h</code>. That's a rarer use case, though.</p>
+ <p>You can also get and set flag values via special functions in
+ <code>gflags.h</code>. That's a rarer use case, though.
+ </p>
-<h2> <A name=declare>DECLARE: Using the Flag in a Different File</A> </h2>
+ <h2> <A name=declare>DECLARE: Using the Flag in a Different File</A> </h2>
-<p>Accessing a flag in the manner of the previous section only works
-if the flag was <code>DEFINE</code>-ed at the top of the file. If it
-wasn't, you'll get an 'unknown variable' error.</p>
+ <p>Accessing a flag in the manner of the previous section only works
+ if the flag was <code>DEFINE</code>-ed at the top of the file. If it
+ wasn't, you'll get an 'unknown variable' error.</p>
-<p>The <code>DECLARE_type</code> macro is available when you want to
-use a flag that's defined in another file. For instance, if I were
-writing <code>bar.cc</code> but wanted to access the big_menu, flag, I
-would put this near the top of <code>bar.cc</code>:</p>
-<pre>
+ <p>The <code>DECLARE_type</code> macro is available when you want to
+ use a flag that's defined in another file. For instance, if I were
+ writing <code>bar.cc</code> but wanted to access the big_menu, flag, I
+ would put this near the top of <code>bar.cc</code>:</p>
+ <pre>
DECLARE_bool(big_menu);
-</pre>
+ </pre>
-<p>This is functionally equivalent to saying <code>extern
+ <p>This is functionally equivalent to saying <code>extern
FLAGS_big_menu</code>.</p>
-<p>Note that such an extern declaration introduces a dependency
-between your file and the file that defines the <code>big_menu</code>
-flag: <code>foo.cc</code>, in this case. Such implicit dependencies
-can be difficult to manage in large projects. For that reason we
-recommend the following guideline:</p>
+ <p>Note that such an extern declaration introduces a dependency
+ between your file and the file that defines the <code>big_menu</code>
+ flag: <code>foo.cc</code>, in this case. Such implicit dependencies
+ can be difficult to manage in large projects. For that reason we
+ recommend the following guideline:</p>
-<blockquote>
-If you DEFINE a flag in <code>foo.cc</code>, either don't DECLARE it
-at all, only DECLARE it in tightly related tests, or only DECLARE
-it in <code>foo.h</code>.
-</blockquote>
+ <blockquote>
+ If you DEFINE a flag in <code>foo.cc</code>, either don't DECLARE it
+ at all, only DECLARE it in tightly related tests, or only DECLARE
+ it in <code>foo.h</code>.
+ </blockquote>
-<p>You should go the do-not-DECLARE route when the flag is only needed
-by <code>foo.cc</code>, and not in any other file. If you want to
-modify the value of the flag in the related test file to see if it is
-functioning as expected, DECLARE it in the <code>foo_test.cc</code>
-file.
+ <p>You should go the do-not-DECLARE route when the flag is only needed
+ by <code>foo.cc</code>, and not in any other file. If you want to
+ modify the value of the flag in the related test file to see if it is
+ functioning as expected, DECLARE it in the <code>foo_test.cc</code>
+ file.
-<p>If the flag does span multiple files, DECLARE it in the associated
-<code>.h</code> file, and make others <code>#include</code> that
-<code>.h</code> file if they want to access the flag. The
-<code>#include</code> will make explicit the dependency between the
-two files. This causes the flag to be a global variable.</p>
+ <p>If the flag does span multiple files, DECLARE it in the associated
+ <code>.h</code> file, and make others <code>#include</code> that
+ <code>.h</code> file if they want to access the flag. The
+ <code>#include</code> will make explicit the dependency between the
+ two files. This causes the flag to be a global variable.
+ </p>
-<h2> <A name=validate>RegisterFlagValidator: Sanity-checking Flag Values</A> </h2>
+ <h2> <A name=validate>RegisterFlagValidator: Sanity-checking Flag Values</A> </h2>
-<p>After DEFINE-ing a flag, you may optionally register a validator
-function with the flag. If you do this, after the flag is parsed from
-the commandline, and whenever its value is changed via a call to
-<code>SetCommandLineOption()</code>, the validator function is called
-with the new value as an argument. The validator function should
-return 'true' if the flag value is valid, and false otherwise.
-If the function returns false for the new setting of the
-flag, the flag will retain its current value. If it returns false for the
-default value, ParseCommandLineFlags will die.
+ <p>After DEFINE-ing a flag, you may optionally register a validator
+ function with the flag. If you do this, after the flag is parsed from
+ the commandline, and whenever its value is changed via a call to
+ <code>SetCommandLineOption()</code>, the validator function is called
+ with the new value as an argument. The validator function should
+ return 'true' if the flag value is valid, and false otherwise.
+ If the function returns false for the new setting of the
+ flag, the flag will retain its current value. If it returns false for the
+ default value, ParseCommandLineFlags will die.
-<p>Here is an example use of this functionality:</p>
-<pre>
+ <p>Here is an example use of this functionality:</p>
+ <pre>
static bool ValidatePort(const char* flagname, int32 value) {
if (value > 0 && value < 32768) // value is ok
return true;
@@ -320,319 +337,346 @@
}
DEFINE_int32(port, 0, "What port to listen on");
DEFINE_validator(port, &ValidatePort);
-</pre>
+ </pre>
-<p>By doing the registration at global initialization time (right
-after the DEFINE_int32), we ensure that the registration happens before
-the commandline is parsed at the beginning of <code>main()</code>.</p>
+ <p>By doing the registration at global initialization time (right
+ after the DEFINE_int32), we ensure that the registration happens before
+ the commandline is parsed at the beginning of <code>main()</code>.</p>
-<p>The above used <code>DEFINE_validator</code> macro calls the
-<code>RegisterFlagValidator()</code> function which returns true if the
-registration is successful. It returns false if the registration fails
-because a) the first argument does not refer to a commandline flag, or
-b) a different validator has already been registered for this flag.
-The return value is available as global static boolean variable named
-<code><flag>_validator_registered</code>.</p>
+ <p>The above used <code>DEFINE_validator</code> macro calls the
+ <code>RegisterFlagValidator()</code> function which returns true if the
+ registration is successful. It returns false if the registration fails
+ because a) the first argument does not refer to a commandline flag, or
+ b) a different validator has already been registered for this flag.
+ The return value is available as global static boolean variable named
+ <code><flag>_validator_registered</code>.
+ </p>
-<h2> <A name=together>Putting It Together: How to Set Up Flags</A> </h2>
+ <h2> <A name=together>Putting It Together: How to Set Up Flags</A> </h2>
-<p>The final piece is the one that tells the executable to process the
-commandline flags, and set the <code>FLAGS_*</code> variables to the
-appropriate, non-default value based on what is seen on the
-commandline. This is equivalent to the <code>getopt()</code> call in
-the getopt library, but has much less overhead to use. In fact, it's
-just a single function call:</p>
+ <p>The final piece is the one that tells the executable to process the
+ commandline flags, and set the <code>FLAGS_*</code> variables to the
+ appropriate, non-default value based on what is seen on the
+ commandline. This is equivalent to the <code>getopt()</code> call in
+ the getopt library, but has much less overhead to use. In fact, it's
+ just a single function call:</p>
-<pre>
+ <pre>
gflags::ParseCommandLineFlags(&argc, &argv, true);
-</pre>
+ </pre>
-<p>Usually, this code is at the beginning of <code>main()</code>.
-<code>argc</code> and <code>argv</code> are exactly as passed in to
-<code>main()</code>. This routine might modify them, which is why
-pointers to them are passed in.</p>
+ <p>Usually, this code is at the beginning of <code>main()</code>.
+ <code>argc</code> and <code>argv</code> are exactly as passed in to
+ <code>main()</code>. This routine might modify them, which is why
+ pointers to them are passed in.
+ </p>
-<p>The last argument is called "remove_flags". If true, then
-<code>ParseCommandLineFlags</code> removes the flags and their
-arguments from <code>argv</code>, and modifies <code>argc</code>
-appropriately. In this case, after the function call,
-<code>argv</code> will hold only commandline arguments, and not
-commandline flags.</p>
+ <p>The last argument is called "remove_flags". If true, then
+ <code>ParseCommandLineFlags</code> removes the flags and their
+ arguments from <code>argv</code>, and modifies <code>argc</code>
+ appropriately. In this case, after the function call,
+ <code>argv</code> will hold only commandline arguments, and not
+ commandline flags.
+ </p>
-<p>If, on the other hand, <code>remove_flags</code> is false, then
-<code>ParseCommandLineFlags</code> will leave argc unchanged, but will
-rearrange the arguments in argv so that the flags are all at the
-beginning. For example, if the input is <code>"/bin/foo" "arg1" "-q"
+ <p>If, on the other hand, <code>remove_flags</code> is false, then
+ <code>ParseCommandLineFlags</code> will leave argc unchanged, but will
+ rearrange the arguments in argv so that the flags are all at the
+ beginning. For example, if the input is <code>"/bin/foo" "arg1" "-q"
"arg2"</code> (which is legal but weird), the function will rearrange
-<code>argv</code> so it reads <code>"/bin/foo", "-q", "arg1",
-"arg2"</code>. In this case, <code>ParseCommandLineFlags</code>
-returns the index into argv that holds the first commandline argument:
-that is, the index past the last flag. (In this example, it would
-return 2, since <code>argv[2]</code> points to <code>arg1</code>.)</p>
+ <code>argv</code> so it reads <code>"/bin/foo", "-q", "arg1",
+"arg2"</code>. In this case, <code>ParseCommandLineFlags</code>
+ returns the index into argv that holds the first commandline argument:
+ that is, the index past the last flag. (In this example, it would
+ return 2, since <code>argv[2]</code> points to <code>arg1</code>.)
+ </p>
-<p>In either case, the <code>FLAGS_*</code> variables are modified
-based on what was <A HREF="#commandline">passed in on the
-commandline</A>.</p>
+ <p>In either case, the <code>FLAGS_*</code> variables are modified
+ based on what was <A HREF="#commandline">passed in on the
+ commandline</A>.</p>
-<h2> <A name=commandline>Setting Flags on the Command Line</A> </h2>
+ <h2> <A name=commandline>Setting Flags on the Command Line</A> </h2>
-<p>The reason you make something a flag instead of a compile-time
-constant, is so users can specify a non-default value on the
-commandline. Here's how they might do it for an application that
-links in <code>foo.cc</code>:</p>
-<pre>
+ <p>The reason you make something a flag instead of a compile-time
+ constant, is so users can specify a non-default value on the
+ commandline. Here's how they might do it for an application that
+ links in <code>foo.cc</code>:</p>
+ <pre>
app_containing_foo --nobig_menu -languages="chinese,japanese,korean" ...
-</pre>
+ </pre>
-<p>This sets <code>FLAGS_big_menu = false;</code> and
-<code>FLAGS_languages = "chinese,japanese,korean"</code>, when
-<code>ParseCommandLineFlags</code> is run.</p>
+ <p>This sets <code>FLAGS_big_menu = false;</code> and
+ <code>FLAGS_languages = "chinese,japanese,korean"</code>, when
+ <code>ParseCommandLineFlags</code> is run.
+ </p>
-<p>Note the atypical syntax for setting a boolean flag to false:
-putting "no" in front of its name. There's a fair bit of flexibility
-to how flags may be specified. Here's an example of all the ways to
-specify the "languages" flag:</p>
-<ul>
- <li> <code>app_containing_foo --languages="chinese,japanese,korean"</code>
- <li> <code>app_containing_foo -languages="chinese,japanese,korean"</code>
- <li> <code>app_containing_foo --languages "chinese,japanese,korean"</code>
- <li> <code>app_containing_foo -languages "chinese,japanese,korean"</code>
-</ul>
+ <p>Note the atypical syntax for setting a boolean flag to false:
+ putting "no" in front of its name. There's a fair bit of flexibility
+ to how flags may be specified. Here's an example of all the ways to
+ specify the "languages" flag:</p>
+ <ul>
+ <li> <code>app_containing_foo --languages="chinese,japanese,korean"</code>
+ <li> <code>app_containing_foo -languages="chinese,japanese,korean"</code>
+ <li> <code>app_containing_foo --languages "chinese,japanese,korean"</code>
+ <li> <code>app_containing_foo -languages "chinese,japanese,korean"</code>
+ </ul>
-<p>For boolean flags, the possibilities are slightly different:</p>
-<ul>
- <li> <code>app_containing_foo --big_menu</code>
- <li> <code>app_containing_foo --nobig_menu</code>
- <li> <code>app_containing_foo --big_menu=true</code>
- <li> <code>app_containing_foo --big_menu=false</code>
-</ul>
-<p>(as well as the single-dash variant on all of these).</p>
+ <p>For boolean flags, the possibilities are slightly different:</p>
+ <ul>
+ <li> <code>app_containing_foo --big_menu</code>
+ <li> <code>app_containing_foo --nobig_menu</code>
+ <li> <code>app_containing_foo --big_menu=true</code>
+ <li> <code>app_containing_foo --big_menu=false</code>
+ </ul>
+ <p>(as well as the single-dash variant on all of these).</p>
-<p>Despite this flexibility, we recommend using only a single form:
-<code>--variable=value</code> for non-boolean flags, and
-<code>--variable/--novariable</code> for boolean flags. This
-consistency will make your code more readable, and is also the format
-required for certain special-use cases like <A
-HREF="#flagfiles">flagfiles</A>.</p>
+ <p>Despite this flexibility, we recommend using only a single form:
+ <code>--variable=value</code> for non-boolean flags, and
+ <code>--variable/--novariable</code> for boolean flags. This
+ consistency will make your code more readable, and is also the format
+ required for certain special-use cases like <A HREF="#flagfiles">flagfiles</A>.
+ </p>
-<p>It is a fatal error to specify a flag on the commandline that has
-not been DEFINED somewhere in the executable. If you need that
-functionality for some reason -- say you want to use the same set of
-flags for several executables, but not all of them DEFINE every flag
-in your list -- you can specify <A
-HREF="#special"><code>--undefok</code></A> to suppress the error.</p>
+ <p>It is a fatal error to specify a flag on the commandline that has
+ not been DEFINED somewhere in the executable. If you need that
+ functionality for some reason -- say you want to use the same set of
+ flags for several executables, but not all of them DEFINE every flag
+ in your list -- you can specify <A HREF="#special"><code>--undefok</code></A> to suppress the error.</p>
-<p>As in getopt(), <code>--</code> by itself will terminate flags
-processing. So in <code>foo -f1 1 -- -f2 2</code>, <code>f1</code> is
-considered a flag, but <code>-f2</code> is not.</p>
+ <p>As in getopt(), <code>--</code> by itself will terminate flags
+ processing. So in <code>foo -f1 1 -- -f2 2</code>, <code>f1</code> is
+ considered a flag, but <code>-f2</code> is not.</p>
-<p>If a flag is specified more than once, only the last specification
-is used; the others are ignored.</p>
+ <p>If a flag is specified more than once, only the last specification
+ is used; the others are ignored.</p>
-<p>Note that flags do not have single-letter synonyms, like they do in
-the getopt library, nor do we allow "combining" flags behind a
-single dash, as in <code>ls -la</code>.</p>
+ <p>Note that flags do not have single-letter synonyms, like they do in
+ the getopt library, nor do we allow "combining" flags behind a
+ single dash, as in <code>ls -la</code>.</p>
-<h2> <A name=default>Changing the Default Flag Value</A> </h2>
+ <h2> <A name=default>Changing the Default Flag Value</A> </h2>
-<p>Sometimes a flag is defined in a library, and you want to change
-its default value in one application but not others. It's simple to
-do this: just assign a new value to the flag in <code>main()</code>,
-before calling <code>ParseCommandLineFlags()</code>:</p>
-<pre>
+ <p>Sometimes a flag is defined in a library, and you want to change
+ its default value in one application but not others. It's simple to
+ do this: just assign a new value to the flag in <code>main()</code>,
+ before calling <code>ParseCommandLineFlags()</code>:</p>
+ <pre>
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(...);
}
-</pre>
+ </pre>
-<p>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.</p>
+ <p>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.</p>
-<h2> <A name="special">Special Flags</a> </h2>
+ <h2> <A name="special">Special Flags</a> </h2>
-<p>There are a few flags defined by the commandlineflags module
-itself, and are available to all applications that use
-commandlineflags. These fall into
-three categories. First are the 'reporting' flags that, when found, cause
-the application to print some information about itself and exit.</p>
+ <p>There are a few flags defined by the commandlineflags module
+ itself, and are available to all applications that use
+ commandlineflags. These fall into
+ three categories. First are the 'reporting' flags that, when found, cause
+ the application to print some information about itself and exit.</p>
-<table><tr valign=top>
- <td><code>--help</code></td>
- <td>shows all flags from all files, sorted by file and then by name;
- shows the flagname, its default value, and its help string</td>
-</tr><tr valign=top>
- <td><code>--helpfull</code></td>
- <td>same as -help, but unambiguously asks for all flags
- (in case -help changes in the future)</td>
-</tr><tr valign=top>
- <td><code>--helpshort</code></td>
- <td>shows only flags for the file with the same name as the executable
- (usually the one containing <code>main()</code>)</td>
-</tr><tr valign=top>
- <td><code>--helpxml</code></td>
- <td>like --help, but output is in xml for easier parsing</td>
-</tr><tr valign=top>
- <td><code>--helpon=FILE </code></td>
- <td>shows only flags defined in FILE.*</td>
-</tr><tr valign=top>
- <td><code>--helpmatch=S</code></td>
- <td>shows only flags defined in *S*.*</td>
-</tr><tr valign=top>
- <td><code>--helppackage</code></td>
- <td>shows flags defined in files in same directory as <code>main()</code></td>
-</tr><tr valign=top>
- <td><code>--version</code></td>
- <td>prints version info for the executable</td>
-</tr></table>
+ <table>
+ <tr valign=top>
+ <td><code>--help</code></td>
+ <td>shows all flags from all files, sorted by file and then by name;
+ shows the flagname, its default value, and its help string</td>
+ </tr>
+ <tr valign=top>
+ <td><code>--helpfull</code></td>
+ <td>same as -help, but unambiguously asks for all flags
+ (in case -help changes in the future)</td>
+ </tr>
+ <tr valign=top>
+ <td><code>--helpshort</code></td>
+ <td>shows only flags for the file with the same name as the executable
+ (usually the one containing <code>main()</code>)</td>
+ </tr>
+ <tr valign=top>
+ <td><code>--helpxml</code></td>
+ <td>like --help, but output is in xml for easier parsing</td>
+ </tr>
+ <tr valign=top>
+ <td><code>--helpon=FILE </code></td>
+ <td>shows only flags defined in FILE.*</td>
+ </tr>
+ <tr valign=top>
+ <td><code>--helpmatch=S</code></td>
+ <td>shows only flags defined in *S*.*</td>
+ </tr>
+ <tr valign=top>
+ <td><code>--helppackage</code></td>
+ <td>shows flags defined in files in same directory as <code>main()</code></td>
+ </tr>
+ <tr valign=top>
+ <td><code>--version</code></td>
+ <td>prints version info for the executable</td>
+ </tr>
+ </table>
-<p>Second are the flags that affect how other flags are parsed.</p>
+ <p>Second are the flags that affect how other flags are parsed.</p>
-<table><tr valign=top>
- <td><code>--undefok=flagname,flagname,...</code></td>
- <td>for those names listed as the argument to <code>--undefok</code>,
- suppress the normal error-exit that occurs when
- <code>--name</code> is seen on the commandline, but
- <code>name</code> has not been DEFINED anywhere in the
- application
-</table>
+ <table>
+ <tr valign=top>
+ <td><code>--undefok=flagname,flagname,...</code></td>
+ <td>for those names listed as the argument to <code>--undefok</code>,
+ suppress the normal error-exit that occurs when
+ <code>--name</code> is seen on the commandline, but
+ <code>name</code> has not been DEFINED anywhere in the
+ application
+ </table>
-<p>Third are the 'recursive' flags, that cause other flag values to be
-set: <code>--fromenv</code>, <code>--tryfromenv</code>,
-<code>--flagfile</code>. These are described below in more
-detail.</p>
+ <p>Third are the 'recursive' flags, that cause other flag values to be
+ set: <code>--fromenv</code>, <code>--tryfromenv</code>,
+ <code>--flagfile</code>. These are described below in more
+ detail.
+ </p>
-<h3> <code>--fromenv</code> </h3>
+ <h3> <code>--fromenv</code> </h3>
-<p><code>--fromenv=foo,bar</code> says to read the values for the
-<code>foo</code> and <code>bar</code> flags from the environment.
-In concert with this flag, you must actually set the values in the
-environment, via a line like one of the two below:</p>
-<pre>
+ <p><code>--fromenv=foo,bar</code> says to read the values for the
+ <code>foo</code> and <code>bar</code> flags from the environment.
+ In concert with this flag, you must actually set the values in the
+ environment, via a line like one of the two below:
+ </p>
+ <pre>
export FLAGS_foo=xxx; export FLAGS_bar=yyy # sh
setenv FLAGS_foo xxx; setenv FLAGS_bar yyy # tcsh
-</pre>
-<p>This is equivalent to specifying <code>--foo=xxx</code>,
-<code>--bar=yyy</code> on the commandline.</p>
+ </pre>
+ <p>This is equivalent to specifying <code>--foo=xxx</code>,
+ <code>--bar=yyy</code> on the commandline.
+ </p>
-<p>Note it is a fatal error to say <code>--fromenv=foo</code> if
-<code>foo</code> is not DEFINED somewhere in the application. (Though
-you can suppress this error via <code>--undefok=foo</code>, just like
-for any other flag.)</p>
+ <p>Note it is a fatal error to say <code>--fromenv=foo</code> if
+ <code>foo</code> is not DEFINED somewhere in the application. (Though
+ you can suppress this error via <code>--undefok=foo</code>, just like
+ for any other flag.)
+ </p>
-<p>It is also a fatal error to say <code>--fromenv=foo</code> if
-<code>FLAGS_foo</code> is not actually defined in the environment.</p>
+ <p>It is also a fatal error to say <code>--fromenv=foo</code> if
+ <code>FLAGS_foo</code> is not actually defined in the environment.
+ </p>
-<h3> <code>--tryfromenv</code> </h3>
+ <h3> <code>--tryfromenv</code> </h3>
-<p><code>--tryfromenv</code> is exactly like <code>--fromenv</code>,
-except it is <b>not</b> a fatal error to say
-<code>--tryfromenv=foo</code> if <code>FLAGS_foo</code> is not
-actually defined in the environment. Instead, in such cases,
-<code>FLAGS_foo</code> just keeps its default value as specified in
-the application.</p>
+ <p><code>--tryfromenv</code> is exactly like <code>--fromenv</code>,
+ except it is <b>not</b> a fatal error to say
+ <code>--tryfromenv=foo</code> if <code>FLAGS_foo</code> is not
+ actually defined in the environment. Instead, in such cases,
+ <code>FLAGS_foo</code> just keeps its default value as specified in
+ the application.
+ </p>
-<p>Note it is still an error to say <code>--tryfromenv=foo</code> if
-<code>foo</code> is not DEFINED somewhere in the application.</p>
+ <p>Note it is still an error to say <code>--tryfromenv=foo</code> if
+ <code>foo</code> is not DEFINED somewhere in the application.
+ </p>
-<h3 id="flagfiles"> <code>--flagfile</code> </h3>
+ <h3 id="flagfiles"> <code>--flagfile</code> </h3>
-<p><code>--flagfile=f</code> tells the commandlineflags module to read
-the file <code>f</code>, and to run all the flag-assignments found in
-that file as if these flags had been specified on the commandline.</p>
+ <p><code>--flagfile=f</code> tells the commandlineflags module to read
+ the file <code>f</code>, and to run all the flag-assignments found in
+ that file as if these flags had been specified on the commandline.</p>
-<p>In its simplest form, <code>f</code> should just be a list of flag
-assignments, one per line. Unlike on the commandline, the equals sign
-separating a flagname from its argument is <i>required</i> for
-flagfiles. An example flagfile, <code>/tmp/myflags</code>:</p>
-<pre>
+ <p>In its simplest form, <code>f</code> should just be a list of flag
+ assignments, one per line. Unlike on the commandline, the equals sign
+ separating a flagname from its argument is <i>required</i> for
+ flagfiles. An example flagfile, <code>/tmp/myflags</code>:</p>
+ <pre>
--nobig_menus
--languages=english,french
</pre>
-<p>With this flagfile, the following two lines are equivalent:<p>
-<pre>
+ <p>With this flagfile, the following two lines are equivalent:
+ <p>
+ <pre>
./myapp --foo --nobig_menus --languages=english,french --bar
./myapp --foo --flagfile=/tmp/myflags --bar
-</pre>
+ </pre>
-<p>Note that many errors are silently suppressed in flagfiles. In
-particular, unrecognized flagnames are silently ignored, as are flags
-that are missing a required value (e.g., a flagfile that just says
-<code>--languages</code>).</p>
+ <p>Note that many errors are silently suppressed in flagfiles. In
+ particular, unrecognized flagnames are silently ignored, as are flags
+ that are missing a required value (e.g., a flagfile that just says
+ <code>--languages</code>).
+ </p>
-<p>The general format of a flagfile is a bit more complicated than the
-simple, common case above. It is: a sequence of filenames, one per
-line, followed by a sequence of flags, one per line, repeated as many
-times as desired. Filenames in a flagfile can use wildcards
-(<code>*</code> and <code>?</code>), and the sequence of flags located
-after a sequence of filenames is processed only if the current
-executable's name matches one of the filenames. It is possible to
-start the flagfile with a sequence of flags instead of a sequence of
-filenames; if such a sequence of flags is present, these flags are
-applied to the current executable no matter what it is.</p>
+ <p>The general format of a flagfile is a bit more complicated than the
+ simple, common case above. It is: a sequence of filenames, one per
+ line, followed by a sequence of flags, one per line, repeated as many
+ times as desired. Filenames in a flagfile can use wildcards
+ (<code>*</code> and <code>?</code>), and the sequence of flags located
+ after a sequence of filenames is processed only if the current
+ executable's name matches one of the filenames. It is possible to
+ start the flagfile with a sequence of flags instead of a sequence of
+ filenames; if such a sequence of flags is present, these flags are
+ applied to the current executable no matter what it is.</p>
-<p>Lines that start with a <code>#</code> are ignored as comments.
-Leading whitespace is also ignored in flagfiles, as are blank
-lines.</p>
+ <p>Lines that start with a <code>#</code> are ignored as comments.
+ Leading whitespace is also ignored in flagfiles, as are blank
+ lines.</p>
-<p>It is possible for a flagfile to use the <code>--flagfile</code>
-flag to include another flagfile.</p>
+ <p>It is possible for a flagfile to use the <code>--flagfile</code>
+ flag to include another flagfile.</p>
-<p>Flags are always processed in the expected order. That is,
-processing begins by examining the flags specified directly on the
-command line. If a flagfile is specified, its contents are processed,
-and then processing continues with remaining flags from the command
-line.</p>
+ <p>Flags are always processed in the expected order. That is,
+ processing begins by examining the flags specified directly on the
+ command line. If a flagfile is specified, its contents are processed,
+ and then processing continues with remaining flags from the command
+ line.</p>
-<h2> <A name="api">The API</a> </h2>
+ <h2> <A name="api">The API</a> </h2>
-<p>In addition to accessing <code>FLAGS_foo</code> directly, it is
-possible to access the flags programmatically, through an API. It is
-also possible to access information about a flag, such as its default
-value and help-string. A <code>FlagSaver</code> makes it easy to
-modify flags and then automatically undo the modifications later.
-Finally, there are somewhat unrelated, but useful, routines to easily
-access parts of <code>argv</code> outside main, including the program
-name (<code>argv[0]</code>).</p>
+ <p>In addition to accessing <code>FLAGS_foo</code> directly, it is
+ possible to access the flags programmatically, through an API. It is
+ also possible to access information about a flag, such as its default
+ value and help-string. A <code>FlagSaver</code> makes it easy to
+ modify flags and then automatically undo the modifications later.
+ Finally, there are somewhat unrelated, but useful, routines to easily
+ access parts of <code>argv</code> outside main, including the program
+ name (<code>argv[0]</code>).</p>
-<p>For more information about these routines, and other useful helper
-methods such as <code>gflags::SetUsageMessage()</code> and
-<code>gflags::SetVersionString</code>, see <code>gflags.h</code>.</p>
+ <p>For more information about these routines, and other useful helper
+ methods such as <code>gflags::SetUsageMessage()</code> and
+ <code>gflags::SetVersionString</code>, see <code>gflags.h</code>.
+ </p>
-<h2> <A name="misc">Miscellaneous Notes</code> </h2>
+ <h2> <A name="misc">Miscellaneous Notes</code> </h2>
-<p>If your application has code like this:</p>
-<pre>
+ <p>If your application has code like this:</p>
+ <pre>
#define STRIP_FLAG_HELP 1 // this must go before the #include!
#include <gflags/gflags.h>
-</pre>
-<p>we will remove the help messages from the compiled source. This can
-reduce the size of the resulting binary somewhat, and may also be
-useful for security reasons.</p>
+ </pre>
+ <p>we will remove the help messages from the compiled source. This can
+ reduce the size of the resulting binary somewhat, and may also be
+ useful for security reasons.</p>
-<h2> <A name="issues">Issues and Feature Requests</code> </h2>
+ <h2> <A name="issues">Issues and Feature Requests</code> </h2>
-<p>Please report any issues or ideas for additional features on <A href="https://github.com/gflags/gflags/issues">GitHub</A>.
-We would also like to encourage <A href="https://github.com/gflags/gflags/pulls">pull requests</A> for bug fixes and implementations of new features.</p>
+ <p>Please report any issues or ideas for additional features on <A
+ href="https://github.com/gflags/gflags/issues">GitHub</A>.
+ We would also like to encourage <A href="https://github.com/gflags/gflags/pulls">pull requests</A> for bug fixes and
+ implementations of new features.</p>
-<hr>
-<address>
-Craig Silverstein, Andreas Schuh<br>
-<script type=text/javascript>
- var lm = new Date(document.lastModified);
- document.write(lm.toDateString());
-</script>
-</address>
+ <hr>
+ <address>
+ Craig Silverstein, Andreas Schuh<br>
+ <script type=text/javascript>
+ var lm = new Date(document.lastModified);
+ document.write(lm.toDateString());
+ </script>
+ </address>
</body>
-</html>
+
+</html>
\ No newline at end of file
