From ce42168940e69f94ca7431de5187c3bf87c41d13 Mon Sep 17 00:00:00 2001 From: Tonis Tiigi Date: Fri, 12 Jul 2019 16:00:57 -0700 Subject: [PATCH] docs: document from platform Co-Authored-By: Tibor Vass Signed-off-by: Tonis Tiigi Signed-off-by: Sebastiaan van Stijn --- docs/reference/builder.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/reference/builder.md b/docs/reference/builder.md index 6b55151fb7..cc11abd323 100644 --- a/docs/reference/builder.md +++ b/docs/reference/builder.md @@ -558,15 +558,15 @@ the first pattern, followed by one or more `!` exception patterns. ## FROM - FROM [AS ] + FROM [--platform=] [AS ] Or - FROM [:] [AS ] + FROM [--platform=] [:] [AS ] Or - FROM [@] [AS ] + FROM [--platform=] [@] [AS ] The `FROM` instruction initializes a new build stage and sets the [*Base Image*](glossary.md#base-image) for subsequent instructions. As such, a @@ -576,21 +576,26 @@ the [*Public Repositories*](https://docs.docker.com/engine/tutorials/dockerrepos - `ARG` is the only instruction that may precede `FROM` in the `Dockerfile`. See [Understand how ARG and FROM interact](#understand-how-arg-and-from-interact). - - `FROM` can appear multiple times within a single `Dockerfile` to create multiple images or use one build stage as a dependency for another. Simply make a note of the last image ID output by the commit before each new `FROM` instruction. Each `FROM` instruction clears any state created by previous instructions. - - Optionally a name can be given to a new build stage by adding `AS name` to the `FROM` instruction. The name can be used in subsequent `FROM` and `COPY --from=` instructions to refer to the image built in this stage. - - The `tag` or `digest` values are optional. If you omit either of them, the builder assumes a `latest` tag by default. The builder returns an error if it cannot find the `tag` value. +The optional `--platform` flag can be used to specify the platform of the image +in case `FROM` references a multi-platform image. For example, `linux/amd64`, +`linux/arm64`, or `windows/amd64`. By default, the target platform of the build +request is used. Global build arguments can be used in the value of this flag, +for example [automatic platform ARGs](#automatic-platform-args-in-the-global-scope) +allow you to force a stage to native build platform (`--platform=$BUILDPLATFORM`), +and use it to cross-compile to the target platform inside the stage. + ### Understand how ARG and FROM interact `FROM` instructions support variables that are declared by any `ARG`