docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #23460 from kevinburke/fix-typo 

typo in builder.md: its => it's
This commit is contained in:
Vincent Demeester 2016-06-11 21:41:33 +02:00 committed by GitHub
parent a29376dfd0 c9a68ffb2a
commit dcc65376ba
1 changed files with 51 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
docs/reference/builder.md
View File

@ -115,11 +115,11 @@ The instruction is not case-sensitive. However, convention is for them to
be UPPERCASE to distinguish them from arguments more easily. be UPPERCASE to distinguish them from arguments more easily.
Docker runs instructions in a `Dockerfile` in order. **The first Docker runs instructions in a `Dockerfile` in order. **The first
instruction must be \`FROM\`** in order to specify the [*Base instruction must be \`FROM\`** in order to specify the [*Base
Image*](glossary.md#base-image) from which you are building. Image*](glossary.md#base-image) from which you are building.
Docker treats lines that *begin* with `#` as a comment, unless the line is Docker treats lines that *begin* with `#` as a comment, unless the line is
a valid [parser directive](builder.md#parser directives). A `#` marker anywhere a valid [parser directive](builder.md#parser directives). A `#` marker anywhere
else in a line is treated as an argument. This allows statements like: else in a line is treated as an argument. This allows statements like:
@ -132,20 +132,20 @@ Line continuation characters are not supported in comments.
## Parser directives ## Parser directives
Parser directives are optional, and affect the way in which subsequent lines Parser directives are optional, and affect the way in which subsequent lines
in a `Dockerfile` are handled. Parser directives do not add layers to the build, in a `Dockerfile` are handled. Parser directives do not add layers to the build,
and will not be shown as a build step. Parser directives are written as a and will not be shown as a build step. Parser directives are written as a
special type of comment in the form `# directive=value`. A single directive special type of comment in the form `# directive=value`. A single directive
may only be used once. may only be used once.
Once a comment, empty line or builder instruction has been processed, Docker Once a comment, empty line or builder instruction has been processed, Docker
no longer looks for parser directives. Instead it treats anything formatted no longer looks for parser directives. Instead it treats anything formatted
as a parser directive as a comment and does not attempt to validate if it might as a parser directive as a comment and does not attempt to validate if it might
be a parser directive. Therefore, all parser directives must be at the very be a parser directive. Therefore, all parser directives must be at the very
top of a `Dockerfile`. top of a `Dockerfile`.
Parser directives are not case-sensitive. However, convention is for them to Parser directives are not case-sensitive. However, convention is for them to
be lowercase. Convention is also to include a blank line following any be lowercase. Convention is also to include a blank line following any
parser directives. Line continuation characters are not supported in parser parser directives. Line continuation characters are not supported in parser
directives. directives.
@ -166,7 +166,7 @@ Invalid due to appearing twice:
FROM ImageName FROM ImageName
``` ```
Treated as a comment due to appearing after a builder instruction: Treated as a comment due to appearing after a builder instruction:
```Dockerfile ```Dockerfile
@ -190,10 +190,10 @@ a comment which is not a parser directive.
```Dockerfile ```Dockerfile
# unknowndirective=value # unknowndirective=value
# knowndirective=value # knowndirective=value
``` ```
Non line-breaking whitespace is permitted in a parser directive. Hence, the Non line-breaking whitespace is permitted in a parser directive. Hence, the
following lines are all treated identically: following lines are all treated identically:
```Dockerfile ```Dockerfile
#directive=value #directive=value
@ -215,26 +215,26 @@ Or
# escape=` (backtick) # escape=` (backtick)
The `escape` directive sets the character used to escape characters in a The `escape` directive sets the character used to escape characters in a
`Dockerfile`. If not specified, the default escape character is `\`. `Dockerfile`. If not specified, the default escape character is `\`.
The escape character is used both to escape characters in a line, and to The escape character is used both to escape characters in a line, and to
escape a newline. This allows a `Dockerfile` instruction to escape a newline. This allows a `Dockerfile` instruction to
span multiple lines. Note that regardless of whether the `escape` parser span multiple lines. Note that regardless of whether the `escape` parser
directive is included in a `Dockerfile`, *escaping is not performed in directive is included in a `Dockerfile`, *escaping is not performed in
a `RUN` command, except at the end of a line.* a `RUN` command, except at the end of a line.*
Setting the escape character to `` ` `` is especially useful on Setting the escape character to `` ` `` is especially useful on
`Windows`, where `\` is the directory path separator. `` ` `` is consistent `Windows`, where `\` is the directory path separator. `` ` `` is consistent
with [Windows PowerShell](https://technet.microsoft.com/en-us/library/hh847755.aspx). with [Windows PowerShell](https://technet.microsoft.com/en-us/library/hh847755.aspx).
Consider the following example which would fail in a non-obvious way on Consider the following example which would fail in a non-obvious way on
`Windows`. The second `\` at the end of the second line would be interpreted as an `Windows`. The second `\` at the end of the second line would be interpreted as an
escape for the newline, instead of a target of the escape from the first `\`. escape for the newline, instead of a target of the escape from the first `\`.
Similarly, the `\` at the end of the third line would, assuming it was actually Similarly, the `\` at the end of the third line would, assuming it was actually
handled as an instruction, cause it be treated as a line continuation. The result handled as an instruction, cause it be treated as a line continuation. The result
of this dockerfile is that second and third lines are considered a single of this dockerfile is that second and third lines are considered a single
instruction: instruction:
```Dockerfile ```Dockerfile
FROM windowsservercore FROM windowsservercore
@ -250,18 +250,18 @@ Results in:
---> dbfee88ee9fd ---> dbfee88ee9fd
Step 2 : COPY testfile.txt c:RUN dir c: Step 2 : COPY testfile.txt c:RUN dir c:
GetFileAttributesEx c:RUN: The system cannot find the file specified. GetFileAttributesEx c:RUN: The system cannot find the file specified.
PS C:\John> PS C:\John>
One solution to the above would be to use `/` as the target of both the `COPY` One solution to the above would be to use `/` as the target of both the `COPY`
instruction, and `dir`. However, this syntax is, at best, confusing as it is not instruction, and `dir`. However, this syntax is, at best, confusing as it is not
natural for paths on `Windows`, and at worst, error prone as not all commands on natural for paths on `Windows`, and at worst, error prone as not all commands on
`Windows` support `/` as the path separator. `Windows` support `/` as the path separator.
By adding the `escape` parser directive, the following `Dockerfile` succeeds as By adding the `escape` parser directive, the following `Dockerfile` succeeds as
expected with the use of natural platform semantics for file paths on `Windows`: expected with the use of natural platform semantics for file paths on `Windows`:
# escape=` # escape=`
FROM windowsservercore FROM windowsservercore
COPY testfile.txt c:\ COPY testfile.txt c:\
RUN dir c:\ RUN dir c:\
@ -279,9 +279,9 @@ Results in:
---> Running in a5ff53ad6323 ---> Running in a5ff53ad6323
Volume in drive C has no label. Volume in drive C has no label.
Volume Serial Number is 1440-27FA Volume Serial Number is 1440-27FA
Directory of c:\ Directory of c:\
03/25/2016 05:28 AM <DIR> inetpub 03/25/2016 05:28 AM <DIR> inetpub
03/25/2016 04:22 AM <DIR> PerfLogs 03/25/2016 04:22 AM <DIR> PerfLogs
04/22/2016 10:59 PM <DIR> Program Files 04/22/2016 10:59 PM <DIR> Program Files
@ -497,7 +497,7 @@ generated images.
RUN has 2 forms: RUN has 2 forms:
- `RUN <command>` (*shell* form, the command is run in a shell, which by - `RUN <command>` (*shell* form, the command is run in a shell, which by
default is `/bin/sh -c` on Linux or `cmd /S /C` on Windows) default is `/bin/sh -c` on Linux or `cmd /S /C` on Windows)
- `RUN ["executable", "param1", "param2"]` (*exec* form) - `RUN ["executable", "param1", "param2"]` (*exec* form)
@ -1209,7 +1209,7 @@ and for any `RUN`, `CMD` and `ENTRYPOINT` instructions that follow it in the
The `WORKDIR` instruction sets the working directory for any `RUN`, `CMD`, The `WORKDIR` instruction sets the working directory for any `RUN`, `CMD`,
`ENTRYPOINT`, `COPY` and `ADD` instructions that follow it in the `Dockerfile`. `ENTRYPOINT`, `COPY` and `ADD` instructions that follow it in the `Dockerfile`.
If the `WORKDIR` doesn't exist, it will be created even if its not used in any If the `WORKDIR` doesn't exist, it will be created even if it's not used in any
subsequent `Dockerfile` instruction. subsequent `Dockerfile` instruction.
It can be used multiple times in the one `Dockerfile`. If a relative path It can be used multiple times in the one `Dockerfile`. If a relative path
@ -1548,7 +1548,7 @@ The `HEALTHCHECK` feature was added in Docker 1.12.
## SHELL ## SHELL
SHELL ["executable", "parameters"] SHELL ["executable", "parameters"]
The `SHELL` instruction allows the default shell used for the *shell* form of The `SHELL` instruction allows the default shell used for the *shell* form of
commands to be overridden. The default shell on Linux is `["/bin/sh", "-c"]`, and on commands to be overridden. The default shell on Linux is `["/bin/sh", "-c"]`, and on
Windows is `["cmd", "/S", "/C"]`. The `SHELL` instruction *must* be written in JSON Windows is `["cmd", "/S", "/C"]`. The `SHELL` instruction *must* be written in JSON
@ -1558,21 +1558,21 @@ The `SHELL` instruction is particularly useful on Windows where there are
two commonly used and quite different native shells: `cmd` and `powershell`, as two commonly used and quite different native shells: `cmd` and `powershell`, as
well as alternate shells available including `sh`. well as alternate shells available including `sh`.
The `SHELL` instruction can appear multiple times. Each `SHELL` instruction overrides The `SHELL` instruction can appear multiple times. Each `SHELL` instruction overrides
all previous `SHELL` instructions, and affects all subsequent instructions. For example: all previous `SHELL` instructions, and affects all subsequent instructions. For example:
FROM windowsservercore FROM windowsservercore
# Executed as cmd /S /C echo default # Executed as cmd /S /C echo default
RUN echo default RUN echo default
# Executed as cmd /S /C powershell -command Write-Host default # Executed as cmd /S /C powershell -command Write-Host default
RUN powershell -command Write-Host default RUN powershell -command Write-Host default
# Executed as powershell -command Write-Host hello # Executed as powershell -command Write-Host hello
SHELL ["powershell", "-command"] SHELL ["powershell", "-command"]
RUN Write-Host hello RUN Write-Host hello
# Executed as cmd /S /C echo hello # Executed as cmd /S /C echo hello
SHELL ["cmd", "/S"", "/C"] SHELL ["cmd", "/S"", "/C"]
RUN echo hello RUN echo hello
@ -1580,21 +1580,21 @@ all previous `SHELL` instructions, and affects all subsequent instructions. For
The following instructions can be affected by the `SHELL` instruction when the The following instructions can be affected by the `SHELL` instruction when the
*shell* form of them is used in a Dockerfile: `RUN`, `CMD` and `ENTRYPOINT`. *shell* form of them is used in a Dockerfile: `RUN`, `CMD` and `ENTRYPOINT`.
The following example is a common pattern found on Windows which can be The following example is a common pattern found on Windows which can be
streamlined by using the `SHELL` instruction: streamlined by using the `SHELL` instruction:
... ...
RUN powershell -command Execute-MyCmdlet -param1 "c:\foo.txt" RUN powershell -command Execute-MyCmdlet -param1 "c:\foo.txt"
... ...
The command invoked by docker will be: The command invoked by docker will be:
cmd /S /C powershell -command Execute-MyCmdlet -param1 "c:\foo.txt" cmd /S /C powershell -command Execute-MyCmdlet -param1 "c:\foo.txt"
This is inefficient for two reasons. First, there is an un-necessary cmd.exe command This is inefficient for two reasons. First, there is an un-necessary cmd.exe command
processor (aka shell) being invoked. Second, each `RUN` instruction in the *shell* processor (aka shell) being invoked. Second, each `RUN` instruction in the *shell*
form requires an extra `powershell -command` prefixing the command. form requires an extra `powershell -command` prefixing the command.
To make this more efficient, one of two mechanisms can be employed. One is to To make this more efficient, one of two mechanisms can be employed. One is to
use the JSON form of the RUN command such as: use the JSON form of the RUN command such as:
@ -1602,14 +1602,14 @@ use the JSON form of the RUN command such as:
RUN ["powershell", "-command", "Execute-MyCmdlet", "-param1 \"c:\\foo.txt\""] RUN ["powershell", "-command", "Execute-MyCmdlet", "-param1 \"c:\\foo.txt\""]
... ...
While the JSON form is unambiguous and does not use the un-necessary cmd.exe, While the JSON form is unambiguous and does not use the un-necessary cmd.exe,
it does require more verbosity through double-quoting and escaping. The alternate it does require more verbosity through double-quoting and escaping. The alternate
mechanism is to use the `SHELL` instruction and the *shell* form, mechanism is to use the `SHELL` instruction and the *shell* form,
making a more natural syntax for Windows users, especially when combined with making a more natural syntax for Windows users, especially when combined with
the `escape` parser directive: the `escape` parser directive:
# escape=` # escape=`
FROM windowsservercore FROM windowsservercore
SHELL ["powershell","-command"] SHELL ["powershell","-command"]
RUN New-Item -ItemType Directory C:\Example RUN New-Item -ItemType Directory C:\Example
@ -1628,16 +1628,16 @@ Resulting in:
Removing intermediate container 87d7a64c9751 Removing intermediate container 87d7a64c9751
Step 3 : RUN New-Item -ItemType Directory C:\Example Step 3 : RUN New-Item -ItemType Directory C:\Example
---> Running in 3e6ba16b8df9 ---> Running in 3e6ba16b8df9
Directory: C:\ Directory: C:\
Mode LastWriteTime Length Name Mode LastWriteTime Length Name
---- ------------- ------ ---- ---- ------------- ------ ----
d----- 6/2/2016 2:59 PM Example d----- 6/2/2016 2:59 PM Example
---> 1f1dfdcec085 ---> 1f1dfdcec085
Removing intermediate container 3e6ba16b8df9 Removing intermediate container 3e6ba16b8df9
Step 4 : ADD Execute-MyCmdlet.ps1 c:\example\ Step 4 : ADD Execute-MyCmdlet.ps1 c:\example\
@ -1654,7 +1654,7 @@ Resulting in:
The `SHELL` instruction could also be used to modify the way in which The `SHELL` instruction could also be used to modify the way in which
a shell operates. For example, using `SHELL cmd /S /C /V:ON|OFF` on Windows, delayed a shell operates. For example, using `SHELL cmd /S /C /V:ON|OFF` on Windows, delayed
environment variable expansion semantics could be modified. environment variable expansion semantics could be modified.
The `SHELL` instruction can also be used on Linux should an alternate shell be The `SHELL` instruction can also be used on Linux should an alternate shell be
required such `zsh`, `csh`, `tcsh` and others. required such `zsh`, `csh`, `tcsh` and others.