Skip to content
This repository has been archived by the owner on Oct 15, 2024. It is now read-only.

Commit

Permalink
Merge branch 'master' into cpack-rpm-packaging
Browse files Browse the repository at this point in the history
  • Loading branch information
robaerd authored Jan 11, 2021
2 parents dcad199 + d3868d5 commit 23a6941
Show file tree
Hide file tree
Showing 116 changed files with 1,065 additions and 2,529 deletions.
7 changes: 3 additions & 4 deletions .cirrus.yml
Original file line number Diff line number Diff line change
Expand Up @@ -119,8 +119,6 @@ mac_task:
install_script:
- | # Install Homebrew formulas
brew install openjdk
brew tap oclint/formulae
brew install oclint
brew install antlr
brew install antlr4-cpp-runtime
brew install augeas
Expand All @@ -143,6 +141,7 @@ mac_task:
brew install maven
brew install moreutils
brew install ninja
brew install oclint/formulae/oclint
brew install npm
brew install openssl
brew install pkg-config
Expand All @@ -166,8 +165,8 @@ mac_task:
- | # Install Python packages
pip3 install cmake-format[yaml]==0.6.3
- | # Install Ruby (We use the Homebrew version of Ruby to install gems, since compiling `ronn` fails with the macOs version of Ruby.)
brew install ruby@2.7
export PATH="/usr/local/opt/ruby@2.7/bin:/usr/local/lib/ruby/gems/2.7.0/bin:$PATH"
brew install ruby
export PATH="/usr/local/opt/ruby/bin:/usr/local/lib/ruby/gems/3.0.0/bin:$PATH"
- | # Install Ruby gems
sudo gem install ronn test-unit --no-document
- | # Install JavaScript packages
Expand Down
108 changes: 108 additions & 0 deletions .github/workflows/macOS_gcc10.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
name: macOS GCC

# Triggers the workflow on push or pull request events
on: [push, pull_request]

env:
# Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)
BUILD_TYPE: RelWithDebInfo
# Unfortunately the tests for the Xerces plugin fail: https://travis-ci.org/ElektraInitiative/libelektra/jobs/483331657#L3740
# The curlget tests fail: https://github.com/ElektraInitiative/libelektra/issues/3382
PLUGINS: 'ALL;-xerces;-curlget'
BINDINGS: 'ALL;-rust'
# Skip homebrew cleanup to avoid issues with removal of packages
HOMEBREW_NO_INSTALL_CLEANUP: 1
CC: gcc-10
CXX: g++-10

jobs:
build:
# The CMake configure and build commands are platform agnostic and should work equally
# well on Windows or Mac. You can convert this to a matrix build if you need
# cross-platform coverage.
# See: https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/managing-complex-workflows#using-a-build-matrix
runs-on: macos-latest

steps:
- uses: actions/checkout@v2

- name: Install Dependencies
run: |
brew install augeas
brew install bison
brew install dbus
brew install discount
brew install flex
brew install gpgme
brew install libev
brew install libgcrypt
brew install libgit2
brew install libuv
brew install lua
brew install ninja
brew install qt
brew install swig
brew install yajl
brew install zeromq
- name: Setup Build Environment
run: |
gem install test-unit --no-document
pip2 install cheetah # Required by kdb-gen
brew tap homebrew/services
brew update # Work around for [Homebrew Services issue 206](https://github.com/Homebrew/homebrew-services/issues/206)
brew services restart dbus
cmake -E make_directory ${{runner.workspace}}/build
- name: Configure CMake
# Use a bash shell so we can use the same syntax for environment variable
# access regardless of the host operating system
shell: bash
working-directory: ${{runner.workspace}}/build
# Note the current convention is to use the -S and -B options here to specify source
# and build directories, but this is only available with CMake 3.13 and higher.
# The CMake binaries on the Github Actions machines are (as of this writing) 3.12
run: |
PATH="/usr/local/opt/ruby@2.7/bin:/usr/local/lib/ruby/gems/2.7.0/bin:$PATH"
PATH="/usr/local/opt/python@3.9/bin:$PATH"
SYSTEM_DIR="$PWD/kdbsystem"
CMAKE_OPT+=(
-GNinja
-DPLUGINS="${PLUGINS:-ALL}"
-DBINDINGS="${BINDINGS:-ALL}"
-DTOOLS="${TOOLS:-ALL}"
-DBUILD_FULL="${BUILD_FULL:-OFF}"
-DBUILD_SHARED="${BUILD_SHARED:-ON}"
-DENABLE_ASAN="${ENABLE_ASAN:-OFF}"
-DCOMMON_FLAGS="${COMMON_FLAGS--Werror}"
-DENABLE_DEBUG=ON
-DCMAKE_EXPORT_COMPILE_COMMANDS=ON
-DKDB_DB_SYSTEM="$SYSTEM_DIR"
-DKDB_DEFAULT_STORAGE="${KDB_DEFAULT_STORAGE:-dump}"
-DKDB_DB_FILE="${KDB_DB_FILE:-default.ecf}"
-DKDB_DB_INIT="${KDB_DB_INIT:-elektra.ecf}"
$TRAVIS_BUILD_DIR
)
printf '—— CMake Config ——\n'
for option in "${CMAKE_OPT[@]}"; do printf '%s\n' "$option"; done
cmake $GITHUB_WORKSPACE -DCMAKE_BUILD_TYPE=$BUILD_TYPE ${CMAKE_OPT[@]}
- name: Build
working-directory: ${{runner.workspace}}/build
shell: bash
# Execute the build. You can specify a specific target with "--target <NAME>"
run: cmake --build .

- name: Install
working-directory: ${{runner.workspace}}/build
shell: bash
run: output="$(cmake --build . --target install 2>&1)" || printf '%s' "$output"

- name: Test
working-directory: ${{runner.workspace}}/build
shell: bash
# Execute tests defined by the CMake configuration.
# See https://cmake.org/cmake/help/latest/manual/ctest.1.html for more detail
run: |
cmake --build . --target run_all
kdb run_all
47 changes: 0 additions & 47 deletions .travis.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
language: cpp
dist: bionic
osx_image: xcode12.2

#
# Define the build matrix
Expand Down Expand Up @@ -151,38 +150,6 @@ matrix:
- ninja run_all
- kdb-full run_all

- os: osx
name: 🍏 GCC
compiler: gcc
addons:
homebrew:
packages:
- augeas
- bison
- dbus
- discount
- flex
- gpgme
- libev
- libgcrypt
- libgit2
- libuv
- lua
- ninja
- openssl
- python@3.9
- qt
- swig
- yajl
- zeromq
update: true
env:
# Unfortunately the tests for the Xerces plugin fail: https://travis-ci.org/ElektraInitiative/libelektra/jobs/483331657#L3740
# The curlget tests fail: https://github.com/ElektraInitiative/libelektra/issues/3382
- PLUGINS='ALL;-xerces;-curlget'
# Skip homebrew cleanup to avoid issues with removal of packages
- HOMEBREW_NO_INSTALL_CLEANUP=1

- os: linux
name: 🐧 GCC
compiler: gcc
Expand Down Expand Up @@ -211,20 +178,6 @@ matrix:
- CXX_COMPILER=clang++-7

before_install:
- |
if [ "$TRAVIS_OS_NAME" = 'osx' ]; then
rvm install 2.7.1
rvm use 2.7.1
gem install test-unit --no-document
if [ "$CC" = 'gcc' ]; then
brew upgrade gcc
export CC=gcc-10
export CXX=g++-10
fi
pip2 install cheetah # Required by kdb-gen
# start D-Bus session bus
brew services start dbus
fi
- |
if [ "$TRAVIS_OS_NAME" = 'linux' ]; then
[ -n "$CC_COMPILER" ] && export CC="$CC_COMPILER"
Expand Down
4 changes: 1 addition & 3 deletions doc/DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -219,7 +219,6 @@ The following functions return an internal string:
```c
const char *keyName(const Key *key);
const char *keyBaseName(const Key *key);
const char *keyOwner(const Key *key);
const char *keyComment(const Key *key);
```
Expand Down Expand Up @@ -262,8 +261,7 @@ databases. For allocation/deallocation we use C++ styled names (e.g
`*New`, `*Del`).

Macros and Enums are written in capital letters. Options start with
`KDB_O`, errors with `KDB_ERR`, namespaces with `KEY_NS` and key types
with `KEY_TYPE`.
`KDB_O`, errors with `KDB_ERR` and namespaces with `KEY_NS`.

Data structures start with a capital letter for every part of the word:

Expand Down
41 changes: 20 additions & 21 deletions doc/keynames/README.md → doc/KEYNAMES.md
Original file line number Diff line number Diff line change
@@ -1,26 +1,25 @@
# Key Names in Elektra

## Preface

This document is a full explanation of how _key names_ work in Elektra.
In addition to this document, a reference Python implementation can be found in [keynames.py](keynames.py).

## 0. Reference Implementation

In addition to this document, a reference Python implementation can be found in [keynames.py](../scripts/keynames.py).
The goal of the Python implementation is not to be fast, or to be used in any way other than as a reference.
If there are any discrepancies between this document, the Python implementation and the actual C implementation in [src/libs/elektra/keyname.c](../../src/libs/elektra/keyname.c), you should consider them as follows:
If there are any discrepancies between this document, the Python implementation and the actual C implementation in [src/libs/elektra/keyname.c](../src/libs/elektra/keyname.c), you should consider them as follows:

1. The C implementation is optimized for speed and much harder to maintain.
It is mostly likely to be incorrect.
1. The C implementation is optimized for speed and thus much harder to implement correctly.
2. In most cases, this document outranks the Python implementation.
There may, however, be cases where the language in this document was too vague and the Python implementation is actually correct.
3. If two of the sources agree, the third one is probably incorrect.
Although again, if one of the agreeing sources is the C implementation it could still be the case that there is a mistake.

In any case: If you find a discrepancy, please file a bug report at https://issues.libelektra.org/new.
In any case: If you find any discrepancies, please file a bug report at https://issues.libelektra.org/new.

> _Note:_ Mistakes happen.
> So there is no 100% always correct specification for Elektra's key names.
> The goal is only to provide a reference that has a very high likelihood of being correct.
> The goal of the Python implementation was to provide a reference that has a very high likelihood of being correct.
_To Elektra developers:_ Feel free to add any unclear or previous incorrect examples to the test cases in [tests/ctest/test_keyname.c](../../tests/ctest/test_keyname.c).
_To Elektra developers:_ Feel free to add any unclear or previous incorrect examples to the test cases in [tests/ctest/test_keyname.c](../tests/ctest/test_keyname.c).
These tests are very fast (1000+ test cases per second) and the more tests the better.

## 1. Key Name Parts and Namespaces
Expand All @@ -38,15 +37,15 @@ Each key is part of one of these _namespaces_:
- system
- default

Each of these namespaces has a very specific meaning, explained in [section 1.2](#12-namespaces-and-root-keys).
Each of these namespaces has a very specific meaning, explained in [Section 1.2](#12-namespaces-and-root-keys).

Apart from the namespace, a key name is just a series of zero or more _key name parts_.
Each key name part is just an arbitrary (possibly empty) sequence of non-zero bytes.

So without knowing anything about how key names are written, we could say that there is a key in the namespace "system" with the key name parts "elektra", "version" and "info".

> _Note:_ Not every such sequence, is a valid key name.
> For more information see [section 4](#4-valid-and-invalid-key-names)
> For more information see [Section 4](#4-valid-and-invalid-key-names)
### 1.1. Key Hierarchy

Expand All @@ -59,8 +58,8 @@ Elektra's keys commonly look like Unix paths:
> _Note:_ How this representation works exactly and how namespaces come into play, will be explained in the next section.
> For now, we only care that there is some similarity to Unix paths.
This is no mistake.
Elektra's _key database (KDB)_ is designed to resemble a Unix filesystem.
This is on purpose.
Elektra's _key database (KDB)_ is designed to resemble a Unix filesystem as much as possible.
In particular, the KDB has a similar hierarchy.
More generally, all key names exhibit this hierarchy.
By going back to thinking about a key name as a namespace and a series of key name parts, we can define this _key hierarchy_.
Expand Down Expand Up @@ -98,7 +97,7 @@ Here are a few examples to show how this works in practice (using the Unix-path-
You can think of the key hierarchy (within a single namespace) as a big tree of keys.
Each node in the tree is a single key `K` and the children of the nodes are the keys that are directly below `K`.

![Tree structure of a key hierarchy](tree.svg)
<img src="https://cdn.rawgit.com/ElektraInitiative/libelektra/master/doc/images/keynames_tree.svg" alt="Tree structure of a key hierarchy" />

The diagram above shows the key hierarchy of the keys in the table above (`A` -> `B` denotes `A` is directly below `B`).

Expand Down Expand Up @@ -146,7 +145,7 @@ To recap, Elektra knows these namespaces:
We mentioned above that there are key names with zero key name parts, i.e. just namespace.
These are called _root keys_ (based on Unix's filesystem root, as well as the root of a tree).

Lets explore them one by one:
Let us explore them one by one:

- The simplest namespace is the **"meta"**.
The namespace "meta" is used exclusively for meta keys, i.e. keys that are attached to another key as metadata.
Expand Down Expand Up @@ -266,7 +265,7 @@ In Elektra this doesn't quite work, but will use this definition for now.

> _Note:_ Only escaped key names can be canonical or non-canonical, so we normally omit the "escaped" specifier.
Let's look at a few examples to get a feeling for canonical and non-canonical key names.
Let us look at a few examples to get a feeling for canonical and non-canonical key names.

| Non-canonical | Canonical |
| ----------------------- | ------------------ |
Expand Down Expand Up @@ -427,7 +426,7 @@ For example, we cannot allow `\#abc`, because that would unescape into `#abc`, j
As mentioned above, Elektra has a notion of array parts.
More specifically, certain key name parts will be interpreted as array indices under certain circumstances (see also [documentation for arrays]()).

<!-- TODO (kodebach): link to array documentation -->
<!-- TODO: link to detailed array documentation -->

We already mentioned above, that array parts have canonical and non-canoncial forms.

Expand Down Expand Up @@ -481,14 +480,14 @@ This is why there are two types of reserved key name:
Even outside the context in which Elektra uses these directly, you should never use `system:/elektra` keys for other purposes.
2. Any key name containing the key name part `®elektra`:
These key names are reserved, but their meaning depends on the context.
Similar to the [METADATA.ini](../METADATA.ini) file for metadata, some conventions for these key names are defined in [reserved name document]().
Similar to the [METADATA.ini](METADATA.ini) file for metadata, some conventions for these key names are defined in [reserved name document]().

> _Note:_ We use UTF-8 here, so `®elektra` is specifically the 9-byte sequence `C2 AE 65 6C 65 6B 74 72 61`.
`Key`s with such key names will _never_ be used in the interface between storage plugins and the rest of Elektra.
This allows storage plugins to use `®elektra` to encode things that otherwise wouldn't be possible (e.g. values of non-leaf keys).

<!-- TODO (kodebach): link to ®elektra document -->
<!-- TODO: link to detailed ®elektra document -->

---

Expand Down Expand Up @@ -519,4 +518,4 @@ Therefore, you can use any `KeySet` locally in your application.
As soon as you pass the `KeySet` into an external function (e.g. `kdbSet`), however, errors may occur since the `KeySet` may pass through a function that requires `KeySet` which are properly validated against array rules.
For more details what conventions and rules exist around arrays, see [documentation for arrays](). [](#ref-footnote-4)

<!-- TODO (kodebach): link to array documentation -->
<!-- TODO: link to detailed array documentation -->
1 change: 1 addition & 0 deletions doc/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ This folder contains documentation for “Elektra – the configuration framewor
- [Installation](INSTALL.md): These instructions tell you how you can install Elektra in your favorite operating system.
- [Compile](COMPILE.md): If you want to compile Elektra from source please take a look at this document.
- [Help](help): This folder contains our man pages in Markdown format. The folder [man](man) contains these man pages in roff format, which you can read using the Unix utility [`man`](https://en.wikipedia.org/wiki/Man_page) if you already installed Elektra.
- [Keynames](KEYNAMES.md): This document describes how Elektra's keynames work.

### API

Expand Down
2 changes: 1 addition & 1 deletion doc/VISION.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ no error-handling and no cleanup):
int main (void)
{
KeySet * myConfig = ksNew (0, KS_END);
Key * key = keyNew ("/sw/samba/#0/current", KEY_CASCADING_NAME, KEY_END);
Key * key = keyNew ("/sw/samba/#0/current", KEY_END);
KDB * handle = kdbOpen (key);
kdbGet (handle, myConfig, key);
Expand Down
11 changes: 11 additions & 0 deletions doc/help/elektra-glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,17 @@
The **mountpoint** is the key where the backend is mounted to.
All keys of the backend are below that key.

- [Key name](/doc/KEYNAMES.md):
All keys in the KDB have a name.
This name is the keys unique identifier and follows a particular structure.
For more information take look at the [keyname documentation](/doc/KEYNAMES.md).

- [Key name part](/doc/KEYNAMES.md):
Key names consist of a series parts (and a namespace).

- [Key base name](/doc/KEYNAMES.md):
The last part of a key name.

- [Namespaces](elektra-namespaces.md):
Allow us to have multiple keys for the same purpose and otherwise the same key name.

Expand Down
File renamed without changes
Loading

0 comments on commit 23a6941

Please sign in to comment.