doc: CI - Describe qemu-user-static usage
What the developer wrote
Authored by Hodlinator
doc: CI - Describe qemu-user-static usage
Should help in cases such as: https://github.com/bitcoin/bitcoin/pull/31144#issuecomment-2450578651
What changed, and why it matters
This commit only adds documentation to the CI README explaining how to set up QEMU user-mode emulation for running tests on foreign CPU architectures. It is a pure documentation change with no code modifications, no security fixes, and no functional changes to Bitcoin Core.
No security action required; treat as routine documentation update.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff adds a nine-line paragraph to ci/README.md describing how to run docker run --rm --privileged docker.io/multiarch/qemu-user-static --reset -p yes so that CI containers can emulate non-host architectures via binfmt_misc/qemu-user-static. No source code, build scripts, tests, or configuration files are modified.
Changed components
ci/README.mdInspect captured patch +9 / −0
diff --git a/ci/README.md b/ci/README.md
index 91a3cee3..9abfce14 100644
--- a/ci/README.md
+++ b/ci/README.md
@@ -28,6 +28,15 @@ the CI locally you may need to reduce that entropy by running:
sudo sysctl -w vm.mmap_rnd_bits=28
```
+To run a test that requires emulating a CPU architecture different from the
+host, we may rely on the container environment recognizing foreign executables
+and automatically running them using `qemu`. The following sets us up to do so
+(also works for `podman`):
+
+```
+docker run --rm --privileged docker.io/multiarch/qemu-user-static --reset -p yes
+```
+
It is recommended to run the CI system in a clean environment. The `env -i`
command below ensures that *only* specified environment variables are propagated
into the local CI.
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.