Revamp the example plugin

CMakeLists.txt

@@ -1,13 +1,17 @@
 cmake_minimum_required(VERSION 3.19...3.28 FATAL_ERROR)
 
-project(trim
-  DESCRIPTION "Trim operator plugin for Tenzir"
+project(example
+  DESCRIPTION "Example plugin for Tenzir"
   LANGUAGES CXX)
 
 find_package(Tenzir REQUIRED PATHS "/opt/tenzir")
 
+# This plugin is set up in a way where every builtin/*.cpp file may define its
+# own plugin. The main src/plugin.cpp file is just a stub that acts as a parent
+# to all the other plugins.
 TenzirRegisterPlugin(
-  TARGET trim
+  TARGET example
   ENTRYPOINT "src/plugin.cpp"
   SOURCES GLOB "src/*.cpp"
+  BUILTINS GLOB "builtins/*.cpp"
   INCLUDE_DIRECTORIES "include")

Dockerfile

@@ -1,18 +1,16 @@
 ARG TENZIR_VERSION=main
 FROM ghcr.io/tenzir/tenzir-dev:${TENZIR_VERSION} AS builder
 
-COPY . /tmp/trim/
+COPY . /tmp/example/
 
-RUN cmake -S /tmp/trim -B /tmp/trim/build -G Ninja -D CMAKE_INSTALL_PREFIX:STRING="$PREFIX"
-RUN cmake --build /tmp/trim/build --parallel
-RUN cmake --install /tmp/trim/build --strip --component Runtime --prefix /tmp/trim/install
+RUN cmake -S /tmp/example -B /tmp/example/build -G Ninja -D CMAKE_INSTALL_PREFIX:STRING="$PREFIX"
+RUN cmake --build /tmp/example/build --parallel
+RUN cmake --install /tmp/example/build --strip --component Runtime --prefix /tmp/example/install
 
 FROM builder AS test
 
-ENV BATS_LIB_PATH=/tmp/tenzir/tenzir/integration/lib
-
-ENTRYPOINT cmake --build /tmp/trim/build --target update-integration
+ENTRYPOINT cmake --build /tmp/example/build --target update-integration
 
 FROM ghcr.io/tenzir/tenzir:${TENZIR_VERSION}
 
-COPY --from=builder --chown=tenzir:tenzir /tmp/trim/install /opt/tenzir
+COPY --from=builder --chown=tenzir:tenzir /tmp/example/install /opt/tenzir

README.md

@@ -1,7 +1,12 @@
 # Tenzir Example Plugin
 
-This is an example plugin for Tenzir, adding a `trim` operaotr that removes
-whitespace from string fields.
+We think that learning how to build a plugin is best done by example. This
+example plugin implements a simple operator `read_custom_log` that parses a
+[custom line-based log format](integration/data/inputs/sample.log).
+
+The operators C++ implementation can be found in
+[`builtins/operators/read_custom_log.cpp`](builtins/operators/read_custom_log.cpp)
+and is extensively commented.
 
 ## Build and run
 
@@ -10,38 +15,39 @@ your additional plugin.
 
 Use `docker compose run --build tenzir '<pipeline>'` to interact with the node
 on the command-line, or set the following environment variables connect your
-node to app.tenzir.com:
+node to [app.tenzir.com](app):
 
-```
+```bash
 export TENZIR_PLUGINS__PLATFORM__API_KEY='<api-key>'
 export TENZIR_PLUGINS__PLATFORM__TENANT_ID='<tenant-id>'
 ```
 
-## Learn how to write a plugin
-
-We think that learning how to build a plugin is best done by example. Tenzir
-ships with a variety of [plugins][plugins-source] and
-[builtins][builtins-source] to get inspired by and to learn from.
-
-If you have any questions, feel free to reach out in the [#developers channel
-on Discord][discord].
-
 ## Run tests
 
 Every plugin defines additional tests using
 [BATS](https://bats-core.readthedocs.io/en/stable/writing-tests.html). Use
 `docker compose run --build tests` to execute your tests and update the
 reference files automatically.
 
+## Further Resources
+
+Tenzir ships with a variety of [plugins][plugins-source] and
+[builtins][builtins-source] to get inspired by and to learn from.
+
+If you have any questions, feel free to reach out in the [#developers channel
+on Discord][discord].
+
 ## Contribute your plugin
 
 If you want to upstream your plugin so that it is bundled with every Tenzir
 installation, open a PR that adds it to the [`plugins/` directory in the
-`tenzir/tenzir` repository][plugins-source]. If your  plugin has no
+`tenzir/tenzir` repository][plugins-source]. If your plugin has no
 dependencies, consider contributing it as a builtin instead. Builtins are
 located in the [`libtenzir/builtins/` directory in the `tenzir/tenzir`
 repository][builtins-source].
 
+[tenzir]: https://github.com/tenzir/tenzir
+[app]: https://app.tenzir.com
 [plugins-source]: https://github.com/tenzir/tenzir/tree/main/plugins
 [builtins-source]: https://github.com/tenzir/tenzir/tree/main/libtenzir/builtins
 [discord]: https://docs.tenzir.com/discord