From e941f698da7a0683c8f19d6f386ede4fd9bf5d96 Mon Sep 17 00:00:00 2001 From: mikelinjie <294893458@qq.com> Date: Wed, 16 Mar 2016 15:26:57 +0800 Subject: [PATCH] make the cache miss clear Signed-off-by: mikelinjie <294893458@qq.com> Signed-off-by: Sebastiaan van Stijn (cherry picked from commit 66b8714da4e92b3587cbbf25116541f4de63169e) --- docs/reference/builder.md | 37 +++++++++++++++++++++++++++++-------- 1 file changed, 29 insertions(+), 8 deletions(-) diff --git a/docs/reference/builder.md b/docs/reference/builder.md index 5819ea36fd..a932276b75 100644 --- a/docs/reference/builder.md +++ b/docs/reference/builder.md @@ -1174,8 +1174,10 @@ 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. 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: +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. + +For example, consider these two Dockerfile: ``` 1 FROM ubuntu @@ -1183,12 +1185,17 @@ For example, consider this Dockerfile: 3 RUN echo $CONT_IMG_VER ``` -If you specify `--build-arg CONT_IMG_VER=` 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. +``` +1 FROM ubuntu +2 ARG CONT_IMG_VER +3 RUN echo hello +``` + +If you specify `--build-arg CONT_IMG_VER=` on the command line, in both +cases, the specification on line 2 does not cause a cache miss; line 3 does +cause a cache miss.`ARG CONT_IMG_VER` causes the RUN line to be identified +as the same as running `CONT_IMG_VER=` echo hello, so if the `` +changes, we get a cache miss. Consider another example under the same command line: @@ -1203,6 +1210,20 @@ 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. +If an `ENV` instruction overrides an `ARG` instruction of the same name, like +this Dockerfile: + +``` +1 FROM ubuntu +2 ARG CONT_IMG_VER +3 ENV CONT_IMG_VER hello +4 RUN echo $CONT_IMG_VER +``` + +Line 3 does not cause a cache miss because the value of `CONT_IMG_VER` is a +constant (`hello`). As a result, the environment variables and values used on +the `RUN` (line 4) doesn't change between builds. + ## ONBUILD ONBUILD [INSTRUCTION]