doc: Improve CI docs on env and qemu-user-static

hodlinator commented at 2:08 pm on November 17, 2025: contributor

Should at least partially fix #31199

DrahtBot added the label Docs on Nov 17, 2025

DrahtBot commented at 2:08 pm on November 17, 2025: contributor

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/33887.

Reviews

See the guideline for information on the review process.

Type	Reviewers
ACK	janb84, maflcko
Concept ACK	waketraindev

If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

in ci/README.md:46 in a8afb65ce9 outdated

42+It is often necessary to run the CI system in a clean environment. The `env`
43+utility ensures *only* specified environment variables are propagated into the
44+local CI. Run the test stage with a specific configuration:
45 
46 ```
47 env -i HOME="$HOME" PATH="$PATH" USER="$USER" bash -c 'FILE_ENV="./ci/test/00_setup_env_arm.sh" ./ci/test_run_all.sh'

maflcko commented at 2:17 pm on November 17, 2025:

For reference, this was half-fixed in commit fd813bf863b1ffa91429de6342285b35bab2bfa4 for env vars that have nothing to do with the CI (like DEBUGINFOD_URLS). However, it is still needed for env vars that have a meaning outside and inside CI (like HOST)

However, your HOST is not set, so the comment “Should help in cases such as: #31176 (comment)” may not be accurate here.

hodlinator commented at 3:17 pm on November 17, 2025:

Thanks! Pushed new version which is hopefully slightly more accurate.

maflcko commented at 10:31 am on November 20, 2025:

reminds me that the bash -c isn’t needed here, now that env is used. Feel free to remove, or ignore the unrelated nit.

maflcko commented at 6:48 pm on November 20, 2025:

reminds me that the bash -c isn’t needed here, now that env is used. Feel free to remove, or ignore the unrelated nit.

Added a commit for this to #33903, as that CI pull didn’t have any review yet anyway.

maflcko approved

maflcko commented at 2:21 pm on November 17, 2025: member

lgtm ACK a8afb65ce9b8cd5fe90fcc570087f175c3662cad

nit: Not sure if the commit message is fully correct

hodlinator force-pushed on Nov 17, 2025

waketraindev commented at 4:05 pm on November 17, 2025: contributor

Concept ACK

nit: Please squash the commits per the contributing guidelines: https://github.com/bitcoin/bitcoin/blob/master/CONTRIBUTING.md#squashing-commits

Both commits touch ci/README.md and cover the same scope.

hodlinator commented at 4:12 pm on November 17, 2025: contributor

nit: Please squash the commits per the contributing guidelines: https://github.com/bitcoin/bitcoin/blob/master/CONTRIBUTING.md#squashing-commits

While they do touch adjacent lines, the commits each address separate sub-issues, both with their own links in respective commit message. So I think it’s more orderly like this. But open to squash if other reviewers agree.

in ci/README.md:42 in f8d83ee4d6

39+docker run --rm --privileged docker.io/multiarch/qemu-user-static --reset -p yes
40+```
41+
42+It is recommended to run the CI system in a clean environment. `env -i` below
43+ensures *only* specified environment variables are propagated into the local CI.
44+Run the test stage with a specific configuration:

janb84 commented at 11:42 am on November 18, 2025:

NIT: small grammar suggestion

0It is recommended to run the CI system in a clean environment. The `env -i` command
1below ensures that *only* specified environment variables are propagated into the local CI.
2To run the test stage with a specific configuration:

hodlinator commented at 1:05 pm on November 18, 2025:

Taken in latest push (wrapped at 80 chars).

janb84 commented at 11:56 am on November 18, 2025: contributor

Concept ACK f8d83ee4d631c95ef6e222d7868bfa9e28b66e05

This PR improves the CI documentation, to clarify certain aspects of the CI which raise questions time to time. (see #31199). I would say that the additional information in this PR would stop some questions from being asked. The information provided is (the docker part) is non-trivial to me, and the importance of env-i can be overlooked so the additional information is welcome.

NIT: Small grammar suggestion.

doc: CI - Clarify how important `env -i` is and why

Would hopefully have helped me in this case: https://github.com/bitcoin/bitcoin/pull/31176#issuecomment-2526410039
Since then however, fd813bf863b1ffa91429de6342285b35bab2bfa4 also made sure a minimal environment is used.

2afbbddee5

doc: CI - Describe qemu-user-static usage

Should help in cases such as: https://github.com/bitcoin/bitcoin/pull/31144#issuecomment-2450578651

552eb90071

hodlinator force-pushed on Nov 18, 2025

janb84 commented at 1:13 pm on November 18, 2025: contributor

ACK 552eb90071fd246ba40037f74329403b72453047

changes since last ACK:

grammar changes.

Thanks for incorporating my NIT.

DrahtBot requested review from maflcko on Nov 18, 2025

maflcko commented at 1:17 pm on November 18, 2025: member

lgtm ACK 552eb90071fd246ba40037f74329403b72453047

in ci/README.md:38 in 552eb90071

35+and automatically running them using `qemu`. The following sets us up to do so
36+(also works for `podman`):
37+
38+```
39+docker run --rm --privileged docker.io/multiarch/qemu-user-static --reset -p yes
40+```

maflcko commented at 10:36 am on November 20, 2025:

maybe unrelated, because I think it was working at some point, but using podman on various distros (Debian/Ubuntu/OpenSuse) to try to run the s390x task fails with a segfault in the depends compilation:

 0...
 1[58/817] Building CXX object qtbase/src/tools/bootstrap/CMakeFiles/Bootstrap.dir/__/__/corelib/io/qfsfileengine_iterator.cpp.o
 2[59/817] Building CXX object qtbase/src/tools/bootstrap/CMakeFiles/Bootstrap.dir/__/__/corelib/io/qloggingcategory.cpp.o
 3FAILED: qtbase/src/tools/bootstrap/CMakeFiles/Bootstrap.dir/__/__/corelib/io/qloggingcategory.cpp.o 
 4/usr/bin/g++ -DHAVE_CONFIG_H -DPCRE2_CODE_UNIT_WIDTH=16 -DPCRE2_DISABLE_JIT -DQT_BOOTSTRAPPED -DQT_EXPLICIT_QFILE_CONSTRUCTION_FROM_PATH -DQT_NO_AS_CONST -DQT_NO_CAST_FROM_ASCII -DQT_NO_CAST_TO_ASCII -DQT_NO_DEBUG -DQT_NO_FOREACH -DQT_NO_JAVA_STYLE_ITERATORS -DQT_NO_NARROWING_CONVERSIONS_IN_CONNECT -DQT_NO_QEXCHANGE -DQT_TYPESAFE_FLAGS -DQT_USE_QSTRINGBUILDER -DQT_VERSION_MAJOR=6 -DQT_VERSION_MINOR=7 -DQT_VERSION_PATCH=3 -DQT_VERSION_STR=\"6.7.3\" -D_LARGEFILE64_SOURCE -D_LARGEFILE_SOURCE -I/ci_container_base/depends/work/build/s390x-linux-gnu/native_qt/6.7.3-3eadf23fa87/qtbase/src/corelib/Core_autogen/include -I/ci_container_base/depends/work/build/s390x-linux-gnu/native_qt/6.7.3-3eadf23fa87/qtbase/include -I/ci_container_base/depends/work/build/s390x-linux-gnu/native_qt/6.7.3-3eadf23fa87/qtbase/include/QtCore -I/ci_container_base/depends/work/build/s390x-linux-gnu/native_qt/6.7.3-3eadf23fa87/qtbase/src/corelib -I/ci_container_base/depends/work/build/s390x-linux-gnu/native_qt/6.7.3-3eadf23fa87/qtbase/src/corelib/global -I/ci_container_base/depends/work/build/s390x-linux-gnu/native_qt/6.7.3-3eadf23fa87/qtbase/src/corelib/kernel -I/ci_container_base/depends/work/build/s390x-linux-gnu/native_qt/6.7.3-3eadf23fa87/qtbase/src/corelib/../3rdparty/tinycbor/src -I/ci_container_base/depends/work/build/s390x-linux-gnu/native_qt/6.7.3-3eadf23fa87/qtbase/include/QtCore/6.7.3 -I/ci_container_base/depends/work/build/s390x-linux-gnu/native_qt/6.7.3-3eadf23fa87/qtbase/include/QtCore/6.7.3/QtCore -I/ci_container_base/depends/work/build/s390x-linux-gnu/native_qt/6.7.3-3eadf23fa87/qtbase/src/corelib/../3rdparty/double-conversion/double-conversion -I/ci_container_base/depends/work/build/s390x-linux-gnu/native_qt/6.7.3-3eadf23fa87/qtbase/src/corelib/../3rdparty/double-conversion -I/ci_container_base/depends/work/build/s390x-linux-gnu/native_qt/6.7.3-3eadf23fa87/qtbase/src/corelib/.rcc -I/ci_container_base/depends/work/build/s390x-linux-gnu/native_qt/6.7.3-3eadf23fa87/qtbase/mkspecs/linux-g++ -I/ci_container_base/depends/work/build/s390x-linux-gnu/native_qt/6.7.3-3eadf23fa87/qtbase/include/QtZlib -I/ci_container_base/depends/work/build/s390x-linux-gnu/native_qt/6.7.3-3eadf23fa87/qtbase/src/3rdparty/zlib -I/ci_container_base/depends/work/build/s390x-linux-gnu/native_qt/6.7.3-3eadf23fa87/qtbase/src/3rdparty/pcre2/src -I/ci_container_base/depends/work/build/s390x-linux-gnu/native_qt/6.7.3-3eadf23fa87/qtbase/src/tools/bootstrap/../../corelib/global -I/ci_container_base/depends/work/build/s390x-linux-gnu/native_qt/6.7.3-3eadf23fa87/qtbase/src/tools/bootstrap/.. -I/ci_container_base/depends/work/build/s390x-linux-gnu/native_qt/6.7.3-3eadf23fa87/qtbase/src/tools/bootstrap/../../3rdparty/tinycbor/src -I/ci_container_base/depends/work/build/s390x-linux-gnu/native_qt/6.7.3-3eadf23fa87/qtbase/src/tools/bootstrap/../../3rdparty/pcre2/src -DNDEBUG -O2 -std=gnu++17 -fPIC -fvisibility=hidden -fvisibility-inlines-hidden -Wall -Wextra -ffunction-sections -fdata-sections -Wsuggest-override -MD -MT qtbase/src/tools/bootstrap/CMakeFiles/Bootstrap.dir/__/__/corelib/io/qloggingcategory.cpp.o -MF qtbase/src/tools/bootstrap/CMakeFiles/Bootstrap.dir/__/__/corelib/io/qloggingcategory.cpp.o.d -o qtbase/src/tools/bootstrap/CMakeFiles/Bootstrap.dir/__/__/corelib/io/qloggingcategory.cpp.o -c /ci_container_base/depends/work/build/s390x-linux-gnu/native_qt/6.7.3-3eadf23fa87/qtbase/src/corelib/io/qloggingcategory.cpp
 5Segmentation fault (core dumped)
 6[60/817] Building CXX object qtbase/src/tools/bootstrap/CMakeFiles/Bootstrap.dir/__/__/corelib/io/qiodevice.cpp.o
 7ninja: build stopped: subcommand failed.
 8make: *** [funcs.mk:343: /ci_container_base/depends/work/build/s390x-linux-gnu/native_qt/6.7.3-3eadf23fa87/./.stamp_built] Error 1
 9make: Leaving directory '/ci_container_base/depends'
10Command '['./ci/test/02_run_container.sh']' returned non-zero exit status 2.
11Error: Process completed with exit code 1.

On Fedora, or RHEL-based VMs with podman and qemu-user-s390x it seems to work. A bit odd and unrelated to the code changes here, but I wanted to drop the note somewhere.

hodlinator commented at 6:48 pm on November 20, 2025:

Yes, I’ve seen similar segfaults when building for s390x on NixOS. Don’t know if some distros apply custom patches or use other versions, or if they set up the environment differently in some other way.

fanquake merged this on Nov 20, 2025

fanquake closed this on Nov 20, 2025

doc: Improve CI docs on env and qemu-user-static #33887

Code Coverage & Benchmarks

Reviews