Skip to content

Commit

Permalink
Docs: Semiautomatic platform ARGs
Browse files Browse the repository at this point in the history
Available for quite some time, but often useful and undocumented.
Fix that and a minor whitespace problem.

Signed-off-by: Chris Evich <cevich@redhat.com>
  • Loading branch information
cevich committed Jul 11, 2024
1 parent f89d4dc commit c314c91
Showing 1 changed file with 50 additions and 0 deletions.
50 changes: 50 additions & 0 deletions docs/Containerfile.5.md
Original file line number Diff line number Diff line change
Expand Up @@ -606,6 +606,56 @@ The secret needs to be passed to the build using the --secret flag. The final im
$ podman build --build-arg HTTPS_PROXY=https://my-proxy.example.com .
```

**Platform/OS/Arch ARG**
-- `ARG <name>`

When building multi-arch manifest-lists or images for a foreign-architecture,
it's often helpful to have access to platform details within the `Containerfile`.
For example, when using a `RUN curl ...` command to install OS/Arch specific
binary into the image. Or, if certain `RUN` operations are known incompatible
or non-performant when emulating a specific architecture.

There are several named `ARG` variables available. The purpose of each should be
self-evident by its name. _However_, in all cases these ARG values are **not**
automatically populated. You must always declare them within each `FROM` section
of the `Containerfile`.

The available `ARG <name>` variables are available with two prefixes:

* `TARGET...` variable names represent details about the currently running build
context (i.e. "inside" the container). These are often the most useful:
* `TARGETOS`: For example `linux`
* `TARGETARCH`: For example `amd64`
* `TARGETPLATFORM`: For example `linux/amd64`
* `TARGETVARIANT`: Uncommonly used, specific to `TARGETARCH`
* `BUILD...` variable names signify details about the _host_ performing the build
(i.e. "outside" the container):
* `BUILDOS`: OS of host performing the build
* `BUILDARCH`: Arch of host performing the build
* `BUILDPLATFORM`: Combined OS/Arch of host performing the build
* `BUILDVARIANT`: Uncommonly used, specific to `BUILDARCH`

An example `Containerfile` that uses `TARGETARCH` to fetch an arch-specific binary could be:

```
FROM busybox
ARG TARGETARCH
RUN curl -sSf -O https://example.com/downloads/bin-${TARGETARCH}.zip
```

Assuming the host platform is `linux/amd64` and foreign-architecture emulation
enabled (e.g. `qemu-user-static`), then running the command:

```
$ podman build --platform linux/s390x .
```

Would end up running `curl` on `https://example.com/downloads/bin-s390x.zip` and producing
a container image suited for the the `linux/s390x` platform. **Note:** Emulation isn't
strictly required, these special build-args will also function when building using
`podman farm build`.


**ONBUILD**
-- `ONBUILD [INSTRUCTION]`
The **ONBUILD** instruction adds a trigger instruction to an image. The
Expand Down

0 comments on commit c314c91

Please sign in to comment.