From f706bc69ba5f27b845ba594b2ca28e63dd17529f Mon Sep 17 00:00:00 2001
From: Steven Allen <steven@stebalien.com>
Date: Wed, 26 Dec 2018 15:49:52 -0800
Subject: [PATCH] docs: flesh out plugin documentation

* Flesh out build documentation.
* Add datastore plugins to plugin list.
* Link to example plugin.
* Add a TOC.

License: MIT
Signed-off-by: Steven Allen <steven@stebalien.com>
---
 docs/plugins.md | 91 ++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 75 insertions(+), 16 deletions(-)

diff --git a/docs/plugins.md b/docs/plugins.md
index bb049f0d1..cdaab663a 100644
--- a/docs/plugins.md
+++ b/docs/plugins.md
@@ -3,47 +3,106 @@
 Since 0.4.11 go-ipfs has an experimental plugin system that allows augmenting
 the daemons functionality without recompiling.
 
-When an IPFS node is created, it will load plugins from the `$IPFS_PATH/plugins`
+When an IPFS node is started, it will load plugins from the `$IPFS_PATH/plugins`
 directory (by default `~/.ipfs/plugins`).
 
-### Plugin types
+**Table of Contents**
+
+- [Plugin Types](#plugin-types)
+    - [IPLD](#ipld)
+    - [Datastore](#datastore)
+- [Available Plugins](#available-plugins)
+- [Installing Plugins](#installing-plugins)
+    - [External Plugin](#external-plugin)
+        - [In-tree](#in-tree)
+        - [Out-of-tree](#out-of-tree)
+    - [Preloaded Plugins](#preloaded-plugins)
+- [Creating A Plugin](#creating-a-plugin)
+
+## Plugin Types
+
+### IPLD
 
-#### IPLD
 IPLD plugins add support for additional formats to `ipfs dag` and other IPLD
 related commands.
 
-### Supported plugins
+### Datastore
 
-| Name | Type |
-|------|------|
-|  git | IPLD |
+Datastore plugins add support for additional datastore backends.
 
-#### Installation
+## Available Plugins
 
-##### Linux
+| Name                                                                            | Type      | Built-In | Description                                    |
+|---------------------------------------------------------------------------------|-----------|----------|------------------------------------------------|
+| [git](https://github.com/ipfs/go-ipfs/tree/master/plugin/plugins/git)           | IPLD      | x        | An IPLD format for git objects.                |
+| [badgerds](https://github.com/ipfs/go-ipfs/tree/master/plugin/plugins/badgerds) | Datastore | x        | A high performance but experimental datastore. |
+| [flatfs](https://github.com/ipfs/go-ipfs/tree/master/plugin/plugins/flatfs)     | Datastore | x        | A stable filesystem-based datastore.           |
+| [levelds](https://github.com/ipfs/go-ipfs/tree/master/plugin/plugins/levelds)   | Datastore | x        | A stable, flexible datastore backend.          |
+
+* **Built-In** plugins are built into the go-ipfs binary and do not need to be
+  installed separately. At the moment, all *known* plugins are built-in as
+  they're mature and have proven themselves to be useful.
+
+## Installing Plugins
+
+External plugins must be installed in `$IPFS_PATH/plugins/` (usually
+`~/.ipfs/plugins/`). Alternatively, plugins can be preloaded and built into the
+go-ipfs binary itself.
+
+### External Plugin
+
+At the moment, this method is only supported on Linux and MacOS. Users of other
+operating systems should follow the instructions for preloaded plugins.
+
+#### In-tree
+
+To build plugins included in
+[plugin/plugins](https://github.com/ipfs/go-ipfs/tree/master/plugin/plugins),
+run:
 
-1. Build included plugins:
 ```bash
 go-ipfs$ make build_plugins
 go-ipfs$ ls plugin/plugins/*.so
 ```
 
-3. Copy desired plugins to `$IPFS_PATH/plugins`
+To install, copy desired plugins to `$IPFS_PATH/plugins`. For example:
+
 ```bash
 go-ipfs$ mkdir -p ~/.ipfs/plugins/
 go-ipfs$ cp plugin/plugins/git.so ~/.ipfs/plugins/
 go-ipfs$ chmod +x ~/.ipfs/plugins/git.so # ensure plugin is executable
 ```
 
-4. Restart daemon if it is running
+Finally, restart daemon if it is running.
 
-##### Other
+#### Out-of-tree
 
-Go currently only supports plugins on Linux, for other platforms you will need
-to compile them into IPFS binary.
+To build out-of-tree plugins, use the plugin's Makefile if provided. Otherwise,
+you can manually build the plugin by running:
 
-1. Uncomment plugin entries in `plugin/loader/preload_list`
+```bash
+myplugin$ go build -buildmode=plugin -i -o myplugin.so myplugin.go
+```
+
+Finally, as with in-tree plugins:
+
+1. Install the plugin in `$IPFS_PATH/plugins`.
+2. Mark the plugin as executable (`chmod +x $IPFS_PATH/plugins/myplugin.so`).
+3. Restart your IPFS daemon (if running).
+
+### Preloaded Plugins
+
+To preload a go-ipfs plugin:
+
+1. Add the plugin to the preload list: `plugin/loader/preload_list`
 2. Build ipfs
 ```bash
 go-ipfs$ make build
 ```
+
+## Creating A Plugin
+
+To create your own out-of-tree plugin, use the [example
+plugin](https://github.com/ipfs/go-ipfs-example-plugin/) as a starting point.
+When you're ready, submit a PR adding it to the list of [available
+plugins](#available-plugins).