libconfig

libconfig is the unified configuration module for SERiF and related projects

This has been broken out of the main serif project to allow for more modularity

Building

In order to build libconfig you need meson>=1.5.0. This can be installed with pip

pip install "meson>=1.5.0"

Then from the root libconfig directory it is as simple as

meson setup build --buildtype=release
meson compile -C build
meson test -C build

this will auto generate a pkg-config file for you so that linking other libraries to libconfig is easy.

Usage

libconfig makes use of reflect-cpp to provide compile time reflection and serialization/deserialization of configuration structs. This allows for config options to be defined in code and strongly typed.

Basic Usage

#include "fourdst/config/config.h"
#include <string>
#include <print>
#include <optional>

struct MyPhysicsOptions {
    int gravity = 10;
    float friction = 0.5f;
    std::optional<float> dampening = 0.1f;
    bool enable_wind = false;
};

struct MyControlOptions {
    double time_step = 0.01;
    double max_time = 100.0;
};

struct MySimulationConfig {
    std::string name = "my_simulation";
    MyPhysicsOptions physics;
    MyControlOptions control;
};

int main() {
    fourdst::config::Config<MySimulationConfig> cfg;
    
    // You can save the default config to a file
    cfg.save("default_config.toml");
    
    // You can save the json schema for the config
    // This allows editors like VS Code to provide autocompletion
    fourdst::config::Config<MySimulationConfig>::save_schema("config.schema.json");
    
    // You can load a config from a file
    try {
        cfg.load("my_config.toml");
        // You can also pass an optional bool as a second argument to turn on verbose error 
        // reporting. This will display a tree of missing or invalid fields. Note that due to limitations
        // in C++'s ability to detect default iniailized values vs initializer list values 
        // missing fields which you set an initializer list for are still considered missing. 
        // **ONLY fields marked with std::optional are exempt from this rule.**
    } catch (const fourdst::config::exceptions::ConfigError& e) {
        std::println("Error loading config: {}", e.what());
    }
    
    // You can access the config values
    std::println("My Simulation Name: {}, My Simulation Gravity: {}", cfg->name, cfg->physics.gravity);
    
    // libconfig intentioanlly discourages direct modification of config values. However, if you need 
    // to modify values after loading them you can use the mutate function. This takes a lambda
    // which recives a mutable reference to the underlying config struct.
    
    cfg.mutate([](MySimulationConfig& config) {
        config->physics.enable_wind = true;
    });
    
    // Making these mutations will put the config into a "MODIFIED" state and will cache the unmodified values. 
    // You can reset the state and revert to the unmodified values with the reset function.
    
    cfg.reset();
    
    // The current state of the config can be checked with the get_state() function or the describe_state() function.
    // get_state returns an enum value while describe_state returns a human readable string.
    
    std::println("Config State: {}", cfg.describe_state());
    fourdst::config::ConfigState state = cfg.get_state();
    
    // Possible states are DEFAULT, LOADED_FROM_FILE, and MODIFIED
}

CLI Integration

libconfig integrates with CLI11 to automatically expose configuration fields as command-line arguments.

#include "CLI/CLI.hpp"
#include "fourdst/config/config.h"

int main(int argc, char** argv) {
    fourdst::config::Config<MySimulationConfig> cfg;
    CLI::App app("My Application");

    // Automatically registers:
    // --name
    // --physics.gravity
    // --physics.friction
    // --physics.enable_wind
    // ... and so on
    fourdst::config::register_as_cli(cfg, app);

    CLI11_PARSE(app, argc, argv);
    
    // cfg is now populated with values from CLI arguments
    return 0;
}

Example output TOML

[main]
name = "my_simulation"
[main.physics]
gravity = 10
friction = 0.5
enable_wind = false
[main.control]
time_step = 0.01
max_time = 100.0

Linking Other Code

At compile time libconfig generates a pkg-config file which makes linking other code to libconfig easy. Note that you will need to have run meson setup at least once to generate the pkg-config file before you can link to it.

Headers are installed to the meson install dir (e.g. /usr/local/include) under a fourdst/config subdirectory so you can include the main header with #include "fourdst/config/config.h". Including this header will include all of the necessary headers for using libconfig.

When linking to libconfig you can use pkg-config --cflags --libs fourdst-config to get the necessary compiler and linker flags. If you are using meson to build your project you can use dependency('fourdst-config') in your meson.build file to link to libconfig.

Libraries are installed to the meson install dir (e.g. /usr/local/lib) with the name libfourdst-config.so on linux and fourdst-config.a on macOS. The pkg-config file will take care of the correct library name for your platform.

Finally, vendor headers and libraries are placed in a dedicated vendor directory in the fourdst directory so as to not interfere with system packages. The pkg-config file will include the necessary include and library paths to use these vendor dependencies as well. For example, libconfig depends on toml++ for parsing TOML files. The toml++ headers are included in fourdst/vendor/tomlplusplus and the pkg-config file will include the necessary include path to use these headers when you link to libconfig.