|
|
@@ -562,7 +562,7 @@ ADD has two forms:
|
|
|
whitespace)
|
|
|
|
|
|
The `ADD` instruction copies new files, directories or remote file URLs from `<src>`
|
|
|
-and adds them to the filesystem of the container at the path `<dest>`.
|
|
|
+and adds them to the filesystem of the container at the path `<dest>`.
|
|
|
|
|
|
Multiple `<src>` resource may be specified but if they are files or
|
|
|
directories then they must be relative to the source directory that is
|
|
|
@@ -1135,6 +1135,40 @@ corresponding `ARG` instruction in the Dockerfile.
|
|
|
To use these, simply pass them on the command line using the `--build-arg
|
|
|
<varname>=<value>` flag.
|
|
|
|
|
|
+### Impact on build caching
|
|
|
+
|
|
|
+`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
|
|
|
+Dockerfile defines an `ARG` variable whose value is different from a previous
|
|
|
+build, then a "cache miss" occurs upon its first usage, not its declaration.
|
|
|
+For example, consider this Dockerfile:
|
|
|
+
|
|
|
+```
|
|
|
+1 FROM ubuntu
|
|
|
+2 ARG CONT_IMG_VER
|
|
|
+3 RUN echo $CONT_IMG_VER
|
|
|
+```
|
|
|
+
|
|
|
+If you specify `--build-arg CONT_IMG_VER=<value>` on the command line the
|
|
|
+specification on line 2 does not cause a cache miss; line 3 does cause a cache
|
|
|
+miss. The definition on line 2 has no impact on the resulting image. The `RUN`
|
|
|
+on line 3 executes a command and in doing so defines a set of environment
|
|
|
+variables, including `CONT_IMG_VER`. At that point, the `ARG` variable may
|
|
|
+impact the resulting image, so a cache miss occurs.
|
|
|
+
|
|
|
+Consider another example under the same command line:
|
|
|
+
|
|
|
+```
|
|
|
+1 FROM ubuntu
|
|
|
+2 ARG CONT_IMG_VER
|
|
|
+3 ENV CONT_IMG_VER $CONT_IMG_VER
|
|
|
+4 RUN echo $CONT_IMG_VER
|
|
|
+```
|
|
|
+In this example, the cache miss occurs on line 3. The miss happens because
|
|
|
+the variable's value in the `ENV` references the `ARG` variable and that
|
|
|
+variable is changed through the command line. In this example, the `ENV`
|
|
|
+command causes the image to include the value.
|
|
|
+
|
|
|
## ONBUILD
|
|
|
|
|
|
ONBUILD [INSTRUCTION]
|
Doug Davis