github.com/dahs81/otto@v0.2.1-0.20160126165905-6400716cf085/website/source/docs/plugins/app.html.md

---
layout: "docs"
page_title: "App Plugins - Appfile"
sidebar_current: "docs-plugins-app"
description: |-
  App plugins enable Otto to detect and work with new application types.
---

# App Plugins

Apps in Otto are responsible for development, build, and deploy of
an application. An example of an app type is [PHP](/docs/apps/php).

By writing an app plugin for Otto, you can add support to Otto for new
kinds of languages and frameworks. You can also override the defaults that
are built-in to Otto by replacing the built-in plugins.

The primary reasons to care about app plugins are:

  * You want to add support for a new language or framework.

  * You want to change the behavior of an existing plugin.

  * You want to support highly custom or legacy application types. This is
    very common in large organizations adopting Otto.

~> **Advanced topic!** Plugin development is a highly advanced topic in
   Otto, and is not required knowledge for day-to-day usage. If you don't plan
   on writing any plugins, we recommend not reading this section of the
   documentation.

If you're interested in provider development, then read on. The remainder of
this page will assume you're familiar with
[plugin basics](/docs/plugins/basics.html)
and that you already have a basic development environment setup.

## Low-Level Interface

The interface you must implement for app plugins is
[App](https://github.com/hashicorp/otto/blob/master/app/app.go).

The interface is extremely low level, giving you the ability to do almost
anything with Otto. However, we provide a lot of higher level helpers
that we recommend using to make your experience writing plugins a lot easier.
The core types also use these high-level helpers.

Rather than go into detail about what each function does for `App`,
we recommend looking at the
[builtin app types](https://github.com/hashicorp/otto/tree/master/builtin/app)
for real examples of how we use the `App` interface.

There is also a very basic
[example app type plugin](https://github.com/hashicorp/otto-example-app-plugin)
to show the general structure of things in the simplest possible form.

## Compilation

Otto has a distinct compilation step through `otto compile`. During this
step, your application type should inspect the environment and use that
to generate files (covered below) that will be used for the other commands
such as `Dev`, `Build`, etc.

In general, Otto tries to do _as much work as possible_ during the
compilation step. Try to compute all the values you need such that when
`Dev`, `Build`, etc. are called, they almost only have to execute an
underlying tool such as Vagrant or Packer to achieve their goals. You
should not be rendering any new configuration outside of the `Compile`
call.

To assist with compilation, we use the
[helper/compile](https://github.com/hashicorp/otto/tree/master/helper/compile)
helper library. This automatically handles file structure, templating,
[ScriptPack usage](/docs/plugins/scriptpack.html),
etc. More on this is covered below.

One thing to be very careful about: set a compilation version on the
`app.CompileResult` value (helper/compile gives you a way to do this). This
version should be used in subsequent function calls to expect a certain file
layout. This lets you change templates in your plugin over time but still
be able to work with previously compiled data.

Practically speaking, a user shouldn't update your plugin and have all
their existing environments break without an `otto compile`. Existing
environments should continue to work even if you changed the directory
structure.

## Bindata

A lot of Otto has static data that is templated onto the filesystem during
the compilation phase. You can see the files that Otto generates in the
`.otto` directory after running `otto compile` on a directory.

The templates for this static data are compiled directly into Otto plugins.
To do this, we use a tool called [go-bindata](https://github.com/jteeuwen/go-bindata).
To invoke `go-bindata`, we use `go generate` which is a command built-in
to Go that executes a command as part of the Go compilation process.
You can see an example of
[how we do this for Ruby](https://github.com/hashicorp/otto/blob/c70a67f85beaa3db353052ee82b8dfc149ff2753/builtin/app/ruby/app.go#L18).

This will create an autogenerated `bindata.go` file. We gitignore this
from the main Otto repository. But you can view it by running `make` within
the Otto directory which will generate all the files for the project.

That bindata is then used in combination with `helper/bindata` which
is covered below in the templating section in order to write the files to
disk. You can see an
[example of that for Ruby here](https://github.com/hashicorp/otto/blob/c70a67f85beaa3db353052ee82b8dfc149ff2753/builtin/app/ruby/app.go#L35).

## Templating

In addition to compiling the static data directly into the final binary,
Otto does a lot of templating. It uses templates to generate the proper output
during `otto compile`.

All of this templating is handled by `helper/bindata` automatically: any
rendered static asset will be processed by the templating engine if the
static asset ends in ".tpl". The final filename removes the ".tpl" extension.

Again, you can see examples of templates in the `data` directory of
the [built-in Ruby application type](https://github.com/hashicorp/otto/tree/master/builtin/app/ruby).

You can use `helper/bindata` directly, which we do in some places, or more
likely you'll be using the `helper/compile` helper to assist with compilation
which automatically processes your data directory for templates.

## ScriptPacks

Otto encourages the use of [ScriptPacks](/docs/plugins/scriptpack.html) for
any logic that isn't running directly on the user's machine, such as in
a development or deployment environmet.

ScriptPacks are pure standalone shell libraries. By putting complex logic
within ScriptPacks, we encourage unit testing and reusability for more stable
app types.

ScriptPacks are integrated directly within the `helper/compile` interface
for easy use. For example, directly from the Ruby application type, within
the compilation options for `helper/compile`:

    ScriptPacks: []*scriptpack.ScriptPack{
        &stdSP.ScriptPack,
        &rubySP.ScriptPack,
    },

This tells the compilation helper to automatically compile in the Ruby
and stdlib ScriptPacks (referenced using their Go package names). Then,
within the shell scripts used by the app type, you can see ScriptPack usage:

    . /otto/scriptpacks/STDLIB/main.sh
    . /otto/scriptpacks/RUBY/main.sh
    otto_init

    otto_output "Installing Ruby ${RUBY_VERSION}. This can take a few minutes..."
    ruby_install_prepare
    ruby_install ruby-${RUBY_VERSION}

The application type then uses the high-level functions from the ScriptPack
directly, which are each well tested on their own.