From 645acfe60631c6cf2ef5b313c706ab580ad19d1e Mon Sep 17 00:00:00 2001 From: Sergiu Deitsch Date: Tue, 11 Jun 2024 19:48:12 +0200 Subject: [PATCH] docs: move to mkdocs-material (#1101) --- .gitignore | 1 + COPYING => LICENSE.md | 19 +- README.rst | 990 +-------------------------------------- docs/build.md | 73 +++ docs/contribute.md | 50 ++ docs/failures.md | 49 ++ docs/index.md | 30 ++ docs/license.md | 3 + docs/log_cleaner.md | 24 + docs/log_stripping.md | 20 + docs/logging.md | 518 ++++++++++++++++++++ docs/overrides/main.html | 8 + docs/packages.md | 34 ++ docs/requirements.txt | 6 + docs/unwinder.md | 57 +++ docs/usage.md | 24 + docs/windows.md | 44 ++ mkdocs.yml | 117 +++++ 18 files changed, 1068 insertions(+), 999 deletions(-) rename COPYING => LICENSE.md (62%) create mode 100644 docs/build.md create mode 100644 docs/contribute.md create mode 100644 docs/failures.md create mode 100644 docs/index.md create mode 100644 docs/license.md create mode 100644 docs/log_cleaner.md create mode 100644 docs/log_stripping.md create mode 100644 docs/logging.md create mode 100644 docs/overrides/main.html create mode 100644 docs/packages.md create mode 100644 docs/requirements.txt create mode 100644 docs/unwinder.md create mode 100644 docs/usage.md create mode 100644 docs/windows.md create mode 100644 mkdocs.yml diff --git a/.gitignore b/.gitignore index 2678271dd..6920e63a2 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ *.orig /build*/ +/site/ bazel-* diff --git a/COPYING b/LICENSE.md similarity index 62% rename from COPYING rename to LICENSE.md index ac95ad875..15a95f955 100644 --- a/COPYING +++ b/LICENSE.md @@ -1,19 +1,18 @@ -Copyright (c) 2024, Google Inc. +Copyright © 2024, Google Inc. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - * Redistributions of source code must retain the above copyright -notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above -copyright notice, this list of conditions and the following disclaimer -in the documentation and/or other materials provided with the -distribution. - * Neither the name of Google Inc. nor the names of its -contributors may be used to endorse or promote products derived from -this software without specific prior written permission. +* Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. +* Redistributions in binary form must reproduce the above copyright notice, this + list of conditions and the following disclaimer in the documentation and/or + other materials provided with the distribution. +* Neither the name of Google Inc. nor the names of its contributors may be used + to endorse or promote products derived from this software without specific + prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT diff --git a/README.rst b/README.rst index 0adc84c44..49b2391b9 100644 --- a/README.rst +++ b/README.rst @@ -7,998 +7,10 @@ Google Logging (glog) is a C++14 library that implements application-level logging. The library provides logging APIs based on C++-style streams and various helper macros. -.. role:: cmake(code) - :language: cmake - -.. role:: cmd(code) - :language: bash - -.. role:: cpp(code) - :language: cpp - -.. role:: bazel(code) - :language: starlark - - Getting Started --------------- -You can log a message by simply streaming things to ``LOG``\ (`__>), e.g., - -.. code:: cpp - - #include - - int main(int argc, char* argv[]) { - // Initialize Google’s logging library. - google::InitGoogleLogging(argv[0]); - - // ... - LOG(INFO) << "Found " << num_cookies << " cookies"; - } - - -The library can be installed using various package managers or compiled from -`source <#building-from-source>`__. For a detailed overview of glog features and -their usage, please refer to the `user guide <#user-guide>`__. - -.. pull-quote:: - [!IMPORTANT] - - The above example requires further `Bazel <#bazel>`__ or - `CMake <#usage-in-projects>`__ setup for use in own projects. - - -.. contents:: Table of Contents - - -Usage in Projects -~~~~~~~~~~~~~~~~~ - -Assuming that glog was previously `built using CMake <#cmake>`__ or installed -using a package manager, you can use the CMake command :cmake:`find_package` to -build against glog in your CMake project as follows: - -.. code:: cmake - - cmake_minimum_required (VERSION 3.16) - project (myproj VERSION 1.0) - - find_package (glog 0.7.0 REQUIRED) - - add_executable (myapp main.cpp) - target_link_libraries (myapp glog::glog) - - -Compile definitions and options will be added automatically to your -target as needed. - -Alternatively, glog can be incorporated into using the CMake command -:cmake:`add_subdirectory` to include glog directly from a subdirectory of your -project by replacing the :cmake:`find_package` call from the previous snippet by -:cmake:`add_subdirectory`. The :cmake:`glog::glog` target is in this case an -:cmake:`ALIAS` library target for the ``glog`` library target. - -Building from Source -~~~~~~~~~~~~~~~~~~~~ - -Bazel -^^^^^ - -To use glog within a project which uses the -`Bazel `__ build tool, add the following lines to -your ``WORKSPACE`` file: - -.. code:: bazel - - load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") - - http_archive( - name = "com_github_gflags_gflags", - sha256 = "34af2f15cf7367513b352bdcd2493ab14ce43692d2dcd9dfc499492966c64dcf", - strip_prefix = "gflags-2.2.2", - urls = ["https://github.com/gflags/gflags/archive/v2.2.2.tar.gz"], - ) - - http_archive( - name = "com_github_google_glog", - sha256 = "122fb6b712808ef43fbf80f75c52a21c9760683dae470154f02bddfc61135022", - strip_prefix = "glog-0.6.0", - urls = ["https://github.com/google/glog/archive/v0.6.0.zip"], - ) - -You can then add :bazel:`@com_github_google_glog//:glog` to the deps section -of a :bazel:`cc_binary` or :bazel:`cc_library` rule, and :code:`#include ` -to include it in your source code. Here’s a simple example: - -.. code:: bazel - - cc_binary( - name = "main", - srcs = ["main.cc"], - deps = ["@com_github_google_glog//:glog"], - ) - -CMake -^^^^^ - -glog can be compiled using `CMake `__ on a wide range of -platforms. The typical workflow for building glog on a Unix-like system with -GNU Make as build tool is as follows: - -1. Clone the repository and change into source directory. - - .. code:: bash - - git clone https://github.com/google/glog.git - cd glog - -2. Run CMake to configure the build tree. - - .. code:: bash - - cmake -S . -B build -G "Unix Makefiles" - - CMake provides different generators, and by default will pick the most - relevant one to your environment. If you need a specific version of Visual - Studio, use :cmd:`cmake . -G `, and see :cmd:`cmake --help` - for the available generators. Also see :cmd:`-T `, which can - be used to request the native x64 toolchain with :cmd:`-T host=x64`. - -3. Afterwards, generated files can be used to compile the project. - - .. code:: bash - - cmake --build build - -4. Test the build software (optional). - - .. code:: bash - - cmake --build build --target test - -5. Install the built files (optional). - - .. code:: bash - - cmake --build build --target install - - -Once successfully built, glog can be -`integrated into own projects <#usage-in-projects>`__. - - -conan -~~~~~ - -You can download and install glog using the `conan -`__ package manager: - -.. code:: bash - - pip install conan - conan install -r conancenter glog/@ - -The glog recipe in conan center is kept up to date by conan center index community -contributors. If the version is out of date, please create an -issue or pull request on the `conan-center-index -`__ repository. - -vcpkg -~~~~~ - -You can download and install glog using the `vcpkg -`__ dependency manager: - -.. code:: bash - - git clone https://github.com/Microsoft/vcpkg.git - cd vcpkg - ./bootstrap-vcpkg.sh - ./vcpkg integrate install - ./vcpkg install glog - -The glog port in vcpkg is kept up to date by Microsoft team members and -community contributors. If the version is out of date, please create an -issue or pull request on the vcpkg repository. - -User Guide ----------- - -glog defines a series of macros that simplify many common logging tasks. -You can log messages by severity level, control logging behavior from -the command line, log based on conditionals, abort the program when -expected conditions are not met, introduce your own verbose logging -levels, customize the prefix attached to log messages, and more. - -Following sections describe the functionality supported by glog. Please note -this description may not be complete but limited to the most useful ones. If you -want to find less common features, please check header files under `src/glog -`__ directory. - -Severity Levels -~~~~~~~~~~~~~~~ - -You can specify one of the following severity levels (in increasing -order of severity): - -1. ``INFO``, -2. ``WARNING``, -3. ``ERROR``, and -4. ``FATAL``. - -Logging a ``FATAL`` message terminates the program (after the message is -logged). - -.. pull-quote:: - [!NOTE] - - Messages of a given severity are logged not only to corresponding severity - logfile but also to other logfiles of lower severity. For instance, a message - of severity ``FATAL`` will be logged to logfiles of severity ``FATAL``, - ``ERROR``, ``WARNING``, and ``INFO``. - -The ``DFATAL`` severity logs a ``FATAL`` error in debug mode (i.e., -there is no ``NDEBUG`` macro defined), but avoids halting the program in -production by automatically reducing the severity to ``ERROR``. - -Unless otherwise specified, glog uses the format - -:: - - /...log..-), e.g., + +``` cpp title="main.cpp" +#include + +int main(int argc, char* argv[]) { + // Initialize Google’s logging library. + google::InitGoogleLogging(argv[0]); + + // ... + LOG(INFO) << "Found " << num_cookies << " cookies"; +} +``` + +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). + +!!! warning + The above example requires further [Bazel](build.md#bazel) or + [CMake](usage.md) setup for use in own projects. diff --git a/docs/license.md b/docs/license.md new file mode 100644 index 000000000..5097c8d99 --- /dev/null +++ b/docs/license.md @@ -0,0 +1,3 @@ +# The 3-Clause BSD License + +--8<-- "LICENSE.md" diff --git a/docs/log_cleaner.md b/docs/log_cleaner.md new file mode 100644 index 000000000..edf091434 --- /dev/null +++ b/docs/log_cleaner.md @@ -0,0 +1,24 @@ +# Automatically Remove Old Logs + +To enable the log cleaner: + +``` cpp +using namespace std::chrono_literals; +google::EnableLogCleaner(24h * 3); // keep your logs for 3 days +``` + +In C++20 (and later) this can be shortened to: + +``` cpp +using namespace std::chrono_literals; +google::EnableLogCleaner(3d); // keep your logs for 3 days +``` + +And then glog will check if there are overdue logs whenever a flush is +performed. In this example, any log file from your project whose last +modified time is greater than 3 days will be `unlink`()ed. + +This feature can be disabled at any time (if it has been enabled) using +``` cpp +google::DisableLogCleaner(); +``` diff --git a/docs/log_stripping.md b/docs/log_stripping.md new file mode 100644 index 000000000..fea5b31c3 --- /dev/null +++ b/docs/log_stripping.md @@ -0,0 +1,20 @@ +# Strip Logging Messages + +Strings used in log messages can increase the size of your binary and +present a privacy concern. You can therefore instruct glog to remove all +strings which fall below a certain severity level by using the +`GOOGLE_STRIP_LOG` macro: + +If your application has code like this: + +``` cpp +#define GOOGLE_STRIP_LOG 1 // this must go before the #include! +#include +``` + +The compiler will remove the log messages whose severities are less than +the specified integer value. Since `VLOG` logs at the severity level +`INFO` (numeric value `0`), setting `GOOGLE_STRIP_LOG` to 1 or greater +removes all log messages associated with `VLOG`s as well as `INFO` log +statements. + diff --git a/docs/logging.md b/docs/logging.md new file mode 100644 index 000000000..a844f4ee3 --- /dev/null +++ b/docs/logging.md @@ -0,0 +1,518 @@ +# 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 +[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) +attached to log messages, and more. + + +## Severity Levels + +You can specify one of the following severity levels (in increasing order of +severity): + +1. `INFO`, +2. `WARNING`, +3. `ERROR`, and +4. `FATAL`. + +Logging a `FATAL` message terminates the program (after the message is logged). + +!!! note + Messages of a given severity are logged not only to corresponding severity + logfile but also to other logfiles of lower severity. For instance, a + message of severity `FATAL` will be logged to logfiles of severity `FATAL`, + `ERROR`, `WARNING`, and `INFO`. + +The `DFATAL` severity logs a `FATAL` error in [debug mode](#debugging-support) +(i.e., there is no `NDEBUG` macro defined), but avoids halting the program in +production by automatically reducing the severity to `ERROR`. + +## Log Files + +Unless otherwise specified, glog uses the format + + /...log..- + Click here to go to latest. + +{% endblock %} diff --git a/docs/packages.md b/docs/packages.md new file mode 100644 index 000000000..837bfda33 --- /dev/null +++ b/docs/packages.md @@ -0,0 +1,34 @@ +# Installation using Package Managers + +## conan + +You can download and install glog using the [conan](https://conan.io) +package manager: + +``` bash +pip install conan +conan install -r conancenter glog/@ +``` + +The glog recipe in conan center is kept up to date by conan center index +community contributors. If the version is out of date, please create an +issue or pull request on the +[conan-center-index](https://github.com/conan-io/conan-center-index) +repository. + +## vcpkg + +You can download and install glog using the +[vcpkg](https://github.com/Microsoft/vcpkg) dependency manager: + +``` bash +git clone https://github.com/Microsoft/vcpkg.git +cd vcpkg +./bootstrap-vcpkg.sh +./vcpkg integrate install +./vcpkg install glog +``` + +The glog port in vcpkg is kept up to date by Microsoft team members and +community contributors. If the version is out of date, please create an +issue or pull request on the vcpkg repository. diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 000000000..c4638af22 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,6 @@ +mike>=2.1.1 +mkdocs-git-committers-plugin-2>=2.3.0 +mkdocs-git-revision-date-localized-plugin>=1.2.6 +mkdocs-material-extensions>=1.3.1 +mkdocs-material>=9.5.26 +mkdocs>=1.6.0 diff --git a/docs/unwinder.md b/docs/unwinder.md new file mode 100644 index 000000000..ea5d8c334 --- /dev/null +++ b/docs/unwinder.md @@ -0,0 +1,57 @@ +# Installation Notes for 64-bit Linux Systems + +!!! note + The description on this page is possibly not up-to-date. + +The [glibc built-in stack-unwinder](#glibc-built-in-stack-unwinder) on 64-bit +systems has some problems with glog. In particular, if you are using +[`InstallFailureSignalHandler()`](failures.md), the signal may be raised in the +middle of `malloc`, holding some `malloc`-related locks when they invoke the +stack unwinder. The built-in stack unwinder may call `malloc` recursively, which +may require the thread to acquire a lock it already holds resulting in a +deadlock. + +## Recommended Approach: `libunwind` + +For above reason, if you use a 64-bit system and you need +`InstallFailureSignalHandler()`, we strongly recommend you install `libunwind` +before trying to configure or install google glog. libunwind can be found +[here](http://download.savannah.nongnu.org/releases/libunwind/libunwind-snap-070410.tar.gz). + +Even if you already have `libunwind` installed, you will probably still need to +install from the snapshot to get the latest version. + +!!! warning + If you install libunwind from the URL above, be aware that you may have + trouble if you try to statically link your binary with glog: that is, if you + link with `gcc -static -lgcc_eh ...`. This is because both `libunwind` and + `libgcc` implement the same C++ exception handling APIs, but they implement + them differently on some platforms. This is not likely to be a problem on + ia64, but may be on x86-64. + +Also, if you link binaries statically, make sure that you add +`-Wl,--eh-frame-hdr` to your linker options. This is required so that +`libunwind` can find the information generated by the compiler required for +stack unwinding. + +Using `-static` is rare, though, so unless you know this will affect you it +probably won't. + +## Alternative Stack-unwinder + +If you cannot or do not wish to install `libunwind`, you can still try to use +two kinds of stack-unwinder: + +### glibc Built-in Stack-unwinder + +As we already mentioned, glibc's unwinder has a deadlock issue. However, if you +don't use `InstallFailureSignalHandler()` or you don't worry about the rare +possibilities of deadlocks, you can use this stack-unwinder. If you specify no +options and `libunwind` isn't detected on your system, the configure script +chooses this unwinder by default. + +### Frame Pointer based Stack-unwinder + +The frame pointer based stack unwinder requires that your application, the glog +library, and system libraries like libc, all be compiled with a frame pointer. +This is *not* the default for x86-64. diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 000000000..1b9676f2d --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,24 @@ +# Using glog in a CMake Project + +Assuming that glog was previously [built using CMake](build.md#cmake) or +installed using a package manager, you can use the CMake command `#!cmake +find_package` to build against glog in your CMake project as follows: + +``` cmake title="CMakeLists.txt" +cmake_minimum_required (VERSION 3.16) +project (myproj VERSION 1.0) + +find_package (glog 0.7.1 REQUIRED) + +add_executable (myapp main.cpp) +target_link_libraries (myapp glog::glog) +``` + +Compile definitions and options will be added automatically to your target as +needed. + +Alternatively, glog can be incorporated into using the CMake command `#!cmake +add_subdirectory` to include glog directly from a subdirectory of your project +by replacing the `#!cmake find_package` call from the previous snippet by +`add_subdirectory`. The `#!cmake glog::glog` target is in this case an `#!cmake +ALIAS` library target for the `glog` library target. diff --git a/docs/windows.md b/docs/windows.md new file mode 100644 index 000000000..43fcb4c6d --- /dev/null +++ b/docs/windows.md @@ -0,0 +1,44 @@ +# Notes for Windows Users + +glog defines the severity level `ERROR`, which is also defined by `windows.h`. +You can make glog not define `INFO`, `WARNING`, `ERROR`, and `FATAL` by defining +`GLOG_NO_ABBREVIATED_SEVERITIES` before including `glog/logging.h`. Even with +this macro, you can still use the iostream like logging facilities: + +``` cpp +#define GLOG_NO_ABBREVIATED_SEVERITIES +#include +#include + +// ... + +LOG(ERROR) << "This should work"; +LOG_IF(ERROR, x > y) << "This should be also OK"; +``` + +However, you cannot use `INFO`, `WARNING`, `ERROR`, and `FATAL` anymore for +functions defined in `glog/logging.h`. + +``` cpp +#define GLOG_NO_ABBREVIATED_SEVERITIES +#include +#include + +// ... + +// This won’t work. +// google::FlushLogFiles(google::ERROR); + +// Use this instead. +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: + +- `#!cpp #define WIN32_LEAN_AND_MEAN` or `NOGDI` **before** + `#!cpp #include `. +- `#!cpp #undef ERROR` **after** `#!cpp #include `. + +See [this issue](http://code.google.com/p/google-glog/issues/detail?id=33) for +more detail. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..8b3640052 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,117 @@ +--- +site_name: Google Logging Library +site_url: https://google.github.io/glog/ +repo_url: https://github.com/google/glog +repo_name: google/glog +edit_uri: edit/0.7.x/docs/ +copyright: Copyright © 2024 Google Inc. & contributors - Change cookie settings +markdown_extensions: + - admonition + - def_list + - pymdownx.details + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets: + base_path: + - '.' + check_paths: true + - pymdownx.superfences + - tables + - toc: + permalink: true +theme: + name: material + custom_dir: docs/overrides + icon: + repo: fontawesome/brands/git-alt + edit: material/pencil + view: material/eye + language: en + features: + - content.action.edit + - content.code.annotate + - content.code.copy + - content.code.select + - header.autohide + - navigation.expand + - navigation.instant.preview + - navigation.instant.progress + - navigation.prune + - navigation.indexes + - toc.follow + - navigation.top + - navigation.path + # - navigation.sections + # - navigation.tabs + # - navigation.tabs.sticky + - navigation.tracking + - search.highlight + - search.share + - search.suggest + palette: + # Palette toggle for automatic mode + - media: "(prefers-color-scheme)" + toggle: + icon: material/brightness-auto + name: Switch to light mode + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: teal + accent: green + toggle: + icon: material/brightness-7 + name: Switch to dark mode + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: black + toggle: + icon: material/brightness-4 + name: Switch to system preference +plugins: + - git-revision-date-localized: + enable_creation_date: true + - git-committers: + repository: google/glog + branch: 0.7.x + - privacy + - search + - tags +extra: + version: + alias: true + default: + - dev + - stable + provider: mike + consent: + actions: + - manage + - accept + - reject + title: Cookie consent + description: >- + We use cookies to recognize your repeated visits and preferences, as well + as to measure the effectiveness of our documentation and whether users + find what they're searching for. With your consent, you're helping us to + make our documentation better. +nav: + - Getting Started: + - Overview: index.md + - Usage in CMake Projects: usage.md + - Building from Source: build.md + - Installation using Package Managers: packages.md + - User Guide: + - Logging: logging.md + - Failure Handler: failures.md + - Log Removal: log_cleaner.md + - Stripping Log Messages: log_stripping.md + - System-specific Considerations: + - Usage on Windows: windows.md + - Linux Unwinder: unwinder.md + - Contributing: contribute.md + - License: license.md