1berry/docker-cli
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add some docs about build-arg's impact on the cache

Browse Source 
Closes #18017

Signed-off-by: Doug Davis <dug@us.ibm.com>
This commit is contained in:
Doug Davis 2015-11-23 03:08:21 -08:00 committed by Tibor Vass
parent 007df1d494
commit ec3aa7ede2
1 changed files with 35 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
docs/reference/builder.md
View File

@ -562,7 +562,7 @@ ADD has two forms:
whitespace) whitespace)
The `ADD` instruction copies new files, directories or remote file URLs from `<src>` 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 Multiple `<src>` resource may be specified but if they are files or
directories then they must be relative to the source directory that is 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 To use these, simply pass them on the command line using the `--build-arg
<varname>=<value>` flag. <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
ONBUILD [INSTRUCTION] ONBUILD [INSTRUCTION]