libsir—a lightweight, cross-platform library for information distribution
Overview
- Synopsis
- Notables
- Cross-platform compatibility
- An example
- Building from source
- Dig in
- 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.
Notables
- No dependencies (other than
libcandpthreads). 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.4.7 ‑ 14.2.1), Clang (3.8 ‑ 19.1.3), Oracle Studio C/C++ (≳12.6), Circle (1.0.0‑210 ‑ 1.0.0‑223), 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.11), Arm HPC C/C++ (22.1 ‑ 24.10), DMD ImportC (2.104.2 ‑ 2.110.0), AMD Optimizing C/C++ (4.0.0 ‑ 5.0.0), Intel oneAPI DPC++/C++ (2023.1 ‑ 2025.0.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.15, 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 ‑ 19.1.3), IBM XL C/C++ (16.1.0.3 ‑ 16.1.0.19), IBM Open XL C/C++ (17.1.1.1 ‑ 17.1.2.13) |
| IBM i (PASE) 7.5 | GCC (10.3.0 ‑ 10.5.0), IBM XL C/C++ (16.1.0.15 ‑ 16.1.0.19) |
| macOS ≳10.15 | Xcode (11.7 ‑ 16.2), GCC (10.4 ‑ 14.2.0), Clang (11.0.3 ‑ 19.1.3), 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.5), Clang‑CL (16.0.6 ‑ 19.1.3), GCC‑MinGW (12.2.1 ‑ 14.2.1), LLVM‑MinGW (15.0 ‑ 19.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 ‑ 19.1.3), 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 ‑ 18.1.8), 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 ‑ 18.1.7) |
| 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.72), Node.js (20.5.0 ‑ 23.2.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
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):
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 |
|
| Test suite (C++) | make tests++ |
|
| Example app | make example |
|
| Static library | make static |
|
| nShared library | make shared |
|
| Installation | make install |
|
- 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:
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
- 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 |
| 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 |
