### Compile Example Manually After Install

Source: https://github.com/goatshriek/stumpless/blob/latest/INSTALL.md

Manually compile an example after installation to verify the install. This ensures the library is correctly linked and accessible.

```bash
gcc docs/examples/entry/entry_example.c -lstumpless -omanual_entry_example
./manual_entry_example
```

--------------------------------

### Conditional Installation of Examples

Source: https://github.com/goatshriek/stumpless/blob/latest/CMakeLists.txt

Installs example files to a specified destination if the INSTALL_EXAMPLES option is enabled. This provides users with sample code to understand library usage.

```cmake
if(INSTALL_EXAMPLES)
  install(
    DIRECTORY "${PROJECT_SOURCE_DIR}/docs/examples"
    DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/doc/libstumpless"
  )
endif()
```

--------------------------------

### Install Build with CMake

Source: https://github.com/goatshriek/stumpless/blob/latest/INSTALL.md

Install the built library on your system using the 'install' target. Use 'sudo' if necessary to write to system directories.

```bash
cmake --install .
```

```bash
sudo cmake --install .
```

--------------------------------

### Install Build Dependencies on Cygwin

Source: https://github.com/goatshriek/stumpless/blob/latest/INSTALL.md

Installs CMake, make, GCC core, G++, and Doxygen on Cygwin using the setup script. Use the -q flag for quiet installation.

```sh
setup-x86_64.exe -q -P cmake,make,gcc-core,gcc-g++,doxygen
```

--------------------------------

### Build and Install Stumpless

Source: https://context7.com/goatshriek/stumpless/llms.txt

Standard CMake workflow for cloning the repository, building, and installing the Stumpless library.

```sh
git clone git@github.com:goatshriek/stumpless.git
mkdir build && cd build
cmake ../stumpless
cmake --build . --parallel 4
sudo cmake --install .
```

--------------------------------

### Verify Build Tools Installation

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/windows-msys2-mingw64.md

Confirm that GCC, CMake, and Ninja are installed and accessible in the /mingw64/bin path.

```sh
which gcc && gcc --version
which cmake && cmake --version
which ninja && ninja --version
# Paths should be under /mingw64/bin
```

--------------------------------

### Library Installation Configuration

Source: https://github.com/goatshriek/stumpless/blob/latest/CMakeLists.txt

Configures the installation of the 'stumpless' target, specifying destinations for runtime binaries, libraries, public headers, and archives. This ensures the library is correctly installed.

```cmake
install(TARGETS stumpless
  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
  LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
  PUBLIC_HEADER DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
  ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
```

--------------------------------

### Initial Stumpless Setup and Build

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/development.md

Clone the repository, create a build directory, and configure the project using CMake. This is the first step before making any code changes.

```sh
git clone git@github.com:goatshriek/stumpless.git

mkdir build
cd build

cmake ../stumpless
```

--------------------------------

### Compile and Run Basic Example (Link with Import Lib)

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/windows-msys2-mingw64.md

Compile a basic C example using GCC, linking directly with the stumpless import library. Use this if linking by name fails.

```sh
# from repo root, after a successful CMake build
cp -f build/stumpless.dll .

# Or B: link using the exact import lib (if A says "cannot find -lstumpless")
gcc -I include -I build/include docs/examples/basic/basic_example.c \
    build/libstumpless.dll.a -lws2_32 -o basic_example.exe

# Run
./basic_example.exe
```

--------------------------------

### Compile and Run Basic Example (Link by Name)

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/windows-msys2-mingw64.md

Compile a basic C example using GCC, linking against the stumpless library by name. Ensure the DLL is in the current directory for runtime.

```sh
# from repo root, after a successful CMake build
cp -f build/stumpless.dll .

# Try A: link by name
gcc -I include -I build/include docs/examples/basic/basic_example.c \
    -L build -lstumpless -lws2_32 -o basic_example.exe

# Run
./basic_example.exe
```

--------------------------------

### Install Stumpless C++ Bindings

Source: https://github.com/goatshriek/stumpless/blob/latest/INSTALL.md

Install the C++ headers and library along with the C headers and library when the C++ bindings are enabled.

```shell
cmake --install .
```

--------------------------------

### Reinstall with Custom Prefix

Source: https://github.com/goatshriek/stumpless/blob/latest/INSTALL.md

Re-run the install command with a specific prefix to change the installation location. This is useful if the default install path is not desired.

```bash
sudo cmake --install . --prefix /usr
```

--------------------------------

### Install MSYS2 using winget

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/windows-msys2-mingw64.md

Use winget to install MSYS2. This is an alternative to manual download and installation.

```powershell
winget install -e --id MSYS2.MSYS2
```

--------------------------------

### Install FreeBSD Package

Source: https://github.com/goatshriek/stumpless/blob/latest/INSTALL.md

Install the Stumpless .pkg package on FreeBSD systems. Ensure correct permissions are set.

```sh
# permissions need to be correct, of course
pkg add libstumpless-2.2.0-amd64.pkg
```

--------------------------------

### Install Build Tools for MSYS2

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/windows-msys2-mingw64.md

Install essential build tools including GCC, CMake, Ninja, and Git for the MinGW64 environment.

```sh
pacman -S --needed \
  mingw-w64-x86_64-gcc \
  mingw-w64-x86_64-cmake \
  mingw-w64-x86_64-ninja \
  git
```

--------------------------------

### Generic Shell Installer

Source: https://github.com/goatshriek/stumpless/blob/latest/INSTALL.md

Execute the generated shell script to install Stumpless on systems without a traditional package manager. Ensure write permissions to the install location.

```sh
# you might need to do this with sudo!
# make sure your permissions allow you to write to the install locations
cd /usr
./libstumpless-2.2.0.sh
```

--------------------------------

### Install Build Dependencies on Debian/Ubuntu

Source: https://github.com/goatshriek/stumpless/blob/latest/INSTALL.md

Installs CMake, make, GCC, G++, and Doxygen using apt for building Stumpless and its documentation.

```sh
sudo apt-get install cmake make gcc g++ doxygen
```

--------------------------------

### Compile and Run C++ Stumpless Example

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/cpp/README.md

Compile the C++ example using g++ and link against the stumplesscpp library. Then, execute the compiled program.

```bash
g++ cpp_usage.cpp -lstumplesscpp -o cpp_usage
./cpp_usage
```

--------------------------------

### Install Build Dependencies on Arch Linux/MSYS2

Source: https://github.com/goatshriek/stumpless/blob/latest/INSTALL.md

Installs CMake, make, GCC, G++, and Doxygen using pacman for building Stumpless and its documentation.

```sh
pacman -S cmake make gcc doxygen
```

--------------------------------

### Pkg-config File Generation and Installation

Source: https://github.com/goatshriek/stumpless/blob/latest/CMakeLists.txt

Generates and installs the pkg-config file for libstumpless if PkgConfig is found. This allows other projects to easily find and link against the library.

```cmake
include(FindPkgConfig QUIET)
if(PKG_CONFIG_FOUND)
  configure_file(
    "${PROJECT_SOURCE_DIR}/tools/pkg-config/libstumpless.pc.in"
    "${PROJECT_BINARY_DIR}/tools/pkg-config/libstumpless.pc"
    @ONLY
  )

  install(
    FILES "${PROJECT_BINARY_DIR}/tools/pkg-config/libstumpless.pc"
    DESTINATION "${CMAKE_INSTALL_LIBDIR}/pkgconfig"
  )
endif()
```

--------------------------------

### Create and Log to SQLite Database

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/sqlite3/README.md

Example of opening a SQLite database target, creating the default logs table if it doesn't exist, and adding a simple message. This demonstrates the basic usage of Stumpless SQLite targets without requiring direct SQLite3 functions.

```c
struct stumpless_target *db_target;

// create the new database (or open the existing one)
db_target = stumpless_open_sqlite3_target( "stumpless_example.sqlite3" );

// create the default logs table (if it doesn't exist)
stumpless_create_default_sqlite3_table( db_target );

// send a simple message to our new logs table
stumpless_add_message( db_target, "cards are on the table" );
```

--------------------------------

### Conditional Installation of HTML Documentation

Source: https://github.com/goatshriek/stumpless/blob/latest/CMakeLists.txt

Includes a CMake script to install HTML documentation if the INCLUDE_HTML_IN_INSTALL option is enabled and supported. This provides web-based documentation.

```cmake
if(INCLUDE_HTML_IN_INSTALL)
  include("${PROJECT_SOURCE_DIR}/tools/cmake/install_html.cmake")
endif()
```

--------------------------------

### Install Debian Package

Source: https://github.com/goatshriek/stumpless/blob/latest/INSTALL.md

Use this command to install the Stumpless .deb package on Debian-based systems. You may need root privileges.

```sh
# you might need sudo (or root privileges) to install
dpkg -i libstumpless-2.2.0-amd64.deb
```

--------------------------------

### Install RPM Package

Source: https://github.com/goatshriek/stumpless/blob/latest/INSTALL.md

Install the Stumpless .rpm package on Red Hat Linux environments. Ensure you have the necessary permissions.

```sh
# again, make sure you have the correct permissions
rpm -i libstumpless-2.2.0-x86_64.rpm
```

--------------------------------

### Combine Log Masks with Stumpless

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/filter/README.md

This example demonstrates how to combine multiple severity masks using bitwise OR operations to include specific severity levels.

```c
// this will allow EMERG, ALERT, CRIT, ERR, and DEBUG severity messages
umplog_set_mask( STUMPLESS_SEVERITY_MASK( STUMPLESS_SEVERITY_DEBUG )
                     | STUMPLESS_SEVERITY_MASK_UPTO( STUMPLESS_SEVERITY_ERR ) );
```

--------------------------------

### Install Gentoo Ebuild

Source: https://github.com/goatshriek/stumpless/blob/latest/INSTALL.md

Install Stumpless using an ebuild file on Gentoo systems. This command merges the package after cleaning and manifesting.

```sh
ebuild libstumpless-2.2.0.ebuild clean manifest install merge
```

--------------------------------

### Add Default WEL Event Source

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/wel/README.md

Installs the necessary registry entries for the default 'Stumpless' event source. This function should be called with appropriate permissions and when the library or executable is in its final location. It can be called multiple times without duplication.

```c
stumpless_add_default_wel_event_source();
```

--------------------------------

### Clone and Build Stumpless

Source: https://github.com/goatshriek/stumpless/blob/latest/README.md

Clone the latest version of the Stumpless source tree, create a build directory, configure the build with cmake, and then build the library. The installation step may require administrator privileges.

```sh
git clone git@github.com:goatshriek/stumpless.git

# creating a new build directory
mkdir build
cd build

# configuring the new build
cmake ../stumpless

# building stumpless (with 4 threads - adjust as desired)
cmake --build . --parallel 4

# install the library (you probably need sudo to do this)
sudo cmake --install .
```

--------------------------------

### Specify Severity with Facility

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/severity_level/README.md

When logging, you must combine a facility code with a severity code. This example shows the verbose way to specify an error severity.

```c
stumplog( STUMPLESS_FACILITY_DAEMON | STUMPLESS_SEVERITY_ERR,
          "the cheese daemon failed again..." );
```

--------------------------------

### Query Custom SQLite3 Log Table

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/sqlite3/README.md

This command-line example shows how to query the custom `card_logs` table using `sqlite3` to verify that the log entry was inserted correctly with its structured data.

```bash
$ sqlite3 -header -column stumpless_example.sqlite3
SQLite version 3.22.0 2018-01-22 18:45:57
Enter ".help" for usage hints.
sqlite> SELECT * FROM card_logs;
log_id      facility    severity    timestamp                    structured_data                                    message
----------  ----------  ----------  ---------------------------  -------------------------------------------------  -----------------
1           8           6           2023-11-23T19:05:33.234523Z  [card suit="hearts" rank="5"][player name="bill"]  a card was played
```

--------------------------------

### Log with EMERG Severity using INFO Macro

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/severity_level/README.md

This example demonstrates how a convenience macro, like `stumplog_i` (INFO level), can be used to log a message with a different severity (EMERG in this case) if explicitly provided.

```c
// this one has a severity of EMERG, despite being an INFO level call
stumplog_i( STUMPLESS_FACILITY_KERN | STUMPLESS_SEVERITY_EMERG,
            "THE SYSTEM IS DOWN!!!" );
```

--------------------------------

### Open a File Target and Log a Simple Message

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/basic/README.md

Opens a file target for logging and sends a basic "hello world" message. Ensure the file target is closed when done.

```c
file_target = stumpless_open_file_target( "example.log" );
stump( "The hello world of stumpless." );
```

--------------------------------

### Create and Log to a File Target (C++)

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/cpp/README.md

Demonstrates opening a file target for logging and logging a simple message. The constructor takes the log file path.

```cpp
#include <stumpless.hpp>

// ...

FileTarget file_logger( "logfile.log" );
```

--------------------------------

### Verify Build with Test Suite

Source: https://github.com/goatshriek/stumpless/blob/latest/INSTALL.md

Run the test suite to verify the build. The 'check' target will download and build Google Test on its first invocation.

```bash
cmake --build . --target check
```

--------------------------------

### Construct and Log a Detailed Entry (C++)

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/cpp/README.md

Illustrates creating a log entry with a specific application name, message ID, and structured data, including elements and parameters, then logging it to a file target.

```cpp
Entry up_to_code( Facility::USER,
                  Severity::INFO,
                  "cpp-demo-app",
                  "up-to-code",
                  "is it up to code?" );

// makes an element named 'subject' and adds it to the entry
Element item( "subject" );
up_to_code.AddElement( item );

// adds a few parameters to the element
Param name( "name", "baked alaska" );
Param result( "result", "not-up-to-code" );

// most `Add` and `Set` methods can be chained together
item.AddParam( name ).AddParam( result );

// writing an entry to the log file
file_logger.Log( up_to_code );

// the resulting entry looks like this:
// <14>1 2020-05-05T19:55:48.368156Z Angus cpp-demo-app 4484 up-to-code [subject name="baked alaska" result="not-up-to-code"] is it up to code?
```

--------------------------------

### Check Build Configuration Constants (C++)

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/cpp/README.md

Illustrates how to check build configuration constants, such as whether socket targets are supported, using C preprocessor directives and C++ namespace constants.

```cpp
#ifdef STUMPLESS_SOCKET_TARGETS_SUPPORTED
  std::stdout << "logging to " << STUMPLESS_DEFAULT_SOCKET << " by default" << std::endl;
#endif

// this check still has to use the C #define
#ifdef STUMPLESS_SOCKET_TARGETS_SUPPORTED
  // this one has a constant that can be used instead
  std::stdout << "logging to " << SocketTarget::DEFAULT_SOCKET << " by default" << std::endl;
#endif
```

--------------------------------

### Create File Target and Log Entry in C++

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/cpp.md

Instantiate a FileTarget and an Entry object for logging. Ensure the necessary headers are included.

```cpp
#include <stumpless.hpp>

// ...

FileTarget myLogFile( "logfile.log" );

Entry processStarting( Facility::USER,
                       Severity::INFO,
                       "my-application",
                       "process-start-msgid",
                       "A new process is starting."
                     );
```

--------------------------------

### Conditional Installation of Manpages

Source: https://github.com/goatshriek/stumpless/blob/latest/CMakeLists.txt

Includes a CMake script to install manpages if the INCLUDE_MANPAGES_IN_INSTALL option is enabled and supported. This provides command-line documentation.

```cmake
if(INCLUDE_MANPAGES_IN_INSTALL)
  include("${PROJECT_SOURCE_DIR}/tools/cmake/install_manpages.cmake")
endif()
```

--------------------------------

### Build and Run Tests with Configuration (Multi-Config Systems)

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/development.md

For multi-config build systems like Visual Studio, include the --config argument to specify the build configuration (e.g., x64-Debug) when building and running tests.

```sh
cmake --build . --parallel 4 --config x64-Debug --target check
```

--------------------------------

### Install MinGW Build Dependencies on MSYS2

Source: https://github.com/goatshriek/stumpless/blob/latest/INSTALL.md

Installs MinGW-specific CMake, make, GCC, and Doxygen packages using pacman. Ensure you are in a MinGW shell.

```sh
pacman -S $MINGW_PACKAGE_PREFIX-cmake \
          $MINGW_PACKAGE_PREFIX-make \
          $MINGW_PACKAGE_PREFIX-gcc \
          $MINGW_PACKAGE_PREFIX-doxygen
```

--------------------------------

### Run Performance Benchmarks

Source: https://github.com/goatshriek/stumpless/blob/latest/INSTALL.md

Execute performance benchmarks using the 'bench' target. This target will download and build Google Benchmark on its first invocation.

```bash
cmake --build . --target bench
```

--------------------------------

### Journald Structured Log Output Example

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/journald/README.md

An example of the JSON output from `journalctl` when querying structured log entries sent to journald. This shows how custom parameters are represented as fields.

```json
{
	"_BOOT_ID" : "e62cf00fedf64d9d8021aa4c62982cb3",
	"MY_REACH" : "global",
	"MY" : "",
	"PRIORITY" : "6",
	"__REALTIME_TIMESTAMP" : "1627776664688160",
	"MY_TOWER" : "secure",
	"__CURSOR" : "s=f7b7ebc77b4b4a23883ba6adf6976ca3;i=278;b=e62cf00fedf64d9d8021aa4c62982cb3;m=151ec212;t=5c87449df5620;x=addbc8df5d0f316c",
	"SYSLOG_TIMESTAMP" : "2021-08-01T00:11:04.687283Z",
	"SYSLOG_IDENTIFIER" : "daily-journal",
	"__MONOTONIC_TIMESTAMP" : "354337298",
	"SYSLOG_MSGID" : "detailed-status",
	"MY_CAUSE" : "noble",
	"_UID" : "1000",
	"_GID" : "1000",
	"_PID" : "763",
	"_TRANSPORT" : "journal",
	"SYSLOG_PID" : "763",
	"_SOURCE_REALTIME_TIMESTAMP" : "1627776664687293",
	"MESSAGE" : "alive and on top",
	"SYSLOG_FACILITY" : "3",
	"MY_POWER" : "pure",
	"_MACHINE_ID" : "6e82c858acbd49a0802be698e8f3cb10",
	"_HOSTNAME" : "debian-10-9"
}
```

--------------------------------

### Configure Project with CMake (Release)

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/windows-msys2-mingw64.md

Configure the build using CMake and Ninja for a Release build type. This creates a 'build' directory.

```sh
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
```

--------------------------------

### Combined Custom Filter Function

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/filter/README.md

This example shows how to create a custom filter that combines element name filtering with the default Stumpless mask filtering logic.

```c
bool
ignore_element_filter( const struct stumpless_target *target,
                       const struct stumpless_entry *entry ) {
  return !stumpless_get_element_by_name( entry, "ignore" )
           && stumpless_mask_filter( target, entry );
}
```

--------------------------------

### Get Current Error Struct

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/development.md

Retrieves the current error struct if the last call failed. This is one of the common error handling functions provided for users.

```c
struct stumpless_error *error = stumpless_get_error();
```

--------------------------------

### Build and Run Tests with Parallel Execution

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/development.md

After making code changes, build the project and run the test suite. Use the --parallel argument to speed up the build process based on your processor's core count.

```sh
cmake --build . --parallel 4 --target check
```

--------------------------------

### Get and Set Target Log Mask

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/filter/README.md

These functions allow you to retrieve the current log mask for a specific target and set a new mask, useful for fine-grained control.

```c
// let's see what we have now
mask = stumpless_get_target_mask( target );

// and make sure that DEBUG messages are NOT included
new_mask = mask & ~STUMPLESS_SEVERITY_MASK( STUMPLESS_SEVERITY_DEBUG ) );
umplog_set_target_mask( target, new_mask );
```

--------------------------------

### Open Local and Remote WEL Targets

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/wel/README.md

Opens an Event Log on the local machine or a remote server with a given name. Ensure the target name is descriptive.

```c
local_wel_target = stumpless_open_local_wel_target( "Stumpless Example" );

remote_wel_target = stumpless_open_remote_wel_target( "\\RemoteServerName",
                                                      "Stumpless Example" );
```

--------------------------------

### Run Specific Test with gtest_filter

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/test.md

To run a specific test or a group of tests, pass the `gtest_filter` option to the test executable. This example shows how to run all tests matching 'SetParam*'.

```bash
./function-test-entry --gtest_filter=SetParam*
```

--------------------------------

### Custom Filter Function

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/filter/README.md

Define a custom filter function that takes a target and entry, returning true if the entry should be logged. This example filters out entries containing an element named 'ignore'.

```c
bool
ignore_element_filter( const struct stumpless_target *target,
                       const struct stumpless_entry *entry ) {
  return !stumpless_get_element_by_name( entry, "ignore" );
}
```

--------------------------------

### Build and Run Specific Benchmark Test

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/benchmark.md

This shell command demonstrates how to build a specific performance test executable for elements and then run the `CopyElement` benchmark, filtering by its name. This is useful for isolating and testing performance changes.

```sh
make performance-test-element && ./performance-test-element --benchmark_filter=CopyElement
```

--------------------------------

### System Page Size Retrieval

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/portability.md

Selects the appropriate function to get the system's memory page size based on available headers (`unistd.h` or `windows.h`). Includes fallback if neither is available.

```c
#ifdef HAVE_UNISTD_H
#  include "private/config/have_unistd.h"
#  define config_getpagesize unistd_getpagesize
#elif HAVE_WINDOWS_H
#  include "private/config/have_windows.h"
#  define config_getpagesize windows_getpagesize
#else
#  include "private/config/fallback.h"
#endif
```

--------------------------------

### Open a File Target

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/file/README.md

Use this function to create a new file target. The provided string will be used as the filename, including any necessary path components.

```c
file_target = stumpless_open_file_target( "path/to/myfile.log" );
```

--------------------------------

### Querying the SQLite Logs Table

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/sqlite3/README.md

This is an example of how a log entry would appear in the 'logs' table after being added using Stumpless. It shows the structure of the data within the table, including the auto-generated log_id and the inserted message.

```bash
$ sqlite3 -header -column stumpless_example.sqlite3
SQLite version 3.22.0 2018-01-22 18:45:57
Enter ".help" for usage hints.
sqlite>
sqlite> SELECT * FROM logs;
log_id      prival      version     timestamp                    hostname    app_name    procid      msgid       structured_data  message
----------  ----------  ----------  ---------------------------  ----------  ----------  ----------  ----------  ---------------  ----------------------
1           14          1           2023-11-22T04:35:02.909888Z  Angus                   3090                                     cards are on the table
```

--------------------------------

### Log Messages with Different Priorities (C++)

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/cpp/README.md

Shows how to log messages to a file target with different levels of detail, including just a message, a message with facility and severity, and a message with formatting.

```cpp
// logs the given message to the file
file_logger.Log( "she just made ANOTHER u-turn" );
// the entry will look like this:
// <14>1 2020-05-15T16:28:56.266031Z Angus - 4484 - - she just made ANOTHER u-turn
// 'Angus' is the name of the system this was logged on
// the three '-' characters are the app name, the message id, and the structured data,
// which were all empty here
// '4484' is PID of the process that logged this message

// logs the given message to the file at the given priority
file_logger.Log( Facility::NEWS, Severity::EMERGENCY,
                 "Helen's lost again!!!" );
// the entry will look like this:
// <56>1 2020-05-15T16:28:56.267113Z Angus - 4484 - - Helen's lost again!!!

// logs the given message and format strings to the file
// you can use format strings with the previous forms as well if you want to
file_logger.Log( "she has gotten lost %d times in the last %d days", 25, 3 );
// the entry will look like this:
// <14>1 2020-05-15T16:28:56.267128Z Angus - 4484 - - she has gotten lost 25 times in the last 3 days
```

--------------------------------

### Build Documentation with CMake

Source: https://github.com/goatshriek/stumpless/blob/latest/INSTALL.md

Build the library's documentation using the 'docs' target. This requires doxygen to be detected during the CMake configuration step.

```bash
cmake --build . --target docs
```

--------------------------------

### Apply Severity Mask to Stdout Target

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/chain/README.md

Applies a severity mask to the stdout target to filter log messages. Messages below INFO severity and messages of the highest severity are excluded. Refer to the filter example for more details on using masks.

```c
mask = STUMPLESS_SEVERITY_MASK_UPTO( STUMPLESS_SEVERITY_INFO )
         & ~STUMPLESS_SEVERITY_MASK_UPTO( STUMPLESS_SEVERITY_ERR );
stumpless_set_target_mask( stdout_target, mask );
```

--------------------------------

### Create Network Target using Builder Pattern (TCP/IPv4)

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/network/README.md

Creates a network target using the builder pattern, allowing configuration before opening. This is useful for targets that may not be immediately available, like TCP destinations.

```c
new_target = stumpless_new_network_target( "new-tcp4-target",
                                           STUMPLESS_IPV4_NETWORK_PROTOCOL,
                                           STUMPLESS_TCP_TRANSPORT_PROTOCOL );
umpless_target_is_open( new_target ); // will return false
umpless_set_destination( new_target, "example.com" );
umpless_set_transport_port( new_target, "6514" );
umpless_open_target( new_target );
umpless_target_is_open( new_target ); // will return true, assuming success
```

--------------------------------

### Configure Project with CMake (Disable Optional Targets)

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/windows-msys2-mingw64.md

Configure the build while explicitly disabling optional targets like SQLite3 and journald on Windows for a quieter configuration.

```sh
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DENABLE_SQLITE3_TARGETS=OFF \
  -DENABLE_JOURNALD_TARGETS=OFF
```

--------------------------------

### Create and Add Entry with Structured Data

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/sqlite3/README.md

This C code demonstrates creating a new log entry with structured data and adding it to the Stumpless target, which will use the custom INSERT SQL.

```c
entry = stumpless_new_entry( STUMPLESS_FACILITY_USER,
                             STUMPLESS_SEVERITY_INFO,
                             "card-counter",
                             "card-played",
                             "a card was played" );

stumpless_add_new_param_to_entry( entry, "card", "suit", "hearts" );
stumpless_add_new_param_to_entry( entry, "card", "rank", "5" );
stumpless_add_new_param_to_entry( entry, "player", "name", "bill" );

stumpless_add_entry( db_target, entry );
```

--------------------------------

### Replace Syslog with Stumplog

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/basic/README.md

Demonstrates how to replace the standard `syslog` function with `stumplog`, which has an identical signature and behavior for easier migration.

```c
syslog( LOG_INFO | LOG_USER, "Failed login for %s", username );

// the above can be directly replaced with:
stumplog( LOG_INFO | LOG_USER, "Failed login for %s", username );
```

--------------------------------

### Query Runtime Version Information with stumpless_version_cmp and stumpless_version_to_string

Source: https://context7.com/goatshriek/stumpless/llms.txt

Query the library version at runtime and compare versions programmatically. The string returned by `stumpless_version_to_string` must be freed by the caller.

```c
#include <stdio.h>
#include <stdlib.h>
#include <stumpless.h>
#include <stumpless/version.h>

int main( void ) {
  struct stumpless_version *v = stumpless_get_version();
  char *v_str = stumpless_version_to_string( v );

  printf( "Running stumpless %s (major=%d, minor=%d, patch=%d)\n",
          v_str, v->major, v->minor, v->patch );
  free( v_str );

  struct stumpless_version min_required = { 2, 1, 0 };
  int cmp = stumpless_version_cmp( v, &min_required );
  if( cmp < 0 ) {
    fprintf( stderr, "ERROR: stumpless >= 2.1.0 required\n" );
  }

  free( v );
  stumpless_free_all();
  return 0;
}
// Output: Running stumpless 3.0.0 (major=3, minor=0, patch=0)
```

--------------------------------

### Create and Populate Simple Chain

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/chain/README.md

Creates a new chain target and adds the previously configured stdout and file targets to it. Log messages sent to this chain will be processed by both targets.

```c
// create a new chain
simple_chain = stumpless_new_chain( "example-simple-chain" );

// add our targets to the chain
stumpless_add_target_to_chain( simple_chain, stdout_target );
stumpless_add_target_to_chain( simple_chain, file_target );
```

--------------------------------

### Error Handling with Try-Catch (C++)

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/cpp/README.md

Demonstrates how to use try-catch blocks to handle Stumpless exceptions in C++, specifically catching an error related to an empty argument and checking the error ID.

```cpp
try {
  file_logger.SetDefaultAppName( NULL );
} catch( StumplessException *e ) {
  // will catch the exception
  if( e->GetErrorId() == ErrorId::ARGUMENT_EMPTY ) {
    std::cout << "the app name was NULL!" << std::endl;
  }
}
```

--------------------------------

### Build with Parallel Jobs

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/test.md

Use the `make -j` flag to specify the number of parallel jobs for building. Adjust the number to control build speed.

```bash
make -j 4 check
```

--------------------------------

### Open and Close File Target

Source: https://context7.com/goatshriek/stumpless/llms.txt

Opens a file for appending logs in RFC 5424 format. The file is created if it doesn't exist. Ensure stumpless_free_all() is called to clean up resources.

```c
#include <stumpless.h>
#include <stdlib.h>

int main( void ) {
  struct stumpless_target *file_target;

  file_target = stumpless_open_file_target( "application.log" );
  if( !file_target ) {
    perror( "failed to open file target" );
    return EXIT_FAILURE;
  }

  stumpless_add_message( file_target, "Service initialised successfully" );
  stumpless_add_log( file_target,
                     STUMPLESS_SEVERITY_ERR | STUMPLESS_FACILITY_DAEMON,
                     "Config reload failed: %s", "permission denied" );

  stumpless_close_file_target( file_target );
  stumpless_free_all();
  return EXIT_SUCCESS;
}
// application.log will contain two RFC 5424-formatted lines
```

--------------------------------

### Open File and Stdout Targets

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/chain/README.md

Opens a file target for writing log messages and a stdout target for console output. These will be used as destinations in a simple chain.

```c
file_target = stumpless_open_file_target( "chain-example.log" );
stdout_target = stumpless_open_stdout_target( "chain-example-stdout" );
```

--------------------------------

### Create a New Entry - C

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/entry/README.md

Creates a new log entry with mandatory fields. Timestamp and process ID are automatically filled when logged.

```c
entry = stumpless_new_entry( STUMPLESS_FACILITY_USER,
                             STUMPLESS_SEVERITY_INFO,
                             "my-app-name",
                             "my-msgid",
                             "my event message" );
```

--------------------------------

### Log Entry to Target in C++

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/cpp.md

Log a previously created Entry object to a FileTarget using the Log function. This requires a valid target and entry.

```cpp
myLogFile.Log( processStarting );
```

--------------------------------

### Build and Run Test Suite

Source: https://github.com/goatshriek/stumpless/blob/latest/INSTALL.md

Builds and executes the test suite for Stumpless using CMake's build mode with the '--target check' option.

```sh
# we can build and run any other target with the `--target` option
# for example, this invocation builds and runs the test suite
cmake --build . --target check

```

--------------------------------

### Custom SQLite3 Prepare Function for Stumpless

Source: https://github.com/goatshriek/stumpless/blob/latest/docs/examples/sqlite3/README.md

This C function prepares and binds data for two SQL INSERT statements using `sqlite3_prepare_v2` and `sqlite3_bind_text`. It extracts 'suit', 'rank', and 'name' from the Stumpless entry and returns an array of prepared statements. Ensure SQLite headers and libraries are linked.

```c
static sqlite3_stmt *card_stmts[2] = { NULL, NULL };

void *
card_played_prepare( const struct stumpless_entry *entry,
                     void *data,
                     size_t *count ) {
  sqlite3 *db = data;
  const char *card_insert_sql = "INSERT INTO played_cards ( suit, rank ) "
                                "VALUES ( $suite, $rank )";
  const char *player_insert_sql = "INSERT INTO taken_turns ( player_name ) "
                                  "VALUES ( $name )";
  const char *suit;
  const char *rank;
  const char *name;

  sqlite3_prepare_v2( db, card_insert_sql, -1, &card_stmts[0], NULL );
  sqlite3_prepare_v2( db, player_insert_sql, -1, &card_stmts[1], NULL );

  suit = stumpless_get_entry_param_value_by_name( entry, "card", "suit" );
  rank = stumpless_get_entry_param_value_by_name( entry, "card", "rank" );
  name = stumpless_get_entry_param_value_by_name( entry, "player", "name" );

  sqlite3_bind_text( card_stmts[0], 1, suit, -1, SQLITE_TRANSIENT );
  sqlite3_bind_text( card_stmts[0], 2, rank, -1, SQLITE_TRANSIENT );
  sqlite3_bind_text( card_stmts[1], 1, name, -1, SQLITE_TRANSIENT );

  free( ( char * ) suit );
  free( ( char * ) rank );
  free( ( char * ) name );

  *count = 2;
  return &card_stmts;
}
```