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>
Steven Allen committed
Dec 26, 2018 at 15:49 UTC
f706bc69ba5f27b845ba594b2ca28e63dd17529f
1 file changed
+75
-16
docs/plugins.md
+75
-16
@@ -3,47 +3,106 @@
3
Since 0.4.11 go-ipfs has an experimental plugin system that allows augmenting
4
the daemons functionality without recompiling.
5
6
-When an IPFS node is created, it will load plugins from the `$IPFS_PATH/plugins`
6
+When an IPFS node is started, it will load plugins from the `$IPFS_PATH/plugins`
7
directory (by default `~/.ipfs/plugins`).
8
9
-### Plugin types
9
+**Table of Contents**
10
+
11
+- [Plugin Types](#plugin-types)
12
+ - [IPLD](#ipld)
13
+ - [Datastore](#datastore)
14
+- [Available Plugins](#available-plugins)
15
+- [Installing Plugins](#installing-plugins)
16
+ - [External Plugin](#external-plugin)
17
+ - [In-tree](#in-tree)
18
+ - [Out-of-tree](#out-of-tree)
19
+ - [Preloaded Plugins](#preloaded-plugins)
20
+- [Creating A Plugin](#creating-a-plugin)
21
+
22
+## Plugin Types
23
+
24
+### IPLD
25
11
-#### IPLD
26
IPLD plugins add support for additional formats to `ipfs dag` and other IPLD
27
related commands.
28
15
-### Supported plugins
29
+### Datastore
30
+
31
+Datastore plugins add support for additional datastore backends.
32
+
33
+## Available Plugins
34
+
35
+| Name | Type | Built-In | Description |
36
+|---------------------------------------------------------------------------------|-----------|----------|------------------------------------------------|
37
+| [git](https://github.com/ipfs/go-ipfs/tree/master/plugin/plugins/git) | IPLD | x | An IPLD format for git objects. |
38
+| [badgerds](https://github.com/ipfs/go-ipfs/tree/master/plugin/plugins/badgerds) | Datastore | x | A high performance but experimental datastore. |
39
+| [flatfs](https://github.com/ipfs/go-ipfs/tree/master/plugin/plugins/flatfs) | Datastore | x | A stable filesystem-based datastore. |
40
+| [levelds](https://github.com/ipfs/go-ipfs/tree/master/plugin/plugins/levelds) | Datastore | x | A stable, flexible datastore backend. |
41
+
42
+* **Built-In** plugins are built into the go-ipfs binary and do not need to be
43
+ installed separately. At the moment, all *known* plugins are built-in as
44
+ they're mature and have proven themselves to be useful.
45
+
46
+## Installing Plugins
47
+
48
+External plugins must be installed in `$IPFS_PATH/plugins/` (usually
49
+`~/.ipfs/plugins/`). Alternatively, plugins can be preloaded and built into the
50
+go-ipfs binary itself.
51
+
52
+### External Plugin
53
17
-| Name | Type |
18
-|------|------|
19
-| git | IPLD |
54
+At the moment, this method is only supported on Linux and MacOS. Users of other
55
+operating systems should follow the instructions for preloaded plugins.
56
21
-#### Installation
57
+#### In-tree
58
23
-##### Linux
59
+To build plugins included in
60
+[plugin/plugins](https://github.com/ipfs/go-ipfs/tree/master/plugin/plugins),
61
+run:
62
25
-1. Build included plugins:
63
```bash
64
go-ipfs$ make build_plugins
65
go-ipfs$ ls plugin/plugins/*.so
66
```
67
31
-3. Copy desired plugins to `$IPFS_PATH/plugins`
68
+To install, copy desired plugins to `$IPFS_PATH/plugins`. For example:
69
+
70
```bash
71
go-ipfs$ mkdir -p ~/.ipfs/plugins/
72
go-ipfs$ cp plugin/plugins/git.so ~/.ipfs/plugins/
73
go-ipfs$ chmod +x ~/.ipfs/plugins/git.so # ensure plugin is executable
74
```
75
38
-4. Restart daemon if it is running
76
+Finally, restart daemon if it is running.
77
+
78
+#### Out-of-tree
79
+
80
+To build out-of-tree plugins, use the plugin's Makefile if provided. Otherwise,
81
+you can manually build the plugin by running:
82
+
83
+```bash
84
+myplugin$ go build -buildmode=plugin -i -o myplugin.so myplugin.go
85
+```
86
+
87
+Finally, as with in-tree plugins:
88
+
89
+1. Install the plugin in `$IPFS_PATH/plugins`.
90
+2. Mark the plugin as executable (`chmod +x $IPFS_PATH/plugins/myplugin.so`).
91
+3. Restart your IPFS daemon (if running).
92
40
-##### Other
93
+### Preloaded Plugins
94
42
-Go currently only supports plugins on Linux, for other platforms you will need
43
-to compile them into IPFS binary.
95
+To preload a go-ipfs plugin:
96
45
-1. Uncomment plugin entries in `plugin/loader/preload_list`
97
+1. Add the plugin to the preload list: `plugin/loader/preload_list`
98
2. Build ipfs
99
```bash
100
go-ipfs$ make build
101
```
102
+
103
+## Creating A Plugin
104
+
105
+To create your own out-of-tree plugin, use the [example
106
+plugin](https://github.com/ipfs/go-ipfs-example-plugin/) as a starting point.
107
+When you're ready, submit a PR adding it to the list of [available
108
+plugins](#available-plugins).