Repository files navigation

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

• 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

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 forstdio 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.

• No dependencies (other thanlibc andpthreads). 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. Thefunction, 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.

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:

• libsir is known to work on most common (and many uncommon) architectures. It has been built and tested onIntel (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),МЦСТ Эльбрус (E2K), andm68k (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 itdoesn't work on your machine, it's probably a bug.

libsir currently supports the following system logging facilities:

• A C++20header-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

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

  Ch

  Python

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 theexample application, whose source code can be located in theexample 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.

There are several options available for building libsir from source:

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

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 theonline documentation.

• See theCI configuration file for practical examples.

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 GNUmake manually.

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:

The VS Code build tasks executemake under the hood—the non-debug tasks map directly to therecipes listed under Unix Makefile; the debug tasks utilize libsir's customenvironment variables to control the build process.

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

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

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

Suggested initial sections:

• Public Functions
• Public Types
• Configuration
• Test suite

• 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.

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

The followingSAST (static application/analysis security/software testing) and dynamic verification tools are used—onevery commit—as part of our comprehensivecontinuous integration testing process:

Additional tools used for libsir development and testing include: