Commit ccc6ecb3 authored by Mitchell Hashimoto's avatar Mitchell Hashimoto

website: custom commands

parent f623dad8
---
layout: "docs"
---
# Custom Command Development
Commands are the components of Packer that add functionality to the
`packer` application. Packer comes with a set of commands out of the
box, such as `build`. Commands are invoked as `packer <COMMAND>`.
Custom commands allow you to add new commands to Packer to perhaps
perform new functionality.
Prior to reading this page, it is assumed you have read the page on
[plugin development basics](/docs/extend/developing-plugins.html).
<div class="alert alert-block">
<strong>Warning!</strong> This is an advanced topic. If you're new to Packer,
we recommend getting a bit more comfortable before you dive into writing
plugins.
</div>
## The Interface
The interface that must be implemented for a command is the `packer.Command`
interface. It is reproduced below for easy reference. The reference below
also contains some basic documentatin of what each of the methods are
supposed to do.
<pre class="prettyprint">
type Command interface {
// Help should return long-form help text that includes the command-line
// usage, a brief few sentences explaining the function of the command,
// and the complete list of flags the command accepts.
Help() string
// Run should run the actual command with the given environmet and
// command-line arguments. It should return the exit status when it is
// finished.
Run(env Environment, args []string) int
// Synopsis should return a one-line, short synopsis of the command.
// This should be less than 50 characters ideally.
Synopsis() string
}
</pre>
### The "Help" Method
The `Help` method returns long-form help. This help is most commonly
shown when a command is invoked with the `--help` or `-h` option.
The help should document all the available command line flags, purpose
of the command, etc.
Packer commands generally follow the following format for help, but
it is not required. You're allowed to make the help look like anything
you please.
```
Usage: packer COMMAND ARGS...
Brief one or two sentence about the function of the command.
Options:
-foo=bar A description of the flag.
-another Another description.
```
### The "Run" Method
`Run` is what is called when the command is actually invoked. It is given
the `packer.Environment`, which has access to almost all components of
the current Packer run, such as UI, builders, other plugins, etc. In addition
to the environment, the remaining command line args are given. These command
line args have already been stripped of the command name, so they can be
passed directly into something like the standard Go `flag` package for
command-line flag parsing.
The return value of `Run` is the exit status for the command. If everything
ran successfully, this should be 0. If any errors occured, it should be any
positive integer.
### The "Synopsis" Method
The `Synopsis` method should return a short single-line description
of what the command does. This is used when `packer` is invoked on its own
in order to show a brief summary of the commands that Packer supports.
The synopsis should be no longer than around 50 characters, since it is
already appearing on a line with other text.
...@@ -54,7 +54,7 @@ ...@@ -54,7 +54,7 @@
<li><a href="/docs/extend/plugins.html">Packer Plugins</a></li> <li><a href="/docs/extend/plugins.html">Packer Plugins</a></li>
<li><a href="/docs/extend/developing-plugins.html">Developing Plugins</a></li> <li><a href="/docs/extend/developing-plugins.html">Developing Plugins</a></li>
<li><a href="/docs/extend/builder.html">Custom Builder</a></li> <li><a href="/docs/extend/builder.html">Custom Builder</a></li>
<li><a href="#">Custom Command</a></li> <li><a href="/docs/extend/command.html">Custom Command</a></li>
<li><a href="#">Custom Provisioner</a></li> <li><a href="#">Custom Provisioner</a></li>
</ul> </ul>
</div><!--/.well --> </div><!--/.well -->
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment