From 8cfcd8738070f24bd66e3b7ed46c6459df3fa9a3 Mon Sep 17 00:00:00 2001 From: Madhav Puri Date: Wed, 16 Sep 2015 01:47:10 -0700 Subject: [PATCH] incorporate doc review comments Signed-off-by: Madhav Puri --- docs/reference/api/docker_remote_api_v1.21.md | 10 ++++---- docs/reference/builder.md | 23 ++++++++++--------- man/Dockerfile.5.md | 23 ++++++++++--------- man/docker-build.1.md | 23 +++++++------------ 4 files changed, 37 insertions(+), 42 deletions(-) diff --git a/docs/reference/api/docker_remote_api_v1.21.md b/docs/reference/api/docker_remote_api_v1.21.md index 1fa18f38f4..0ac6040555 100644 --- a/docs/reference/api/docker_remote_api_v1.21.md +++ b/docs/reference/api/docker_remote_api_v1.21.md @@ -1367,11 +1367,11 @@ Query Parameters: - **memswap** - Total memory (memory + swap), `-1` to disable swap. - **cpushares** - CPU shares (relative weight). - **cpusetcpus** - CPUs in which to allow execution (e.g., `0-3`, `0,1`). -- **buildargs** – JSON map of string pairs for build-time variables. Users can - set these values at build-time and they are used as environment context - for the command(s) run as part of the Dockerfile's `RUN` instruction or - for variable expansion in other Dockerfile instructions. Read more about - the `ARG` instruction [here](/reference/builder/#arg) +- **buildargs** – JSON map of string pairs for build-time variables. Users pass + these values at build-time. Docker uses the `buildargs` as the environment + context for command(s) run via the Dockerfile's `RUN` instruction or for + variable expansion in other Dockerfile instructions. This is not meant for + passing secret values. [Read more about the buildargs instruction](/reference/builder/#arg) Request Headers: diff --git a/docs/reference/builder.md b/docs/reference/builder.md index 848d69717c..c519102052 100644 --- a/docs/reference/builder.md +++ b/docs/reference/builder.md @@ -1058,19 +1058,20 @@ useful interactions between `ARG` and `ENV` instructions: 4 RUN echo $CONT_IMG_VER ``` -The command line passes the `--build-arg` and sets the `v2.0.1` value. And the `ARG -CONT_IMG_VER` is defined on line 2 of the Dockerfile. On line 3, the `ENV` -instruction of the same name resolves to `v2.0.1` as the build-time variable -was passed from the command line and expanded here. +Unlike an `ARG` instruction, `ENV` values are always persisted in the built +image. Consider a docker build without the --build-arg flag: + +``` +$ docker build Dockerfile +``` + +Using this Dockerfile example, `CONT_IMG_VER` is still persisted in the image but +its value would be `v1.0.0` as it is the default set in line 3 by the `ENV` instruction. The variable expansion technique in this example allows you to pass arguments -from the command line and persist them in the final image by leveraging the `ENV` -instruction. Variable expansion is only supported for the `Dockerfile` instructions -described [here](#environment-replacement). - -Unlike an `ARG` instruction, `ENV` values are always persisted in the built image. If -`docker build` were run without setting the `--build-arg` flag, then -`CONT_IMG_VER` is still persisted in the image but its value would be `v1.0.0`. +from the command line and persist them in the final image by leveraging the +`ENV` instruction. Variable expansion is only supported for [a limited set of +Dockerfile instructions.](#environment-replacement) Docker has a set of predefined `ARG` variables that you can use without a corresponding `ARG` instruction in the Dockerfile. diff --git a/man/Dockerfile.5.md b/man/Dockerfile.5.md index b29745e2e7..528fb67522 100644 --- a/man/Dockerfile.5.md +++ b/man/Dockerfile.5.md @@ -408,19 +408,20 @@ A Dockerfile is similar to a Makefile. 4 RUN echo $CONT_IMG_VER ``` - The command line passes the `--build-arg` and sets the `v2.0.1` value. And the `ARG - CONT_IMG_VER` is defined on line 2 of the Dockerfile. On line 3, the `ENV` - instruction of the same name resolves to `v2.0.1` as the build-time variable - was passed from the command line and expanded here. + Unlike an `ARG` instruction, `ENV` values are always persisted in the built + image. Consider a docker build without the --build-arg flag: + + ``` + $ docker build Dockerfile + ``` + + Using this Dockerfile example, `CONT_IMG_VER` is still persisted in the image but + its value would be `v1.0.0` as it is the default set in line 3 by the `ENV` instruction. The variable expansion technique in this example allows you to pass arguments - from the command line and persist them in the final image by leveraging the `ENV` - instruction. Variable expansion is only supported for the `Dockerfile` instructions - described [here](#environment-replacement). - - Unlike an `ARG` instruction, `ENV` values are always persisted in the built image. If - `docker build` were run without setting the `--build-arg` flag, then - `CONT_IMG_VER` is still persisted in the image but its value would be `v1.0.0`. + from the command line and persist them in the final image by leveraging the + `ENV` instruction. Variable expansion is only supported for [a limited set of + Dockerfile instructions.](#environment-replacement) Docker has a set of predefined `ARG` variables that you can use without a corresponding `ARG` instruction in the Dockerfile. diff --git a/man/docker-build.1.md b/man/docker-build.1.md index f725f83aa8..06cdefff1e 100644 --- a/man/docker-build.1.md +++ b/man/docker-build.1.md @@ -53,22 +53,15 @@ cloned locally and then sent as the context. The default is *Dockerfile*. **--build-arg**=*variable* - Set value for build-time variable. This option allows you to specify -values of the variables that are available for expansion/substitution in the -Dockerfile instructions like ADD, COPY etc, without an explicit prior definition by -the ENV instruction. The build-time variables are also passed as environment -context for the command(s) that will be executed as part of RUN instruction -of Dockerfile, if there is no explicit prior definition by the ENV instruction. -Normally, these variables are not persisted in the resulting Docker image. This gives -the flexibility to build an image by passing host specific environment variables (like -http_proxy) that will be used on the RUN commands without affecting portability -of the generated image. -However, as with any variable, they can be persisted in the final image if they are used in an -ENV instruction (e.g. ENV myName=$myName will save myName in the image). + name and value of a **buildarg**. -Only the build-time variables that are defined using the ARG instruction of Dockerfile -are allowed to be expanded or passed as environment to the RUN command. Read more about -ARG instruction in Dockerfile reference. + For example, if you want to pass a value for `http_proxy`, use + `--bulid-arg=http_proxy="http://some.proxy.url"` + + Users pass these values at build-time. Docker uses the `buildargs` as the + environment context for command(s) run via the Dockerfile's `RUN` instruction + or for variable expansion in other Dockerfile instructions. This is not meant + for passing secret values. [Read more about the buildargs instruction](/reference/builder/#arg) **--force-rm**=*true*|*false* Always remove intermediate containers, even after unsuccessful builds. The default is *false*.