parameter-framework

Introduction

The parameter-framework is a plugin-based and rule-based framework for handling parameters. This means that you can:

1. Describe your system's structure and its parameters (in XML) - aka. What;
2. Write (in C++) or reuse a backend (aka. plugin) for accessing the parameters that you just described - aka. How;
3. Define (in XML or in a domain-specific-language) conditions/rules upon which a given parameter must take a given value - aka. When.

Usage examples

Alsa controls on embedded platforms

The parameter-framework can be used to set the value of alsa controls (switches, volumes, etc.) on smartphones/tablets based on parameter-framework rules (in this example, they transcribe use-cases). For accessing parameters (i.e. alsa controls), you may use the alsa plugin.

Parameters in files

The filesystem plugin can be used to write parameters in files. This is particularly useful for files in /sys managing GPIOs.

More details

The parameter-framework's core comes in the form of a shared library. Its client has to provide:

• configuration files describing the structure of the system to be managed by the parameter-framework and what plugins it must use to read/write into each subsystem;
• a list of criteria (representing the state of the client) and their possible values;
• configuration files describing the value that each part of the system (aka parameter) must take - this is done by writing rules based on the criteria described above.

At runtime, the most usual communication between the client and the parameter-framework are:

1. The update of criteria (that are used in the rules introduced above) and
2. Update all relevant parameters according to the new criteria values. The parameter-framework uses the appropriate backend for writing the values in each underlying subsystem.

The parameter-framework comes with several tools, including a command-line interface: remote-process.

Going further

See the wiki on github.

Compiling

You may take a look at .travis.yml and appveyor.yml for examples on how we build the Parameter Framework in the CI. It will probably help if you have troubles building the Parameter Framework even after reading the following sections:

Dependencies

In order to compile you'll need, at the very least:

• CMake (v3.2.2 or later) (v3.3.0 or later on Windows);
• A C/C++ compiler supporting C++11;
• libxml2 headers and libraries (Provided by the libxml2-dev on debian-based distributions);

If you want to use the remote command interface (NETWORKING=ON by default), you'll also need:

• Standalone ASIO (1.10.6 or later) (Provided by libasio-dev on debian-based distributions) ASIO is C++ header-only ASynchronous-IO library.

If you want to compile the Python bindings (PYTHON_BINDINGS=ON by default), you'll also need:

• SWIG 2.0 (A binding generator);
• Python2.7 development environment (Provided by python2.7-dev on debian-based distributions)

If you want to compile and run the tests (BUILD_TESTING=ON by default), you'll also need:

• Catch (Provided by catch on debian-based distributions). Catch is a single-header test framework - as such you may also download it directly here;
• Python2.7 (Provided by python2.7 on debian-based distribution - it is preinstalled on most distributions).

If you want to build the code documentation (DOXYGEN=OFF by default), you'll need doxygen and graphviz. This doc is already available to you - see the wiki.

To list all available configuration options, try cmake -L (you may also filter-out lines starting with CMAKE_).

How-To

If you are already familiar with CMake, you know what to do.

Run cmake . then make. You may then install libraries, headers and binaries with make install. By default, they are installed under /usr/local on unix OSes; if you want to install them under a custom directory, you may do so by passing it to the cmake . command; e.g.

# Always use absolute paths in CMake "-D" options: you don't know where
# relative paths will be evaluated from.
cmake -DCMAKE_INSTALL_PREFIX=/path/to/custom/install .

If you want to provide your own dependencies (e.g. your own version of libxml2), you should pass the base paths as the CMAKE_PREFIX_PATH variable, e.g.:

cmake -DCMAKE_PREFIX_PATH='/path/to/dependency1/;/path/to/dependency2/'

For more information on how to use CMAKE_PREFIX_PATH, see CMake's documentation.

Also, CMake can build a project out-of-tree, which is the recommended method:

mkdir /path/to/build/directory
cd /path/to/build/directory
cmake /path/to/sources/of/parameter-framework
make

After a build you may want to run the parameter-framework tests with make test or ctest.

Compiling on Windows

The only supported compiler on Windows in Visual Studio 14 2015. The 2013 version does not support some C++11 features. When running CMake's configuration step (the first call to CMake) you must specify the build system you want to use, i.e. -G Visual Studio 14 2015 Win64. Again, you may refer to appveyor.yml.

If you don‘t already have libxml2 headers/libraries and don’t want to build them by yourself, we have a precompiled version for x86-64. These are provided for reference and as a convenience for development purpose only; when making a final product, you should recompile the latest libxml2 release yourself.

Compiled with Visual Studio 12 2013:

• in debug configuration
• in release configuration

We have mirrored ASIO 1.10.6 here.

Once you have downloaded and uncompressed these two dependencies, add the following two entries to CMAKE_PREFIX_PATH:

/path/to/libxml2-x86_64/
/path/to/asio-1.10.6/