github.com/dahs81/otto@v0.2.1-0.20160126165905-6400716cf085/website/source/docs/plugins/basics.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Basics - Plugins"
     4  sidebar_current: "docs-plugins-basics"
     5  description: |-
     6    Basic guide to how plugins work in Otto.
     7  ---
     8  
     9  # Plugin Basics
    10  
    11  This page documents the basics of how the plugin system in Otto
    12  works, and how to setup a basic development environment for plugin development
    13  if you're writing an Otto plugin.
    14  
    15  If you're only looking for how to use plugins, see the
    16  [plugin installation page](/docs/plugins/install.html). If you're interested
    17  in developing plugins but haven't read the guide on installation, read
    18  that as well since it'll be important to understand how to install the
    19  plugin you create.
    20  
    21  ~> **Advanced topic!** Plugin development is a highly advanced
    22  topic in Otto, and is not required knowledge for day-to-day usage.
    23  If you don't plan on writing any plugins, we recommend not reading
    24  this section of the documentation.
    25  
    26  ## How it Works
    27  
    28  The plugin system for Otto is based on multi-process RPC.
    29  
    30  Otto executes these binaries in a certain way and uses Unix domain
    31  sockets or network sockets to perform RPC with the plugins.
    32  
    33  If you try to execute a plugin directly, an error will be shown:
    34  
    35  ```
    36  $ otto-app-ruby
    37  This binary is an Otto plugin. These are not meant to be
    38  executed directly. Please execute `otto`, which will load
    39  any plugins automatically.
    40  ```
    41  
    42  The code within the binaries must adhere to certain interfaces.
    43  The network communication and RPC is handled automatically by higher-level
    44  Otto libraries. The exact interface to implement is documented
    45  in its respective documentation section.
    46  
    47  Otto provides high-level libraries for making the creation of plugins
    48  simple and to ensure a common behavior.
    49  
    50  ## Developing a Plugin
    51  
    52  Developing a plugin is simple. The only knowledge necessary to write
    53  a plugin is basic command-line skills and basic knowledge of the
    54  [Go programming language](https://golang.org).
    55  
    56  -> **Note:** A common pitfall is not properly setting up a
    57  `$GOPATH`. This can lead to strange errors. You can read more about
    58  this [here](https://golang.org/doc/code.html) to familiarize
    59  yourself.
    60  
    61  Create a new Go project somewhere in your `$GOPATH`. If you're a
    62  GitHub user, we recommend creating the project in the directory
    63  `$GOPATH/src/github.com/USERNAME/otto-plugin-NAME`, where `USERNAME`
    64  is your GitHub username and `NAME` is the name of the plugin you're
    65  developing. This structure is what Go expects and simplifies things down
    66  the road.
    67  
    68  With the directory made, create a `main.go` file. This project will
    69  be a binary so the package is "main":
    70  
    71  ```
    72  package main
    73  
    74  import (
    75  	"github.com/hashicorp/otto/plugin"
    76  )
    77  
    78  func main() {
    79  	plugin.Serve(&plugin.ServeOpts{
    80  		AppFunc: AppFactory,
    81  	})
    82  }
    83  ```
    84  
    85  And that's basically it! You'll have to change the argument given to
    86  `plugin.Serve` to be your actual plugin, but that is the only change
    87  you'll have to make. See the GoDoc or the
    88  [example plugin](https://github.com/hashicorp/otto-example-app-plugin)
    89  for more details.
    90  
    91  Instead of going into extreme technical detail here, we've uploaded a
    92  really basic [example app plugin](https://github.com/hashicorp/otto-example-app-plugin).
    93  Please use that as a guide for developing your own plugin combined with
    94  the GoDoc of Otto itself.