# Endiafile

> The recipe format for East India images: Dockerfile syntax, the instructions a recipe may use, and how a build reads them.

A recipe is an Endiafile: a file written in Dockerfile syntax. East India reads the subset below and refuses everything else before any virtual machine starts, naming the file, line and column as a compiler does, for example `recipes/dotnet.Endiafile:3:1: HEALTHCHECK is not supported in this release`.

## File names

A folder with one recipe names it `Endiafile`; a folder with several names each `name.Endiafile`, such as `recipes/dotnet.Endiafile`. The name changes nothing else, so a Dockerfile written for Docker is a recipe under either name. A build without `-f` reads `Endiafile` and otherwise `Dockerfile`; `-f` takes a file of any name, such as an existing `name.Dockerfile`.

## Syntax

Syntax is Docker's. Keywords are case-insensitive, and `#` at the start of a line begins a comment. Lines end in LF or CRLF, and a leading byte-order mark is ignored. The escape character at the end of a line continues the instruction on the next line, and comment or blank lines inside a continuation are dropped. The parser directive `# escape=` followed by `\` (the default) or a backtick is read only before the first instruction, comment or blank line. The directives `# syntax=` and `# check=` are refused with `UNSUPPORTED_FIELD`. A recipe larger than 1 MiB, or not valid UTF-8, is refused with `INVALID_DEFINITION`.

## Layout and stages

A recipe has optional `ARG` instructions, then one or more stages. Each stage begins with a `FROM` and runs to the next `FROM` or the end of the recipe. An instruction other than `ARG` before the first `FROM` is refused with `INVALID_DEFINITION`.

`FROM <name>` names an earlier stage when an earlier `FROM ... AS <name>` gave that name, and an image otherwise, as in Docker; a stage cannot name itself or a later stage. A stage built `FROM` an earlier stage starts from that stage's result, with its configuration and labels. A stage name matches `[a-z][a-z0-9._-]*` once lower-cased, and names compare without regard to case. Any other name is refused with `INVALID_DEFINITION`, and so is a name that two stages share.

A build makes its target stage, `--target` or the last stage, and the stages its `FROM` lines pass through. It checks the other stages but does not build them, as Docker's BuildKit skips them. An `ARG` before the first `FROM` is visible only to `FROM` lines, and a stage sees a build argument only after its own `ARG` for it. A stage's variables end with the stage, so a later stage receives only what its parent's configuration holds, such as `ENV`.

**One layer per stage, not per instruction**

East India caches and commits each stage as a whole. A change to any step of a stage reruns every step of that stage and of every stage built on it. [Layers, stages and the build cache](/docs/by-hand/building-images/#layers-stages-and-the-build-cache) explains why, and how to split a recipe.

## Instructions

| Instruction | Behaviour in a Windows build |
|---|---|
| `FROM <image or stage> [AS <name>]` | Begins a stage and names its parent: an earlier stage, or any image reference. A reference to no image fails the build with `NOT_FOUND`. `AS <name>` names the stage. Flags such as `--platform` are refused. |
| `ARG <name>[=<default>]` | Declares a build argument. Before `FROM`, it is visible only to `FROM`; after `FROM`, from its own line on. `ARG <name>` after `FROM` without a default takes the value of the same `ARG` before `FROM`. |
| `ENV <key>=<value> ...` or `ENV <key> <value>` | Sets environment variables for later steps and for the image's configuration. |
| `LABEL <key>=<value> ...` | Adds labels. |
| `WORKDIR <path>` | Sets the working folder for later steps and for the image's configuration, and creates it in the build machine if missing. A relative path is relative to the previous `WORKDIR`. The default is `C:\`. |
| `SHELL ["<executable>", "<argument>", ...]` | Sets the shell for the shell form of `RUN`, `CMD` and `ENTRYPOINT`. The default is `["cmd", "/S", "/C"]`. Only the JSON form is accepted. |
| `RUN <command>` or `RUN ["<executable>", "<argument>", ...]` | Runs a program in the builder. Flags such as `--mount`, and here-documents, are refused. |
| `COPY <source>... <destination>` | Copies files from the build context into the builder. Flags (`--from`, `--chown`, `--chmod`, `--link`, `--parents`, `--exclude`) and URLs are refused. |
| `USER <user>` | Names the account that later `RUN` steps run as. Machines made from the image also run their main process as that account, as in Docker, and a child image inherits it. `SYSTEM` (case-insensitive), and no `USER`, run as SYSTEM. `COPY` and `WORKDIR` are unaffected. A `RUN` step whose account does not exist fails with `BUILD_FAILED` and Docker's message `unable to find user <name>`. |
| `EXPOSE <port>[/tcp] ...` | Records ports in the configuration. It opens nothing. `/udp` is refused. |
| `ENTRYPOINT` and `CMD` | Set the image's main process, in JSON or shell form, by Docker's rules: the shell form runs through the shell; `CMD` supplies default arguments to a JSON-form `ENTRYPOINT`; a shell-form `ENTRYPOINT` ignores `CMD`; an `ENTRYPOINT` instruction clears an earlier `CMD`. |
| `ADD`, `VOLUME`, `HEALTHCHECK`, `ONBUILD`, `STOPSIGNAL`, `MAINTAINER` | Refused with `UNSUPPORTED_FIELD`. |

## Words, quoting and variables

**JSON form.** A JSON array of strings, as in Docker. An argument that is not a valid JSON array of strings is read as the shell form, as Docker reads it.

**Words and quoting.** Inside `ENV`, `LABEL`, `ARG`, `WORKDIR`, `COPY`, `USER` and `EXPOSE`, single quotes are literal. Double quotes group words and remove the escape character before `"`, `$` and the escape character itself. Outside quotes, the escape character makes the next character literal.

**Variable expansion.** `$NAME`, `${NAME}`, `${NAME:-word}` (the value, or `word` when unset or empty) and `${NAME:+word}` (`word` when set and not empty, otherwise nothing) are expanded in `FROM`, `ARG` defaults, `ENV`, `LABEL`, `WORKDIR`, `COPY` sources and destination, `USER` and `EXPOSE`. The escape character before `$` keeps it literal. East India does not expand `RUN`, `CMD`, `ENTRYPOINT` or `SHELL`; the shell expands `RUN`.

## Ignore files

A build uses the first of these that exists, and no other:

1. `<recipe file name>.endiaignore` beside the recipe;
2. `<recipe file name>.dockerignore` beside the recipe;
3. `.endiaignore` at the root of the build context;
4. `.dockerignore` at the root.

Its patterns follow Docker's `.dockerignore` rules.

## Build steps

- A `RUN` step runs as SYSTEM, unless a `USER` instruction names another account.
- A `RUN` step that exits with 3010 makes the builder restart the machine and carry on. A step that exits with 1641 has started a restart itself, and the builder waits for it. Any other non-zero exit fails the build and quotes the step's last 50 lines of output.
- Each `RUN` step may take up to 30 minutes.
- Build machines can reach the internet, so recipes can download installers.
