Mon, 01 Feb 2021 00:00:00 GMT

0.9.4 Release

guid: a3f66c2f-ae6a-412b-bdbd-f8950adb2334

author: Mihael Pranjić

pubDate: Mon, 01 Feb 2021 22:54:30 +0100

shortDesc: Key Name Improvements, Debian and Fedora Packaging

We are proud to release Elektra 0.9.4.

What is Elektra?

Elektra serves as a universal and secure framework to access configuration settings in a global, hierarchical key database. For more information, visit https://libelektra.org.

You can also read the news on our website

Highlights

Important Breaking Changes to key names et al. see below

Debian and Fedora Packaging with CPack see below

Important Breaking Changes

The structure of key names has been changed. see below (Klemens Böswirth)
This change breaks mountpoint configurations. Please follow the upgrade procedure shown below.

The backend fallback procedure introduced in Elektra 0.8.15 has been removed and the structure of the warnings metadata array has been changed. see below (Klemens Böswirth)

We removed the ini plugin (superseded by the TOML plugin), the null plugin (superseded by the base64 plugin) and the tcl plugin (Markus Raab, Philipp Gackstatter)

Important Changes to Key Names

There have been significant changes to Elektra's key names:

The most important change is that you now need a : after the namespace. So instead of system/elektra/version you have to use system:/elektra/version.

The second big change is to array elements. From now on keyNew ("/array/#10", KEY_END) will create a Key with name /array/#_10, to make arrays more user-friendly by preserving numerical ordering.

The whole implementation for keySetName, keyAddName, etc. has been completely rewritten. If you rely on specific behavior of Elektra's key names and have already taken the two changes above into account, please refer to the newly created key name documentation and Python reference implementation.

Metakeys now use the namespace meta:/. The accessor functions keyGetMeta and keySetMeta automatically add this namespace to preserve compatibility. However, if you use the recently introduced keyMeta or otherwise directly access the key name of a metakey, you will have to update your code.

default:/ is a new namespace used for keys that exist purely to represent a default value (e.g. generated by the spec plugin).

Looking up cascading keys with ksLookup now looks at namespaces in the following order:

proc:/

dir:/

user:/

system:/

default:/

/ (cascading key itself)

The final lookup of the cascading key itself, will be removed in a future release. Please update your code to generate default:/ keys, if you rely on this feature.

Note: The spec plugin already generates default:/ keys.

The function keyInactive has been removed. The concept of inactive keys no longer exists, use comment/# instead.

ElektraNamespace is the new C++ enum class for the Elektra's namespaces. You should prefer it to using KEY_NS_SYSTEM et al. directly, if you use C++.

keyGetFullName et al. have been removed. The concept of a "full name (with owner)" no longer exists.

A huge thanks to (Klemens Böswirth) for doing these important changes and clean-ups.

Mountpoint upgrade

The change to key names breaks existing mountpoint configurations.

It is not hard to fix the mountpoint configs even after the updating to the new version.

There are two places that will still contain the old syntax after the update:

1. Every key below (and including) system:/elektra/mountpoints/<MOUNTPOINT> uses an old key names as <MOUNTPOINT>, if the mountpoint was created with kdb mount.

2. The value of all keys matching system:/elektra/mountpoints/*/mountpoint must be valid key names.

Fixing the first instance is optional. There the key name is just used to create a unique name for the mountpoint.

The second instance, however, must be fixed or Elektra will be unusable.

Disclaimer: We cannot guarantee that the commands below work for all cases. We also make no guarantees that the command will not break things.

Please report any problems.

You have been warned. Manually backup important data first.

For the migration you can use the following commands:

#! /usr/bin/env sh
kdb export system:/elektra/mountpoints ni > mountpoints.ini
sed -E 's~((^\[?|/mountpoint = )(user|system))((\\\\)?/)~\1:\4~g' mountpoints.ini > mountpoints_corrected.ini
kdb mv -r system:/elektra/mountpoints system:/elektra/mountpoints-backup
kdb import system:/elektra/mountpoints ni < mountpoints_corrected.ini

Note: The original system:/elektra/mountpoints data will be moved to system:/elektra/mountpoints-backup

Debian and Fedora Packaging with CPack

We are now using CPack to generate modular Debian, Ubuntu (DEB) and Fedora (RPM) packages. This simplifies the packaging process and solves problems where a PR, which introduces changes to installed files, fails. We can now also set distribution specific dependencies with CPack, which is needed for some packages. (Robert Sowula)

We now provide DEB and RPM packages for releases and for every commit on master in our own repositories using CPack for:

DEB packages for Debian Buster

DEB packages for Ubuntu Bionic

DEB packages for Ubuntu Focal

RPM packages for Fedora 33

A big thanks to (Robert Sowula) for introducing CPack and creating the repositories.

Short Installation Guide

DEB packages

1. First, you need to obtain the repository key:

sudo apt-key adv --keyserver keys.gnupg.net --recv-keys F26BBE02F3C315A19BF1F791A9A25CC1CC83E839

2. Add deb https://debs.libelektra.org/<DISTRIBUTION> <DISTRIBUTION> main into /etc/apt/sources.list where <DISTRIBUTION> is the codename of your distributions e.g. focal, bionic or buster.

apt-get install libelektra5-all

RPM packages

Download our .repo configuration file and add it to yum/dnf.

To get all packaged plugins, bindings and tools install:

dnf install libelektra5-all

For more available packages, further instructions on how to add our repositories or instructions on how to use our master built packages, please refer to our install documentation.

Version Bump

The 0.9.* series of Elektra is for development of Elektra 1.0. Elektra 1.0 will be incompatible to 0.8 and as such, we need a SO version bump. We used this release to bump the SO version from 4 to 5 due to the breaking changes that are not visible in the API.

Note: that within 0.9.* we likely introduce further breaking changes but we will not bump the SO version again.

The package names which consist of the SO Version also changed from libelektra4* to libelektra5*. If you used our previous repository with master built packages, please make sure to migrate to our new package repositories described above or in our install documentation.

The version of the Java bindings was also bumped from 4 to 5, although the API is also work in progress.

A big thanks to (Robert Sowula) for doing the necessary renamings.

Plugins

The following section lists news about the plugins we updated in this release.

jni

Fix rare memleak when the jni plugin is closed. (Mihael Pranjić)

mINI

We changed the provides clause in the plugin contract. Now mINI offers support for the properties format (storage/properties) instead of the INI file format (storage/ini). This makes sense, since the plugin never supported the section syntax of INI files. (René Schwaiger)

Quickdump

Support for the old quickdump v1 and v2 formats has been removed. (Klemens Böswirth)

Simple INI

The plugin contract now correctly states that the plugin offers support for the properties format. Before it would state that the plugin offered support for the INI file format. This is not true, since the plugin does not support the section syntax of the INI file format.

YAML CPP

We fixed an use after free bug in the plugin. (René Schwaiger)

Yan LR

The plugin now works (with and) requires ANTLR 4.9. (René Schwaiger)

Libraries

The text below summarizes updates to the C (and C++)-based libraries of Elektra.

Compatibility

We removed the fallback procedure introduced in Elektra 0.8.15 (using KDB_DB_FILE (default.ecf) for system:/elektra, if the bootstrap backend KDB_DB_INIT (elektra.ecf) isn't found). If you still rely on this feature, either use kdb upgrade-bootstrap before upgrading, or manually extract system:/elektra into elektra.ecf.

There was an update to how warnings are generated. For users this means that the warnings metadata now forms a proper array. Specifically, the first 100 warnings are stored below to the meta keys warnings/#0, warnings/#1, ..., warnings/#9, warnings/#_10, ..., warnings/#_99. After that, warnings will wrap around, so the 101st warning will be stored as warnings/#0, 102nd as warnings/#1 etc.

Core

kdbSet now properly handles, if the given parentKey is NULL or has read-only name, value or metadata. (Klemens Böswirth)

Proposal

Removed elektraKeyGetMetaKeySet and moved keySetStringF to the hosts plugin. (Philipp Gackstatter)

Removed ksPopAtCursor. (Philipp Gackstatter)

Bindings

Bindings allow you to utilize Elektra using various programming languages. This section keeps you up-to-date with the multi-language support provided by Elektra.

Lua

Remove ipairs support and add our own iterator to add support for Lua 5.4, since __ipairs was deprecated. (Manuel Mausz)

JNA

Fixed allocation not correctly conveyed on key set initialization (Michael Tucek)

C++

ElektraNamespace is the new C++ enum class for the Elektra's namespaces. You should prefer it to using KEY_NS_SYSTEM et al. directly, if you use C++. The array ELEKTRA_NAMESPACES can be used to iterate over all namespaces. (Klemens Böswirth)

Ruby

Enable __declspec attributes for Ruby 3.0. (Mihael Pranjić)

Tools

The kdb cmd-line tool outputs better error messages on wrong names like user or user: as user:/ is now required. (Markus Raab)

The QtGUI was updated to be compatible with the new key name structure. (Klemens Böswirth)

Scripts

We fixed the (possibly) infinitely running function generate-random-string in check-env-dep. (René Schwaiger)

Documentation

Finalize 1.0 decisions. (Markus Raab)

Update API design document (Markus Raab and Stefan Hanreich)

Update release instructions (Robert Sowula)

Changed API documentation terms [current, latest] to [latest, master]. The API documentation of the latest release is now available at https://doc.libelektra.org/api/latest/html/ and of the current Git master at https://doc.libelektra.org/api/master/html/. (Robert Sowula)

Tests

Tests that use additional executables can now be installed and run via kdb <testname>. Existing tests have been update to support this. (Klemens Böswirth)

Update source formatting check to clang-format 11. (Mihael Pranjić)

Build

CMake

Use Lua 5.4 when available. (Mihael Pranjić)

Force RTLD_NODELETE on dlopen() when the ENABLE_ASAN CMake option is used. This enables ASAN to find symbols which otherwise might be unloaded. (Mihael Pranjić)

Docker

We added a Docker image for building the documentation on Debian Sid. (René Schwaiger)

We removed the Docker image for building the documentation on Debian Stretch. (René Schwaiger)

Add Fedora 33 Dockerfile for Cirrus and Jenkins CI. (Mihael Pranjić)

Debian Sid: update to clang 11. (Mihael Pranjić)

Infrastructure

Cirrus

Upgrade Cirrus Fedora docker image to Fedora 33. (Mihael Pranjić)

Upgrade to Ruby 3.0 for macOS builds. (Mihael Pranjić)

GitHub Actions

We added a build job that translates Elektra with GCC on macOS. (Mihael Pranjić, René Schwaiger)

Jenkins

We refactored shared code between pipelines into a Jenkins Shared Library. (Robert Sowula)

We now use Debian Sid to build the documentation instead of Debian Stretch. The Doxygen version in Debian stretch contains a bug that causes the generation of the PDF documentation to fail. (René Schwaiger)

Use Fedora 33 and 32, drop Fedora 31 use in Jenkins. (Mihael Pranjić)

The Main and Release Pipeline now creates packages for Debian Buster, Ubuntu Bionic, Ubuntu Focal and Fedora-33. These packages are also installed and automatically tested before they are published. To install these packages, please refer to our Install documentation. (Robert Sowula)

We updated our Release Pipeline to push changes directly to our Git repositories. (Robert Sowula)

Travis

Move macOS GCC 10 build job to GitHub Actions. (Mihael Pranjić)

Website

The website is generated from the repository, so all information about plugins, bindings and tools are always up-to-date.

Outlook

We are currently working on following topics:

Elektrify KDE (Dardan Haxhimustafa), (Felix Resch) and (Mihael Pranjić)

1.0 API (Stefan Hanreich) and (Klemens Böswirth)

Improve Java Development Experience (Michael Tucek)

Elektrify GNOME (Mihael Pranjić)

Continious Releases (Robert Sowula)

KDB access using FUSE (Alexander Firbas)

Default TOML plugin (Jakob Fischer)

Improve Plugin Framework (Vid Leskovar)

Improve 3-way merge (Dominic Jäger)

Shell completion (Ulrike Schäfer)

Ansible bindings (Thomas Waser)

Statistics

We closed 21 issues for this release.

About 13 authors changed 1280 files with 26471 insertions(+) and 29959 deletions(-) in 428 commits.

Thanks to all authors for making this release possible!

Join the Initiative!

We welcome new contributors! Read here about how to get started.

As first step, you could give us feedback about these release notes. Contact us via our issue tracker.

Get the Release!

You can download the release from here or GitHub

The hashsums are:

name: elektra-0.9.4.tar.gz

size: 7562103

md5sum: 670a3e9ab225ef53cb2db9058225d7d9

sha1: 2a5729462fc61694f2b81ca7dbd3620f09cbbf72

sha256: e1f11f063ab262ce056238ca17aa60442a450a0bb6c5f57a9959df0365576bc6

The release tarball is also available signed using GnuPG from here or on GitHub

The following GPG Key was used to sign this release: 12CC44541E1B8AD9B66AFAD55262E7353324914A

Already built API documentation can be found here or on GitHub.

Stay tuned!

Subscribe to the RSS feed to always get the release notifications.

If you also want to participate, or for any questions and comments please contact us via our issue tracker on GitHub.