github.com/askholme/packer@v0.7.2-0.20140924152349-70d9566a6852/website/source/docs/extend/command.html.markdown (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Custom Command Development"
     4  ---
     5  
     6  # Custom Command Development
     7  
     8  Commands are the components of Packer that add functionality to the
     9  `packer` application. Packer comes with a set of commands out of the
    10  box, such as `build`. Commands are invoked as `packer <COMMAND>`.
    11  Custom commands allow you to add new commands to Packer to perhaps
    12  perform new functionality.
    13  
    14  Prior to reading this page, it is assumed you have read the page on
    15  [plugin development basics](/docs/extend/developing-plugins.html).
    16  
    17  Command plugins implement the `packer.Command` interface and are served
    18  using the `plugin.ServeCommand` function. Commands actually have no control
    19  over what keyword invokes the command with the `packer` binary. The keyword
    20  to invoke the command depends on how the plugin is installed and configured
    21  in the core Packer configuration.
    22  
    23  <div class="alert alert-block">
    24    <strong>Warning!</strong> This is an advanced topic. If you're new to Packer,
    25    we recommend getting a bit more comfortable before you dive into writing
    26    plugins.
    27  </div>
    28  
    29  ## The Interface
    30  
    31  The interface that must be implemented for a command is the `packer.Command`
    32  interface. It is reproduced below for easy reference. The actual interface
    33  in the source code contains some basic documentation as well explaining
    34  what each method should do.
    35  
    36  <pre class="prettyprint">
    37  type Command interface {
    38  	Help() string
    39  	Run(env Environment, args []string) int
    40  	Synopsis() string
    41  }
    42  </pre>
    43  
    44  ### The "Help" Method
    45  
    46  The `Help` method returns long-form help. This help is most commonly
    47  shown when a command is invoked with the `--help` or `-h` option.
    48  The help should document all the available command line flags, purpose
    49  of the command, etc.
    50  
    51  Packer commands generally follow the following format for help, but
    52  it is not required. You're allowed to make the help look like anything
    53  you please.
    54  
    55  ```
    56  Usage: packer COMMAND [options] ARGS...
    57  
    58    Brief one or two sentence about the function of the command.
    59  
    60  Options:
    61  
    62    -foo=bar                  A description of the flag.
    63    -another                  Another description.
    64  ```
    65  
    66  ### The "Run" Method
    67  
    68  `Run` is what is called when the command is actually invoked. It is given
    69  the `packer.Environment`, which has access to almost all components of
    70  the current Packer run, such as UI, builders, other plugins, etc. In addition
    71  to the environment, the remaining command line args are given. These command
    72  line args have already been stripped of the command name, so they can be
    73  passed directly into something like the standard Go `flag` package for
    74  command-line flag parsing.
    75  
    76  The return value of `Run` is the exit status for the command. If everything
    77  ran successfully, this should be 0. If any errors occured, it should be any
    78  positive integer.
    79  
    80  ### The "Synopsis" Method
    81  
    82  The `Synopsis` method should return a short single-line description
    83  of what the command does. This is used when `packer` is invoked on its own
    84  in order to show a brief summary of the commands that Packer supports.
    85  
    86  The synopsis should be no longer than around 50 characters, since it is
    87  already appearing on a line with other text.