diff --git a/doc/news/_preparation_next_release.md b/doc/news/_preparation_next_release.md index 0479d1233f2..1d3155e0fe3 100644 --- a/doc/news/_preparation_next_release.md +++ b/doc/news/_preparation_next_release.md @@ -16,24 +16,24 @@ You can also read the news [on our website](https://www.libelektra.org/news/0.9. ## Highlights -- Important Breaking Changes to Keynames et al. _[more info](#hl-1)_ -- Debian and Fedora Packaging with CPack _[more info](#hl-2)_ - -### Important Breaking Changes +- Important Breaking Changes to key names et al. _[see below](#hl-1)_ +- Debian and Fedora Packaging with CPack _[see below](#hl-2)_ -- The structure of key names has been changed. [more info](#br-1) _(Klemens Böswirth)_
+### Important Breaking Changes + +- The structure of key names has been changed. [see below](#br-1) _(Klemens Böswirth)_
**This change breaks mountpoint configurations.** - Please follow the upgrade procedure [below](#mountpoint-upgrade). -- The backend fallback procedure introduced in Elektra 0.8.15 has been removed and the structure of the `warnings` metadata array has been changed. [more info](#br-2) _(Klemens Böswirth)_ + Please follow the upgrade procedure [shown below](#mountpoint-upgrade). +- 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](#br-2) _(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 Keynames - -There have been significant changes to Elektra's Keynames. +#### 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`. @@ -41,12 +41,12 @@ There have been significant changes to Elektra's Keynames. - 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 internal implementation for `keySetName`, `keyAddName`, etc. has been completely rewritten. - If you rely on specific behaviour of Elektra's Keynames and have already taken the two changes above into account, please refer to the newly created [Keyname documentation](../KEYNAMES.md) and [Python reference implementation](../../scripts/keynames.py). +- 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](../KEYNAMES.md) and [Python reference implementation](../../scripts/keynames.py). - Metakeys now use the namespace `meta:/`. The accessor function `keyGetMeta` and `keySetMeta` automatically add this namespace to preserve compatibility. - However, if you use the recently introduced `keyMeta` or otherwise directly access the keyname of a metakey, you will have to update your code. + 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). @@ -74,10 +74,10 @@ There have been significant changes to Elektra's Keynames. A huge thanks to _(Klemens Böswirth)_ for doing these important changes and clean-ups. -#### Mountpoint upgrade - +#### 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. @@ -95,6 +95,8 @@ 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](https://issues.libelektra.org/3633). +> > _You have been warned. Manually backup important data first._ For the migration you can use the following commands: @@ -109,10 +111,10 @@ 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 - +### 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: @@ -120,13 +122,13 @@ We now provide DEB and RPM packages for releases and for every commit on master - DEB packages for Debian Buster - DEB packages for Ubuntu Bionic - DEB packages for Ubuntu Focal -- RPM packages for Fedora 33. +- RPM packages for Fedora 33 A big thanks to _(Robert Sowula)_ for introducing CPack and creating the repositories. #### Short Installation Guide -To add our DEB package repositories following steps need to be done: +##### DEB packages 1. First, you need to obtain the repository key: @@ -141,7 +143,9 @@ sudo apt-key adv --keyserver keys.gnupg.net --recv-keys F26BBE02F3C315A19BF1F791 apt-get install libelektra5-all ``` -2. To add our RPM package repositories you need to download our [.repo configuration file](https://rpms.libelektra.org/fedora-33/libelektra.repo) and add it to yum/dnf. +##### RPM packages + +Download our [.repo configuration file](https://rpms.libelektra.org/fedora-33/libelektra.repo) and add it to yum/dnf. To get all packaged plugins, bindings and tools install: @@ -157,7 +161,7 @@ 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. +> _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](../INSTALL.md). @@ -168,7 +172,7 @@ A big thanks to _(Robert Sowula)_ for doing the necessary renamings. ## Plugins -The following section lists news about the [modules](https://www.libelektra.org/plugins/readme) we updated in this release. +The following section lists news about the [plugins](https://www.libelektra.org/plugins/readme) we updated in this release. ### jni @@ -206,7 +210,7 @@ The text below summarizes updates to the [C (and C++)-based libraries](https://w - 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 internal update to how warnings are generated. +- 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. @@ -244,6 +248,7 @@ you up to date with the multi-language support provided by Elektra. ## 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 @@ -253,7 +258,7 @@ you up to date with the multi-language support provided by Elektra. ## Documentation -- Finalize 1.0 decisions. _(Markus Raab)_ +- Finalize 1.0 [decisions](/doc/decisions). _(Markus Raab)_ - Update [API design document](/doc/DESIGN.md) _(Markus Raab and Stefan Hanreich)_ - Update [release instructions](../todo/RELEASE) _(Robert Sowula)_ - Changed API documentation terms [current, latest] to [latest, master]. @@ -342,7 +347,7 @@ The [hashsums are:](https://github.com/ElektraInitiative/ftp/blob/master/release <<`scripts/generate-hashsums elektra-0.9.<>.tar.gz`>> -The release tarball is also available signed by Markus Raab using GnuPG from +The release tarball is also available signed by Mihael Pranjić using GnuPG from [here](https://www.libelektra.org/ftp/elektra/releases/elektra-0.9.<>.tar.gz.gpg) or on [GitHub](https://github.com/ElektraInitiative/ftp/blob/master/releases/elektra-0.9.<>.tar.gz.gpg?raw=true) diff --git a/doc/todo/NEWS.md b/doc/todo/NEWS.md index 9c7e9b672ba..88a44d9a330 100644 --- a/doc/todo/NEWS.md +++ b/doc/todo/NEWS.md @@ -41,7 +41,7 @@ This is the quickest way to get started with Elektra without compiling and other ## Plugins -The following section lists news about the [modules](https://www.libelektra.org/plugins/readme) we updated in this release. +The following section lists news about the [plugins](https://www.libelektra.org/plugins/readme) we updated in this release. ### <> @@ -208,7 +208,7 @@ The [hashsums are:](https://github.com/ElektraInitiative/ftp/blob/master/release <<`scripts/generate-hashsums elektra-0.9.<>.tar.gz`>> -The release tarball is also available signed by Markus Raab using GnuPG from +The release tarball is also available signed using GnuPG from [here](https://www.libelektra.org/ftp/elektra/releases/elektra-0.9.<>.tar.gz.gpg) or on [GitHub](https://github.com/ElektraInitiative/ftp/blob/master/releases/elektra-0.9.<>.tar.gz.gpg?raw=true) diff --git a/scripts/cmake/ElektraCache.cmake b/scripts/cmake/ElektraCache.cmake index 4a1668d6b74..ea120739d9c 100644 --- a/scripts/cmake/ElektraCache.cmake +++ b/scripts/cmake/ElektraCache.cmake @@ -403,6 +403,7 @@ mark_as_advanced ( XercesC_DIR OPENSSL_INCLUDE_DIR LUA_EXECUTABLE # The following settings are internal (not to be changed by users): + FEDORA CARGO_EXECUTABLE DIFF_COMMAND GLib_CONFIG_INCLUDE_DIR @@ -441,6 +442,7 @@ mark_as_advanced ( ADDED_DIRECTORIES ADDED_PLUGINS REMOVED_PLUGINS + REMOVED_TOOLS ADDED_BINDINGS LIBGCRYPTCONFIG_EXECUTABLE jna diff --git a/src/bindings/cpp/include/key.hpp b/src/bindings/cpp/include/key.hpp index 5e4c9ddefc3..6679423f0d7 100644 --- a/src/bindings/cpp/include/key.hpp +++ b/src/bindings/cpp/include/key.hpp @@ -599,7 +599,7 @@ inline Key::Key (Key const & k) : key (k.key) /** * @copydoc keyNew * - * @throw bad_alloc if key could not be constructed (allocation problems) + * @throw KeyInvalidName if key could not be constructed * * @param keyName the name of the new key */ @@ -611,7 +611,7 @@ inline Key::Key (const char * keyName, ...) key = ckdb::keyVNew (keyName, ap); va_end (ap); - if (!key) throw KeyInvalidName (keyName, ""); + if (!key) throw KeyInvalidName (keyName, "A key name consists of [:]/."); operator++ (); } @@ -619,7 +619,7 @@ inline Key::Key (const char * keyName, ...) /** * @copydoc keyNew * - * @throw bad_alloc if key could not be constructed (allocation problems) + * @throw KeyInvalidName if key could not be constructed * * @warning Not supported on some compilers, e.g. * clang which requires you to only pass non-POD @@ -635,7 +635,7 @@ inline Key::Key (const std::string keyName, ...) key = ckdb::keyVNew (keyName.c_str (), ap); va_end (ap); - if (!key) throw std::bad_alloc (); + if (!key) throw KeyInvalidName (keyName, "A key name consists of [:]/."); operator++ (); } @@ -643,7 +643,7 @@ inline Key::Key (const std::string keyName, ...) /** * @copydoc keyNew * - * @throw bad_alloc if key could not be constructed (allocation problems) + * @throw KeyInvalidName if key could not be constructed * * @param keyName the name of the new key * @param ap the variable argument list pointer @@ -652,7 +652,7 @@ inline Key::Key (const char * keyName, va_list ap) { key = ckdb::keyVNew (keyName, ap); - if (!key) throw std::bad_alloc (); + if (!key) throw KeyInvalidName (keyName, "A key name consists of [:]/."); operator++ (); } diff --git a/src/bindings/cpp/tests/testcpp_key.cpp b/src/bindings/cpp/tests/testcpp_key.cpp index 60ce0d33cc7..425e1864168 100644 --- a/src/bindings/cpp/tests/testcpp_key.cpp +++ b/src/bindings/cpp/tests/testcpp_key.cpp @@ -545,7 +545,7 @@ TEST (key, valid) for (auto & invalid_name : invalid_names) { - EXPECT_THROW (Key (invalid_name, KEY_END), std::bad_alloc); + EXPECT_THROW (Key (invalid_name, KEY_END), kdb::KeyInvalidName); } Key v1 ("user:/", KEY_END); diff --git a/src/bindings/swig/ruby/kdb.i b/src/bindings/swig/ruby/kdb.i index a9d353bbf02..5fa20182a49 100644 --- a/src/bindings/swig/ruby/kdb.i +++ b/src/bindings/swig/ruby/kdb.i @@ -123,7 +123,7 @@ the original C++ class in the following aspects: %catches (kdb::KeyTypeMismatch, kdb::KeyException) kdb::Key::getString; %catches (kdb::KeyTypeMismatch, kdb::KeyException) kdb::Key::getBinary; -%catches (std::bad_alloc) kdb::Key::Key; +%catches (kdb::KeyInvalidName) kdb::Key::Key; /* ignore certain methods */