Browse Source

Improve build cache miss doc for `ARG` and `RUN`

The documentation already says the cache miss happens only at `ARG`
variable usage, not declaration, but there is a very common implicit
usage: `RUN`, which this commit documents even more, improving on #21790.

Also, use `definition` instead of `declaration`: it's the same thing, and
`definition` is already used in this documentation, contrary to
`declaration`.

Also, distinguish between "instructions" and "variables defined by `ARG`
instructions".

Signed-off-by: Thomas Riccardi <riccardi@systran.fr>
Thomas Riccardi 9 years ago
parent
commit
82f5ef2d25
1 changed files with 3 additions and 2 deletions
  1. 3 2
      docs/reference/builder.md

+ 3 - 2
docs/reference/builder.md

@@ -1174,8 +1174,9 @@ To use these, simply pass them on the command line using the `--build-arg
 `ARG` variables are not persisted into the built image as `ENV` variables are.
 `ARG` variables are not persisted into the built image as `ENV` variables are.
 However, `ARG` variables do impact the build cache in similar ways. If a
 However, `ARG` variables do impact the build cache in similar ways. If a
 Dockerfile defines an `ARG` variable whose value is different from a previous
 Dockerfile defines an `ARG` variable whose value is different from a previous
-build, then a "cache miss" occurs upon first use of the `ARG` variable. The
-declaration of the `ARG` variable does not count as a use.
+build, then a "cache miss" occurs upon its first usage, not its definition. In
+particular, all `RUN` instructions following an `ARG` instruction use the `ARG`
+variable implicitly (as an environment variable), thus can cause a cache miss.
 
 
 For example, consider these two Dockerfile:
 For example, consider these two Dockerfile: