README.md

Config C++

Manage your C++ application config.

Table of contents

• Goal
• Introduction
• Quick start
  • Installing config-cxx
  • Editing config overrides
  • Usage
• Articles
  • Configuration Files
  • Environment Variables
• Examples
• Compiler support

🎯 Goal

Goal of the Config C++ is to provide a library like node-config to the C++ community.

Introduction

Config C++ organizes hierarchical configurations for your app deployments.

It lets you define a set of default parameters, and extend them for different deployment environments (development, testing, staging, production, etc.).

Configurations are stored in configuration files within your application, and can be overridden and extended by environment variables.

Quick Start

The following examples are in JSON format (YAML and XML are also supported).

Install in your app directory, and edit the default config file:

1. Add config to git submodules (execute in project root):

$ mkdir externals && cd externals
$ git submodule add https://github.com/cieslarmichal/config-cxx.git
$ git submodule update --init --recursive

2. Link with library:

set(BUILD_CONFIG_CXX_TESTS OFF)

add_subdirectory(externals/config-cxx)

add_executable(main Main.cpp)

target_link_libraries(main config-cxx)

$ mkdir config
$ vi config/default.json

{
  "db": {
    "name": "users",
    "host": "localhost",
    "port": 3306,
    "user": "default",
    "password": "default"
  }
}

Edit config overrides for production deployment:

 $ vi config/production.json

{
  "db": {
    "host": "postgres",
    "user": "admin",
    "password": "secretpassword"
  }
}

Use configs in your code:

#include <iostream>
#include "config-cxx/Config.h"

config::Config config;

auto dbName = config.get<std::string>("db.name"); // "users"
auto dbHost = config.get<std::string>("db.host"); // "postgres"
auto dbPort = config.get<int>("db.port"); // 3306
auto dbUser = config.get<int>("db.user"); // "admin"
auto dbPassword = config.get<int>("db.password"); // "secretpassword"
auto authEnabled = config.get<bool>("auth.enabled"); // true

config.get() will throw an exception for undefined keys to help catch typos and missing values. Use config.has() to test if a configuration value is defined.

Before starting your app specify target CXX environment:

$ export CXX_ENV=production

Running in this configuration, the port and name elements of db will come from the default.json file, and the host, user and password elements will come from the production.json override file.

📖 Articles

• Configuration Files
• Environment Variables

Examples

Check out the example project in examples directory.

Compiler support

• MSVC➚ version 143 or newer.
• GCC➚ version 13 or newer.
• Clang➚ version 16 or newer.
• Apple Clang➚ version 16 or newer.

Dependencies

• GTest (set BUILD_CONFIG_CXX_TESTS=OFF CMake flag to disable this dependency)
• nlohmann/json

Contributing

Feel free to join Config C++ development! 🚀

Please check CONTRIBUTING guide.

Visit us on discord if you want to know more about contributing.

📝 Compilation guides

• Clang++
• Apple Clang++
• G++
• MSVC