ElektraInitiative/libelektra: 0.9.4 Release

• guid: a3f66c2f-ae6a-412b-bdbd-f8950adb2334
• author: Mihael Pranjic
• 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

<a id="hl-1"></a>

Important Breaking Changes

• The structure of key names has been changed. see below (Klemens Böswirth) <br/> 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)

<a id="br-1"></a>

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 behaviour 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.

<a id="mountpoint-upgrade"></a>

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

<a id="hl-2"></a>

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

1. 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

<a id="br-2"></a>

• 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-Docu 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.

Permalink to this NEWS entry

For more information, see https://libelektra.org

Best regards, Elektra Initiative