From 3167d5d52cccef2f3e537807904bd80b6934ec62 Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Wed, 20 Feb 2019 11:47:39 +0100 Subject: [PATCH] document post-processor execpt more --- website/source/docs/commands/build.html.md | 11 ++--- website/source/docs/commands/validate.html.md | 9 ++-- .../docs/templates/post-processors.html.md | 42 ++++++++++++++----- 3 files changed, 42 insertions(+), 20 deletions(-) diff --git a/website/source/docs/commands/build.html.md b/website/source/docs/commands/build.html.md index 61ee8c3a9..605dcef7f 100644 --- a/website/source/docs/commands/build.html.md +++ b/website/source/docs/commands/build.html.md @@ -27,11 +27,12 @@ artifacts that are created will be outputted at the end of the build. This will allow the user to inspect state and so on. - `-except=foo,bar,baz` - Run all the builds and post-processors except those - with the given comma-separated names. Build and post-processor names by - default are their type, unless a specific `name` attribute is specified - within the configuration. Any post-processor following a skipped - post-processor will not run. Because post-processors can be nested in - arrays a differ post-processor chain can still run. + with the given comma-separated names. Build names by default are their + type, unless a specific `name` attribute is specified within the + configuration. Any post-processor following a skipped post-processor will + not run. Because post-processors can be nested in arrays a different + post-processor chain can still run. A post-processor with an empty name + will be ignored. - `-force` - Forces a builder to run when artifacts from a previous build prevent a build from running. The exact behavior of a forced build is left diff --git a/website/source/docs/commands/validate.html.md b/website/source/docs/commands/validate.html.md index 6f1a54c82..fd7b4f144 100644 --- a/website/source/docs/commands/validate.html.md +++ b/website/source/docs/commands/validate.html.md @@ -33,10 +33,11 @@ Errors validating build 'vmware'. 1 error(s) occurred: - `-syntax-only` - Only the syntax of the template is checked. The configuration is not validated. -- `-except=foo,bar,baz` - Builds all the builds except those with the given - comma-separated names. Build names by default are the names of their - builders, unless a specific `name` attribute is specified within the - configuration. +- `-except=foo,bar,baz` - Builds all the builds and post-processors except + those with the given comma-separated names. Build names by default are the + names of their builders, unless a specific `name` attribute is specified + within the configuration. A post-processor with an empty name will be + ignored. - `-only=foo,bar,baz` - Only build the builds with the given comma-separated names. Build names by default are the names of their builders, unless a diff --git a/website/source/docs/templates/post-processors.html.md b/website/source/docs/templates/post-processors.html.md index b656dd72a..cd4ce1fd8 100644 --- a/website/source/docs/templates/post-processors.html.md +++ b/website/source/docs/templates/post-processors.html.md @@ -38,7 +38,8 @@ defined builders and send it through the post-processors. This means that if you have one post-processor defined and two builders defined in a template, the post-processor will run twice (once for each builder), by default. There are ways, which will be covered later, to control what builders post-processors -apply to, if you wish. +apply to, if you wish. It is also possible to prevent a post-processor from +running. ## Post-Processor Definition @@ -136,21 +137,40 @@ post-processor requested that the input be kept, so it will keep it around. ## Run on Specific Builds -You can use the `only` or `except` configurations to run a post-processor only -with specific builds. These two configurations do what you expect: `only` will -only run the post-processor on the specified builds and `except` will run the -post-processor on anything other than the specified builds. +You can use the `only` or `except` fields to run a post-processor only with +specific builds. These two fields do what you expect: `only` will only run the +post-processor on the specified builds and `except` will run the post-processor +on anything other than the specified builds. A sequence of post-processors will +execute until a skipped post-processor. An example of `only` being used is shown below, but the usage of `except` is effectively the same. `only` and `except` can only be specified on "detailed" -configurations. If you have a sequence of post-processors to run, `only` and -`except` will only affect that single post-processor in the sequence. +fields. If you have a sequence of post-processors to run, `only` and `except` +will affect that post-processor and stop the sequence. + +The `-except` option can specifically skip a named post processor. ``` json -{ - "type": "vagrant", - "only": ["virtualbox-iso"] -} +[ + { + // can also be skipped when running `packer build -except vbox` + "name": "vbox", + "type": "vagrant", + "only": ["virtualbox-iso"] + }, + { + "type": "compress" // will only be executed when vbox is + } +], +[ + "compress", // will run even if vbox is skipped, from the same start as vbox. + { + "type": "upload", + "endpoint": "http://example.com" + } + // this list of post processors will execute + // using build, not another post-processor. +] ``` The values within `only` or `except` are *build names*, not builder types. If