libsir 2.2.5
Standard Incident Reporter
Loading...
Searching...
No Matches
libsir

libsir—a lightweight, cross-platform library for information distribution

Release Commits License OpenHub GitLab Coverage Coverity REUSE Maintainability Reliability Security Scorecard Practices

Overview

Synopsis

libsir is a cross-platform, thread-safe logging library written in C (ISO/IEC 9899:2011 C11) that is designed to simplify and streamline the generation and distribution of human-readable information in software.

Using libsir, you can make a single call that simultaneously sends information to multiple destinations, each with their own individual preference for format and levels.

Each 'level' or 'priority' of output can be visually styled however you wish for stdio destinations. This allows for immediate visual confirmation that a message appeared in the terminal that you should pay attention to, while less pressing information is more subtle in appearance.

libsir visual graph

Notables

  • No dependencies (other than libc and pthreads). On Windows, libsir uses the native synchronization API.
  • Accompanied by a robust test suite to ensure dependable behavior, even if you make modifications to the source.
  • Won't fail silently—C library or platform level errors are captured and stored for posterity, on a per-thread basis. The function, file, and line number from which it originated are also captured. Additionally, libsir defines its own set of error messages to aid in troubleshooting.
  • Hardened—every function contains sanity checks for internal state as well as arguments passed in through the external interfaces. libsir's standard make recipes use ‑Wall ‑Wextra ‑Wpedantic (and pass with ‑Wmissing‑prototypes ‑Wdouble‑promotion ‑Wfloat‑conversion ‑Wmissing‑declarations ‑Wswitch‑enum ‑Wformat‑nonliteral ‑Wformat‑truncation ‑Wbad‑function‑cast ‑Wextra‑semi‑stmt, too.)
  • Full documentation, thanks to Doxygen.
  • Lightweight—the shared library comes in at around 70 KiB, and the static library around 50 KiB.

Cross-platform compatibility

At this time, libsir is supported (that is, it compiles and passes the test suites) on at least the following operating system and toolchain combinations:

System Toolchain
Linux ≳2.6.32
(glibc ≳2.4, musl ≳1.2.3, uClibc‑ng ≳1.0.43)
GCC (4.8.4 ‑ 14.2.1),  Clang (3.8 ‑ 18.1.8),  Oracle Studio C/C++ (≳12.6),  Circle (1.0.0‑210 ‑ 1.0.0‑217),  IBM Advance Toolchain (14 ‑ 17),  IBM XL C/C++ (16.1.1.2 ‑ 16.1.1.15),  IBM Open XL C/C++ (17.1.1.0 ‑ 17.1.1.2),  NVIDIA HPC SDK C/C++ (23.5 ‑ 24.7),  Arm HPC C/C++ (22.1 ‑ 24.04),  DMD ImportC (2.104.2 ‑ 2.110.0),  AMD Optimizing C/C++ (4.0.0 ‑ 4.2.0),  Intel oneAPI DPC++/C++ (2023.1 ‑ 2024.2.1),  Open64 (5, AMD 4.5.2.1),  Intel C++ Compiler Classic (2021.9.0 ‑ 2021.10.0),  Portable C Compiler (1.2.0.DEVEL‑20230730),  Kefir (≳0.3.0),  Chibicc (2020.12.6),  CompCert C (3.11 ‑ 3.14, no‑TLS),  Chamois‑CompCert C (3.14‑20231130, TLS)
Android ≳5 Android NDK (r25c ‑ r27b)
IBM AIX 7.2, 7.3 GCC (8.3 ‑ 12.3),  Clang (18.1.2 ‑ 18.1.8),  IBM XL C/C++ (16.1.0.3 ‑ 16.1.0.18),  IBM Open XL C/C++ (17.1.1.1 ‑ 17.1.2.9)
IBM i (PASE) 7.5 GCC (10.3.0 ‑ 10.5.0),  IBM XL C/C++ (16.1.0.15 ‑ 16.1.0.18)
macOS ≳10.15 Xcode (11.7 ‑ 16.0),  GCC (10.4 ‑ 14.2.0),  Clang (11.0.3 ‑ 18.1.8),  DMD ImportC (2.105.0 ‑ 2.110.0),  Intel C++ Compiler Classic (2021.9.0 ‑ 2021.10.0)
Windows ≳10, 11 Microsoft Visual C/C++ (17.6 ‑ 17.11.3),  Clang‑CL (16.0.6 ‑ 18.1.8),  GCC‑MinGW (12.2.1 ‑ 14.2.1),  LLVM‑MinGW (15.0 ‑ 18.1.8),  Embarcadero C++ (7.20 ‑ 7.70),  OrangeC (≳6.71.10)
Cygwin 3.4 GCC (11.2 ‑ 13.2.1)
FreeBSD ≳11.3 GCC (11.4 ‑ 13.2.1),  Clang (10 ‑ 18.1.8),  DMD ImportC (2.105.0 ‑ 2.110.0)
NetBSD 9.2 GCC (7.5 ‑ 13.2),  Clang (15.0.7 ‑ 17.0.6)
OpenBSD 7.3 GCC (11.2),  Clang (13 ‑ 17.0.6),  DMD ImportC (2.106.0 ‑ 2.110.0)
DragonFly BSD 6.4 GCC (8.3 ‑ 13),  Clang (10.0.1 ‑ 17.0.6)
GNU/Hurd GCC (9.5 ‑ 13.2),  Clang (9.0.1 ‑ 13.0.1)
Haiku R1b4 GCC (11.2 ‑ 13.2),  Clang (12.0.1 ‑ 17.0.6)
Solaris 11.4 GCC (10.3 ‑ 11.2),  Clang (6 ‑ 18.1.8),  Oracle Studio C/C++ (≳12.6)
illumos GCC (7.5 ‑ 13.2),  Clang (15.0.7 ‑ 18.1.8),  Oracle Studio C/C++ (≳12.6)
SerenityOS GCC (13.1)
WebAssembly/JS Emscripten (3.1.45 ‑ 3.1.66),  Node.js (20.5.0 ‑ 22.8.0)
  • libsir is known to work on most common (and many uncommon) architectures. It has been built and tested on Intel (x86_64, i686, x32), ARM (ARMv6, ARMv7HF, ARMv8‑A), POWER (PowerPC, PPC64, PPC64le), MIPS (MIPS64, MIPS32, 74Kc), SPARC (SPARC64, V8, LEON3), z/Architecture (S390X), SuperH (SH‑4A), RISC‑V (RV32, RV64), OpenRISC (OR1200), Kalray MPPA® (Coolidge™, KVX), and m68k (ColdFire, 68020+).
  • This table only lists toolchains that have been tested and is by no means exhaustive—newer (or older) versions are likely to work without fanfare. In fact, if it doesn't work on your machine, it's probably a bug.

System Loggers

libsir currently supports the following system logging facilities:

Log Facility System Description
Event Log Windows System log viewable with Event Viewer
os_log macOS System log viewable with Console (or log)
syslog (many) BSD-style system logging via syslog() (local only)

C++ compatibility

Language Bindings

  • Bindings for scripting tools and other high-level programming languages are available, including support for:

     Ch 
     Python 

An example

Some sample terminal output from libsir demonstrating the default text styling settings for stdio (note that this is just a sample; libsir supports 4, 8, and 24-bit color modes, so a virtually limitless number of configurations are possible):

sample terminal output

This output is from the example application, whose source code can be located in the example directory. If you're curious about a very basic implementation of libsir in a practical context, that's a good place to start.

Coming soon: A C++20 version of the example program.

Building from source

There are several options available for building libsir from source:

Unix Makefile

The Makefiles are compatible with GNU Make version 3.81 and later (4.4 recommended) and support both native and cross-compilation builds on most Unix-like operating systems: AIX, Solaris, illumos, Linux, macOS, Cygwin, BSD, GNU/Hurd, Haiku, etc.

Environment variables

A number of environment variables are available which affect the way in which libsir and its various build artifacts are created (e.g., turning off optimizations and enabling debug symbols). Information about these variables and how to use them with GNU make can be found in the online documentation.

Recipes

Recipe Type Command     Output file(s)
Test suite (C) make tests
  • build/bin/sirtests[.exe]
Test suite (C++) make tests++
  • build/bin/sirtests++[.exe]
Example app make example
  • build/bin/sirexample[.exe]
Static library make static
  • build/lib/libsir_s.a
nShared library make shared
  • build/lib/libsir.so
Installation make install
  • $PREFIX/lib/libsir_s.a
  • $PREFIX/lib/libsir.so
  • $PREFIX/include/sir.h
  • $PREFIX/include/sir/*.h

Visual Studio Code

A VS Code workspace file is located in the root of the repository (sir.code-workspace). Build tasks are only configured for macOS and Linux. On other platforms, use the integrated terminal to run GNU `make` manually.

Build Tasks

To run a task, open the command list (⌘ + ⇧ + P on macOS, ⌃ + ⇧ + P on Linux), then start typing "run task" until you see "Tasks: Run Task". Click the item or press the key combination listed next to it. You should then see a drop-down menu containing all of the build tasks for libsir, which are listed here:

Build Task Description
Clean Deletes all intermediate files and previously compiled binaries.
Static Library Compiles libsir as a static library.
Static Library [DBG] Compiles libsir as a static library with debug symbols.
Shared Library Compiles libsir as a shared library.
Shared Library [DBG] Compiles libsir as a shared library with debug symbols.
C Test Suite Compiles the C test suite.
C Test Suite [DBG] Compiles the C test suite with debug symbols.
C++ Test Suite Compiles the C++ test suite.
C++ Test Suite [DBG] Compiles the C++ test suite with debug symbols.
C Example App Compiles the C sample application.

The VS Code build tasks execute make under the hood—the non-debug tasks map directly to the recipes listed under Unix Makefile; the debug tasks utilize libsir's custom environment variables to control the build process.

Visual Studio 2022

A Visual Studio 2022 solution containing appropriate project files can be found in the msvs directory. Tested on Windows 11 (x86, x64, and Arm64) with Visual Studio 17.6+. See the README for more information.

MSBuild

Visual Studio is technically not required in order to build the Visual Studio 2022 solution; this may also be accomplished using "Build Tools for Visual Studio 2022" (download, reference). This is a stand-alone toolchain that does not require Visual Studio 2022 and includes compilers and MSBuild.

Using MSBuild from the command-line

Using MSBuild is pretty straightforward. Start a Developer Command Prompt, and then just supply the path to the .sln file, task (e.g. build), configuration (e.g. release), and platform (e.g. x64). Here's an example that builds libsir in release mode for x86_64 when executed from the root of the libsir repository:

MSBuild .\msvs\libsir.sln -t:Rebuild -p:Configuration=Release -p:Platform=x64

Dig in

If you are genuinely interested in utilizing libsir, you are encouraged to read the full online documentation to get a better understanding of the library's capabilities and interfaces.

Suggested initial sections:

GNU Global

SAST Tools

The developers are obsessed with the quality, reliability, and correctness of libsir.

The following SAST (static application/*analysis security*/*software testing*) and dynamic verification tools are used—on every commit—as part of our comprehensive continuous integration testing process:

Tool Usage
PVS-Studio Static analysis tool for C, C++, C#, and Java code
Clang Analyzer, Sanitizers Static and dynamic analysis tools for C, C++, and Objective-C code
Coveralls, gcovr Line-by-line test coverage reporting and statistical analysis
Coverity® Scan Find and fix defects in Java, C/C++, C#, JS, Ruby, and Python code
Cppcheck Static analysis tool for C and C++ code
DUMA Detect Unintended Memory Access, a memory debugger
Flawfinder Scans C and C++ source code for potential security weaknesses
GCC Static Analyzer Coverage-guided symbolic execution static analyzer for C code
GNU Cppi C preprocessor directive linting, indenting, and regularization
GNU Global Source code indexing and tagging system
OpenOSC Object size checking library to detect buffer overflows in C/C++ code
Oracle Developer Studio Performance, security, and thread analysis tools for C, C++, and Fortran
REUSE Verifies compliance with the REUSE licensing guidelines
Semgrep A fast, open-source, static analysis engine for many languages
SonarCloud Cloud-based code quality and security analysis tools
Valgrind Tools for memory debugging, memory leak detection, and profiling
Visual Studio Code Analyzer Tools to analyze and improve C/C++ source code quality

Other Tools

Additional tools used for libsir development and testing include:

Tool Usage
CBMC, ESBMC Bounded Model Checkers for C and C++ programs
Dr. Memory Memory debugging tool for Windows, Linux, macOS, and Android
Funcheck A tool for checking function call return protections
Frama-C Framework for Modular Analysis of C programs
Intel® VTune™ Profiler Performance analysis and profiling tools for Intel systems
Luke Stackwalker Sampling C/C++ code profiler for Microsoft Windows
NetBSD lint(1) A C (C90/C99/C11/C17/C23) program verifier
PurifyPlus™ Run-time analysis tools for application reliability and performance
ShellCheck A static analysis tool for Unix shell scripts
Smatch Smatch (Source Matcher) is a static analysis tool for C code
SoftIntegration Ch C/C++ interpreter and interactive platform for scientific computing
Very Sleepy Sampling CPU profiler for Microsoft Windows applications
Vftrace A performance profiling library with a focus on HPC applications