Repository navigation
Conversation
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.
JalonSolov
reviewed
Oct 10, 2026
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this changes
The images published from here were Alpine-only in practice:
Dockerfile.debianbuilt
FROM thevlang/vlang:alpine-build, so:debianand:alpinewere the sameimage and "Debian" meant only the tag.
:ubuntu-buildwas amd64-only. There wasalso no way to build a tag that named a version - only floating tags tracked V
master.
:debianis Debian nowBuilt from
debian-base/debian-build, so a program compiled in it is a glibcbinary that runs on Debian, Ubuntu, Fedora and their derivatives, where a musl
binary from
:alpinedoes not.The build uses
make CC=clang, notVFLAGS='-cc gcc':debian-buildinstallsclang 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 isthe recipe
Dockerfile.debian.dev-fullhas always used, and it is why thatimage built while this one could not.
Two new variants
:nix- the toolchain comes from one pinned nixpkgs revision instead ofapk add/apt install, so the image is reproducible, and any nixpkgslibrary 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- ascratchimage with a static V compiler, forv versionand 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 invlang/v'shub_docker_ci.ymlcan pass the tag and publish:<version>builtfrom exactly that revision.
docker build --build-arg V_REV=0.5.2does the samelocally.
Workflows
docker-containerdriver, so a multi-platform manifest isactually produced (the default builder cannot make one)
vars.PLATFORMS/vars.DOCKER_REPOSITORYgiven fallbacks, so a missingrepository 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 publishingDockerfiles 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-releasereports Debian GNU/Linux 12,lddreportsGLIBC 2.36,
v versionreportsV 0.5.2 407c52e,v runprints 42, and thebinary it produces links
libc.so.6, i.e. it is a glibc dynamic executablerather than a musl one.
v fmtworks too, which is a subcommand that rebuildscmd/tools/vfmtfrom the source tree at run time.:static- the image builds (78.6 MB compressed) and was run:docker run <image> v versionV 0.5.2 ef2ec06docker run <image>(default CMD)V 0.5.2 ef2ec06v run /src/probe.vlibgc.anot foundv fmt /src/x.vthe V source tree could not be found/bin/shFROM scratchBuilding it also fixed three things reading the Dockerfile could not: the
makestep ended withv -versionfailing on a missingPATH,vwasabsent from
PATHin the final image too, andCMD ["v"]could never haveworked because a bare
vstarts 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:
:nixis unbuilt here -nixos/nixis geo-blocked from where this waswritten (CloudFront 403), so the pinned-toolchain idiom it uses is standard
but needs a CI run to be trusted.
linux/amd64only. Theworkflows ask for both architectures, but that path has not run.
:ubuntu-buildgaining arm64 - the workflow change is in place and thepackage 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 isthe 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
tccfromvlang/tccbin, and thelinux-amd64build there is compiled on Ubuntu 24.04 and wants
GLIBC_2.38, whichdebian:12does not have. That fetch is not fatal - V falls back tocc, andthe selector has a musl fallback branch - so
make CC=clangsucceeds ondebian: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>.vfile suffixes belong to a target,and
os_is_target_ofturns out to have no callers in the compiler at all, so itwas never a gate. What actually happens, verified with the local compiler:
-os vinixis accepted (vlib/v/pref/pref.v:190lists it), and C generationworks, 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.cis 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-vinixon an Ubuntu runner.On a vinix image with
vlang/coreutilsNot 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 guestand streams it over serial
run_vm.pydrives that and reads a verdict marker off the console, treatingFATAL EXCEPTIONandKERNEL PANICas failureUSE_TCG=1is set when the host is not Darwin, so no KVM is needed — whichis what makes it workable inside a container
scripts/build-aarch64.sh --no-isoskips the ISO, and vinix's nightly alreadybuilds 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 vinixtarget in CI for thefirst 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.