Sanar Cfgd

Note

Repository Mirrors

• git.nuros.org (sanarde/cfgd): primary, self-hosted Forgejo instance, accounts restricted to the core team.
• GitHub (sanarde/cfgd): mirror for external contributors. Issues and Pull Requests opened here are welcome and are reviewed and processed by the core team.

About

Configuration service for SanarDE that keeps typed, schema-described settings in a text file and serves them from a binary database.

Dependencies

• C17 compiler
• Meson (>= 1.0) and Ninja
• libdbus-1

Optional:

• systemd, for the user unit
• dbus-run-session, to run the integration tests

Build

meson setup build
meson compile -C build
meson test -C build
meson install -C build

The systemd user unit is installed only when its directory is given, for example -Dsystemd_user_unit_dir=/usr/lib/systemd/user.

Files

• Schemas: *.schema in $XDG_DATA_DIRS/cfgd/schemas and $XDG_DATA_HOME/cfgd/schemas. A schema in a later directory replaces one with the same id; $XDG_DATA_HOME wins.
• User settings: $XDG_CONFIG_HOME/cfgd/cfgd.conf (default ~/.config/cfgd/cfgd.conf).
• Overrides, read only: $XDG_CONFIG_HOME/cfgd/conf.d/*.conf, applied in alphabetical order below cfgd.conf.
• Database: $XDG_RUNTIME_DIR/cfgd/cache.db, rebuilt by the daemon, and $XDG_RUNTIME_DIR/cfgd/generation.

Keys and sections that no schema defines are ignored with a warning, so a typo does not go unnoticed. Warnings are printed once until the problem changes.

The effective value of a key is the first of: cfgd.conf, the last conf.d file that sets it, the default of the schema. A value that has the wrong type or is not allowed by the schema is ignored with a warning and the next one applies.

Schemas

A schema file describes the keys of one application:

[schema]
id = org.nuros.sanar.filer
path = /org/nuros/sanar/filer/

[show-hidden]
type = b
default = false
summary = Show hidden files

[sort-key]
type = s
default = name
choices = name; size; modified

[window-width]
type = i
default = 1120
min = 480
max = 16384

The key show-hidden above has the full path /org/nuros/sanar/filer/show-hidden. Key names use a-z, 0-9 and -. The types are b (boolean), i (64-bit integer), d (double), s (string) and as (list of strings). choices applies to s, min and max to i and d.

Settings file

# comment
[/org/nuros/sanar/filer]
show-hidden = true
sort-key = size
recent = /home/a;/home/b

A section is the path of a schema without the trailing slash. Booleans are true or false. A list is separated by ;. In strings and list items \\, \n, \t, \r and \s (a space at the edge of a value) are escapes, and \; is a semicolon inside a list item. The daemon changes only the lines it needs to, so comments and formatting stay as they are. When cfgd.conf is a symbolic link, the file it points to is changed and its permissions are kept.

Command line

cfgd get KEY
cfgd set KEY VALUE
cfgd reset KEY
cfgd list [PREFIX]
cfgd watch [PREFIX]
cfgd compile [-c config-dir] [-r runtime-dir] [-s schema-dir]...

get and list read the database directly. set and reset go through the daemon. watch prints KEY=VALUE for every change. compile builds the database without the daemon, from the default directories or from the ones given; it refuses to run while the daemon is running. Values are written in the notation of the settings file.

Library

Link with pkg-config --cflags --libs libcfgd. Schemas of an application are installed to pkg-config --variable=schemadir libcfgd.

#include <cfgd/cfgd.h>

cfgd_t *cfgd = cfgd_open();
bool hidden;

if (cfgd_get_bool(cfgd, "/org/nuros/sanar/filer/show-hidden", &hidden))
    ...

cfgd_set_bool(cfgd, "/org/nuros/sanar/filer/show-hidden", true);

Reads come from the memory-mapped database and do not call the daemon. A subscription made with cfgd_subscribe is served by cfgd_dispatch, which is called when the descriptor from cfgd_notify_fd becomes readable. The functions are described in lib/include/cfgd/cfgd.h.

D-Bus interface

Session bus, name org.nuros.sanar.cfgd, object /org/nuros/sanar/cfgd, interface org.nuros.sanar.Cfgd.

• Set(s key, s value): the value is in the notation of the settings file.
• Reset(s key)
• Signal Changed(as keys).

Errors: org.nuros.sanar.Cfgd.Error.InvalidKey, InvalidValue and Failed.

Any client of the session bus can call these methods, so an application that is allowed to talk to the session bus can change all settings.

Running

The daemon cfgdd starts on demand through the installed D-Bus service file. With the systemd unit it is started by systemd instead. Without either, run cfgdd in the session. Only one daemon can use a runtime directory at a time. The daemon exits when the session bus connection is lost, and SIGHUP makes it read all files again.

Links

• CONTRIBUTING

License

GPL-3.0-only. See LICENSE.