Skip to content
Permalink
Browse files

Documentation: Add basic storage plugin tutorial

  • Loading branch information...
sanssecours committed Mar 11, 2019
1 parent 699e349 commit 5538934ef482c21a7034199364fd24237b80b7d8
@@ -17,3 +17,5 @@
\newunicodechar{🍏}{green apple}
\newunicodechar{🍎}{red apple}
\newunicodechar{🐧}{penguin}
\newunicodechar{🐣}{hatching chick}
\newunicodechar{🐓}{cockerel}
@@ -185,6 +185,7 @@ you up to date with the multi-language support provided by Elektra.

## Documentation

- We added a (very) basic tutorial that tells you [how to write a (well behaved) storage plugin](../tutorials/storage-plugins.md). _(René Schwaiger)_
- The documentation now uses [fenced code blocks](https://help.github.com/en/articles/creating-and-highlighting-code-blocks#syntax-highlighting) to improved the syntax highlighting of code snippets. _(René Schwaiger)_
- The [Markdown Link Converter](https://master.libelektra.org/doc/markdownlinkconverter) now uses the style

@@ -4,7 +4,7 @@ This file serves as a tutorial on how to write a storage plugin (which includes

## Types of Plugins

- Storage plugins are used by Elektra in order to store data in the Elektra Key Database
- [Storage plugins](storage-plugins.md) are used by Elektra in order to store data in the Elektra Key Database
in an intelligent way. They act as a liaison between configuration files and the Key Database. Storage plugins are largely responsible for
the functionality of Elektra and they allow many of its advanced features to work.
These plugins act as sources and destinations of configuration settings.
@@ -0,0 +1,48 @@
# How-To: Write a (Well Behaved) Storage Plugin

The [plugin tutorial](plugins.md) already covers some of the most interesting parts on how to write a (storage) plugin. This text will tell you a little bit more about how a storage plugin should act. While it is usually relatively easy to create a plugin that stores basic key-value pairs, adding advanced features such as support for

- [arrays](arrays.md), and
- [metadata](../dev/metadata.md),

takes more work. Before you continue with this text, please make sure that you read all of the linked documents.

## Don’t Add Additional Keys

One common problem of storage plugins is, that they store too many keys. For example, if the user adds the keys

- `user/tests/storage/root` and
- `user/tests/storage/root/level1/level2/level3`,

then your plugin should only store those two keys. **Do not** add the keys

- `user/tests/storage/root/level1`, or
- `user/tests/storage/root/level1/level2`

to the key set. One plugin that handles this situation properly is [YAML CPP](/src/plugins/yamlcpp/), as the following [Markdown Shell Recorder test](https://master.libelektra.org/tests/shell/shell_recorder/tutorial_wrapper) shows:

```sh
# Mount plugin
sudo kdb mount config.yaml user/tests/storage yamlcpp
# Add key-value pairs
kdb set user/tests/storage/root 🐓
kdb set user/tests/storage/root/level1/level2/level3 🐣
# Make sure that YAML CPP did not store any additional keys
kdb ls user/tests/storage/root
#> user/tests/storage/root
#> user/tests/storage/root/level1/level2/level3
# Undo modifications to the key database
sudo kdb umount user/tests/storage
```

.

<!--
TODO: Describe difference between keys that store null values (binary data) and empty values (string data)
TODO: Describe how to store arrays properly (`array` metadata): Just add a link to `arrays.md`
TODO: Add information on how plugins should store comment (meta)data
TODO: Document that a plugin should keep the ordering of key-value pairs of a document intact, when writing data back to the configuration file
-->
@@ -24,6 +24,7 @@ endif (CMAKE_COMPILER_IS_GNUCXX AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 4.9)

add_msr_test (tutorial_arrays "${CMAKE_SOURCE_DIR}/doc/tutorials/arrays.md")
add_msr_test (tutorial_cascading "${CMAKE_SOURCE_DIR}/doc/tutorials/cascading.md")
add_msr_test (tutorial_storage_plugins "${CMAKE_SOURCE_DIR}/doc/tutorials/storage-plugins.md" REQUIRED_PLUGINS yamlcpp)

if (ENABLE_ASAN)
message (STATUS "Excluding Markdown Shell Recorder test for `validation`, as it leaks memory and fails with ASAN enabled")

0 comments on commit 5538934

Please sign in to comment.
You can’t perform that action at this time.