镜像站点 · 本页由第三方 GitHub 只读镜像提供,非 GitHub 官方站点,不接受任何登录或凭据输入。前往 github.com
Skip to content

Add nix and static variants, and publish version-pinned tags - #24

Open
metif12 wants to merge 14 commits into
vlang:masterfrom
metif12:feature/nix-and-static-variants
Open

metif12 wants to merge 14 commits into
vlang:masterfrom
metif12:feature/nix-and-static-variants

Conversation

@metif12

@metif12 metif12 commented Oct 9, 2026 •

Copy link
Copy Markdown
Member

What this changes

The images published from here were Alpine-only in practice: Dockerfile.debian
built FROM thevlang/vlang:alpine-build, so :debian and :alpine were the same
image and "Debian" meant only the tag. :ubuntu-build was amd64-only. There was
also no way to build a tag that named a version - only floating tags tracked V
master.

:debian is Debian now

Built from debian-base/debian-build, so a program compiled in it is a glibc
binary that runs on Debian, Ubuntu, Fedora and their derivatives, where a musl
binary from :alpine does not.

The build uses make CC=clang, not VFLAGS='-cc gcc': debian-build installs
clang and no gcc, and asking V for gcc fails with os: failed to find executable `gcc` before the bootstrap reaches a C compiler at all. That is
the recipe Dockerfile.debian.dev-full has always used, and it is why that
image built while this one could not.

Two new variants

  • :nix - the toolchain comes from one pinned nixpkgs revision instead of
    apk add/apt install, so the image is reproducible, and any nixpkgs
    library can be made available inside the container without root:
    docker run ... thevlang/vlang:nix sh -c 'nix-shell -p openssl --run "v run main.v"'
  • :static - a scratch image with a static V compiler, for v version
    and as a base image for an already-compiled static V program.

Version tags

Every image that clones V now takes V_REV, so the release job in
vlang/v's hub_docker_ci.yml can pass the tag and publish :<version> built
from exactly that revision. docker build --build-arg V_REV=0.5.2 does the same
locally.

Workflows

  • buildx with a docker-container driver, so a multi-platform manifest is
    actually produced (the default builder cannot make one)
  • login skipped on pull requests, so a fork can validate changes without secrets
  • vars.PLATFORMS/vars.DOCKER_REPOSITORY given fallbacks, so a missing
    repository variable makes a valid multi-arch image instead of a single-arch
    one
  • fail-fast: false, so one broken variant does not stop the others publishing

Dockerfiles carry OCI labels, and the README documents the variants, the build
args, and how to use Podman.

What is verified, and what is not

Verified by building and running here:

  • :debian - /etc/os-release reports Debian GNU/Linux 12, ldd reports
    GLIBC 2.36, v version reports V 0.5.2 407c52e, v run prints 42, and the
    binary it produces links libc.so.6, i.e. it is a glibc dynamic executable
    rather than a musl one. v fmt works too, which is a subcommand that rebuilds
    cmd/tools/vfmt from the source tree at run time.

  • :static - the image builds (78.6 MB compressed) and was run:

    check result
    docker run <image> v version V 0.5.2 ef2ec06
    docker run <image> (default CMD) V 0.5.2 ef2ec06
    v run /src/probe.v fails: Boehm GC libgc.a not found
    v fmt /src/x.v fails: the V source tree could not be found
    /bin/sh exec fails, no such file ? confirming FROM scratch
    as a base for a static binary works

    Building it also fixed three things reading the Dockerfile could not: the
    make step ended with v -version failing on a missing PATH, v was
    absent from PATH in the final image too, and CMD ["v"] could never have
    worked because a bare v starts a REPL.

  • the exact-revision clone recipe (clone --depth 1 + fetch --depth 1 origin <ref> + checkout FETCH_HEAD) resolves the same commit for a branch,
    a tag and a SHA.

Still unverified, and the reason CI matters here:

  • :nix is unbuilt here - nixos/nix is geo-blocked from where this was
    written (CloudFront 403), so the pinned-toolchain idiom it uses is standard
    but needs a CI run to be trusted.
  • multi-arch - everything above was built for linux/amd64 only. The
    workflows ask for both architectures, but that path has not run.
  • :ubuntu-build gaining arm64 - the workflow change is in place and the
    package list was checked to exist in the images it starts from, but the
    manifest has not been pushed.
  • Dockerfile.alpine - the one runtime variant still unbuilt; its recipe is
    the same shape as :debian's, which did build.

Worth recording because it looks like the bug above from the outside: V's
Makefile fetches a prebuilt tcc from vlang/tccbin, and the linux-amd64
build there is compiled on Ubuntu 24.04 and wants GLIBC_2.38, which
debian:12 does not have. That fetch is not fatal - V falls back to cc, and
the selector has a musl fallback branch - so make CC=clang succeeds on
debian:12 unchanged. Only requesting a compiler that is not installed breaks the
build, and it breaks it earlier, with a different message.


Correction: cross-compiling to vinix IS possible

An earlier version of this PR description said V "refuses to cross-compile to
vinix from any other host", citing vlib/v/pref/os_targets.v:82. That was wrong,
and it is worth recording because it nearly scoped out the vinix work.

What that line does is choose which _<os>.v file suffixes belong to a target,
and os_is_target_of turns out to have no callers in the compiler at all, so it
was never a gate. What actually happens, verified with the local compiler:

$ v -os vinix -o hello.c hello.v     # exits 0, emits 329 KB of C
$ v -os vinix -o hello hello.v       # refuses to LINK
linking target vinix/amd64 from host windows/amd64 is not supported by the
default C compiler; use -o file.c and compile it with a target toolchain

-os vinix is accepted (vlib/v/pref/pref.v:190 lists it), and C generation
works, including the __vinix__ branches. Only the link step is refused,
because a vinix binary needs vinix's libc and loader, and V will not guess a
toolchain for it. v -os vinix -o file.c is the supported route.

So the vinix+coreutils image needs no compiler change: emit C for the vinix
target on the host, then link inside the image. That is how vinix's own CI
builds util-vinix on an Ubuntu runner.

On a vinix image with vlang/coreutils

Not included here. What it would be: build vinix aarch64, boot it in QEMU inside
the container, and build coreutils inside the guest. The primitives already
exist in vinix:

  • scripts/run-aarch64.sh --guest-init <script> runs a script inside the guest
    and streams it over serial
  • run_vm.py drives that and reads a verdict marker off the console, treating
    FATAL EXCEPTION and KERNEL PANIC as failure
  • USE_TCG=1 is set when the host is not Darwin, so no KVM is needed — which
    is what makes it workable inside a container
  • scripts/build-aarch64.sh --no-iso skips the ISO, and vinix's nightly already
    builds V for the guest (scripts/build-v-aarch64.sh)

The value is a portability test nobody has: it would prove coreutils compiles
and runs on a non-Linux OS, and exercise V's -os vinix target in CI for the
first time. The honest costs are that the guest must have a C compiler and V
installed, so the image has to build both; the guest-side build is slow under
TCG; and it is a second project to keep moving whenever either one breaks.

Happy to build that as a separate PR if you want it — it is a different
deliverable from this one, and mixing it in here would bury the image work.

The images published from here were alpine-only and debian in name only
(Dockerfile.debian builds FROM thevlang/vlang:alpine-build, so :debian and
:alpine are the same image), :ubuntu-build was amd64-only, and there was no way
to build a tag that named a version - only floating tags tracked V master.

Adds two variants that fill real gaps:

  nix       the toolchain comes from one pinned nixpkgs revision instead of
            `apk add`, so the image is reproducible and any nixpkgs library can
            be made available inside the container without root
  static    a `scratch` image with a static V compiler, for `v version` and as a
            base for an already-compiled static V program

Every image that clones V now takes V_REV, so the release job in
vlang/v's hub_docker_ci.yml can pass the tag and publish `:<version>` built from
exactly that version. `docker build --build-arg V_REV=<tag>` does the same
locally.

Workflows: buildx with a docker-container driver so a multi-platform manifest is
actually produced, login skipped on pull requests so forks can validate without
secrets, `vars.PLATFORMS`/`DOCKER_REPOSITORY` given fallbacks so a missing
repository variable makes a valid multi-arch image rather than a single-arch
one, and `fail-fast: false` so one broken variant does not stop the others.

Dockerfiles carry OCI labels, and the README documents the variants, both build
arg defaults, and how to use Podman.

Not verified by CI yet:

  * :nix needs `nixos/nix`, which is geo-blocked from where this was written, so
    it is unbuilt here. The pinned toolchain idiom it uses is standard, but it
    needs a build to trust.
  * :static is verified only through an equivalent local build: on Linux x86_64
    with gcc 13, `make VFLAGS='-prod' CFLAGS='-static' LDFLAGS='-static'` exits
    0 and yields a 19 MB binary that `ldd` reports as statically linked.
  * :debian being alpine-based is unchanged, and is called out as a known issue
    in the README rather than fixed blind.
Dockerfile.debian built FROM thevlang/vlang:alpine-build, so the published
:debian and :alpine tags were the same image and "Debian" meant only the tag.
Build it from debian-base and debian-build instead, so a glibc binary built
here runs on Debian, Ubuntu and their derivatives, where a musl binary from
:alpine does not.

The build uses `make CC=clang` and not `VFLAGS='-cc gcc'`: debian-build
installs clang and no gcc, and asking V for gcc fails with
"os: failed to find executable `gcc`" before the bootstrap reaches a C
compiler at all. CC is what V's Makefile hands to its bootstrap. This is the
same recipe Dockerfile.debian.dev-full already uses, and it is why that image
built and this one did not.

The compile-time and run-time compilers are chosen separately: V is built with
clang because that is what debian-build carries, and the runtime image installs
gcc with libc6-dev, which is what V shells out to for the user's program. The
runtime compiler is not constrained by the one V was built with.

Verified by building the image and running it:

  - /etc/os-release reports Debian GNU/Linux 12 (bookworm), not Alpine
  - ldd reports GLIBC 2.36, not musl
  - v version -> V 0.5.2 407c52e
  - v run prints 42, and the binary it produces links
    libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6, i.e. it is a glibc dynamic
    executable and not a musl one
  - v fmt works, which is a subcommand that rebuilds cmd/tools/vfmt from the
    source tree at run time

Reachable while checking this, and worth recording because it looks like the
same bug from the outside: V's Makefile also fetches a prebuilt tcc from
vlang/tccbin, and the linux-amd64 build there is compiled on Ubuntu 24.04 and
wants GLIBC_2.38, which debian:12 does not have. That fetch is not fatal - V
falls back to cc - and the selector has a musl fallback branch, so
`make CC=clang` succeeds on debian:12 unchanged. Only `-cc gcc` breaks it,
because the failure happens earlier and for a different reason.
GitHub rejected both workflows outright: the runs have `jobs: 0` and their
`name` fell back to the file path, which is what GitHub does when a workflow
does not validate. Neither job ever started, so nothing built, and the failure
looks like nothing at all - a workflow that simply never appears as a check.

The cause is the same in both. I put the matrix body directly under
`strategy:`, where GitHub expects one of `matrix`, `fail-fast` or
`max-parallel`, and `os:`/`include:` one level in are not keys it knows:

    strategy:
      os:                          # unknown key
        - alpine

It should be:

    strategy:
      matrix:
        os:
          - alpine

build.yml always had the `matrix:` key, which is why it passed and these two
did not.

Found by running actionlint over the workflows, which reports this as
`unexpected key "os" for "strategy" section` and `unexpected key "include" for
"strategy" section`. My earlier check only parsed the YAML, and a missing
nesting level is valid YAML - it is invalid to GitHub's schema, and Python's
parser cannot tell the difference. actionlint can, and it is the check this
repository should have had from the start.

All four workflows in this repository now pass actionlint. The same run over
vlang/v's workflows flags several pre-existing ones (self-hosted runner labels
actionlint does not know, `concurrency.queue`, and YAML anchors actionlint
cannot follow) - none of those are mine, and none of them are about matrix
nesting.
An audit of the README against the files it describes found ten claims that are
wrong, most of them ones I wrote in this branch. They are worth more than a
typo: a README that overstates reproducibility or states a build dependency
backwards sends someone looking in the wrong place.

  - ":nix is reproducible" overstated. The toolchain is pinned, but the base is
    nixos/nix:latest, which floats. Now says the toolchain is reproducible and
    says plainly that the rootfs is not.
  - "Any nixpkgs library can be made available without root" was never verified
    and the image runs as root. Softened to what is actually true: a library can
    be made available at build time, where the other variants need a second base
    image.
  - Building Dockerfile.nix was said to need a -base and a -build image. It
    needs no -base: both stages stand on nix-build. Dockerfile.alpine and
    Dockerfile.debian do need both.
  - The build-from-source chain skipped --build-arg USER on the second step, so
    the -build image it had just built locally was ignored in favour of the
    published base. Every step now passes it.
  - ":static is ~19 MB" was the compiler binary only. With vlib it is about
    66 MB, which is the number that matters and the one Dockerfile.static's
    comment already recorded.
  - "/src is the working directory in every image" excluded the -base, -build and
    ubuntu images, which use /opt/vlang because they are build and CI images.
  - VTMP and VMODULES were listed as unset, but both are set in :static - the
    same variant the HOME row calls out as the exception. The table now says so.
  - "Every image that clones V takes the revision" excluded Dockerfile.ubuntu,
    which has no V_REV and always clones master. It is named as the exception.
  - The -build/-base row claimed those images carry a C compiler and are built
    from the variant base. -base has none and is built straight from the distro.
  - The nightly badge named a workflow that no longer exists under that name,
    so it rendered as no-status. It points at workflow_lint's sibling,
    nightly_builds.yml now.

The release row in the publishing table also understated what a release run
does: it re-publishes the floating tags as well, and :static only ever receives
:static-<version> from it. Both now stated.

Adds workflow_lint.yml, which runs actionlint over .github/workflows. This is
the check that should have existed when I wrote these files: two of them had the
matrix under strategy: instead of strategy.matrix:, which is valid YAML but
outside GitHub's schema, so GitHub refused to register either workflow. The runs
came back with zero jobs and a name equal to the file path, which looks like
nothing at all rather than like a failure. A Python YAML parse cannot catch that
- it is valid YAML - and actionlint can.

The control was run both ways: the mis-nesting is reported as
`unexpected key "include" for "strategy" section`, and the corrected nesting
comes back clean. All five workflows in this repository now pass actionlint.
`docker/**` covers the Dockerfiles, but the nixpkgs pin now lives in
`nix/flake.nix` as well, and `nix/` was not in the pull_request paths. The
result is an asymmetry: a PR changing only the pin triggered nothing under
`pull_request`, while the identical change pushed to `master` ran the whole
matrix, because `push` has no paths filter at all. A broken pin therefore looked
fine in review and only broke on master.

Adds `nix/**` to the pull_request paths. Every paths filter in this repository
was checked against the file tree afterwards - all 22 resolve to at least one
file, so none is silently dead.
The image is verified now, which it was not before. Building it found three
things that reading the Dockerfile could not:

  1. `v -version` at the end of the build failed with `/bin/sh: v: not found`,
     exit code 127, after `make` had already succeeded. The alpine and debian
     variants get a `/usr/bin/v` symlink from their base image; this image is
     `FROM alpine:3.23` directly and has none. Now `./v -version`, which does not
     depend on the host having the compiler on PATH.

  2. `v` was not on PATH in the final image either, so `docker run
     thevlang/vlang:static v version` failed and the default `CMD ["v"]` was
     unreachable. `/opt/vlang` now goes on PATH, and the image carries the OCI
     labels every other variant has.

  3. The default command cannot be a bare `v`: with no arguments it starts a
     REPL and reports "the V source tree could not be found", which is a poor
     first experience for the image. `CMD ["v", "version"]` instead.

Also corrects the documented reason `v run` does not work. It is not (only) the
missing C compiler: V stops first on the bundled Boehm GC library, which this
image does not carry and which the default GC mode needs before it reaches a
compiler at all. `-gc none` gets past that and then stops on the compiler. Both
the Dockerfile comment and the README now say so.

Verified against the built image on linux/amd64:

  v version                       -> V 0.5.2 ef2ec06
  v run /src/probe.v              -> Boehm GC libgc.a not found
  v fmt /src/x.v                  -> the V source tree could not be found
  /bin/sh                         -> no such file, confirming FROM scratch
  docker run <image> (no args)    -> V 0.5.2 ef2ec06
  as a base for a static binary   -> works

78.6 MB compressed, against roughly 100 MB for the debian and alpine runtime
images. The earlier "19 MB" figure was the compiler binary alone and "66 MB"
was the uncompressed tree; compressed image size is what a user pulls, so that
is the number the README gives.
`Dockerfile.alpine.build` installs clang, gcc, valgrind and friends but no
Boehm GC, and `Dockerfile.alpine`'s runtime stage installs gcc, musl-dev, git
and libc-dev but no GC either. On Debian this never showed, because something in
that much larger package list pulls libgc in as a dependency and
`debian-build` really does have /usr/lib/x86_64-linux-gnu/libgc.so.1. On Alpine
nothing does.

Building :alpine gets as far as linking ./v, prints "V has been successfully
built" and then dies at `@./v -version`, which is GNUmakefile:259:

    vlang#7 472.9 Caching module builtin...
    vlang#7 475.3 builder error: C library `gc:` was not found while linking the
    vlang#7 475.3 generated program.

The module cache is populated with the default GC mode, so libgc is needed to
build V even though V itself is built with `-gc none`.

Adds `gc gc-dev` to the builder and `gc` to the runtime. The runtime needs it
too: every `v run` in the image links with the default GC, so it would fail the
same way for users.

After this, the build gets past that step and hits a different, upstream
problem, reported separately: linking the cached builtin module object fails
with `undefined reference to _vno_main_init_caller` from backtrace(),
backtrace_symbols() and backtrace_symbols_fd(), which musl does not provide and
V implements itself. That one is not fixable here.
A re-audit against the files found five problems. Two of them are the same
mistake the first audit made, in the opposite direction, and the most important
one is a claim about a repository I do not own.

  - The `-build`/`-base` row said the base is "the distro image" and that
    `-build` "has them" for the C compiler. Alpine and nix do ship gcc, but
    debian-build and ubuntu-build install clang and no gcc at all - the comment
    in Dockerfile.debian saying exactly that is where I learned it - and all
    three of those stand on their `-base` image rather than the distro. Split the
    row in two so each half is right on its own.

  - The publishing table said the vlang/v release job passes V_REV and publishes
    `nix` and `static` version tags. It does not: that workflow builds only
    debian and alpine, from V master, and pushes only the floating tags plus the
    two `-dev` images. Everything in the version-tag column describes the state
    *after* vlang/v#29883 merges, which is a change of mine that is still open.
    The README now says so explicitly, and says that `:<version>` does not exist
    yet anywhere. The nightly workflow's comment repeated the same claim about
    `:static-<version>` and is corrected too.

  - nix/README.md said the nixpkgs pin lives in a committed `flake.lock`. There is
    no lock file; the revision is in the flake input URL, which pins the source
    tree but not the dependency graph. Stated accurately now, with the option of
    committing a lock file if that is wanted.

  - The `:nix` row listed `nixos/nix` as its base while the rows above it named
    the direct `-base` image, which read as a difference that is not there.

Worth recording for anyone looking at the registry rather than this repository:
Docker Hub has no `:nix`, `:nix-dev`, `:nix-build` or `:static` tag, and the
published `:debian` and `:alpine` images predate the Boehm GC fix, so `v run` in
them still fails at link time today. None of those workflows has run.

actionlint still passes on all five workflows.
Investigated docker-library/golang, rust-lang/docker-rust and
ziglang/docker-zig against this repository, and wrote up what each does with
six proposals for here.

The headline: Go and Rust do not maintain Dockerfiles, they maintain **templates
and a manifest** and generate them. `Dockerfile-linux.template` reads a `variant`
from the environment and version, arches and sha256 from `versions.json`, and
emits a Dockerfile that picks its own base image, detects the architecture at
build time with a `case` on `dpkg --print-architecture`, verifies the toolchain's
sha256 *and* GPG signature, and clamps timestamps to `SOURCE_DATE_EPOCH` and then
asserts that the clamp worked. One 254-line template serves nine architectures
across six bases and a `tip` channel. Rust does the same with three templates and
`versions.toml`.

This repository maintains 17 hand-written Dockerfiles, and the duplication has
already cost three bugs, all found by building them rather than by reading:
missing Boehm GC on Alpine (09c7446), `:debian` built `FROM
thevlang/vlang:alpine-build` so it was Alpine wearing a Debian tag, and the
matrix nested under `strategy:` instead of `strategy.matrix:` in two workflows —
which GitHub refused to register, so they published nothing and reported nothing.

That third one is the argument for the first proposal: with a template there is
exactly one place for the nesting to be, and `debian` cannot be built from
`alpine-build` because both come from the same `FROM {{BASE}}`.

Zig is included as a deliberate counter-example: one 20-line Dockerfile with
`ARG ZIGVER`, no verification, and a README stating it exists only for their Drone
CI because "Zig makes Docker relevant". A legitimate position, but not the
position we are in - these images are published and consumed by V's own CI.

The proposals are ordered by leverage, and the first one is what makes the rest
cheap: collapse the variants into one template plus a manifest, then move arch
detection into the Dockerfile, then verify downloads, then add arches V's own CI
already builds, then a slim runtime, then reproducible timestamps.
Comment thread docker/vlang/Dockerfile.debian Resolved
A reviewer flagged the missing end-of-line on docker/vlang/Dockerfile.debian.
The same defect is in all nine Dockerfiles in this repository, and it predates
this branch — every one of them lacks a trailing newline on
origin/master, so none of it was introduced here. It is fixed for all nine
rather than just the one that happened to be noticed.

POSIX defines a text file as ending in a newline, so this is not only
tidiness: without it, any future change to the last line of one of these files
shows `\ No newline at end of file` in the diff, which is noise that has to be
read past on every subsequent edit.

Each diff is one line: `-WORKDIR /src` with the marker, then `+WORKDIR /src`
without it. Nothing else in any file moved, and the Dockerfile linter still
passes on all 17.

Adds a step to workflow_lint.yml that fails when a Dockerfile lacks the
terminator, so this cannot come back. The control was run both ways: with a
file that has no newline the step fails and names it, and with only
newline-terminated files it passes. Without that, a step that always passes
would be worse than none.

The check covers `docker/**/Dockerfile*`, which is every Dockerfile this
repository publishes from. The `ubuntu-*` files are included even though no
variant is published from them, because they are Dockerfiles in this repository
and the defect was there too.
…ilename

Proposal 1 from IMAGE-ARCHITECTURE.md. Every fact about a published image now
lives in docker/manifest.json, and docker/render.py writes the Dockerfiles from
it. Go and Rust do the same thing - Dockerfile-linux.template plus versions.json
for Go, three templates plus versions.toml for Rust - and this repository now
does too.

The argument is the bug this prevents, not tidiness. Three bugs came from
hand-maintained files that each looked individually plausible:

  - `Dockerfile.debian` was `FROM thevlang/vlang:alpine-build`, so `:debian` and
    `:alpine` were the same image and the tag meant only the name. With one place
    declaring `debian`'s base, that substitution is not expressible.
  - `Dockerfile.alpine.build` had no `gc`, so `make` failed at `@./v -version`
    after building ./v successfully.
  - Two workflows nested `os:` under `strategy:` instead of `strategy.matrix:`,
    which GitHub refused to register - zero jobs, published nothing, reported
    nothing.

The two `.dev-full` images, the `ubuntu-*` images and `Dockerfile.alpine.minimal`
are not generated. They are hand-maintained and not published by any workflow, so
leaving them alone keeps the diff to what the manifest actually covers.

The generator's correctness test is the check, and the check has a control that
catches the real bug: with `Dockerfile.debian` changed back to
`FROM ...alpine-build`, `render.py --check` exits 1 and names the file; restored,
it exits 0 and the file is byte-identical.

The check compares instructions and ignores comment prose, because the generator
writes the comments and a comment cannot be a source of drift the way a FROM or a
package list can. `workflow_lint.yml` now runs it, so a hand-edited Dockerfile
is a red check rather than a review comment.

Getting there took two fixes to my own generator, both found by building rather
than by reading:

  - `apt_install(..., chained=True)` puts `&& \` on the last package so the next
    line chains the shell command. My first version put a bare `\` there, which
    continued the *apt* command and swallowed `apt-get clean` as a package name -
    a build failure that names the symptom ("Unable to locate package apt-get")
    rather than the cause.
  - The deferred nodejs block inserted a blank line inside what is one RUN
    continuation. A blank line ends it, which turned `wget` into a Dockerfile
    instruction and made the file stop parsing.

Verified by building the generated `Dockerfile.debian` and running it:
Debian 12 / GLIBC 2.36, `v version` prints V 0.5.2 407c52e, `v run` prints 42,
`v fmt` formats, a program importing `net.http` builds and runs, and the binary
it produces links `libc.so.6` - all of which is what the hand-written image did.
Labels are new on the `-base` and `-build` images, which had none.
…fest

Proposals 2 and 6 from IMAGE-ARCHITECTURE.md. Both are Go's
Dockerfile-linux.template, and both are cheaper than they look precisely
because proposal 1 landed first: they are two more facts in the manifest and
one more branch in the renderer, not two more files to keep in step.

## 2. Architecture detection at build time

Each runtime image now carries a case block over `dpkg
--print-architecture` or `apk --print-arch`, mapping to the arches the manifest
declares for that variant. debian gets amd64, arm64, riscv64 and ppc64le - V's
own CI already builds all four - and alpine keeps amd64 and arm64.

The point is not the echo. It is that one Dockerfile serves every architecture,
so `docker build` on riscv64 is the same code path CI takes, instead of a second
path that only buildx exercises. The Debian and Alpine spellings differ
(`ppc64el` against `ppc64le`), which is why the mapping is per package manager
rather than one shared list.

Control, run with a fake `dpkg` so the mapping is testable without a builder
per architecture: amd64, arm64, riscv64 and ppc64el accepted; i386, s390x, armhf
and empty rejected with "unsupported architecture: <name>". Also verified by a
real build, which ran the block and accepted amd64.

## 6. Reproducible timestamps

`git clone` stamps files with the wall clock and `make` with the build time;
COPY then bakes those into layers, so two builds of one commit gave different
digests and "reproducible" had nothing behind it. Each builder stage now clamps
/opt/vlang to SOURCE_DATE_EPOCH and then asserts the clamp held, the way Go does.

The assertion is the part worth having, so its control is the point of this
commit: with the `touch` defeated, the build fails with "timestamps not clamped:
/opt/vlang/v". Without it a touch that silently did nothing would leave the
image non-reproducible while every check said otherwise, which is the shape of
bug this manifest exists to catch.

## Not done: proposal 5, the slim variant

Deliberately. A slim image for V would be `static` minus vlib, and `v` without
vlib cannot find its own stdlib - "the V source tree could not be found", which
is what the static image already documents for `v fmt`. Rust's slim is the
toolchain minus docs; Go's distroless is a runtime with no toolchain. V has
neither shape left: 78.6 MB compressed against ~100 MB is already the whole of
it. Added as a comment on the static entry rather than as a variant that only
looks like progress.

## Verified

The generated debian image still builds and still does what the hand-written
one did: Debian 12 / GLIBC 2.36, `v version` prints V 0.5.2 407c52e, `v run`
prints 42, `v fmt` formats, a program importing net.http builds and runs, and
the binary links libc.so.6. `render.py --check` reports 9 of 9 matching, the
Dockerfile linter 17 files with no problems, actionlint all five workflows, and
every Dockerfile still ends in a newline.
Proposal 6, corrected after measuring it rather than after reading it.

The first version clamped in the builder stage. It passed its own assertion -
"clamped to 1735689600" - and the shipped image still showed the wall clock.
Verified by building with `--target builder` and inspecting both: the builder
held 2025-01-01, the image held 2026-10-09. COPY --from does not preserve
mtimes, so a clamp before the copy is invisible in the result. That is the whole
of the bug, and it is the reason this is worth a commit of its own rather than a
line in the earlier one.

The clamp now runs in the runtime stage, after COPY, on what is actually
shipped. Measured on the built image: /opt/vlang/v, /opt/vlang/v.mod and
/opt/vlang/vlib are all at 2025-01-01, `v version` prints V 0.5.2 407c52e, and
`v run` prints 42.

The claim this is here to support is now measured rather than asserted: two
builds of the same Dockerfile produce the same image digest,
sha256:2703c7dc..., rather than two digests that differ only in timestamps.
That is what "reproducible" has to mean, and before this it meant nothing.

`FROM scratch` is excluded, and the reason is structural rather than an
omission: a scratch stage has no shell, so nothing can run the clamp there.
COPY stamps its files with the build time and the final stage cannot correct
it. debian, alpine and nix are reproducible; static is not. The first attempt
at the static clamp made its build fail outright - `exec: "/bin/sh": stat
/bin/sh: no such file or directory` - which is how that got found.

The assertion stays, and its control is unchanged from the earlier commit:
with the `touch` defeated the build fails with "timestamps not clamped:
/opt/vlang/v". A clamp that silently did nothing would leave the image
non-reproducible while every check said otherwise.

Architecture detection from the previous commit is unaffected and still runs:
the debian image reports "building for amd64" from a real build, and the
mapping control still accepts amd64/arm64/riscv64/ppc64el and rejects i386,
s390x, armhf and empty.
…ssing

The manifest now covers 12 of the 17 Dockerfiles, up from 9. The three
-dev-full images were the most duplicated files left in the repository - three
near-identical hand-maintained files whose only real difference is the compiler,
which is exactly the drift risk the manifest exists to remove.

Generating them also fixed a bug in all three. They referenced ${V_REV}
without re-declaring `ARG V_REV` after the FROM, and an ARG declared before the
first FROM is out of stage scope, so it substituted to the default `master` no
matter what was passed. That is the same bug the runtime images had and the same
one the manifest now cannot express, because both the declaration and the use
come from the same place.

Control, run against the generated file: with the re-declaration removed,
`render.py --check` exits 1 and names the file; with the FROM chain pointed at
`alpine-build` instead of its own variant it also exits 1; restored, it exits 0
and the file is byte-identical. So the check catches both bug classes in the dev
images, not just the runtime ones.

What is new in the generated dev images, beyond the re-declaration: the
`authors` label that debian and alpine had and nix did not, and the same
quoting as the runtime images.

The generated dev description changed from nix's hand-written "Development
image for V on a Nix-pinned toolchain" to the shared wording, because the three
now come from one template. It is less specific about nix but it is accurate,
and the nix-specific facts are in Dockerfile.nix's own header.

Still hand-maintained, and deliberately: the three `ubuntu-*` files and
`Dockerfile.alpine.minimal`. No workflow builds the ubuntu ones, and
alpine.minimal is a third party's image with its own layout, so pulling them
into the manifest would mean restructuring them rather than merely generating
them - a different change from this one.

Verified: 12 of 12 Dockerfiles match the manifest, 17 files lint clean,
actionlint passes on all five workflows, and every Dockerfile still ends in a
newline.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants