Parser Directives in docker

The parser directives

As the name implies, the parser directives instruct the Dockerfile parser to handle the content of Dockerfile as specified in the directives. The parser directives are optional and must be at the top of a Dockerfile. Currently, escape is the only supported directive.

We usually use escape character to extend a single line to multiple lines. On UNIX-like platforms, \ is the escape character, whereas, on Windows, \ is a directory path separator and ` is the escape character. By default, the Dockerfile parser considers \ is the escape character, and you could override this on Windows using the escape parser directive, as shown here:

# escape=`

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 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 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 instruction:

FROM microsoft/nanoserver
COPY testfile.txt c:\\
RUN dir c:\

Results in:

PS E:\myproject> docker build -t cmd .

Sending build context to Docker daemon 3.072 kB
Step 1/2 : FROM microsoft/nanoserver
 ---> 22738ff49c6d
Step 2/2 : COPY testfile.txt c:\RUN dir c:
GetFileAttributesEx c:RUN: The system cannot find the file specified.
PS E:\myproject>

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 natural for paths on Windows, and at worst, error-prone as not all commands on Windows support / as the path separator.

Results in:

PS E:\myproject> docker build -t succeeds --no-cache=true .

Sending build context to Docker daemon 3.072 kB
Step 1/3 : FROM microsoft/nanoserver
 ---> 22738ff49c6d
Step 2/3 : COPY testfile.txt c:\
 ---> 96655de338de
Removing intermediate container 4db9acbb1682
Step 3/3 : RUN dir c:\
 ---> Running in a2c157f842f5
 Volume in drive C has no label.
 Volume Serial Number is 7E6D-E0F7

 Directory of c:\

10/05/2016  05:04 PM             1,894 License.txt
10/05/2016  02:22 PM    <DIR>          Program Files
10/05/2016  02:14 PM    <DIR>          Program Files (x86)
10/28/2016  11:18 AM                62 testfile.txt
10/28/2016  11:20 AM    <DIR>          Users
10/28/2016  11:20 AM    <DIR>          Windows
           2 File(s)          1,956 bytes
           4 Dir(s)  21,259,096,064 bytes free
 ---> 01c7f3bef04f
Removing intermediate container a2c157f842f5
Successfully built 01c7f3bef04f
PS E:\myproject>