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.

Best regards, Elektra Initiative