docs: document build outputs

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com>
Signed-off-by: Tibor Vass <tibor@docker.com>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
(cherry picked from commit f7009ee12628bcf9e72ca44abd75b3f3aa5b054f)
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Upstream-commit: f6ec0a368edb29c46a6b8afb1e7e8217317389c1
Component: cli

Author: tonistiigi

components/cli/docs/reference/commandline/build.md

@@ -47,6 +47,7 @@ Options:
                                 'host': use the Docker host network stack
                                 '<network-name>|<network-id>': connect to a user-defined network
       --no-cache                Do not use cache when building the image
+  -o, --output                  Output destination (format: type=local,dest=path)
       --pull                    Always attempt to pull a newer version of the image
       --progress                Set type of progress output (only if BuildKit enabled) (auto, plain, tty). 
                                 Use plain to show container output
@@ -489,6 +490,97 @@ FROM alpine AS production-env
 $ docker build -t mybuildimage --target build-env .
 ```
 
+### Custom build outputs
+
+By default, a local container image is created from the build result. The
+`--output` (or `-o`) flag allows you to override this behavior, and a specify a
+custom exporter. For example, custom exporters allow you to export the build
+artifacts as files on the local filesystem instead of a Docker image, which can
+be useful for generating local binaries, code generation etc.
+
+The value for `--output` is a CSV-formatted string defining the exporter type
+and options. Currently, `local` and `tar` exporters are supported. The `local`
+exporter writes the resulting build files to a directory on the client side. The
+`tar` exporter is similar but writes the files as a single tarball (`.tar`).
+
+If no type is specified, the value defaults to the output directory of the local
+exporter. Use a hyphen (`-`) to write the output tarball to standard output
+(`STDOUT`).
+
+The following example builds an image using the current directory (`.`) as build
+context, and exports the files to a directory named `out` in the current directory.
+If the directory does not exist, Docker creates the directory automatically:
+
+```bash
+$ docker build -o out .
+```
+
+The example above uses the short-hand syntax, omitting the `type` options, and
+thus uses the default (`local`) exporter. The example below shows the equivalent
+using the long-hand CSV syntax, specifying both `type` and `dest` (destination
+path):
+
+```bash
+$ docker build --output type=local,dest=out .
+```
+
+Use the `tar` type to export the files as a `.tar` archive: 
+
+```bash
+$ docker build --output type=tar,dest=out.tar .
+```
+
+The example below shows the equivalent when using the short-hand syntax. In this
+case, `-` is specified as destination, which automatically selects the `tar` type,
+and writes the output tarball to standard output, which is then redirected to
+the `out.tar` file:
+
+```bash
+docker build -o - . > out.tar
+```
+
+The `--output` option exports all files from the target stage. A common pattern
+for exporting only specific files is to do multi-stage builds and to copy the
+desired files to a new scratch stage with [`COPY --from`](../builder.md#copy).
+
+The example `Dockerfile` below uses a separate stage to collect the
+build-artifacts for exporting:
+
+```Dockerfile
+FROM golang AS build-stage
+RUN go get -u github.com/LK4D4/vndr
+
+FROM scratch AS export-stage
+COPY --from=build-stage /go/bin/vndr /
+```
+
+When building the Dockerfile with the `-o` option, only the files from the final
+stage are exported to the `out` directory, in this case, the `vndr` binary:
+
+```bash
+$ docker build -o out .
+
+[+] Building 2.3s (7/7) FINISHED
+ => [internal] load build definition from Dockerfile                                                                          0.1s
+ => => transferring dockerfile: 176B                                                                                          0.0s
+ => [internal] load .dockerignore                                                                                             0.0s
+ => => transferring context: 2B                                                                                               0.0s
+ => [internal] load metadata for docker.io/library/golang:latest                                                              1.6s
+ => [build-stage 1/2] FROM docker.io/library/golang@sha256:2df96417dca0561bf1027742dcc5b446a18957cd28eba6aa79269f23f1846d3f   0.0s
+ => => resolve docker.io/library/golang@sha256:2df96417dca0561bf1027742dcc5b446a18957cd28eba6aa79269f23f1846d3f               0.0s
+ => CACHED [build-stage 2/2] RUN go get -u github.com/LK4D4/vndr                                                              0.0s
+ => [export-stage 1/1] COPY --from=build-stage /go/bin/vndr /                                                                 0.2s
+ => exporting to client                                                                                                       0.4s
+ => => copying files 10.30MB                                                                                                  0.3s
+
+$ ls ./out
+vndr
+```
+
+> **Note**: This feature requires the BuildKit backend. You can either
+> [enable BuildKit](../builder.md#buildkit) or use the [buildx](https://github.com/docker/buildx)
+> plugin which provides more output type options.
+
 ### Specifying external cache sources
 
 In addition to local build cache, the builder can reuse the cache generated from