libsir

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

Overview

• Synopsis
• Notables
• Cross-platform compatibility
  • System Loggers
  • C++ compatibility
  • Language Bindings
• An example
• Building from source
  • Unix Makefile
    • Environment Variables
    • Recipes
  • Visual Studio Code
    • Build Tasks
  • Visual Studio 2022
    • MSBuild
• Dig in
  • GNU Global
• SAST Tools
• Other Tools

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.0.1),  Clang (3.8 ‑ 18.1.3),  Oracle Studio C/C++ (≳12.6),  Circle (1.0.0‑200),  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.3),  Arm HPC C/C++ (22.1 ‑ 23.10),  DMD ImportC (2.104.2 ‑ 2.108.0),  AMD Optimizing C/C++ (4.0.0 ‑ 4.2.0),  Intel oneAPI DPC++/C++ (2023.1 ‑ 2024.1.0),  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 ‑ r26c)
IBM AIX 7.2, 7.3	GCC (8.3 ‑ 12.3),  Clang (18.1.2 ‑ 18.1.3),  IBM XL C/C++ (16.1.0.3 ‑ 16.1.0.16),  IBM Open XL C/C++ (17.1.1.1 ‑ 17.1.2.4)
IBM i (PASE) 7.5	GCC (10.3.0 ‑ 10.5.0),  IBM XL C/C++ (16.1.0.16)
macOS ≳10.15	Xcode (11.7 ‑ 15.3),  GCC (10.4 ‑ 13.2.1),  Clang (11.0.3 ‑ 17.0.6),  DMD ImportC (2.105.0 ‑ 2.108.0),  Intel C++ Compiler Classic (2021.9.0 ‑ 2021.10.0)
Windows ≳10, 11	Microsoft Visual C/C++ (17.6 ‑ 17.9.5),  Clang‑CL (16.0.6 ‑ 18.1.3),  GCC‑MinGW (12.2.1 ‑ 14.0.1),  LLVM‑MinGW (15.0 ‑ 18.1.3),  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 ‑ 17.0.6),  DMD ImportC (2.105.0 ‑ 2.108.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)
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.2),  Oracle Studio C/C++ (≳12.6)
illumos	GCC (7.5 ‑ 13.2),  Clang (15.0.7 ‑ 17.0.6)
SerenityOS	GCC (13.1)
WebAssembly/JS	Emscripten (3.1.45 ‑ 3.1.56),  Node.js (20.5 ‑ 21.7.2)

• 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

• A C++20 header-only wrapper is available which allows for easy integration with C++ projects, including optional support for popular formatting libraries:

  {fmt}

  std::format

  Boost.Format

  std::iostream

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
Shared 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

• See the CI configuration file for practical examples.

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:

• Public Functions
• Public Types
• Configuration
• Test suite

GNU Global

• A GNU Global-generated tagged and cross-referenced hypertext source code listing is available.
• This tagged listing is a valuable aid for new developers seeking an understanding of the libsir source code.

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
PurifyPlus™	Run-time analysis tools for application reliability and performance
ShellCheck	A static analysis tool for Unix shell scripts
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