Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: flesh out plugin documentation #5876

Merged
merged 2 commits into from
Dec 27, 2018
Merged

docs: flesh out plugin documentation #5876

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f706bc6
docs: flesh out plugin documentation
Stebalien Dec 26, 2018
02a1fea
docs: address CR on plugin documentation
Stebalien Dec 27, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 75 additions & 16 deletions docs/plugins.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Datastore plugins add support for additional datastore backends.

## Available Plugins

| 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sound more like the deleted In-tree tag. Built-in gives me the impression they are already in the binary and do not need to be loaded at all.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They are. I've tried to clarify that.

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This paragraph seems to be part of the subsequent External Plugin section.

`~/.ipfs/plugins/`). Alternatively, plugins can be preloaded and built into the
go-ipfs binary itself.

### External Plugin

| Name | Type |
|------|------|
| git | IPLD |
At the moment, this method is only supported on Linux and MacOS. Users of other
operating systems should follow the instructions for preloaded plugins.

#### Installation
#### In-tree

##### Linux
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.

#### Out-of-tree

To build out-of-tree plugins, use the plugin's Makefile if provided. Otherwise,
you can manually build the plugin by running:

```bash
myplugin$ go build -buildmode=plugin -i -o myplugin.so myplugin.go
```

Finally, as with in-tree plugins:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: this seems pretty much the same as the previous install instructions (mkdir, copy, chmod, restart), maybe we can just point there if there is no substantial difference.


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).

##### Other
### Preloaded Plugins
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does "preloaded" mean in this context? (in contrast with the normal plugin, is it included in the binary?) What's the advantage with respect to just dropping it into the plugins dir?


Go currently only supports plugins on Linux, for other platforms you will need
to compile them into IPFS binary.
To preload a go-ipfs plugin:

1. Uncomment plugin entries in `plugin/loader/preload_list`
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).