File: content/manuals/build/building/multi-platform.md
Issue
The document contains contradictory information about QEMU requirements for multi-platform builds. In the "Prerequisites" section:
If you're using Docker Engine standalone and you need to build multi-platform
images using emulation, official BuildKit releases bundle QEMU user-mode
emulators, so in most cases you don't need to install QEMU manually.
But then in the "QEMU" strategy section under "Install QEMU manually":
The prerequisites for installing QEMU are:
- Linux kernel version 4.8 or later
binfmt-support version 2.1.7 or later
- The QEMU binaries must be statically compiled and registered with the
fix_binary flag
And then:
Use the tonistiigi/binfmt image to
install QEMU and register the executable types on the host with a single
command:
$ docker run --privileged --rm tonistiigi/binfmt --install all
Why this matters
A reader trying to set up multi-platform builds would be confused about whether they need to manually install QEMU or not. The document first says "you don't need to install QEMU manually" because BuildKit bundles it, but then provides detailed instructions for manual installation without clearly explaining when the bundled version is insufficient. The relationship between the bundled QEMU and the manual installation process is unclear.
Suggested fix
Clarify the conditions under which manual QEMU installation is necessary:
- State clearly that Docker Desktop and recent Docker Engine versions with bundled BuildKit don't need manual QEMU setup
- Explain that manual installation is only needed for:
- Third-party BuildKit packages that don't ship bundled emulators
- Older Docker Engine versions
- Custom BuildKit installations
- Move the manual installation section under a clear heading like "When manual QEMU installation is required" or "Troubleshooting QEMU emulation"
Found by nightly documentation quality scanner
File:
content/manuals/build/building/multi-platform.mdIssue
The document contains contradictory information about QEMU requirements for multi-platform builds. In the "Prerequisites" section:
But then in the "QEMU" strategy section under "Install QEMU manually":
And then:
Why this matters
A reader trying to set up multi-platform builds would be confused about whether they need to manually install QEMU or not. The document first says "you don't need to install QEMU manually" because BuildKit bundles it, but then provides detailed instructions for manual installation without clearly explaining when the bundled version is insufficient. The relationship between the bundled QEMU and the manual installation process is unclear.
Suggested fix
Clarify the conditions under which manual QEMU installation is necessary:
Found by nightly documentation quality scanner