builder: Update documentation WRT environment replacement

Docker-DCO-1.1-Signed-off-by: Erik Hollensbe <github@hollensbe.org> (github: erikh)
This commit is contained in:
Erik Hollensbe 2014-10-27 20:05:29 +00:00 committed by Tibor Vass
parent 9efb51fbc1
commit 15192a0bc1
1 changed files with 41 additions and 0 deletions

View File

@ -104,6 +104,47 @@ be treated as an argument. This allows statements like:
Here is the set of instructions you can use in a `Dockerfile` for building
images.
### Environment Replacement
**Note:** prior to 1.3, `Dockerfile` environment variables were handled
similarly, in that they would be replaced as described below. However, there
was no formal definition on as to which instructions handled environment
replacement at the time. After 1.3 this behavior will be preserved and
canonical.
Environment variables (declared with the `ENV` statement) can also be used in
certain instructions as variables to be interpreted by the `Dockerfile`. Escapes
are also handled for including variable-like syntax into a statement literally.
Environment variables are notated in the `Dockerfile` either with
`$variable_name` or `${variable_name}`. They are treated equivalently and the
brace syntax is typically used to address issues with variable names with no
whitespace, like `${foo}_bar`.
Escaping is possible by adding a `\` before the variable: `\$foo` or `\${foo}`,
for example, will translate to `$foo` and `${foo}` literals respectively.
Example (parsed representation is displayed after the `#`):
FROM busybox
ENV foo /bar
WORKDIR ${foo} # WORKDIR /bar
ADD . $foo # ADD . /bar
COPY \$foo /quux # COPY $foo /quux
The instructions that handle environment variables in the `Dockerfile` are:
* `ENV`
* `ADD`
* `COPY`
* `WORKDIR`
* `EXPOSE`
* `VOLUME`
* `USER`
`ONBUILD` instructions are **NOT** supported for environment replacement, even
the instructions above.
## The `.dockerignore` file
If a file named `.dockerignore` exists in the source repository, then it