From 06cf91270c80a6dd00f5dd5646219b2f892427b9 Mon Sep 17 00:00:00 2001 From: Aaron Fiore Date: Mon, 23 Feb 2026 15:44:16 -0800 Subject: [PATCH] markdown: plugins: update documentation --- markdown/How-do-I-use-it.md | 65 ++++++++++++++++++++++++++++++------- 1 file changed, 53 insertions(+), 12 deletions(-) diff --git a/markdown/How-do-I-use-it.md b/markdown/How-do-I-use-it.md index 2af4923..7f59719 100644 --- a/markdown/How-do-I-use-it.md +++ b/markdown/How-do-I-use-it.md @@ -170,24 +170,65 @@ See the container `times help` command for details. ### Plugins -Plugins allow you to use docker-finance public APIs, libraries and environment (client and/or container) to meet your unique needs. These plugins are categorical; as in, there are client-side ("custom") plugins and repository ("repo") plugins. Additionally, there are subcategories such as `docker`, `finance` and `root` (respective to their modules). +Plugins (pluggables) allow you to leverage `dfi` client/container APIs, libraries and environments to meet your unique needs. -Client-side custom plugins allow you to drop-in any code that you write and keep them locally. Repository plugins are plugins that remain within the repository and will require a pull request for any changes to be made. Client-side custom plugins can be used for either client or container modules (see directory layout). +For more information and examples, see some of the various existing plugins (pluggables) and respective help usage, i.e.; -Upon client `gen`, a client-side directory layout is generated. This layout consists of: - - `${DOCKER_FINANCE_CLIENT_PLUGINS}/client/docker` - - Custom plugins that function only client-side (`lib_docker`) - - `${DOCKER_FINANCE_CLIENT_PLUGINS}/container/{finance,root}` - - Custom plugins that function only container-side (`lib_finance`, `root`) + - Client-side (host): `dfi plugins help` + - Container-side: `dfi plugins help` + - Within `root` interpreter: `dfi::help()` -**WARNING: don't change the parent client-side directory layout** (although, you can add subdirectories): - - e.g., `${DOCKER_FINANCE_CLIENT_PLUGINS}/container/finance/my_experimental_plugins/{file1.ext,file2.ext}` +#### Plugins: Layout -This client-side "custom" layout somewhat mirrors the repository's plugins layout (see [`client/plugins`](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/plugins) and [`container/plugins`](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/container/plugins)). +Plugins are categorical: -For more information, see the example plugins and help usage of each module, e.g.; `plugins help` or `help()`. + 1. Repository (`repo`) plugins + - These plugins remain within the repository and will require a pull request for any changes to be made to them. -> Note: for custom plugins within directory `docker` and `finance` that utilize the shell, any language can be used so long as the file is executable, reads the shell environment and can initiailize their respective libraries (`lib_docker`, `lib_finance`). + 2. End-user (`custom`) plugins + - These plugins remain on your client (host) and are bind-mounted to your container; allowing you to drop-in any code that you write while keeping them local and private. + +Within these categories are subcategories where plugins exist either client-side (host) or container-side; meaning, they rely upon (or operate within) their respective client/container APIs/libraries/environments: + + 1. `client` | *Tends to operate only client-side (host) but can also utilize a container* + - `docker` | *Operates **only** from the `bash` shell* + * Called client-side with `dfi plugins` + * Can be any language so long as: + - The file is executable by the shell + - The plugin reads the shell environment + - The plugin initializes the respective library (`lib_docker`) + 2. `container` | *Operates **only** within the container* + - `finance` | *Operates **only** from the `bash` shell* + * Called container-side with `dfi plugins` + * Can be any language so long as: + - The file is executable by the shell + - The plugin reads the shell environment + - The plugin initializes the respective library (`lib_finance`) + - `root` | *Operates **only** within the `root` interpreter* + * Called container-side by either two different ways: + - Within a running `dfi root` instance: + * `dfi::plugin::load("repo/a_repo_plugin/plugin.cc")` + * `dfi::plugin::load("custom/my_custom_plugin/plugin.cc")` + - With the `dfi root plugins` command + * Use tab completion to see available plugins (pluggables) + * Can only be languages supported by the interpreter (C/C++) + +To mirror these categories, a client-side `custom` plugin directory layout is generated upon `dfi gen`. This layout consists of: + + 1. `${DOCKER_FINANCE_CLIENT_PLUGINS}/client/docker` + - This path remains client-side only (not bind-mounted) + - This layout mirrors `repo` plugins [`client/plugins`](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/client/plugins) + 2. `${DOCKER_FINANCE_CLIENT_PLUGINS}/container/{finance,root}` + - The container directory is bind-mounted to `DOCKER_FINANCE_CONTAINER_PLUGINS` + - This layout mirrors `repo` plugins [`container/plugins`](https://gitea.evergreencrypto.co/EvergreenCrypto/docker-finance/src/branch/master/container/plugins) + +**WARNING: don't change the above expected layout!** However, you can add subdirectories, e.g.; + + - `${DOCKER_FINANCE_CLIENT_PLUGINS}/client/docker/my_docker_plugins/plugin.bash` + - `${DOCKER_FINANCE_CLIENT_PLUGINS}/container/finance/my_finance_plugins/plugin.bash` + - `${DOCKER_FINANCE_CLIENT_PLUGINS}/container/root/my_plugin/my_plugin.cc` + * NOTE: `root` pluggable auto-(un)loading requires a parent directory as the callable namespace (and more) + - See docs for details: `dfi dev-tools/${USER}:default doxygen gen` ### Caveats & Oddities