Mon, 04 Oct 2021 00:00:00 GMT

0.9.8 Release

guid: 0CB8C139-730C-4CCD-9FB4-0C7C4AA4DBF2

author: Mihael Pranjić

pubDate: Mon, 04 Oct 2021 00:02:45 +0200

shortDesc: Redshift Elektrified, HL API & Java Binding Improvements

We are proud to release Elektra 0.9.8.

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.

You can try out the latest Elektra release using our docker image elektra/elektra. This is the quickest way to get started with Elektra without compiling and other obstacles, simply run:

docker pull elektra/elektra
docker run -it elektra/elektra

Highlights

kdb now prohibits write operations on cascading keys that miss a corresponding existing key. See the details in the Tools section below and the new subsection on cascading writes in the tutorial on cascading keys for further information. (Alexander Firbas)

Redshift is now elektrified. (Tobias Schubert @qwepoizt)

Redshift and Elektra

We have created a version of Redshift that uses Elektra for configuration management!

We removed and refactored Redshift's code for loading configuration files, parsing CLI options and validating configuration to use Elektra. Redshift with Elektra has about 700 fewer lines of code (-16%) and is a great example of what Elektra is all about: More applications with less code for configuration management!

To test it, take a look at our PR Refactor to use Elektra and follow the instructions provided in CONTRIBUTING.md.

Benefits of Redshift using Elektra

Refactoring Redshift to use Elektra brings the following benefits:

Fewer lines of code: reduction of ~700 LOC or 16% (measured across all *.c and *.h files exclusive of files automatically generated by Elektra).

Adding new configuration settings is easier and takes less time: Validation and parsing of setting values (from configuration file and CLI options) is handled by Elektra - no custom code required!

Clean separation of application code and the specification of supported configuration settings (including defaults and validation rules).

Automatic generation of CLI help text.

HL API improvements

Redshift with Elektra uses the high-level API.

We have made a large number of improvements to the high-level API in the course of refactoring Redshift. The highlights are:

Improved detection of differences in specification between an application's compilation and runtime.

Improved validation of CLI options.

Early detection of errors in specification files.

Updated and improved documentation and tutorials.

Various other bugfixes.

More improvements and details are explained in later sections of these release notes.

Thanks to Klemens Böswirth, Markus Raab and Tobias Schubert!

Windows releases

We are now shipping experimental releases for Windows 32- and 64-bit! They can be downloaded here.

A big success is that Redshift already works with Elektra under Windows.

Plugins

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

gopts

The gopts plugin now includes deeply nested options and arguments in the generated help message. (Tobias Schubert @qwepoizt)

Errors from gopts are now correctly reported. (Klemens Böswirth)

Fix wrong variable names in gopts_win32.h. (Tobias Schubert @qwepoizt)

range

The range plugin now uses metakey type as fallback, if check/type is not specified. (Tobias Schubert @qwepoizt)

The range now treats all validation problems as warnings during kdbGet(). (Tobias Schubert @qwepoizt)

spec

The spec plugin now runs before other postgetstorage plugins, so that validation can happen during kdbGet as well. This is especially relevant in combination with gopts. (Klemens Böswirth)

Make spec plugin (with no support for # and _ in key names) work in mingw-w64 builds. (Tobias Schubert @qwepoizt)

sync

Add support for mingw-w64 builds using fflush. (Tobias Schubert @qwepoizt)

wresolver

Add missing ELEKTRA_PLUGIN_COMMIT export. (Tobias Schubert @qwepoizt)

TOML

Improvements to the parser, comment handling and especially quoting of strings. (Klemens Böswirth)

The toml plugin now supports all four kinds of strings via the tomltype metadata. The plugin also remembers which kind was used and handles escape sequences properly, instead of always converting to basic strings. For details take a look at the updated README (Klemens Böswirth)

The comment/#/space metakey is now used correctly to store the actual whitespace characters from the file, instead of a number. (Klemens Böswirth)

Libraries

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

Compatibility

Introduced public C API function ksSearch

Previously public function ksSearchInternal is now static. Use ksSearch instead.

(Michael Tucek)

Core

Remove obsolete ksNeedSync function. (Mihael Pranjić)

Replace various occurences of sprintf by snprintf and fix out of bounds array access in markdownlinkconverter. (Mihael Pranjić)

High-level API

Modified High-level API to treat all warnings as errors. (Tobias Schubert @qwepoizt)

Implemented support for warnings in High-level API error handling. (Tobias Schubert @qwepoizt)

Fix a small bug for warnings in High-level API. (Tobias Schubert @qwepoizt)

Fix resource management in High-level API error handling. (Tobias Schubert @qwepoizt)

Implement a check to detect whether an application's specification was properly mounted and spec-mounted. (Tobias Schubert @qwepoizt)

Implement a check to detect whether an application's specification was changed after installation. (Tobias Schubert @qwepoizt)

Add sanity-checks to resource management. (Tobias Schubert @qwepoizt)

Refactor and modularize code. (Tobias Schubert @qwepoizt)

Update and improve inline documentation. (Tobias Schubert @qwepoizt)

Remove "minimal validation" in favor of the new checks (see above). (Tobias Schubert @qwepoizt)

Ease

Implement calculation of a specification token (=sha-256 hash). (Tobias Schubert @qwepoizt)

Add asmonier's sha-2 for sha-256 hash calculation. (Tobias Schubert @qwepoizt)

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.

Java binding

Upgraded Java binding gradle wrapper to 7.2.

Java source files are formatted using the Google Java format

Renamed zero argument static factory method Key::createNameless to Key::create. To migrate to this change, just update calling code to use the new method name.

Updated method documentation previously publishing the error key based error handling approach to the Java binding consumer. Such arguments are now explicitly only used for returning warning information in case no error occurred. In case of an exceptional state, appropriate exceptions are thrown. Such exceptions provide access to the underlying key containing warning and error information as metadata. Please review API usage to consider the more elaborated explanation of how Elektra uses this argument's value. Affected signatures:

Updated javadoc for KDB::open(Key)

Updated javadoc for KDB::open(KeySet, Key)

Updated javadoc for KDB::close(Key)

Updated javadoc for KDB::get(Key)

Updated javadoc for KDB::get(KeySet, Key)

Updated javadoc for KDB::set(KeySet, Key), better explaining the relevance of the second argument parentKey

Introduced KeySet::remove(Key) and KeySet::remove(String)

Removed KeySet::lookup(Key, int) and KeySet::lookup(String, int) as well as accompanying flag definitions KeySet::KDB_O_NONE, KeySet::KDB_O_DEL and KeySet::KDB_O_POP. Please use KeySet::lookup(Key) and KeySet::lookup(String) instead. Instead of KeySet::KDB_O_DEL, please consider using Key::release. The proper replacement for KeySet::KDB_O_POP is KeySet::remove(Key) or KeySet::remove(String).

Native library proxy interface Elektra is now package private (previously was public).

Added example Java plugin whitelist (see here)

Changed Key nextMeta() to Optional<Key> nextMeta () no longer throwing NoSuchElementException for non-exceptional behavior

Native library proxy interface Elektra is now package private (previously was public)

Added example Java plugin whitelist

Added support of binary valued keys:

Introduced Key::getBinary() and Key::setBinary(byte[])

Renamed KeyBinaryTypeNotSupportedException to KeyStringValueException

Introduced KeyBinaryValueException

Improved Key test coverage

Fixed example project in examples/external/java/read-keys-example

now works with a standard installation of Elektra

updated code to work with current Java binding

KeySetReleasedException and KeyReleasedException have been replaced by the native IllegalStateException

Introduced abstraction ReadableKey to better reflect the limitations of metadata keys via a type hierarchy. Metadata keys are now returned as ReadableKeys:

Key extends ReadableKey

Key class is now final

Changed Key Key::nextMeta() to Optional<ReadableKey> Key::nextMeta(), no longer throwing NoSuchElementException for non-exceptional behavior

Changed Key Key::currentMeta() to ReadableKey Key::currentMeta()

Changed Optional<Key> Key::getMeta(String) to Optional<ReadableKey> Key::getMeta(String)

Metadata keys can no longer be manually released

Removed Key::incRef, Key::decRef and Key::getRef

ReadableKey/Key now implements Comparable<ReadableKey>

int Key::cmp(Key) has been renamed to int Key::compareTo(Key)

ReadableKey now implements equals and hashCode in line with the contract for int Key::compareTo(Key)

ReadableKey/Key no longer implements Iterable<String> for iterating over the parts of a key's name - use Iterator<String> ReadableKey::keyNameIterator () instead

Key now implements Iterable<Key> to iterate over a key's metadata ReadableKeys

Fixed API method typo: Renamed ReadableKey::isDirectBelow/Key::isDirectBelow to isDirectlyBelow

KeyNameIterator and KeySetIterator are now package private

KeySetAppendException has been renamed to KeySetException and now conveys general KeySet related exceptional states

KeySet now implements SortedSet<Key> (see Java API). Previously KeySet was only implementing Iterator<Key>. Now a native key set can be used via its KeySet representation wherever one of the following Java Collection Framework interfaces is supported:

Iterable

Collection

Set

SortedSet

(Michael Tucek)

GLib

Compile glib binding with -Wno-pedantic for compatibility. (Mihael Pranjić)

Tools

Really add all tools when using -DTOOLS=ALL. (Markus Raab)

ZeroMQ Hub: fix compilation and man page. (Markus Raab)

Configure packaging for FUSE tool. (Alexander Firbas)

FUSE: fix bug preventing binary writes. (Alexander Firbas)

Ambiguous write operations are now disabled in kdb. (Alexander Firbas)

webd: update npm dependencies. (Mihael Pranjić)

KDB

kdb set, kdb meta-set: Only allow writes to the cascading namespace if the lookup succeeds. Otherwise, the operation is ambiguous and therefore aborted. No more guessing of namespaces in case a cascading key is given (user:, system: for kdb set, spec: for kdb meta-set), (Alexander Firbas)

kdb set, kdb meta-set: Validation of keys can no longer be bypassed by using non-cascading keys (except with the new --force (-f) option). (Alexander Firbas)

Disable -N/--namespace option in all kdb subcommands (Alexander Firbas)

Implement new name part getter commands kdb namespace, kdb basename and kdb dirname. (Alexander Firbas)

kdb file: Remove namespace guessing (in case a cascading key is given, it needs to resolve to an existing key). (Alexander Firbas)

kdb editor/import: Disable the use of cascading names (and the 'validate' strategy operating on cascading keys) entirely. (Alexander Firbas)

Update numerous tests to comply with changes above. (Alexander Firbas)

Add a new subsection on cascading writes to the tutorial on cascading keys. (Alexander Firbas)

kdb gen: Generate specification token during code-generation and add it to generated contract. (Tobias Schubert @qwepoizt)

kdb gen: Improve naming of variables to make code easier to understand. (Tobias Schubert @qwepoizt)

kdb spec-mount: Improve usability by failing with helpful error messages, if the specification contains errors. (Tobias Schubert @qwepoizt)

Scripts

Add script for mingw-w64 i686 build. (Tobias Schubert @qwepoizt)

Documentation

Add link and small improvements to tutorial about writing specifications and logger. (Markus Raab)

doc: add pre/postconditions and invariants to module key (@lawli3t)

doc: add pre/postconditions and invariants to module keymeta (@lawli3t)

Fix broken links (@lawli3t)

Remove previous authors. (Markus Raab)

add pre/postconditions and invariants to module keytest (@lawli3t)

Updated the news template. (Mihael Pranjić)

Update and improve tutorial and in-code comments for high-level API (Tobias Schubert @qwepoizt)

Improve documentation of opts library (Tobias Schubert @qwepoizt)

Update tutorial "High-level API (with code-generation)" to reflect change of loadConfiguration()'s signature in release 0.9.5 (Tobias Schubert @qwepoizt)

add pre/postconditions and invariants to module keyvalue (@lawli3t)

Update and improve inline documentation of kdb gen. (Tobias Schubert @qwepoizt)

Fix broken links. (Robert Sowula)

Tests

Fix failing testshell_markdown_tutorial_crypto on Mac OS and other OS with GnuPG version >= 2.3.1. (Peter Nirschl @petermax2)

Use clang-format 12 for Restyled and update Restyled version. (Mihael Pranjić)

Update all Restyled formatters to current versions. (Mihael Pranjić)

Add additional test cases for module keytest (@lawli3t)

Update tests for high-level API to work with new specification token mechanism. (Tobias Schubert @qwepoizt)

Add tests for libease's sha-256. (Tobias Schubert @qwepoizt)

Add tests for sha-256 hash calculation of a KeySet. (Tobias Schubert @qwepoizt)

Add additional test cases for module keymeta (@lawli3t)

Packaging

Add packages for openSuse Leap 15.3. (Robert Sowula)

Build

CMake

Add files generated by CMake to .gitignore. (Tobias Schubert @qwepoizt)

Add support for i686 to mingw-w64 toolchains. (Tobias Schubert @qwepoizt)

Add plugins type, cache, spec, gopts, sync to mingw-w64 builds. (Tobias Schubert @qwepoizt)

Docker

Add docker images for ABI tests. (Robert Sowula)

Enable BuildKit features to leverage tmpfs to speed up docker build commands. (Mihael Pranjić)

Bump Gradle to version 7.2. (Mihael Pranjić)

Bump Debian Buster images to Bullseye and Stretch images to Buster. We still leave one Debian Stretch job due to upstream Debian LTS support until June 2022. (Mihael Pranjić)

Add Dockerfiles for openSUSE Leap 15.3 and CentOS Stream 8. (Robert Sowula)

Add docker image for OpenWrt package building. (Robert Sowula)

Add files generated by docker when tutorial run-all-tests-with-docker is followed to .gitignore. (Tobias Schubert @qwepoizt)

Restyled

Upgrade to latest stable restylers. (Mihael Pranjić)

Added Google Java formatter (Michael Tucek)

Infrastructure

Jenkins

Add ABI test stage for release pipeline. (Robert Sowula)

Move check stages that don't build the code to a dedicated stage, to avoid confusion when parallel builds are aborted. (Robert Sowula)

Add test stages for openSUSE and CentOS. (Robert Sowula)

Use tmpfs in Docker to speed up the test suite. (Mihael Pranjić)

Add OpenWrt package building stage to release pipeline. (Robert Sowula)

Add debian-bullseye-mingw-w64-i686 build to Jenkinsfile. (Tobias Schubert @qwepoizt)

Cirrus

Bump FreeBSD images to 12.2 and 13.0 using the LLVM 12 toolchain, drop FreeBSD 11. (Mihael Pranjić)

Fix cirrus-file parsing errors. (Mihael Pranjić)

Redistribute CPU and memory resources and enable greedy instances. (Mihael Pranjić)

GitHub Actions

Migrate most macOS build jobs to GitHub actions to speed up builds. (Mihael Pranjić)

Upgrade macOS GCC build job to GCC 11. (Mihael Pranjić)

Website

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

Update npm dependencies. (Mihael Pranjić)

Outlook

We are currently working on following topics:

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

KDB access using FUSE (Alexander Firbas)

Improve Java Development Experience (Michael Tucek)

Improve Plugin Framework (Klemens Böswirth)

Default TOML plugin (Klemens Böswirth), (Markus Raab) and (Jakob Fischer)

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

Elektrify GNOME (Mihael Pranjić)

Continious Releases (Robert Sowula)

Improve 3-way merge (Dominic Jäger)

Shell completion (Ulrike Schäfer)

Ansible module (Thomas Waser)

Statistics

We closed 59 issues for this release.

About 17 authors changed 396 files with 13155 insertions(+) and 8331 deletions(-) in 597 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.8.tar.gz

size: 7753097

md5sum: d978c17aae94d79f9d1f26b547bc46fe

sha1: 9725bfd6fca832ed472290e9de3711e01e9bfe54

sha256: b1e8908c138b84e788fdff25eab1c2b07e0b422a5fd1667814539ea02f151c58

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.

Permalink to this NEWS entry

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