Merge branch '0.7.x'

google · Jun 12, 2024 · 0c10a02 · 0c10a02
2 parents 44c2e9d + 9ca8073
commit 0c10a02
Show file tree

Hide file tree

Showing 6 changed files with 142 additions and 117 deletions.
diff --git a/docs/failures.md b/docs/failures.md
@@ -21,15 +21,33 @@ from the signal handler.
         @     0x7f892f7ef1c4 (unknown)
         @           0x4046f9 (unknown)
 
-By default, the signal handler writes the failure dump to the standard
-error. You can customize the destination by
-`#!cpp InstallFailureWriter()`.
+
+## Customizing Handler Output
+
+By default, the signal handler writes the failure dump to the standard error.
+However, it is possible to customize the destination by installing a callback
+using the `#!cpp google::InstallFailureWriter()` function. The function expects
+a pointer to a function with the following signature:
+
+``` cpp
+void YourFailureWriter(const char* message/* (1)! */, std::size_t length/* (2)! */);
+```
+
+1. The pointer references the start of the failure message.
+
+    !!! danger
+        The string is **not null-terminated**.
+
+2. The message length in characters.
+
+!!! warning "Possible overflow errors"
+    Users should not expect the `message` string to be null-terminated.
 
 ## User-defined Failure Function
 
 `FATAL` severity level messages or unsatisfied `CHECK` condition
 terminate your program. You can change the behavior of the termination
-by `InstallFailureFunction`.
+by `google::InstallFailureFunction`.
 
 ``` cpp
 void YourFailureFunction() {
@@ -43,7 +61,13 @@ int main(int argc, char* argv[]) {
 ```
 
 By default, glog tries to dump the stacktrace and calls `#!cpp std::abort`. The
-stacktrace is generated only when running the application on a system supported
-by glog. Currently, glog supports x86, x86_64, PowerPC architectures,
-`libunwind`, and the Debug Help Library (`dbghelp`) on Windows for extracting
-the stack trace.
+stacktrace is generated only when running the application on a system
+supported[^1] by glog.
+
+[^1]: To extract the stack trace, glog currently supports the following targets:
+
+    * x86, x86_64,
+    * PowerPC architectures,
+    * `libunwind`,
+    * and the Debug Help Library (`dbghelp`) on Windows.
+
diff --git a/docs/flags.md b/docs/flags.md
@@ -0,0 +1,93 @@
+# Adjusting Output
+
+Several flags influence glog's output behavior.
+
+## Using Command-line Parameters and Environment Variables
+
+If the [Google gflags
+library](https://github.com/gflags/gflags) is installed on your machine,
+the build system will automatically detect and use it, allowing you to
+pass flags on the command line.
+
+!!! example "Activate `--logtostderr` in an application from the command line"
+    A binary `you_application` that uses glog can be started using
+    ``` bash
+    ./your_application --logtostderr=1
+    ```
+    to log to `stderr` instead of writing the output to a log file.
+
+!!! tip
+    You can set boolean flags to `true` by specifying `1`, `true`, or `yes`. To
+    set boolean flags to `false`, specify `0`, `false`, or `no`. In either case
+    the spelling is case-insensitive.
+
+
+If the Google gflags library isn't installed, you set flags via
+environment variables, prefixing the flag name with `GLOG_`, e.g.,
+
+!!! example "Activate `logtostderr` without gflags"
+    ``` bash
+    GLOG_logtostderr=1 ./your_application
+    ```
+
+The following flags are most commonly used:
+
+`logtostderr` (`bool`, default=`false`)
+
+:   Log messages to `stderr` instead of logfiles.
+
+`stderrthreshold` (`int`, default=2, which is `ERROR`)
+
+:   Copy log messages at or above this level to `stderr` in addition to
+    logfiles. The numbers of severity levels `INFO`, `WARNING`, `ERROR`,
+    and `FATAL` are 0, 1, 2, and 3, respectively.
+
+`minloglevel` (`int`, default=0, which is `INFO`)
+
+:   Log messages at or above this level. Again, the numbers of severity
+    levels `INFO`, `WARNING`, `ERROR`, and `FATAL` are 0, 1, 2, and 3,
+    respectively.
+
+`log_dir` (`string`, default="")
+
+:   If specified, logfiles are written into this directory instead of
+    the default logging directory.
+
+`v` (`int`, default=0)
+
+:   Show all `#!cpp VLOG(m)` messages for `m` less or equal the value of this
+    flag. Overridable by `#!bash --vmodule`. Refer to [verbose
+    logging](logging.md#verbose-logging) for more detail.
+
+`vmodule` (`string`, default="")
+
+:   Per-module verbose level. The argument has to contain a
+    comma-separated list of `<module name>=<log level>`. `<module name>` is a
+    glob pattern (e.g., `gfs*` for all modules whose name starts with "gfs"),
+    matched against the filename base (that is, name ignoring .cc/.h./-inl.h).
+    `<log level>` overrides any value given by `--v`. See also [verbose
+    logging](logging.md#verbose-logging) for more details.
+
+Additional flags are defined in
+[flags.cc](https://github.com/google/glog/blob/master/src/flags.cc). Please see
+the source for their complete list.
+
+## Modifying Flags Programmatically
+
+You can also modify flag values in your program by modifying global variables
+`FLAGS_*`. Most settings start working immediately after you update `FLAGS_*`.
+The exceptions are the flags related to destination files. For instance, you
+might want to set `FLAGS_log_dir` before calling `google::InitGoogleLogging`.
+
+!!! example "Setting `log_dir` at runtime"
+    ``` cpp
+    LOG(INFO) << "file";
+    // Most flags work immediately after updating values.
+    FLAGS_logtostderr = 1;
+    LOG(INFO) << "stderr";
+    FLAGS_logtostderr = 0;
+    // This won’t change the log destination. If you want to set this
+    // value, you should do this before google::InitGoogleLogging .
+    FLAGS_log_dir = "/some/log/directory";
+    LOG(INFO) << "the same file";
+    ```
diff --git a/docs/index.md b/docs/index.md
@@ -13,14 +13,14 @@ You can log a message by simply streaming things to `LOG`(<a particular
 #include <glog/logging.h>
 
 int main(int argc, char* argv[]) {
-    // Initialize Google’s logging library.
-    google::InitGoogleLogging(argv[0]);
-
-    // ...
-    LOG(INFO) << "Found " << num_cookies << " cookies";
+    google::InitGoogleLogging(argv[0]); // (1)!
+    LOG(INFO) << "Found " << num_cookies << " cookies"; // (2)!
 }
 ```
 
+1. Initialize the Google Logging Library
+2. Log a message with informational severity
+
 The library can be installed using various [package managers](packages.md) or
 compiled [from source](build.md). For a detailed overview of glog features and
 their usage, please refer to the [user guide](logging.md).

diff --git a/docs/logging.md b/docs/logging.md
@@ -1,8 +1,8 @@
 # Logging
 
 glog defines a series of macros that simplify many common logging tasks. You can
-log messages by [severity level](#severity-levels), [control
-logging](#adjusting-output) behavior from the command line, log based on
+log messages by [severity level](#severity-levels), [control logging](flags.md)
+behavior from the command line, log based on
 [conditionals](#conditional-occasional-logging), abort the program when
 [expected conditions](#runtime-checks) are not met, introduce your [own logging
 levels](#verbose-logging), [customize the prefix](#format-customization)
@@ -146,102 +146,6 @@ of type `#!cpp void*` that allows supplying user data to the callback.
     ```
 
 
-## Adjusting Output
-
-Several flags influence glog's output behavior.
-
-### Using Command-line Parameters and Environment Variables
-
-If the [Google gflags
-library](https://github.com/gflags/gflags) is installed on your machine,
-the build system will automatically detect and use it, allowing you to
-pass flags on the command line.
-
-!!! example "Activate `--logtostderr` in an application from the command line"
-    A binary `you_application` that uses glog can be started using
-    ``` bash
-    ./your_application --logtostderr=1
-    ```
-    to log to `stderr` instead of writing the output to a log file.
-
-!!! tip
-    You can set boolean flags to `true` by specifying `1`, `true`, or `yes`. To
-    set boolean flags to `false`, specify `0`, `false`, or `no`. In either case
-    the spelling is case-insensitive.
-
-
-If the Google gflags library isn't installed, you set flags via
-environment variables, prefixing the flag name with `GLOG_`, e.g.,
-
-!!! example "Activate `logtostderr` without gflags"
-    ``` bash
-    GLOG_logtostderr=1 ./your_application
-    ```
-
-The following flags are most commonly used:
-
-`logtostderr` (`bool`, default=`false`)
-
-:   Log messages to `stderr` instead of logfiles.
-
-`stderrthreshold` (`int`, default=2, which is `ERROR`)
-
-:   Copy log messages at or above this level to `stderr` in addition to
-    logfiles. The numbers of severity levels `INFO`, `WARNING`, `ERROR`,
-    and `FATAL` are 0, 1, 2, and 3, respectively.
-
-`minloglevel` (`int`, default=0, which is `INFO`)
-
-:   Log messages at or above this level. Again, the numbers of severity
-    levels `INFO`, `WARNING`, `ERROR`, and `FATAL` are 0, 1, 2, and 3,
-    respectively.
-
-`log_dir` (`string`, default="")
-
-:   If specified, logfiles are written into this directory instead of
-    the default logging directory.
-
-`v` (`int`, default=0)
-
-:   Show all `#!cpp VLOG(m)` messages for `m` less or equal the value of this
-    flag. Overridable by `#!bash --vmodule`. Refer to [verbose
-    logging](#verbose-logging) for more detail.
-
-`vmodule` (`string`, default="")
-
-:   Per-module verbose level. The argument has to contain a
-    comma-separated list of `<module name>=<log level>`. `<module name>`
-    is a glob pattern (e.g., `gfs*` for all modules whose name starts
-    with "gfs"), matched against the filename base (that is, name
-    ignoring .cc/.h./-inl.h). `<log level>` overrides any value given by
-    `--v`. See also [verbose logging](#verbose-logging) for
-    more details.
-
-Additional flags are defined in
-[flags.cc](https://github.com/google/glog/blob/master/src/flags.cc). Please see
-the source for their complete list.
-
-### Modifying Flags Programmatically
-
-You can also modify flag values in your program by modifying global variables
-`FLAGS_*`. Most settings start working immediately after you update `FLAGS_*`.
-The exceptions are the flags related to destination files. For instance, you
-might want to set `FLAGS_log_dir` before calling `google::InitGoogleLogging`.
-
-!!! example "Setting `log_dir` at runtime"
-    ``` cpp
-    LOG(INFO) << "file";
-    // Most flags work immediately after updating values.
-    FLAGS_logtostderr = 1;
-    LOG(INFO) << "stderr";
-    FLAGS_logtostderr = 0;
-    // This won’t change the log destination. If you want to set this
-    // value, you should do this before google::InitGoogleLogging .
-    FLAGS_log_dir = "/some/log/directory";
-    LOG(INFO) << "the same file";
-    ```
-
-
 ## Conditional / Occasional Logging
 
 Sometimes, you may only want to log a message under certain conditions.
@@ -341,19 +245,21 @@ Specifying these options will specifically:
 
 The wildcarding functionality 3. supports both `*` (matches 0 or more
 characters) and `?` (matches any single character) wildcards. Please also refer
-to [command line flags](#adjusting-output) for more information.
+to [command line flags](flags.md) for more information.
 
 There's also `#!cpp VLOG_IS_ON(n)` "verbose level" condition macro. This macro
 returns `#!cpp true` when the `--v` is equal to or greater than `n`. The macro can be
 used as follows:
 
 ``` cpp
 if (VLOG_IS_ON(2)) {
-    // do some logging preparation and logging
-    // that can’t be accomplished with just VLOG(2) << ...;
+    // (1)
 }
 ```
 
+1. Here we can perform some logging preparation and logging that can’t be
+   accomplished with just `#!cpp VLOG(2) << "message ...";`
+
 Verbose level condition macros `VLOG_IF`, `VLOG_EVERY_N` and `VLOG_IF_EVERY_N`
 behave analogous to `LOG_IF`, `LOG_EVERY_N`, `LOG_IF_EVERY_N`, but accept a
 numeric verbosity level as opposed to a severity level.

diff --git a/docs/windows.md b/docs/windows.md
@@ -34,11 +34,11 @@ google::FlushLogFiles(google::GLOG_ERROR);
 ```
 
 If you don't need `ERROR` defined by `windows.h`, there are a couple of more
-workarounds which sometimes don't work:
+workarounds which sometimes don't work[^1]:
 
 -  `#!cpp #define WIN32_LEAN_AND_MEAN` or `NOGDI` **before**
    `#!cpp #include <windows.h>`.
 -  `#!cpp #undef ERROR` **after** `#!cpp #include <windows.h>`.
 
-See [this issue](http://code.google.com/p/google-glog/issues/detail?id=33) for
-more detail.
+[^1]: For more information refer to [this
+      issue](http://code.google.com/p/google-glog/issues/detail?id=33).
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -9,6 +9,7 @@ markdown_extensions:
   - admonition
   - attr_list
   - def_list
+  - footnotes
   - md_in_html
   - pymdownx.details
   - pymdownx.highlight:
@@ -110,6 +111,7 @@ nav:
       - Installation using Package Managers: packages.md
   - User Guide:
       - Logging: logging.md
+      - Adjusting Output: flags.md
       - Custom Sinks: sinks.md
       - Failure Handler: failures.md
       - Log Removal: log_cleaner.md