diff --git a/website/source/docs/extend/command.html.markdown b/website/source/docs/extend/command.html.markdown new file mode 100644 index 000000000..b24a5d640 --- /dev/null +++ b/website/source/docs/extend/command.html.markdown @@ -0,0 +1,90 @@ +--- +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 `. +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). + +
+ Warning! This is an advanced topic. If you're new to Packer, + we recommend getting a bit more comfortable before you dive into writing + plugins. +
+ +## 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. + +
+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
+}
+
+ +### 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. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 8648da5ef..3d1a8e7ab 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -54,7 +54,7 @@
  • Packer Plugins
  • Developing Plugins
  • Custom Builder
  • -
  • Custom Command
  • +
  • Custom Command
  • Custom Provisioner