Wed Mar 26 15:20:18 2008 Google Inc. <opensource@google.com>

	* google-gflags: version 0.8
	* Export DescribeOneFlag() in the API
	* Add support for automatic line wrapping at 80 cols for gflags.py
	* Bugfix: do not treat an isolated "-" the same as an isolated "--"
	* Update rpm spec to point to Google Code rather than sourceforge (!)
	* Improve documentation (including documenting thread-safety)
	* Improve #include hygiene
	* Improve testing


git-svn-id: https://gflags.googlecode.com/svn/trunk@21 6586e3c6-dcc4-952a-343f-ff74eb82781d

ChangeLog

+Wed Mar 26 15:20:18 2008  Google Inc. <opensource@google.com>
+
+	* google-gflags: version 0.8
+	* Export DescribeOneFlag() in the API
+	* Add support for automatic line wrapping at 80 cols for gflags.py
+	* Bugfix: do not treat an isolated "-" the same as an isolated "--"
+	* Update rpm spec to point to Google Code rather than sourceforge (!)
+	* Improve documentation (including documenting thread-safety)
+	* Improve #include hygiene
+	* Improve testing
+	
 Thu Oct 18 11:33:20 2007  Google Inc. <opensource@google.com>
 
 	* google-gflags: version 0.7

configure

 #! /bin/sh
 # Guess values for system-dependent variables and create Makefiles.
-# Generated by GNU Autoconf 2.59 for gflags 0.7.
+# Generated by GNU Autoconf 2.59 for gflags 0.8.
 #
 # Report bugs to <opensource@google.com>.
 #
@@ -423,8 +423,8 @@ SHELL=${CONFIG_SHELL-/bin/sh}
 # Identity of this package.
 PACKAGE_NAME='gflags'
 PACKAGE_TARNAME='gflags'
-PACKAGE_VERSION='0.7'
-PACKAGE_STRING='gflags 0.7'
+PACKAGE_VERSION='0.8'
+PACKAGE_STRING='gflags 0.8'
 PACKAGE_BUGREPORT='opensource@google.com'
 
 ac_unique_file="README"
@@ -954,7 +954,7 @@ if test "$ac_init_help" = "long"; then
   # Omit some internal or obsolete options to make the list less imposing.
   # This message is too long to be a string in the A/UX 3.1 sh.
   cat <<_ACEOF
-\`configure' configures gflags 0.7 to adapt to many kinds of systems.
+\`configure' configures gflags 0.8 to adapt to many kinds of systems.
 
 Usage: $0 [OPTION]... [VAR=VALUE]...
 
@@ -1020,7 +1020,7 @@ fi
 
 if test -n "$ac_init_help"; then
   case $ac_init_help in
-     short | recursive ) echo "Configuration of gflags 0.7:";;
+     short | recursive ) echo "Configuration of gflags 0.8:";;
    esac
   cat <<\_ACEOF
 
@@ -1163,7 +1163,7 @@ fi
 test -n "$ac_init_help" && exit 0
 if $ac_init_version; then
   cat <<\_ACEOF
-gflags configure 0.7
+gflags configure 0.8
 generated by GNU Autoconf 2.59
 
 Copyright (C) 2003 Free Software Foundation, Inc.
@@ -1177,7 +1177,7 @@ cat >&5 <<_ACEOF
 This file contains any messages produced by compilers while
 running configure, to aid debugging if configure makes a mistake.
 
-It was created by gflags $as_me 0.7, which was
+It was created by gflags $as_me 0.8, which was
 generated by GNU Autoconf 2.59.  Invocation command line was
 
   $ $0 $@
@@ -1823,7 +1823,7 @@ fi
 
 # Define the identity of the package.
  PACKAGE='gflags'
- VERSION='0.7'
+ VERSION='0.8'
 
 
 cat >>confdefs.h <<_ACEOF
@@ -20943,7 +20943,7 @@ _ASBOX
 } >&5
 cat >&5 <<_CSEOF
 
-This file was extended by gflags $as_me 0.7, which was
+This file was extended by gflags $as_me 0.8, which was
 generated by GNU Autoconf 2.59.  Invocation command line was
 
   CONFIG_FILES    = $CONFIG_FILES
@@ -21006,7 +21006,7 @@ _ACEOF
 
 cat >>$CONFIG_STATUS <<_ACEOF
 ac_cs_version="\\
-gflags config.status 0.7
+gflags config.status 0.8
 configured by $0, generated by GNU Autoconf 2.59,
   with options \\"`echo "$ac_configure_args" | sed 's/[\\""\`\$]/\\\\&/g'`\\"
 

configure.ac

@@ -4,7 +4,7 @@
 # make sure we're interpreted by some minimal autoconf
 AC_PREREQ(2.57)
 
-AC_INIT(gflags, 0.7, opensource@google.com)
+AC_INIT(gflags, 0.8, opensource@google.com)
 # The argument here is just something that should be in the current directory
 # (for sanity checking)
 AC_CONFIG_SRCDIR(README)

doc/gflags.html

@@ -81,11 +81,11 @@ translates directly to Python.</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>base/commandlineflags.h</code>.  Here's an example file,
+<code>google/gflags.h</code>.  Here's an example file,
 <code>foo.cc</code>:</p>
 
 <pre>
-   #include "base/commandlineflags.h"
+   #include &lt;google/gflags.h&gt;
 
    DEFINE_bool(big_menu, true, "Include 'advanced' options in the menu listing");
    DEFINE_string(languages, "english,french,german",
@@ -131,7 +131,7 @@ be in the global namespace.</p>
 <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> appended.  In the above
+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>
 
@@ -145,7 +145,7 @@ variable:</p>
 </pre>
 
 <p>You can also get and set flag values via special functions in
-<code>commandlineflags.h</code>.  That's a rarer use case, though.</p>
+<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>
@@ -173,16 +173,21 @@ recommend the following guideline:</p>
 
 <blockquote>
 If you DEFINE a flag in <code>foo.cc</code>, either don't DECLARE it
-at all, or only DECLARE it in <code>foo.h</code>.
+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 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.</p>
-
+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>
 
 <h2> <A name=together>Putting It Together: How to Set Up Flags</A> </h2>
 

packages/deb/changelog

+google-gflags (0.8-1) unstable; urgency=low
+
+  * New upstream release.
+
+ -- Google Inc. <opensource@google.com>  Wed, 26 Mar 2008 15:20:18 -0700
+
 google-gflags (0.7-1) unstable; urgency=low
 
   * New upstream release.

packages/rpm/rpm.spec

-%define	ver	%VERSION
 %define	RELEASE	1
 %define rel     %{?CUSTOM_RELEASE} %{!?CUSTOM_RELEASE:%RELEASE}
 %define	prefix	/usr
 
 Name: %NAME
 Summary: A commandline flags library that allows for distributed flags
-Version: %ver
+Version: %VERSION
 Release: %rel
 Group: Development/Libraries
-URL: http://code.google.com/p/google-gflags
+URL: http://code.google.com/p/gflags
 License: BSD
 Vendor: Google
 Packager: Google Inc. <opensource@google.com>
-Source: http://google-gflags.googlecode.com/files/%{NAME}-%{PACKAGE_VERSION}.tar.gz
+Source: http://%{NAME}.googlecode.com/files/%{NAME}-%{VERSION}.tar.gz
 Distribution: Redhat 7 and above.
 Buildroot: %{_tmppath}/%{name}-root
 Prefix: %prefix
@@ -26,6 +25,7 @@ the ability to define flags in the source file in which they're used.
 %package devel
 Summary: A commandline flags library that allows for distributed flags
 Group: Development/Libraries
+Requires: %{NAME} = %{VERSION}
 
 %description devel
 The %name-devel package contains static and debug libraries and header

python/setup.py

@@ -32,7 +32,7 @@
 from distutils.core import setup
 
 setup(name='gflags',
-      version='0.6',
+      version='0.8',
       description='Google Commandline Flags Module',
       license='BSD',
       author='Google Inc.',

src/gflags.cc

@@ -40,7 +40,6 @@
 #include <errno.h>
 #include <string.h>
 #include <assert.h>
-#include <pthread.h>
 #include <fnmatch.h>
 #include <pthread.h>
 #include <string>
@@ -96,8 +95,7 @@ static const char kError[] = "ERROR: ";
 // The help message indicating that the commandline flag has been
 // 'stripped'. It will not show up when doing "-help" and its
 // variants. The flag is stripped if STRIP_FLAG_HELP is set to 1
-// before including base/commandlineflags.h (or in
-// base/global_strip_options.h).
+// before including google/gflags.h.
 
 const char kStrippedFlagHelp[] = "\001\002\003\004 (unknown) \004\003\002\001";
 
@@ -105,7 +103,7 @@ const char kStrippedFlagHelp[] = "\001\002\003\004 (unknown) \004\003\002\001";
 // Enables deferred processing of flags in dynamically loaded libraries.
 static bool allow_command_line_reparsing = false;
 
-static bool logging_is_probably_set_up = false;   // google3-specific
+static bool logging_is_probably_set_up = false;
 
 // This is used by the unittest to test error-exit code
 void (*commandlineflags_exitfunc)(int) = &exit;   // from stdlib.h
@@ -114,7 +112,7 @@ void (*commandlineflags_exitfunc)(int) = &exit;   // from stdlib.h
 // FlagValue
 //    This represent the value a single flag might have.  The major
 //    functionality is to convert from a string to an object of a
-//    given type, and back.
+//    given type, and back.  Thread-compatible.
 // --------------------------------------------------------------------
 
 class FlagValue {
@@ -375,21 +373,19 @@ CommandLineFlag::~CommandLineFlag() {
 const char* CommandLineFlag::CleanFileName() const {
   // Compute top-level directory & file that this appears in
   // search full path backwards.
-  // Stop going backwards at kGoogle; and skip by the first slash.
-  // E.g.
-  //   filename_where_defined = "froogle/wrapping/autowrap/clustering/**.cc"
-  //   filename_where_defined = "file/util/fileutil.cc"
-  static const char kGoogle[] = "";    // can set this to whatever
+  // Stop going backwards at kRootDir; and skip by the first slash.
+  static const char kRootDir[] = "";    // can set this to root directory,
+                                        // e.g. "myproject"
 
-  if (sizeof(kGoogle)-1 == 0)          // no prefix to strip
+  if (sizeof(kRootDir)-1 == 0)          // no prefix to strip
     return filename();
 
   const char* clean_name = filename() + strlen(filename()) - 1;
   while ( clean_name > filename() ) {
     if (*clean_name == PATH_SEPARATOR) {
-      if (strncmp(clean_name, kGoogle, sizeof(kGoogle)-1) == 0) {
-        // ".../google/base/logging.cc" ==> "base/logging.cc"
-        clean_name += sizeof(kGoogle)-1;    // past "/google/"
+      if (strncmp(clean_name, kRootDir, sizeof(kRootDir)-1) == 0) {
+        // ".../myproject/base/logging.cc" ==> "base/logging.cc"
+        clean_name += sizeof(kRootDir)-1;    // past "/myproject/"
         break;
       }
     }
@@ -790,7 +786,7 @@ const char* ProgramInvocationName() {             // like the GNU libc fn
 }
 const char* ProgramInvocationShortName() {        // like the GNU libc fn
   const char* slash = strrchr(argv0, '/');
-#ifdef OS_WINDOWS
+#if defined(WIN32) || defined(_WIN32) || defined(__WIN32__)
   if (!slash)  slash = strrchr(argv0, '\\');
 #endif
   return slash ? slash + 1 : argv0;
@@ -939,7 +935,8 @@ uint32 CommandLineFlagParser::ParseNewCommandLineFlags(int* argc, char*** argv,
     char* arg = (*argv)[i];
 
     // Like getopt(), we permute non-option flags to be at the end.
-    if (arg[0] != '-') {           // must be a program argument
+    if (arg[0] != '-' ||           // must be a program argument
+        (arg[0] == '-' && arg[1] == '\0')) {  // "-" is an argument, not a flag
       memmove((*argv) + i, (*argv) + i+1, (*argc - (i+1)) * sizeof((*argv)[i]));
       (*argv)[*argc-1] = arg;      // we go last
       first_nonopt--;              // we've been pushed onto the stack
@@ -950,7 +947,7 @@ uint32 CommandLineFlagParser::ParseNewCommandLineFlags(int* argc, char*** argv,
     if (arg[0] == '-') arg++;      // allow leading '-'
     if (arg[0] == '-') arg++;      // or leading '--'
 
-    // - and -- alone mean what they do for GNU: stop options parsing
+    // -- alone means what it does for GNU: stop options parsing
     if (*arg == '\0') {
       first_nonopt = i+1;
       break;

src/gflags_reporting.cc

@@ -37,8 +37,8 @@
 // reporting flags, but we also have flags like --helpxml, etc.
 //
 // There's only one function that's meant to be called externally:
-// HandleCommandLineHelpFlags().  (Well, actually,
-// ShowUsageWithFlags() and ShowUsageWithFlagsRestrict() can be called
+// HandleCommandLineHelpFlags().  (Well, actually, ShowUsageWithFlags(),
+// ShowUsageWithFlagsRestrict(), and DescribeOneFlag() can be called
 // externally too, but there's little need for it.)  These are all
 // declared in the main commandlineflags.h header file.
 //
@@ -110,7 +110,7 @@ static void AddString(const string& s,
 
 // Create a descriptive string for a flag.
 // Goes to some trouble to make pretty line breaks.
-static string DescribeOneFlag(const CommandLineFlagInfo& flag) {
+string DescribeOneFlag(const CommandLineFlagInfo& flag) {
   string main_part = (string("    -") + flag.name +
                       " (" + flag.description + ')');
   const char* c_string = main_part.c_str();
@@ -242,8 +242,8 @@ static bool FileMatchesSubstring(const string& filename,
 
 // Show help for every filename which matches any of the target substrings.
 // If substrings is empty, shows help for every file. If a flag's help message
-// has been stripped (e.g. by adding '#define STRIP_FLAG_HELP 1' to
-// base/global_strip_options.h), then this flag will not be displayed by
+// has been stripped (e.g. by adding '#define STRIP_FLAG_HELP 1' before
+// including google/gflags.h), then this flag will not be displayed by
 // '--help' and its variants.
 static void ShowUsageWithFlagsMatching(const char *argv0,
                                        const vector<string> &substrings) {

src/gflags_unittest.cc

@@ -35,6 +35,7 @@
 
 #include "config.h"
 #include <stdio.h>
+#include <stdlib.h>     // for &exit
 #include <string.h>
 #include <unistd.h>     // for unlink()
 #include <sys/stat.h>   // for mkdir()
@@ -46,8 +47,7 @@
 using std::vector;
 using std::string;
 
-// Returns the number of elements in an array.  We don't use the safer
-// version in base/basictypes.h as commandlineflags is open-sourced.
+// Returns the number of elements in an array.
 #define GET_ARRAY_SIZE(arr) (sizeof(arr)/sizeof(*(arr)))
 
 DECLARE_string(tryfromenv);   // in commandlineflags.cc
@@ -1109,6 +1109,43 @@ TEST(ParseCommandLineFlagsUsesLastDefinitionTest,
   EXPECT_EQ(3, ParseTestFlag(false, GET_ARRAY_SIZE(argv) - 1, argv));
 }
 
+TEST(ParseCommandLineFlagsAndDashArgs, TwoDashArgFirst) {
+  const char* argv[] = {
+    "my_test",
+    "--",
+    "--test_flag=0",
+    NULL,
+  };
+
+  EXPECT_EQ(-1, ParseTestFlag(true, GET_ARRAY_SIZE(argv) - 1, argv));
+  EXPECT_EQ(-1, ParseTestFlag(false, GET_ARRAY_SIZE(argv) - 1, argv));
+}
+
+TEST(ParseCommandLineFlagsAndDashArgs, TwoDashArgMiddle) {
+  const char* argv[] = {
+    "my_test",
+    "--test_flag=7",
+    "--",
+    "--test_flag=0",
+    NULL,
+  };
+
+  EXPECT_EQ(7, ParseTestFlag(true, GET_ARRAY_SIZE(argv) - 1, argv));
+  EXPECT_EQ(7, ParseTestFlag(false, GET_ARRAY_SIZE(argv) - 1, argv));
+}
+
+TEST(ParseCommandLineFlagsAndDashArgs, OneDashArg) {
+  const char* argv[] = {
+    "my_test",
+    "-",
+    "--test_flag=0",
+    NULL,
+  };
+
+  EXPECT_EQ(0, ParseTestFlag(true, GET_ARRAY_SIZE(argv) - 1, argv));
+  EXPECT_EQ(0, ParseTestFlag(false, GET_ARRAY_SIZE(argv) - 1, argv));
+}
+
 static int Main(int argc, char **argv) {
   // We need to call SetArgv before InitGoogle, so our "test" argv will
   // win out over this executable's real argv.  That makes running this

src/google/gflags.h.in

@@ -50,6 +50,24 @@
 //
 // For more details, see
 //    doc/gflags.html
+//
+// --- A note about thread-safety:
+//
+// We describe many functions in this routine as being thread-hostile,
+// thread-compatible, or thread-safe.  Here are the meanings we use:
+//
+// thread-safe: it is safe for multiple threads to call this routine
+//   (or, when referring to a class, methods of this class)
+//   concurrently.
+// thread-hostile: it is not safe for multiple threads to call this
+//   routine (or methods of this class) concurrently.  In gflags,
+//   most thread-hostile routines are intended to be called early in,
+//   or even before, main() -- that is, before threads are spawned.
+// thread-compatible: it is safe for multiple threads to read from
+//   this variable (when applied to variables), or to call const
+//   methods of this class (when applied to classes), as long as no
+//   other thread is writing to the variable or calling non-const
+//   methods of this class.
 
 #ifndef BASE_COMMANDLINEFLAGS_H__
 #define BASE_COMMANDLINEFLAGS_H__
@@ -120,13 +138,22 @@ extern void GetAllFlags(std::vector<CommandLineFlagInfo>* OUTPUT);
 extern void ShowUsageWithFlags(const char *argv0);  // what --help does
 extern void ShowUsageWithFlagsRestrict(const char *argv0, const char *restrict);
 
+// Create a descriptive string for a flag.
+// Goes to some trouble to make pretty line breaks.
+extern std::string DescribeOneFlag(const CommandLineFlagInfo& flag);
+
+// Thread-hostile; meant to be called before any threads are spawned.
 extern void SetArgv(int argc, const char** argv);
+// The following functions are thread-safe as long as SetArgv() is
+// only called before any threads start.
 extern const std::vector<std::string>& GetArgvs();  // all of argv as a vector
 extern const char* GetArgv();               // all of argv as a string
 extern const char* GetArgv0();              // only argv0
 extern uint32 GetArgvSum();                 // simple checksum of argv
 extern const char* ProgramInvocationName(); // argv0, or "UNKNOWN" if not set
 extern const char* ProgramInvocationShortName();   // basename(argv0)
+// ProgramUsage() is thread-safe as long as SetUsageMessage() is only
+// called before any threads start.
 extern const char* ProgramUsage();          // string set by SetUsageMessage()
 
 
@@ -135,6 +162,8 @@ extern const char* ProgramUsage();          // string set by SetUsageMessage()
 // or whatever, and set them by calling "FLAGS_foo = bar" (or, more
 // commonly, via the DEFINE_foo macro).  But if you need a bit more
 // control, we have programmatic ways to get/set the flags as well.
+// These programmatic ways to access flags are thread-safe, but direct
+// access is only thread-compatible.
 
 // Return true iff the flagname was found.
 // OUTPUT is set to the flag's value, or unchanged if we return false.
@@ -196,6 +225,8 @@ extern std::string SetCommandLineOptionWithMode(const char* name, const char* va
 // work is done in the constructor and destructor, so in the standard
 // usage example above, the compiler would complain that it's an
 // unused variable.
+//
+// This class is thread-safe.
 
 class FlagSaver {
  public:
@@ -251,6 +282,7 @@ extern const char *StringFromEnv(const char *varname, const char *defval);
 //   usage += argv[0] + " <uselessarg1> <uselessarg2>";
 //   SetUsageMessage(usage);
 // Do not include commandline flags in the usage: we do that for you!
+// Thread-hostile; meant to be called before any threads are spawned.
 extern void SetUsageMessage(const std::string& usage);
 
 // Looks for flags in argv and parses them.  Rearranges argv to put
@@ -280,8 +312,10 @@ extern uint32 ParseCommandLineNonHelpFlags(int *argc, char*** argv,
 // it's too late to change that now. :-(
 extern void HandleCommandLineHelpFlags();   // in commandlineflags_reporting.cc
 
-// Allow command line reparsing.  Disables the error normaly generated
-// when an unknown flag is found, since it may be found in a later parse.
+// Allow command line reparsing.  Disables the error normally
+// generated when an unknown flag is found, since it may be found in a
+// later parse.  Thread-hostile; meant to be called before any threads
+// are spawned.
 extern void AllowCommandLineReparsing();
 
 // Reparse the flags that have not yet been recognized.