Merge pull request #13 into master

01c45cf assets/markdown: plugins: add bitcoin documentation (Aaron Fiore)
06cf912 markdown: plugins: update documentation (Aaron Fiore)
f3952ba markdown: move plugins documentation (Aaron Fiore)

markdown/How-do-I-contribute.md

@@ -51,24 +51,7 @@ When developing non-code documentation, please work with the [dfi-docs](https://
 
 #### 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).
-
-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).
-
-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`)
-
-**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}`
-
-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)).
-
-For more information, see the example plugins and help usage of each module, e.g.; `plugins help` or `help()`.
-
-> 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`).
+Primary plugin documentation can be found [here](How-do-I-use-it.md#plugins). Technically speaking, you can write custom plugins and never need to merge with the repository but if you feel that the plugin(s) would be beneficial to the public, add testcases and send everything with a [pull request](#pull-request).
 
 #### Pull Request
 

markdown/How-do-I-use-it.md

@@ -21,6 +21,7 @@
 - **[How do I use it?](#how-do-i-use-it)**
   * [Mostly-Unified CLI](#mostly-unified-cli)
   * [Flow Layout](#flow-layout)
+  * [Plugins](#plugins)
   * [Caveats & Oddities](#caveats--oddities)
 
 ## How do I use it?
@@ -167,6 +168,154 @@ All `times` related files will reside in `${DOCKER_FINANCE_CONTAINER_FLOW}/times
 
 See the container `times help` command for details.
 
+### Plugins
+
+Plugins (pluggables) allow you to leverage `dfi` client/container APIs, libraries and environments to meet your unique needs.
+
+Checkout this two-part client/container set of [Bitcoin plugins](#plugins-bitcoin) to see how all APIs/libraries/environments can work together in unison.
+
+For more information and other examples, see some of the various existing plugins (pluggables) and respective help usage, i.e.;
+
+  - Client-side (host): `dfi <platform/user:tag> plugins help`
+  - Container-side: `dfi <profile/subprofile> plugins help`
+  - Within `root` interpreter: `dfi::help()`
+
+#### Plugins: Layout
+
+Plugins are categorical:
+
+  1. Repository (`repo`) plugins
+     - These plugins remain within the repository and will require a pull request for any changes to be made to them.
+
+  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 <platform/user:tag> 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 <profile/subprofile> 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 <profile/subprofile> root` instance:
+           * `dfi::plugin::load("repo/a_repo_plugin/plugin.cc")`
+           * `dfi::plugin::load("custom/my_custom_plugin/plugin.cc")`
+         - With the `dfi <profile/subprofile> 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 <platform/user:tag> 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`
+
+#### Plugins: Bitcoin
+
+`dfi`'s bitcoin plugin is a two-part client/container set of plugins that gives you direct access to bitcoin's libbitcoinkernel (and related headers/symbols).
+
+The following demo assumes that you'll be using a fresh setup and that you've at least satisfied the required dependencies in [Installation](How-do-I-get-started.md#installation) (Docker Engine/Compose/Buildx, Bash, Git).
+
+If you're a first-time user and/or developer who simply wants a quickstart, run the following before proceeding:
+
+```bash
+git clone --depth=1 https://gitea.com/EvergreenCrypto/docker-finance docker-finance/repo
+./docker-finance/repo/client/install.bash && source ~/.bashrc
+dfi archlinux/${USER}:default gen all=all profile=testprofile/testuser confirm=no dev=on
+```
+
+##### Plugins: Bitcoin: Client
+
+Here, we prepare client-side dependencies and build everything needed for the container-side plugin:
+
+<video src="../assets/examples/webm/client-plugins-bitcoin.webm" controls></video>
+
+Shell 1:
+
+```bash
+# NOTE: editing will only be required once (unless you `gen type=build` in the future)
+dfi archlinux/${USER}:default edit type=build
+dfi archlinux/${USER}:default build type=default
+```
+
+Shell 2:
+
+```bash
+dfi archlinux/${USER}:default up
+```
+
+Shell 1:
+
+```bash
+dfi archlinux/${USER}:default plugins repo/bitcoin.bash get
+dfi archlinux/${USER}:default plugins repo/bitcoin.bash build
+```
+
+##### Plugins: Bitcoin: Container
+
+Here, we see the multiple ways the container-side plugin can be loaded and also test its functionality:
+
+<video src="../assets/examples/webm/container-root-plugins-bitcoin_cli.webm" controls></video>
+
+Shell 2 (or open a new shell into container, as seen in the demo):
+
+```bash
+dfi testprofile/testuser root
+```
+
+Within `root` interpreter:
+
+```cpp
+// NOTE:
+//   - The demo shows `btck` tab completion (which can't be put here)
+//   - semicolons are not needed, since the following is executed per line
+GetRandHash()
+dfi::plugin::load("repo/bitcoin/bitcoin.cc")
+GetRandHash()
+dfi::macro::load("repo/test/unit.C", "Random*")
+.quit
+```
+
+Shell 2:
+
+```bash
+BENCHMARK_FILTER="^Random" dfi testprofile/testuser root plugins/repo/bitcoin/bitcoin.cc 'dfi::macro::load(\"repo/test/benchmark.C\"); dfi::common::exit(0);'
+dfi testprofile/testuser root plugins/repo/bitcoin/bitcoin.cc 'dfi::macro::load(\"repo/web/server.C\")'
+```
+
+##### Plugins: Bitcoin: Web browser
+
+Here, we see a real-world visualization of what the container-side plugin can produce. In this example, with the plugin previously loaded (as seen above), we sample bitcoin's RNG:
+
+<video src="../assets/examples/webm/container-root-plugins-bitcoin_web.webm" controls></video>
+
+- Open browser to `http://127.0.0.1:8080`
+  * Default port can be changed with client-side command: `dfi archlinux/${USER}:default edit type=env`
+- Click `rng_sample` -> Enter sample amount
+- Click `reload`
+
 ### Caveats & Oddities
 
 #### Caveats & Oddities: Flow