This is an automated email from the ASF dual-hosted git repository. klesh pushed a commit to branch docs/single-binary-plugins in repository https://gitbox.apache.org/repos/asf/devlake-website.git
commit 21793bea5aefe34e6f02d8de7acf2d94cd84b36b Author: Klesh Wong <[email protected]> AuthorDate: Sat Oct 31 11:59:22 2026 +0800 docs: describe the single binary and plugin sideloading `make build` now produces one `bin/lake` with the framework, the API and every official plugin compiled in, and a deployed binary still loads extra `.so` plugins from PLUGIN_DIR. - Rewrite the "Compiling" section, which was rendered as a code block and documented two things that do not exist: `PLUGIN=<name>` (the variable is DEVLAKE_PLUGINS) and `make build-worker`. - Add a "Sideloading plugins" section: where the .so files go, why they must be built with the matching toolchain, and that a plugin which fails to load is skipped rather than taking the server down. - Document PLUGIN_DIR in the environment variables reference, including the container mount path and the override warning. --- docs/DeveloperManuals/DeveloperSetup.md | 36 +++++++++++++++++++++++++++++---- docs/GettingStarted/Environment.md | 14 +++++++++++++ 2 files changed, 46 insertions(+), 4 deletions(-) diff --git a/docs/DeveloperManuals/DeveloperSetup.md b/docs/DeveloperManuals/DeveloperSetup.md index 6d0bbd4bac8..5d41f9386c2 100644 --- a/docs/DeveloperManuals/DeveloperSetup.md +++ b/docs/DeveloperManuals/DeveloperSetup.md @@ -121,10 +121,38 @@ For provisioning, customizing, and creating dashboards, please refer to our [Gra ## Compiling - - Compile all plugins: `make build-plugin` - - Compile specific plugins: `PLUGIN=<PLUGIN_NAME> make build-plugin` - - Compile server: `make build` - - Compile worker: `make build-worker` +`make build` produces a single `bin/lake` binary: the framework, the API and every official plugin are compiled into it. + +```sh +cd backend +make build +``` + +While iterating you usually do not want all of them. `DEVLAKE_PLUGINS` takes a comma-separated list: + +```sh +DEVLAKE_PLUGINS=jira,gitlab make build +``` + +To build plugins as shared objects instead — to sideload them into an existing binary, or to ship a server without any plugin compiled in — use: + +```sh +make build-plugin # every plugin +DEVLAKE_PLUGINS=jira,gitlab make build-plugin # a subset +``` + +The output lands in `bin/plugins/<name>/<name>.so`. + +## Sideloading plugins + +A released `lake` binary already contains every official plugin, and it still accepts extras. Any `.so` found under `PLUGIN_DIR` (default `bin/plugins`) is opened at startup and registered on top of the compiled-in set, so you can add a custom plugin — or replace an official one — without rebuilding DevLake. + +Two things to know before you try it: + +- The `.so` has to be built with `go build -buildmode=plugin` against the **same DevLake version, Go toolchain, build flags and dependency versions** as the binary that loads it. Go rejects a plugin whose copy of a shared package differs, so build it in the matching `lake-builder` image rather than on your host. +- A plugin that fails to load is logged and skipped. The server keeps running without it, so check the log after adding one. + +The plugin entry point (`PluginEntry`, implementing `plugin.PluginMeta`) and the interfaces a plugin can implement are described in the [plugin development manual](https://github.com/apache/devlake/blob/main/backend/DevelopmentManual.md). ## References diff --git a/docs/GettingStarted/Environment.md b/docs/GettingStarted/Environment.md index cfc13ad879c..991319ecce2 100644 --- a/docs/GettingStarted/Environment.md +++ b/docs/GettingStarted/Environment.md @@ -8,6 +8,20 @@ This document explains how to set environment variables for Apache DevLake and w ## Environment Variables +### PLUGIN_DIR + +Directory scanned at startup for shared-object plugins (`.so`). The released binary already contains every official plugin; anything found here is loaded on top of that set, which makes this the directory to use for a custom or third-party plugin. + +| Environment Variable | Description | Default Value | +| -------------------- | ------------------------------------------------------------------------------------ | ------------- | +| `PLUGIN_DIR` | Directory scanned for sideloaded `.so` plugins. A missing directory is not an error. | `bin/plugins` | + +- In the Docker image, mount your plugins over `/app/bin/plugins`. +- A plugin that fails to load — usually a toolchain or dependency mismatch — is logged and skipped; the server keeps running without it. +- A sideloaded plugin whose name matches an official plugin overrides it, and the override is logged as a warning. + +See [Sideloading plugins](../DeveloperManuals/DeveloperSetup.md#sideloading-plugins) for how to build one. + ### ENABLE_SUBTASKS_BY_DEFAULT This environment variable is used to enable or disable the execution of subtasks.
