Skip to content

The configuration system for ALICE O2.

License

Notifications You must be signed in to change notification settings

AliceO2Group/Configuration

Repository files navigation

Travis Status JIRA

Configuration module

The Configuration module provides a way to access Configuration data from various backends in a uniform way. Users get an interface to backends by providing a URI to the ConfigurationFactory class, which returns an implementation of ConfigurationInterface. Values can be retrieved from the interface one-by-one using simple getters, or multiple at a time using getRecursive(). The getRecursive() function returns a tree-like data structure, which models the hierarchy of directories or paths.

Installation

To install without aliBuild follow these instructions.

aliBuild installation

Follow this tutorial to install aliBuild.

Install Configuration module:

aliBuild build Configuration --defaults o2
alienv load Configuration/latest
Development

If you want to make changes to the source code initialise the development package first:

aliBuild init Configuration@master

and then use make to recompile

cd sw/BUILD/Configuration-latest/Configuration
make -j install

Instance and backends

The configuration instance can be requested form the factory based on provided URI:

#include <Configuration/ConfigurationFactory.h>
using namespace o2::configuration;

std::unique_ptr<ConfigurationInterface> = ConfigurationFactory::getConfiguration("backend://[host][:port][/path]");

The URI is constructed based on the table below:

Backend name URI backned Host Port Path Dependency
INI file ini:// - - Relative or absolute file path -
JSON file json:// - - Relative or absolute file path -
Consul consul:// Server's hostname Server's port - ppconsul
Consul JSON consul-json:// Consul host Consul port Path to a value with JSON data ppconsul
Consul INI consul-ini:// Consul host Consul port Path to a value with INI data ppconsul
String str:// - - List of ; separated key-values; . is used to define levels (as in ptree) -
Apricot apricot:// Server's hostname Server's port - cURL

Getting values

Use . as path separator.

Getting a value

Simply use templated get method and provide path as parameter:

auto conf = ConfigurationFactory::getConfiguration("ini://temp/config.ini"); // absolute path
int value = conf->get<int>("my_dir.my_key");

Using prefix

If you need to get multiple values from a single node consider using setPrefix:

auto conf = ConfigurationFactory::getConfiguration("json://config.json"); // relative path
conf->setPrefix("my_dir");
int value = conf->get<int>("my_key");

Managing failures

When the value under requested path does not exist use one of the following ways to handle it.

  1. Catch an exception
auto conf = ConfigurationFactory::getConfiguration("ini://temp/config.ini");
try {
  conf->get<int>("my_dir.my_wrong_key");
} catch (std::runtime_error&) { ... }
  1. Provide default value as a second parameter to get method
auto conf = ConfigurationFactory::getConfiguration("ini://temp/config.ini");
int value = conf->get<int>("my_dir.my_wrong_key", 321);

Getting a subtree of values

When tree of values or flat key-value map is needed:

auto conf = ConfigurationFactory::getConfiguration("consul://localhost:8500");

// Get a tree
boost::property_tree::ptree subTree = conf->getRecursive("my_dir");
subTree.get<int>("my_key");

// Get flat key-value map
std::unordered_map<std::string, std::string> map = conf->getRecursiveMap("my_dir");
map["my_key"];

Putting values

Putting values in currently supported only by Consul backend.

auto conf = ConfigurationFactory::getConfiguration("consul://localhost:8500");
conf->put<int>("my_dir.my_key", 123);

Consul server setup

See detailed instructions.

Release

  1. Update the version number in the CMakeLists.txt
  2. Commit, push
  3. New Release in github
  4. Check in alidist that there is a PR to bump the version of configuration. It should be created by itself via a GH action.