From 957aa3aa622d48839c99a51eb8f8b1f55d16b06b Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Tue, 24 Mar 2015 13:13:50 +0000 Subject: [PATCH 01/14] doc: Add download and issue report instructions to project page --- index.html | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/index.html b/index.html index 3a66713..25b7f59 100644 --- a/index.html +++ b/index.html @@ -38,6 +38,7 @@
Table of contents
Introduction
+
Download and Installation
Finding and Linking to gflags using CMake
DEFINE: Defining Flags In Program
Accessing the Flag
@@ -49,6 +50,8 @@
Changing the Default Flag Value
Special Flags
The API
+
Miscellaneous Notes
+
Issues and Feature Requests

@@ -91,6 +94,15 @@ 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.

+

Download and Installation

+ +

The gflags library can be downloaded from GitHub. +You can clone the project using the command:

+
+   git clone git@github.com:schuhschuh/gflags.git
+
+

Build and installation instructions are provided in the INSTALL file.

+

Finding and Linking to gflags using CMake

Using gflags within a project which uses CMake for its build system is easy. Therefore, simply add the following CMake code to your CMakeLists.txt file. @@ -544,6 +556,10 @@ methods such as gflags::SetUsageMessage() and reduce the size of the resulting binary somewhat, and may also be useful for security reasons.

+

Issues and Feature Requests

+ +

Please report any issues or ideas for additional features on GitHub. +We would also like to encourage pull requests for bug fixes and implementations of new features.

From 3398e7b0c920e84a137b1860f838b7d353d23e75 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Tue, 24 Mar 2015 15:04:35 +0000 Subject: [PATCH 02/14] doc: Remove no longer needed include_directories command from CMake example --- index.html | 2 -- 1 file changed, 2 deletions(-) diff --git a/index.html b/index.html index 25b7f59..5c43cb7 100644 --- a/index.html +++ b/index.html @@ -109,8 +109,6 @@ You can clone the project using the command:

    find_package (gflags REQUIRED)
-   include_directories (${gflags_INCLUDE_DIR})
-   
    add_executable (foo main.cc)
    target_link_libraries (foo gflags)
From d7a69edf6697dd6a2b062ccf5a963883f1457e98 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Tue, 24 Mar 2015 19:13:18 +0000 Subject: [PATCH 03/14] doc: Update CMake example and demonstrate use of config options --- index.html | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/index.html b/index.html index 5c43cb7..56037aa 100644 --- a/index.html +++ b/index.html @@ -107,10 +107,29 @@ You can clone the project using the command:

Using gflags within a project which uses CMake for its build system is easy. Therefore, simply add the following CMake code to your CMakeLists.txt file. +

The following CMake variables can be set to request a particular imported gflags library target +to link against. By default, the multi-threaded gflags library with static linkage is chosen if available. +It is recommended to only define these variables if a specific library must be used. +Otherwise, the gflags-config.cmake module will choose a suitable and available library for you. +These configuration options can also be added to the CMake cache (using CMake's option command) so they can +be modified via the CMake GUI or specified as arguments to CMake instead, e.g., +"cmake -D gflags_SHARED:BOOL=TRUE -D gflags_NOTHREADS:BOOL=FALSE <gflags_source_dir>".

-   find_package (gflags REQUIRED)
-   add_executable (foo main.cc)
-   target_link_libraries (foo gflags)
+   set(gflags_SHARED    FALSE)
+   set(gflags_NOTHREADS FALSE)
+
+ +

Find gflags installation. The gflags_DIR 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.

+
+   find_package(gflags REQUIRED)
+
+

Finally, add your executable build target which uses gflags to parse the command arguments with dependency on the +imported gflags library target:

+
+   add_executable(foo main.cc)
+   target_link_libraries(foo ${gflags_LIBRARIES})

DEFINE: Defining Flags In Program

From 73bb1e87c94e1aaa1969bc9bf0c4144ee0ee0f70 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Tue, 24 Mar 2015 23:07:20 +0000 Subject: [PATCH 04/14] fix: GitHub URLs to point to gflags organization --- index.html | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/index.html b/index.html index 56037aa..2d04378 100644 --- a/index.html +++ b/index.html @@ -96,12 +96,12 @@ translates directly to Python.

Download and Installation

-

The gflags library can be downloaded from GitHub. +

The gflags library can be downloaded from GitHub. You can clone the project using the command:

-   git clone git@github.com:schuhschuh/gflags.git
+   git clone git@github.com:gflags/gflags.git
-

Build and installation instructions are provided in the INSTALL file.

+

Build and installation instructions are provided in the INSTALL file.

Finding and Linking to gflags using CMake

@@ -575,8 +575,8 @@ useful for security reasons.

Issues and Feature Requests

-

Please report any issues or ideas for additional features on GitHub. -We would also like to encourage pull requests for bug fixes and implementations of new features.

+

Please report any issues or ideas for additional features on GitHub. +We would also like to encourage pull requests for bug fixes and implementations of new features.

From 745082dbd385905c800295d50df38c9a6de22475 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Tue, 24 Mar 2015 23:09:53 +0000 Subject: [PATCH 05/14] fix: Example CMake command --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 2d04378..4a53e00 100644 --- a/index.html +++ b/index.html @@ -113,7 +113,7 @@ It is recommended to only define these variables if a specific library must be u Otherwise, the gflags-config.cmake module will choose a suitable and available library for you. These configuration options can also be added to the CMake cache (using CMake's option command) so they can be modified via the CMake GUI or specified as arguments to CMake instead, e.g., -"cmake -D gflags_SHARED:BOOL=TRUE -D gflags_NOTHREADS:BOOL=FALSE <gflags_source_dir>".

+"cmake -D gflags_SHARED:BOOL=TRUE -D gflags_NOTHREADS:BOOL=FALSE <foo_source_dir>".

    set(gflags_SHARED    FALSE)
    set(gflags_NOTHREADS FALSE)

From e1d15b33406ec571095e7a91dbc4b2ada1ae3bac Mon Sep 17 00:00:00 2001
From: Andreas Schuh 
Date: Wed, 25 Mar 2015 03:13:22 +0000
Subject: [PATCH 06/14] doc: Use "gflags" as link dependency instead of
 ${gflags_LIBRARIES}

---
 index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.html b/index.html
index 4a53e00..c844ee9 100644
--- a/index.html
+++ b/index.html
@@ -129,7 +129,7 @@ the gflags installation automatically.

 imported gflags library target:

 
    add_executable(foo main.cc)
-   target_link_libraries(foo ${gflags_LIBRARIES})
+   target_link_libraries(foo gflags)
 

 
 
 DEFINE: Defining Flags In Program 


From 16651b78706e7ac3a1697146dd3b41f885ac73f1 Mon Sep 17 00:00:00 2001
From: Andreas Schuh 
Date: Fri, 19 Feb 2016 13:43:27 +0000
Subject: [PATCH 07/14] #115 Use HTTPS as default Git clone protocol

---
 index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.html b/index.html
index c844ee9..5b13c58 100644
--- a/index.html
+++ b/index.html
@@ -99,7 +99,7 @@ translates directly to Python.

 
The gflags library can be downloaded from GitHub.
 You can clone the project using the command:

 
-   git clone git@github.com:gflags/gflags.git
+   git clone https://github.com/gflags/gflags.git
 

 
Build and installation instructions are provided in the INSTALL file.

 

From ea1cc83b50dc44df1f38891d9c95e99e2f127a80 Mon Sep 17 00:00:00 2001
From: Andreas Schuh 
Date: Tue, 1 Mar 2016 22:00:58 +0000
Subject: [PATCH 08/14] doc: Use of find_package COMPONENTS or inclusion as
 subproject

---
 index.html | 41 +++++++++++++++++++++++++----------------
 1 file changed, 25 insertions(+), 16 deletions(-)

diff --git a/index.html b/index.html
index 5b13c58..d3aee33 100644
--- a/index.html
+++ b/index.html
@@ -39,7 +39,7 @@
   
 Table of contents 

   
 Introduction 

   
 Download and Installation 

-  
 Finding and Linking to gflags using CMake

+  
 Linking to gflags using CMake

   
 DEFINE: Defining Flags In Program 

   
 Accessing the Flag 

   
 DECLARE: Using the Flag in a Different File 

@@ -103,28 +103,37 @@ You can clone the project using the command:

Build and installation instructions are provided in the INSTALL file.

-

Finding and Linking to gflags using CMake

+

Linking to gflags using CMake

-

Using gflags within a project which uses CMake for its build system is easy. Therefore, simply add the following CMake code to your CMakeLists.txt file. +

Using gflags within a project which uses CMake 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. + +

To use an external gflags installation, add the following CMake code to your CMakeLists.txt file.

-

The following CMake variables can be set to request a particular imported gflags library target -to link against. By default, the multi-threaded gflags library with static linkage is chosen if available. -It is recommended to only define these variables if a specific library must be used. -Otherwise, the gflags-config.cmake module will choose a suitable and available library for you. -These configuration options can also be added to the CMake cache (using CMake's option command) so they can -be modified via the CMake GUI or specified as arguments to CMake instead, e.g., -"cmake -D gflags_SHARED:BOOL=TRUE -D gflags_NOTHREADS:BOOL=FALSE <foo_source_dir>".

-
-   set(gflags_SHARED    FALSE)
-   set(gflags_NOTHREADS FALSE)
-
- -

Find gflags installation. The gflags_DIR variable must be set to the <prefix>/lib/cmake/gflags directory +

Find gflags installation. The gflags_DIR 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.

    find_package(gflags REQUIRED)
+

To request a particular imported gflags library target to link against, use the COMPONENTS option of +the find_package command. For example, to force the use of the single-threaded static library, use the command

+
+   find_package(gflags COMPONENTS nothreads_static)
+
+

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.

+ +

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 add_subdirectory(gflags). See the top of the gflags/CMakeLists.txt +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.

+

Finally, add your executable build target which uses gflags to parse the command arguments with dependency on the imported gflags library target:


From 78c66b37266707a3cf2904c3891b08cddae8d83e Mon Sep 17 00:00:00 2001
From: Andreas Schuh 
Date: Fri, 25 Nov 2016 18:09:44 +0000
Subject: [PATCH 09/14] doc: Add section on how to use gflags with Bazel

---
 index.html | 57 ++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 49 insertions(+), 8 deletions(-)

diff --git a/index.html b/index.html
index d3aee33..5dcc4b6 100644
--- a/index.html
+++ b/index.html
@@ -39,7 +39,8 @@
   
 Table of contents 

   
 Introduction 

   
 Download and Installation 

-  
 Linking to gflags using CMake

+  
 Declare dependency on gflags with CMake

+  
 Declare dependency on gflags with Bazel

   
 DEFINE: Defining Flags In Program 

   
 Accessing the Flag 

   
 DECLARE: Using the Flag in a Different File 

@@ -101,9 +102,14 @@ You can clone the project using the command:

 
    git clone https://github.com/gflags/gflags.git
 

-
Build and installation instructions are provided in the INSTALL file.

+
Build and installation instructions are provided in the
+INSTALL file.
+The installation of the gflags package includes configuration files for popular build systems
+such as pkg-config,
+CMake, and Bazel.

 
-
 Linking to gflags  using CMake

+
+
 Declare dependency on gflags with CMake

 
 
Using gflags within a project which uses CMake 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
@@ -141,6 +147,38 @@ imported gflags library target:

    target_link_libraries(foo gflags)
+

Declare dependency on gflags with Bazel

+ +

To use gflags within a project which uses Bazel as build tool, +add the following lines to your WORKSPACE file +(see also Bazel documentation of git_repository): + +

+git_repository(
+    name   = "com_github_gflags_gflags",
+    commit = "<INSERT COMMIT SHA HERE>",
+    remote = "https://github.com/gflags/gflags.git",
+)
+
+bind(
+    name = "gflags",
+    actual = "@com_github_gflags_gflags//:gflags",
+)
+
+ +

You can then add //external: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.

+ +

For example, see the following BUILD rule of the gflags/example project:

+ +
+cc_binary(
+    name = "foo",
+    srcs = ["main.cc"],
+    deps = ["//external:gflags"],
+)
+
+

DEFINE: Defining Flags In Program

Defining a flag is easy: just use the appropriate macro for the @@ -284,17 +322,20 @@ static bool ValidatePort(const char* flagname, int32 value) { return false; } DEFINE_int32(port, 0, "What port to listen on"); -static const bool port_dummy = RegisterFlagValidator(&FLAGS_port, &ValidatePort); +DEFINE_validator(port, &ValidatePort);

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

-

RegisterFlagValidator() returns true if the -registration is successful. It return false if the registration fails +

The above used DEFINE_validator macro calls the +RegisterFlagValidator() 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.

+b) a different validator has already been registered for this flag. +The return value is available as global static boolean variable named +<flag>_validator_registered.

Putting It Together: How to Set Up Flags

From 971dd2a4fadac9cdab174c523c22df79efd63aa5 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Fri, 25 Nov 2016 18:48:27 +0000 Subject: [PATCH 10/14] doc: Bazel gflags_nothreads target --- index.html | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/index.html b/index.html index 5dcc4b6..e0afb47 100644 --- a/index.html +++ b/index.html @@ -164,10 +164,17 @@ bind( name = "gflags", actual = "@com_github_gflags_gflags//:gflags", ) + +bind( + name = "gflags_nothreads", + actual = "@com_github_gflags_gflags//:gflags_nothreads", +)

You can then add //external: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.

+or cc_library rule, and #include "gflags/gflags.h" to include it in your source code. +This use the shared gflags library with multi-threading enabled. In order to use the single-threaded shared +gflags library, use the external dependency //external:gflags_nothreads instead.

For example, see the following BUILD rule of the gflags/example project:

From 48f409438b127949f8a6e8293e90bbe5880922d6 Mon Sep 17 00:00:00 2001 From: Razvan Musaloiu-E Date: Thu, 1 Dec 2016 09:20:44 -0800 Subject: [PATCH 11/14] Removed the unused link to #varz --- index.html | 1 - 1 file changed, 1 deletion(-) diff --git a/index.html b/index.html index e0afb47..97c9476 100644 --- a/index.html +++ b/index.html @@ -47,7 +47,6 @@
RegisterFlagValidator: Sanity-checking Flag Values
Putting It Together: How to Set Up Flags
Setting Flags on the Command Line
-
Setting Flags at Runtime
Changing the Default Flag Value
Special Flags
The API
From 48cdc7933284c171a9295259bf2e017a8db4d802 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Thu, 5 Jul 2018 23:23:21 +0100 Subject: [PATCH 12/14] doc: Use of Bazel bind discouraged --- index.html | 19 +++++-------------- 1 file changed, 5 insertions(+), 14 deletions(-) diff --git a/index.html b/index.html index e0afb47..efb3d61 100644 --- a/index.html +++ b/index.html @@ -159,22 +159,13 @@ git_repository( commit = "<INSERT COMMIT SHA HERE>", remote = "https://github.com/gflags/gflags.git", ) - -bind( - name = "gflags", - actual = "@com_github_gflags_gflags//:gflags", -) - -bind( - name = "gflags_nothreads", - actual = "@com_github_gflags_gflags//:gflags_nothreads", -) -

You can then add //external: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. -This use the shared gflags library with multi-threading enabled. In order to use the single-threaded shared -gflags library, use the external dependency //external:gflags_nothreads instead.

+

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. This use the shared gflags library with multi-threading enabled. +In order to use the single-threaded shared gflags library, use the dependency +@com_github_gflags_gflags//:gflags_nothreads instead.

For example, see the following BUILD rule of the gflags/example project:

From 8411df715cf522606e3b1aca386ddfc0b63d34b4 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Sun, 11 Nov 2018 20:44:23 +0000 Subject: [PATCH 13/14] Update CMake and Bazel examples --- index.html | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/index.html b/index.html index 1192603..bfccd82 100644 --- a/index.html +++ b/index.html @@ -114,7 +114,7 @@ such as pkg-conf 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. - +

To use an external gflags installation, add the following CMake code to your CMakeLists.txt file.

Find gflags installation. The gflags_DIR variable must be set to the <prefix>/lib/cmake/gflags directory @@ -143,7 +143,7 @@ any installation of the gflags subproject products.

imported gflags library target:

    add_executable(foo main.cc)
-   target_link_libraries(foo gflags)
+   target_link_libraries(foo gflags::gflags)

Declare dependency on gflags with Bazel

@@ -154,15 +154,15 @@ add the following lines to your WORKSPACE file 
 git_repository(
-    name   = "com_github_gflags_gflags",
-    commit = "<INSERT COMMIT SHA HERE>",
+    name = "com_github_gflags_gflags",
     remote = "https://github.com/gflags/gflags.git",
+    tags = "v2.2.2"
 )

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. This use the shared gflags library with multi-threading enabled. +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 @com_github_gflags_gflags//:gflags_nothreads instead.

From 048c14220ac49f992217e08a7f76e74530dd9390 Mon Sep 17 00:00:00 2001 From: Andreas Schuh Date: Fri, 18 Sep 2020 17:48:58 +0100 Subject: [PATCH 14/14] Add doc/README.md with command to update gh-pages --- README.md | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..f0a9ce7 --- /dev/null +++ b/README.md @@ -0,0 +1,4 @@ +To update the GitHub Pages at http://gflags.github.io/gflags/, use command: +``` +git subtree push --prefix=doc/ origin gh-pages +```