From 1be337b3834a6fd70c3ef4e96d9e4860cba9816c Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Mon, 29 Apr 2019 13:06:09 +0200 Subject: [PATCH 1/3] update docs for definig Builders and PostProcessors --- packer/post_processor.go | 11 +++-- .../docs/extending/custom-builders.html.md | 43 ++++++------------- .../extending/custom-post-processors.html.md | 13 ++++-- 3 files changed, 28 insertions(+), 39 deletions(-) diff --git a/packer/post_processor.go b/packer/post_processor.go index 3be6f3599..c9b07e037 100644 --- a/packer/post_processor.go +++ b/packer/post_processor.go @@ -14,12 +14,11 @@ type PostProcessor interface { Configure(...interface{}) error // PostProcess takes a previously created Artifact and produces another - // Artifact. If an error occurs, it should return that error. If `keep` - // is true, then the previous artifact defaults to being kept if - // user has not given a value to keep_input_artifact. If forceOverride - // is true, then any user input for keep_input_artifact is ignored and - // the artifact is either kept or discarded according to the value set in - // `keep`. + // Artifact. If an error occurs, it should return that error. If `keep` is + // true, then the previous artifact defaults to being kept if user has not + // given a value to keep_input_artifact. If forceOverride is true, then any + // user input for keep_input_artifact is ignored and the artifact is either + // kept or discarded according to the value set in `keep`. // PostProcess is cancellable using context PostProcess(context.Context, Ui, Artifact) (a Artifact, keep bool, forceOverride bool, err error) } diff --git a/website/source/docs/extending/custom-builders.html.md b/website/source/docs/extending/custom-builders.html.md index 302401533..63cfdb40b 100644 --- a/website/source/docs/extending/custom-builders.html.md +++ b/website/source/docs/extending/custom-builders.html.md @@ -32,8 +32,7 @@ method should do. ``` go type Builder interface { Prepare(...interface{}) error - Run(ui Ui, hook Hook, cache Cache) (Artifact, error) - Cancel() + Run(context.Context, ui Ui, hook Hook) (Artifact, error) } ``` @@ -94,11 +93,19 @@ artifact section below. If something goes wrong during the build, an error can be returned, as well. Note that it is perfectly fine to produce no artifact and no error, although this is rare. -### The "Cancel" Method +### Cancellation +The `Run` method is often run in parallel. -The `Run` method is often run in parallel. The `Cancel` method can be called at -any time and requests cancellation of any builder run in progress. This method -should block until the run actually stops. +#### With the "Cancel" Method ( up until packer 1.3 ) + +The `Cancel` method can be called at any time and requests cancellation of any +builder run in progress. This method should block until the run actually stops. +Not that the Cancel method will no longer be called since packer 1.4.0. + +#### Context cancellation ( from packer 1.4 ) + +The `<-ctx.Done()` can unblock at any time and signifies request for +cancellation of any builder run in progress. Cancels are most commonly triggered by external interrupts, such as the user pressing `Ctrl-C`. Packer will only exit once all the builders clean up, so it @@ -135,7 +142,7 @@ hook, making sure the communicator is not nil, since this is required for provisioners. An example of calling the hook is shown below: ``` go -hook.Run(packer.HookProvision, ui, comm, nil) +hook.Run(context.Context, packer.HookProvision, ui, comm, nil) ``` At this point, Packer will run the provisioners and no additional work is @@ -145,25 +152,3 @@ necessary. and will likely change in a future version. They aren't fully "baked" yet, so they aren't documented here other than to tell you how to hook in provisioners. -## Caching Files - -It is common for some builders to deal with very large files, or files that -take a long time to generate. For example, the VMware builder has the -capability to download the operating system ISO from the internet. This is -timely process, so it would be convenient to cache the file. This sort of -caching is a core part of Packer that is exposed to builders. - -The cache interface is `packer.Cache`. It behaves much like a Go -[RWMutex](https://golang.org/pkg/sync/#RWMutex). The builder requests a "lock" -on certain cache keys, and is given exclusive access to that key for the -duration of the lock. This locking mechanism allows multiple builders to share -cache data even though they're running in parallel. - -For example, both the VMware and VirtualBox builders support downloading an -operating system ISO from the internet. Most of the time, this ISO is -identical. The locking mechanisms of the cache allow one of the builders to -download it only once, but allow both builders to share the downloaded file. - -The [documentation for -packer.Cache](https://github.com/hashicorp/packer/blob/master/packer/cache.go) -is very detailed in how it works. diff --git a/website/source/docs/extending/custom-post-processors.html.md b/website/source/docs/extending/custom-post-processors.html.md index 0ec5f71a5..8d368aa26 100644 --- a/website/source/docs/extending/custom-post-processors.html.md +++ b/website/source/docs/extending/custom-post-processors.html.md @@ -37,7 +37,7 @@ explaining what each method should do. ``` go type PostProcessor interface { Configure(interface{}) error - PostProcess(Ui, Artifact) (a Artifact, keep bool, err error) + PostProcess(context.Context, Ui, Artifact) (a Artifact, keep, mustKeel bool, err error) } ``` @@ -69,6 +69,8 @@ validates, but will never actually run the build. The `PostProcess` method is where the real work goes. PostProcess is responsible for taking one `packer.Artifact` implementation, and transforming it into another. +A `PostProcess` call can be cancelled at any moment, cancellation is triggered +when the done chan of the context struct (`<-ctx.Done()`) unblocks . When we say "transform," we don't mean actually modifying the existing `packer.Artifact` value itself. We mean taking the contents of the artifact and @@ -78,14 +80,17 @@ transformation would be taking the `Files()` from the original artifact, compressing them, and creating a new artifact with a single file: the compressed archive. -The result signature of this method is `(Artifact, bool, error)`. Each return -value is explained below: +The result signature of this method is `(Artifact, bool, bool, error)`. Each +return value is explained below: - `Artifact` - The newly created artifact if no errors occurred. -- `bool` - If true, the input artifact will forcefully be kept. By default, +- `bool` - If keep true, the input artifact will forcefully be kept. By default, Packer typically deletes all input artifacts, since the user doesn't generally want intermediary artifacts. However, some post-processors depend on the previous artifact existing. If this is `true`, it forces packer to keep the artifact around. +- `bool` - If forceOverride is true, then any user input for + keep_input_artifact is ignored and the artifact is either kept or discarded + according to the value set in `keep`. - `error` - Non-nil if there was an error in any way. If this is the case, the other two return values are ignored. From 27cf53003fda15a0f6335be72b247fc8ece4ce59 Mon Sep 17 00:00:00 2001 From: Megan Marsh Date: Tue, 30 Apr 2019 11:56:39 +0200 Subject: [PATCH 2/3] Update website/source/docs/extending/custom-post-processors.html.md Co-Authored-By: azr --- website/source/docs/extending/custom-post-processors.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/source/docs/extending/custom-post-processors.html.md b/website/source/docs/extending/custom-post-processors.html.md index 8d368aa26..c4bc34544 100644 --- a/website/source/docs/extending/custom-post-processors.html.md +++ b/website/source/docs/extending/custom-post-processors.html.md @@ -37,7 +37,7 @@ explaining what each method should do. ``` go type PostProcessor interface { Configure(interface{}) error - PostProcess(context.Context, Ui, Artifact) (a Artifact, keep, mustKeel bool, err error) + PostProcess(context.Context, Ui, Artifact) (a Artifact, keep, mustKeep bool, err error) } ``` From e7c4cc622ed6545d36e501277f7dac9b37f29ccb Mon Sep 17 00:00:00 2001 From: Megan Marsh Date: Tue, 30 Apr 2019 11:56:56 +0200 Subject: [PATCH 3/3] Update website/source/docs/extending/custom-post-processors.html.md Co-Authored-By: azr --- website/source/docs/extending/custom-post-processors.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/source/docs/extending/custom-post-processors.html.md b/website/source/docs/extending/custom-post-processors.html.md index c4bc34544..e940047b3 100644 --- a/website/source/docs/extending/custom-post-processors.html.md +++ b/website/source/docs/extending/custom-post-processors.html.md @@ -69,7 +69,7 @@ validates, but will never actually run the build. The `PostProcess` method is where the real work goes. PostProcess is responsible for taking one `packer.Artifact` implementation, and transforming it into another. -A `PostProcess` call can be cancelled at any moment, cancellation is triggered +A `PostProcess` call can be cancelled at any moment. Cancellation is triggered when the done chan of the context struct (`<-ctx.Done()`) unblocks . When we say "transform," we don't mean actually modifying the existing