0.9.1 Release

• guid: 8c64fe8a-87a5-4b72-b772-d98c8a4a5efd
• author: Mihael Pranjić
• pubDate: Tue, 26 Nov 2019 14:55:19 +0100
• shortDesc: KDE Integration, Rust&Go Bindings, Code Generation

We are proud to release Elektra 0.9.1.

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

• We are working on integrating Elektra into KDE. A new Elektra plugin called kconfig was added which can read KDE's kconfig ini files. Additionally we are working on a fork of KDE's KConfig configuration system and patching it to use libelektra. (Dardan Haxhimustafa) and (Felix Resch)
• The elektra and elektra-sys crates have been published to crates.io for easier usage of our Rust binding. (Philipp Gackstatter)
• We improved our Go bindings. (Raphael Gruber)
• Code Generation is ready for productive use. (Klemens Böswirth)

Code Generation

While the new kdb gen was already included in the last release, it is now fully functional and ready for productive use. To get started take a look at the new man-page for kdb-gen(1).

If you specifically want to use it with the High-Level API take a look at this tutorial.

We also created a new CMake function that will be available, if you include Elektra via CMake's find_package. The function is called elektra_kdb_gen and can be used to tell CMake about files that are generated via kdb gen. (Klemens Böswirth)

Further Highlights

• We migrated our build server and website to up-to-date hardware. (Markus Raab and Djordje Bulatovic)
• Elektra now has a technical preview of a new merge library. It is written in C99 and can currently be used with kdb cmerge. (Dominic Jäger)
• We make it easier for new developers to join Elektra, e.g., see new get started. (Hani Torabi)
• We made many cleanups, to get Elektra ready for 1.0!

Plugins

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

General

• We removed 12 obsolete or unfinished plugins:
  • boolean,
  • cachefilter,
  • cpptype,
  • dini,
  • enum,
  • regexstore,
  • required,
  • haskell,
  • simplespeclang,
  • regexdispatcher,
  • typechecker,
  • struct. (Markus Raab, René Schwaiger)
• We unified the name of the config check function of the plugins to nameOfPluginCheckConf. Before this update some plugins used the name nameOfPluginCheckConfig instead. (René Schwaiger)
• We improved the error messages in crypto, fcrypt, and gpgme plugins. (Peter Nirschl)
• We now correctly handle return codes (error codes) of execv in the GPG module. (Peter Nirschl)
• We improved the documentation of ksAppendKey regarding ownership of keys. (Raphael Gruber)
• We removed the experimental status of the following plugins:
  • gopts
  • specload. (Klemens Böswirth)
• We added the following experimental plugins:
  • kconfig. (Dardan Haxhimustafa)

Camel

We removed the experimental plugin. For a plugin that is able to parse similar syntax, please take a look at the

• YAJL , and
• YAML CPP

plugins. (René Schwaiger)

GOpts

• The error message, if non of the gopts variants can be compiled, was improved. (Klemens Böswirth)
• A better error, if the plugin fails to load argv from the system, was added. (Klemens Böswirth)
• A function to detect help mode, without invoking elektraGetOpts was added. It simply checks, whether --help is one of the string in argv. (Klemens Böswirth)
• Increase test timeout from 120s to 240s. (Mihael Pranjić)

KConfig

• We added a plugin which can be used to parse kconfig INI files. (Dardan Haxhimustafa)

Mmapstorage

• We now store the OPMPHM inside of the mmap format. (Mihael Pranjić)
• The storage format was changed and many sanity checks were improved or added. (Mihael Pranjić)
• Enforce consistency by writing the magic file footer last. (Mihael Pranjić)
• Filter empty meta KeySets to save space. (Mihael Pranjić)

Noresolver

• The plugin now correctly sets the path in the parentKey. It therefore now supports set calls. (Klemens Böswirth)

Path

• The Markdown Shell Recorder test of the plugin now also works, if you execute it as root user. (René Schwaiger)

Spec

• There is now the config key missing/log that allows logging of all missing required keys. (Klemens Böswirth)
• spec now internally handles errors differently. There should be no external impact apart from better performance. (Klemens Böswirth)

Specload

• We now treat relative paths as relative to KDB_DB_SPEC instead of the current working directory. (Klemens Böswirth)
• Changes to default or type metadata are no longer supported, since they are not safe in every case. (Klemens Böswirth)
• The plugin no longer has the experimental status. (Klemens Böswirth)

Tcl

• We made sure that building the plugin works, if you use the latest version of CMake (3.15.3) and Boost (1.71). (René Schwaiger)

Type

• We added an option to disable the restoring of boolean values. This useful for storage formats like YAML that have native boolean types. (Klemens Böswirth)

Yajl

• Yajl now correctly supports Elektras boolean types using the type plugin. For example, setting on, enable or true all map to JSONs native true value. See the type plugin for more details about boolean types. (Philipp Gackstatter)

YAwn

• We removed the plugin in favor of Yan LR. (René Schwaiger)

YAy PEG

• We removed the plugin in favor of Yan LR. (René Schwaiger)

Libraries

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

Compatibility

We introduced several incompatible changes:

• The library libelektra, which is a collection of different elektra libraries, is now removed. Users of CMake or pkg-config should not be affected. Otherwise change -lelektra to -lelektra-core -lelektra-kdb or whatever parts of Elektra your application uses. (Markus Raab)
• The conversion functions elektraKeyTo* and elektra*ToString are now part of the elektra-ease library instead of the elektra-highlevel library. This should not cause any breaking changes since elektra-highlevel already depends on elektra-ease. In addition the header elektra/conversion.h is kept for compatibility. (Klemens Böswirth)
• Fixes in documentation that might disallow some code operating in grey areas before. (Markus Raab)
• We removed keyRel and keyRel2 since it can be easily replaced by other existing functions. (Philipp Gackstatter)

We changed the following symbols:

• ELEKTRA_PLUGIN_COMMIT
• elektraKeyToString
• elektraKeyToBoolean
• elektraKeyToChar
• elektraKeyToOctet
• elektraKeyToShort
• elektraKeyToUnsignedShort
• elektraKeyToLong
• elektraKeyToUnsignedLong
• elektraKeyToLongLong
• elektraKeyToUnsignedLongLong
• elektraKeyToFloat
• elektraKeyToDouble
• elektraKeyToLongDouble
• elektraBooleanToString
• elektraCharToString
• elektraOctetToString
• elektraShortToString
• elektraUnsignedShortToString
• elektraLongToString
• elektraUnsignedLongToString
• elektraLongLongToString
• elektraUnsignedLongLongToString
• elektraFloatToString
• elektraDoubleToString
• elektraLongDoubleToString
• kdb_octet_t
• kdb_boolean_t
• kdb_short_t
• kdb_long_t
• kdb_long_long_t
• kdb_unsigned_short_t
• kdb_unsigned_long_t
• kdb_unsigned_long_long_t
• kdb_char_t
• kdb_float_t
• kdb_double_t
• kdb_long_double_t

Core

• A new plugin function, kdbCommit, was implemented. The function is carried out in the commit phase of kdbSet and separates the commit functionality from the kdbSet() function. (Vid Leskovar)
• kdbconfig.h is no longer included in the installed headers. This is because it could cause conflicts with other config.h-type headers from applications. (Klemens Böswirth)
• ksAppendKey: state that it only fail on memory problems. (Markus Raab)
• Fix memory leak in kdbGet. (Markus Raab)
• Implemented kdberrors.h directly without generation of the specification file because of drastically reduced error code count (Michael Zronek)
• keyIsDirectBelow was renamed to keyIsDirectlyBelow. (Philipp Gackstatter)
• keyMeta was added to provide access to a key's underlying KeySet that holds its metadata keys. (Philipp Gackstatter)
• Removed the obsolete ksLookupByString and ksLookupByBinary, as well as deprecated KDB_O_* options. (Philipp Gackstatter)
• Added keyLock and keyIsLocked. (Manuel Mausz)
• Removed keyVInit. (Manuel Mausz)

Opts

• The option -h is no longer used to indicate help mode. Only --help, will invoke help mode. (Klemens Böswirth)

Proposal

• Removed or moved several functions of kdbproposal.h:
  • elektraKsToMemArray was moved to kdbease.h,
  • elektraLookupOptions was moved to kdbprivate.h,
  • keySetStringF was moved to kdbinternal.h,
  • Removed ksPrev and elektraKsPrev,
  • Removed elektraRenameKeys and replaced it with ksRenameKeys. (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.

• We removed the Haskell and GI bindings. (Markus Raab)
• Avoid unnecessary copying std::string where possible (setString and setMeta only). (Manuel Mausz)
• CPP: add Key::is{Name,Value,Meta}Locked. (Manuel Mausz)
• GLIB: removed gelektra_keyset_resize. (Manuel Mausz)
• GLIB: removed gelektra_keyset_rewind, gelektra_keyset_next, gelektra_keyset_current, gelektra_keyset_getcursor, gelektra_keyset_setcursor. (Manuel Mausz)
• GLIB: renamed gelektra_keyset_atcursor to gelektra_keyset_at. (Manuel Mausz)
• gsettings: adapt iterator. (Manuel Mausz)
• SWIG: Add KeyNotFoundException exception. (Manuel Mausz)
• SWIG: Fix KeySet equality operators. (Manuel Mausz)
• SWIG/Python: hash(key) will throw unless the key name is locked. (Manuel Mausz)
• SWIG/Python: Add operator overloadings for len(Key), repr(Key), str(KeySet), repr(KeySet). (Manuel Mausz)
• SWIG/Python: Add alternative Key constructor Key(name, value, [dict]). (Manuel Mausz)
• SWIG/Python: Add KeySet.extend([key1, key2,...]) and KeySet.append(key1, key2, ...). (Manuel Mausz)
• SWIG/Python: Add KeySet.append(key_name, key_value, key_opts) which directly creates and appends a key. (Manuel Mausz)
• SWIG/Python: Add KeySet.unpack_names(), KeySet.unpack_basenames(), KeySet.filter(func), KeySet.filter_below(where), Key.array_elements(). (Manuel Mausz)

Java

• Completely overhauled the Java binding to be able to use Elektra plugins directly. A new PluginLoader can load Elektra plugins or a native implemented Java plugin. All Plugins now implement the new Plugin interface. For an example see the test case. (Michael Zronek)
• Upgraded maven dependencies for Java binding (Michael Zronek)
• The Java binding now supports the error codes in a native way. All exceptions contain the necessary information. (Michael Zronek)
• Further improved the Java binding such as wording and documentation. (Michael Zronek)

Rust

• Add the elektra-sys crate which contains raw bindings to libelektra for Rust. (Philipp Gackstatter)
• Add the elektra crate which contains safe wrapper methods for the raw bindings. The crate contains bindings for the low-level API, which means that the data types Key and KeySet can now safely be used from Rust. The Rust version of the API has been designed to take advantage of Rust's type system and to be in accordance with the memory safety of Rust. For instance, the Key has been divided into StringKey and BinaryKey, to prevent type mismatches at compile-time. With the binding for KDB, one can take advantage of the elektra ecosystem from Rust. See the Readme for more. (Philipp Gackstatter)
• Rewrote the KDBError to follow the specification fully and in particular allow catching out of memory errors by catching resource errors. (Philipp Gackstatter)
• Added a keyset! macro to easily create a keyset with many keys in a single invocation. (Philipp Gackstatter)

Tools

• KDB_EXEC_PATH, which can be used to add further external tools to kdb, now supports : to separate paths. kdb list-tools and run_env were improved to take advantage of this. (Markus Raab)
• Checks for kdbCommit have been added to kdb plugin-check. (Vid Leskovar)
• Added PID file config setting for kdb-run-rest-frontend (Markus Raab)
• Added kdb meta-show command which prints out all metadata along with its values for a given key. (Michael Zronek)
• Removed kdb vset as it does not properly put metadata to the spec namespace. (Michael Zronek)
• Renamed kdb plugin commands following a hierarchical structure. kdb info is now kdb plugin-info, kdb check is now kdb plugin-check and kdb list is now kdb plugin-list. We also removed the obsolete kdb fstab. (Philipp Gackstatter)
• Renamed kdb meta commands:
  • kdb getmeta is now kdb meta-get
  • kdb lsmeta is now kdb meta-ls
  • kdb showmeta is now kdb meta-show
  • kdb rmmeta is now kdb meta-rm
  • kdb setmeta is now kdb meta-set (Philipp Gackstatter)
• Fix test tool gen-gpg-testkey by giving a narrower GPG key description. Fixes mismatches with existing GPG keys that contain "elektra.org" as e-mail address. (Peter Nirschl)
• kdb list-commands and kdb plugins-list now sort their output in an alphabetical order (Anton Hößl)
• kdb plugin-list does now mention in the helptext that with option -v the output is sorted by the plugin status (Anton Hößl)
• kdb import, kdb export and kdb editor now search the plugin database for suitig plugins so it's now possible to run kdb export /hello json instead of having to specify the plugin for the desired format directly. (Anton Hößl)
• get and mount: Remove dependency on kdbprivate.h (Philipp Gackstatter)

Scripts

• We structured the scripts. (Markus Raab)

• Removed the scripts

  • scripts/elektra-merge,
  • scripts/elektra-mount,
  • scripts/elektra-umount,
  • convert-fstab,
  • convert-hosts,
  • convert-inittab,
  • convert-users,
  • scripts/benchmark_libsplit.sh,
  • scripts/zsh and
  • example-xorg. (Markus Raab)

• Renamed scripts/run_dev_env to scripts/dev/run_env. (Markus Raab)

• The script draw-all-plugins now also works properly, if the repository path contains space characters. (René Schwaiger)

• The script link-checker now deduplicates the list of links before checking them. The timeout and amount of retries was also reduced. Lastly the script now supports a whitelist. Any link stored in tests/linkchecker.whitelist will not be checked. (Klemens Böswirth)

• We removed a script used to compare the runtime performance of YAML plugins. (René Schwaiger)

• Cleanup: separation of dev, admin and completion scripts. (Markus Raab, Rene Schwaiger)

• Pre-commit hook pre-commit-check-formatting now lives in scripts/dev/pre-commit-check-formatting. (Klemens Böswirth)

• The new script reformat-javascript formats the JavaScript code of the repository using the tool prettier. (René Schwaiger)

• We renamed

  • the script reformat-source to reformat-c, and
  • the script reformat-shfmt to reformat-shell. (René Schwaiger)

• The script cmake-format now requires cmake-format 0.6. (René Schwaiger)

• The new script reformat-java formats the Java code in the repository using clang-format. (René Schwaiger)

• The Markdown Shell Recorder now also works correctly on FreeBSD. (René Schwaiger)

Documentation

• Added a tutorial on how to write language bindings. Visit our new README. (Michael Zronek, Raphael Gruber, Philipp Gackstatter)
• Clarified subtyping in the language bindings tutorial. (Michael Zronek)
• A second tutorial on writing bindings for the high-level API was created as well. (Klemens Böswirth, Raphael Gruber)
• Added info on how to include xerces plugin with homebrew installation. (Anton Hößl)
• The compile instructions do not assume that you use make or gcc to build Elektra anymore. (René Schwaiger)
• Add hints about reformatting with docker. (Dominic Jäger)
• Add instructions about sourcing on FreeBSD. (Dominic Jäger)
• Add information on debuggers to main testing documentation. (Dominic Jäger)
• Added design decision for error code implementations. (Michael Zronek)
• Fixed some typos and links in the documentation and add new iterate example. (Philipp Gackstatter)
• Clarified warnings metadata in the error-handling guideline. (Michael Zronek)
• We fixed minor spelling mistakes in the documentation. (René Schwaiger)
• Corrected buildserver documentation. (Djordje Bulatovic)
• Add merge library into kdbset example. (Dominic Jäger)
• We updated links for the INI parsing library Nickel. (René Schwaiger)
• Added some information about contributing to Elektra. (Hani Torabi)

Tests

• We changed how the formatting test detects code differences. This update should get rid of transient errors as reported here. (René Schwaiger)
• We disabled the test for the conversion engine. For more information, please take a look at issue #3086. (René Schwaiger)
• We disabled the test testmod_zeromqsend from the command kdb run_all, since it caused timeouts in high load scenarios. (Mihael Pranjić)
• The (Markdown) Shell Recorder now prints the protocol for a failed test, even if the test modified the database permanently. (René Schwaiger)
• We rerun ctest twice to ignore temporary build failures. (Markus Raab)

Build

CMake

• kdbtypes.h is now generated directly via a CMake configure_file call. (Klemens Böswirth)
• The variable ELEKTRA_STAT_ST_SIZE_F now contains the correct format specifier for the st_size member of the stat struct on macOS. (René Schwaiger)
• We simplified and unified the CMake code for the Shell Tests and the Shell Recorder. (René Schwaiger)
• CMake now prints warnings about missing man pages. (René Schwaiger)
• The build system does not update a man page in the folder doc/man any more, if ronn only changed the creation date of the man page. (René Schwaiger)

Compilation

• We now have a setup for proper symbol versioning. (Klemens Böswirth)
• We do not use implicit typing in the code of the conditionals and yamlcpp plugin any more. After this update, the code compiles without any warnings, even though we now use the compiler switch -Wconversion. (René Schwaiger)
• JNA and JNI are not built concurrently anymore to avoid dependency resolution fails. (Michael Zronek)

Docker

• Added Dockerfile for Ubuntu Bionic (Djordje Bulatovic)
• We removed all Haskell packages from the Dockerfiles in the folder scripts/docker. (René Schwaiger)
• We added a basic Dockerfile for Arch Linux. (René Schwaiger)
• We updated the Dockerfile for Alpine Linux. (René Schwaiger)

Vagrant

• We added a Vagrantfile for a virtual machine based on FreeBSD 12. (René Schwaiger)

Other

• The reformatting script now checks that the correct version of cmake-format is used. (Klemens Böswirth, René Schwaiger)
• Improved various error messages and synchronized documentations. (Michael Zronek)
• Improved range plugin error message. (Michael Zronek)
• Improved error codes documentation to clarify the hierarchy for developers. (Michael Zronek)
• Release notes now use git's union merge driver. (Dominic Jäger)
• Updated asciinema recording to correctly use sudo. (Michael Zronek)
• Add pkg-config file for kdbmerge. (Raphael Gruber)

Infrastructure

Cirrus

• The 🔗 Check build job now merges PRs before checking links. (Klemens Böswirth)

• We enabled logging in the build job 🍎 Clang. This update makes sure that Elektra’s logging code compiles without warnings on macOS. (René Schwaiger)

• All macOS build jobs now use Xcode 11.1 instead of Xcode 10.1. (René Schwaiger)

• We removed all non-POSIX shell code from the Cirrus configuration file. (René Schwaiger)

• The macOS build jobs now use Ruby 2.6. (René Schwaiger)

• We do not call ninja directly anymore. Instead we use cmake --build. This has the advantage that we do not have to care about the Generator used by CMake. (René Schwaiger)

• We added the build job 😈 ASAN, which builds and executes Elektra on FreeBSD with enabled AddressSanitizer. (René Schwaiger)

• We now store common commands in one place at the top of the configuration file. This makes it easier to selectively disable certain build jobs. (René Schwaiger)

• The new job 📚 Check checks

  • that the man pages are up-to-date, and
  • that building the PDF version of the Doxygen documentation works. (René Schwaiger)

• The new build job 🐧 Fedora builds and tests Elektra on Fedora Linux. (René Schwaiger)

Jenkins

• We upgraded all servers to Buster. (Markus Raab)
• Jenkins does not auto cancel build jobs of the master branch anymore. (René Schwaiger)
• Updated xUnit plugin in Jenkinsfile. (Djordje Bulatovic)

Restyled

• Restyled now also formats Markdown files with prettier. (René Schwaiger)

Travis

• The build job 🍏 GCC now uses the Travis Homebrew addon to install dependencies. (René Schwaiger)
• We now build and test Elektra on Ubuntu 18.04 (Bionic Beaver) instead of Ubuntu 16.04 (Xenial Xerus). (René Schwaiger)

Website

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

• Renamed the sub menu Getting Started in the menu Documentation to About Elektra and removed the sub-sub-menus Compiling, Installation and Tutorials. These sub-sub-menus are now sub-menus of Documentation. A new sub menu labeled Get Started added to the menu Documentation with some newcomer-friendly information. Renamed the Getting Started sub menu in Development to Contribute to Elektra. The green button on the main page is routed to the new Get Started page. (Hani Torabi)
• The website now lives in the folder website to avoid confusion with the REST backend of the Web-UI. (Markus Raab)
• Improve main page of website, restructure getting started. (Markus Raab)

Outlook

We are currently working on following topics:

• Elektrify KDE (Dardan Haxhimustafa) and (Felix Resch)
• Elektrify LCDproc (Klemens Böswirth) and (Jakob Fischer)
• Reduce the number of merge conflicts in 3-way merge. (Dominic Jäger)
• Go bindings and improved Web-UI (Raphael Gruber)
• Improved Error handling (Michael Zronek)
• New default storage (René Schwaiger) and (Jakob Fischer)
• Shell completion (Ulrike Schäfer)
• Improve Elektra developer experience (Hani Torabi)
• Ansible bindings (Thomas Waser)
• Plugin interface improvements (Vid Leskovar)

Statistics

We closed 75 issues for this release.

About 29 authors changed 1651 files with 82267 insertions(+) and 41690 deletions(-) in 1623 commits.

Thanks to all authors for making this release possible!

Finished Thesis

• Klemens Böswirth: We explore the feasibility of using Elektra in a real-world project. We focused especially on using the high-level API with code-generation. In the thesis, we implemented new versions of LCDproc, one with the low-level API and one with the high-level API. Then we did some benchmarks to compare them. Our results indicate, that Elektra is very much usable in real-world projects. However, we also found that there is still potential for further optimizations.
• Mihael Pranjić: We design a binary storage format for Elektra's data structures and implement a cache plugin based on the format. The cache plugin leverages the mmap() system call to read and write data. Our cache implementation for Elektra's data structures makes the access to the KDB more than 80 times faster for larger data sets. The penalty for cache misses is below 20 percent for reasonably sized data sets.

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:

• author: mpranj
• file: elektra-0.9.1.tar.gz
• size: 7534156
• md5sum: 42ff587adb7c3f15807ac4dae6722261
• sha1: bf250260a4efa20e5444f0a7f0027430bc7aa8a0
• sha256: df1d2ec1b4db9c89c216772f0998581a1cbb665e295ff9a418549360bb42f758

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

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