dfd1045284
7476b46f1893a4858616d2a8456a7c43238851ed guix: Build dmg as a static binary (Carl Dong) 06d6cf6784421290e6235fe8684d5e08ed6f1b62 depends: libdmg-hfsplus: Skip CMake RPATH patching (Carl Dong) 65176ab5730dff34466caaecdd292625ef8294fc guix: Remove codesign_allocate+pagestuff from unsigned tarball (Carl Dong) ca85679eb43b8375a95d82101977829d08fb1e1b guix: Use clang-toolchain instead of clang (Carl Dong) 1aec0eda8fd31a57b0621eea616398017c2ead98 guix: Fallback to local build for substitute-enabled Guix users (Carl Dong) 1742f8e12d163852df09575e03edcd3db73198ee guix: Add early health check for guix-daemon (Carl Dong) c1ae726a13ecfa5e7e9fdc3030a8110b8bb263f8 guix: More thoroughly control native toolchain (Carl Dong) 39741128d3775d198dbee34dc827353bfd18acd8 guix: Supply --link-profile (Carl Dong) d55a1056ee565afed64e42d6f6efb6b0adc5599b guix: Add troubleshooting documentation entries (Carl Dong) 7f401c953f8bb3574cec48561e13ef3b47dedc6e guix: Adapt guix-build to prelude, restructure hier (Carl Dong) 4eccf063b252bfe256cf72d363a24cf0183e926e guix: Remove guix-build.sh filename extension (Carl Dong) 7753357a7bae98ec775c707b9dec4cea1e945802 guix: Add source-able bash prelude and utils (Carl Dong) e5b49a01f5d0f631e7f08f86ca8a2c2b8213319f guix: Create windeploy inside distsrc-* (Carl Dong) 3e9982ab3877eb8fe0a8c0cb3d847ac0913c7336 contrib: Silence git-describe when looking for tag (Carl Dong) d5a71e97853ea9e1b879e8c76bfb01d4bef33172 guix: Use --cores instead of --max-jobs (Carl Dong) Pull request description: This PR addresses a few hiccups encountered by the brave souls who've been experimenting with the Guix scripts: - Resolves confusion between `--cores=` and `--max-jobs=` - `guix`'s `--cores=` actually corresponds to make's `--jobs=`, so let's just control `--cores=` with our overridable env var - `git-describe` will scream `fatal: no tag exactly matches '<hash>'` when looking for a tag, but we don't care, so silence that - `windeploy/unsigned` should be inside `distsrc-*` and created idempotently (sorry I know this one annoyed people) - Add troubleshooting documentation to `README.md` - Add early health check for `guix-daemon` in case user forgot to start a `guix-daemon` - Depending on configuration, a `--fallback` flag may be needed to tell Guix to not fail if substitutes fail but fallback to building locally - `codesign_allocate` and `pagestuff` are now unnecessary for codesigning as we're now using `signapple` A few robustness changes are also included: - We supply the `--link-profile` flag, as some Guix packages may expect the profile to be available under `$HOME/.guix-profile` - We now clear and manually set all toolchain-related env vars (e.g. `C*_INCLUDE_PATH`) ourselves, after patching a Qt::moc bug - We use the native `clang-toolchain` package for darwin builds instead of `clang`, lining up with all our other toolchain packages. Finally, we restructure the guix building hierarchy such that it looks something like: ``` guix-build-<short-hash-or-version-tag> ├── distsrc-<short-hash-or-version-tag>-${HOST} │ ├── contrib │ ├── depends │ ├── src │ └── ... ├── distsrc-<short-hash-or-version-tag>-... └── output ├── dist-archive │ └── bitcoin-<short-hash-or-version-tag>.tar.gz ├── *-linux-* │ ├── bitcoin-<short-hash-or-version-tag>-*-linux-*-debug.tar.gz │ └── bitcoin-<short-hash-or-version-tag>-*-linux-*.tar.gz ├── x86_64-apple-darwin18 │ ├── bitcoin-<short-hash-or-version-tag>-osx64.tar.gz │ ├── bitcoin-<short-hash-or-version-tag>-osx-unsigned.dmg │ └── bitcoin-<short-hash-or-version-tag>-osx-unsigned.tar.gz └── x86_64-w64-mingw32 ├── bitcoin-<short-hash-or-version-tag>-win64-debug.zip ├── bitcoin-<short-hash-or-version-tag>-win64-setup-unsigned.exe ├── bitcoin-<short-hash-or-version-tag>-win64.zip └── bitcoin-<short-hash-or-version-tag>-win-unsigned.tar.gz ``` Separating guix builds by their version identifier (basically namespacing them) allows us to change the layout in the future without worry about potential naming conflicts. ACKs for top commit: sipa: ACK 7476b46f1893a4858616d2a8456a7c43238851ed laanwj: ACK 7476b46f1893a4858616d2a8456a7c43238851ed Tree-SHA512: 0e899aa941aafdf552b2a7e8a08131ee9283180bbef7334439e2461a02aa7235ab7b9ca9c149b80fc5d0a9f4bbd35bc80fcee26197c0836ba8eaf2d86ffa0386 |
||
---|---|---|
.. | ||
libexec | ||
patches | ||
guix-build | ||
manifest.scm | ||
README.md |
Bootstrappable Bitcoin Core Builds
This directory contains the files necessary to perform bootstrappable Bitcoin Core builds.
Bootstrappability furthers our binary security guarantees by allowing us to audit and reproduce our toolchain instead of blindly trusting binary downloads.
We achieve bootstrappability by using Guix as a functional package manager.
Requirements
Conservatively, a x86_64 machine with:
- 16GB of free disk space on the partition that /gnu/store will reside in
- 8GB of free disk space per platform triple you're planning on building (see
the
HOSTS
environment variable description)
Setup
Installing Guix
If you're just testing this out, you can use the Dockerfile for convenience. It automatically speeds up your builds by using substitutes. If you don't want this behaviour, refer to the next section.
Otherwise, follow the Guix installation guide.
Note: For those who like to keep their filesystems clean, Guix is designed to be very standalone and will not conflict with your system's package manager/existing setup. It only touches
/var/guix
,/gnu
, and~/.config/guix
.
Choosing your security model
Guix allows us to achieve better binary security by using our CPU time to build everything from scratch. However, it doesn't sacrifice user choice in pursuit of this: users can decide whether or not to bootstrap and to use substitutes (pre-built packages).
After installation, you may want to consider adding substitute servers from which to download pre-built packages to speed up your build if that fits your security model (say, if you're just testing that this works). Substitute servers are set up by default if you're using the Dockerfile.
If you prefer not to use any substitutes, make sure to supply --no-substitutes
like in the following snippet. The first build will take a while, but the
resulting packages will be cached for future builds.
export ADDITIONAL_GUIX_COMMON_FLAGS='--no-substitutes'
Likewise, to perform a bootstrapped build (takes even longer):
export ADDITIONAL_GUIX_COMMON_FLAGS='--no-substitutes' ADDITIONAL_GUIX_ENVIRONMENT_FLAGS='--bootstrap'
Using a version of Guix with guix time-machine
capabilities
Note: This entire section can be skipped if you are already using a version of Guix that has the
guix time-machine
command.
Once Guix is installed, if it doesn't have the guix time-machine
command, pull
the latest guix
.
guix pull --max-jobs=4 # change number of jobs accordingly
Make sure that you are using your current profile. (You are prompted to do this
at the end of the guix pull
)
export PATH="${HOME}/.config/guix/current/bin${PATH:+:}$PATH"
Controlling the number of threads used by guix
build commands
By default, the scripts under ./contrib/guix
will invoke all guix
build
commands with --cores="$JOBS"
. Note that $JOBS
defaults to $(nproc)
if not
specified. However, astute manual readers will also notice that there is a
--max-jobs=
flag (which defaults to 1 if unspecified).
Here is the difference between --cores=
and --max-jobs=
:
Note: When I say "derivation," think "package"
--cores=
- controls the number of CPU cores to build each derivation. This is the value
passed to
make
's--jobs=
flag.
--max-jobs=
- controls how many derivations can be built in parallel
- defaults to 1
Therefore, the default is for guix
build commands to build one derivation at a
time, utilizing $JOBS
threads.
Specifying the $JOBS
environment variable will only modify --cores=
, but you
can also modify the value for --max-jobs=
by specifying
$ADDITIONAL_GUIX_COMMON_FLAGS
. For example, if you have a LOT of memory, you
may want to set:
export ADDITIONAL_GUIX_COMMON_FLAGS='--max-jobs=8'
Which allows for a maximum of 8 derivations to be built at the same time, each
utilizing $JOBS
threads.
Or, if you'd like to avoid spurious build failures caused by issues with parallelism within a single package, but would still like to build multiple packages when the dependency graph allows for it, you may want to try:
export JOBS=1 ADDITIONAL_GUIX_COMMON_FLAGS='--max-jobs=8'
Usage
As a Tool for Deterministic Builds
From the top of a clean Bitcoin Core repository:
./contrib/guix/guix-build.sh
After the build finishes successfully (check the status code please), compare hashes:
find output/ -type f -print0 | sort -z | xargs -r0 sha256sum
Recognized environment variables
-
HOSTS
Override the space-separated list of platform triples for which to perform a bootstrappable build. (defaults to "x86_64-linux-gnu arm-linux-gnueabihf aarch64-linux-gnu riscv64-linux-gnu powerpc64-linux-gnu powerpc64le-linux-gnu x86_64-w64-mingw32 x86_64-apple-darwin18")
-
SOURCES_PATH
Set the depends tree download cache for sources. This is passed through to the depends tree. Setting this to the same directory across multiple builds of the depends tree can eliminate unnecessary redownloading of package sources.
-
BASE_CACHE
Set the depends tree cache for built packages. This is passed through to the depends tree. Setting this to the same directory across multiple builds of the depends tree can eliminate unnecessary building of packages.
-
SDK_PATH
Set the path where extracted SDKs can be found. This is passed through to the depends tree. Note that this is should be set to the parent directory of the actual SDK (e.g. SDK_PATH=$HOME/Downloads/macOS-SDKs instead of $HOME/Downloads/macOS-SDKs/Xcode-11.3.1-11C505-extracted-SDK-with-libcxx-headers).
-
JOBS
Override the number of jobs to run simultaneously, you might want to do so on a memory-limited machine. This may be passed to:
guix
build commands as inguix environment --cores="$JOBS"
make
as inmake --jobs="$JOBS"
xargs
as inxargs -P"$JOBS"
(defaults to the value of
nproc
outside the container) -
SOURCE_DATE_EPOCH
Override the reference UNIX timestamp used for bit-for-bit reproducibility, the variable name conforms to standard. (defaults to the output of
$(git log --format=%at -1)
) -
V
If non-empty, will pass
V=1
to allmake
invocations, makingmake
output verbose.Note that any given value is ignored. The variable is only checked for emptiness. More concretely, this means that
V=
(settingV
to the empty string) is interpreted the same way as not settingV
at all, and thatV=0
has the same effect asV=1
. -
SUBSTITUTE_URLS
A whitespace-delimited list of URLs from which to download pre-built packages. A URL is only used if its signing key is authorized (refer to the substitute servers section for more details).
-
ADDITIONAL_GUIX_COMMON_FLAGS
Additional flags to be passed to all
guix
commands. For a fully-bootstrapped build, set this to--bootstrap --no-substitutes
(refer to the security model section for more details). Note that a fully-bootstrapped build will take quite a long time on the first run. -
ADDITIONAL_GUIX_TIMEMACHINE_FLAGS
Additional flags to be passed to
guix time-machine
. -
ADDITIONAL_GUIX_ENVIRONMENT_FLAGS
Additional flags to be passed to the invocation of
guix environment
insideguix time-machine
.
Tips and Tricks
Speeding up builds with substitute servers
This whole section is automatically done in the convenience Dockerfiles
For those who are used to life in the fast (and trustful) lane, you can specify substitute servers from which to download pre-built packages.
For those who only want to use substitutes from the official Guix build farm and have authorized the build farm's signing key during Guix's installation, you don't need to do anything.
Step 1: Authorize the signing keys
For the official Guix build farm at https://ci.guix.gnu.org, run as root:
guix archive --authorize < ~root/.config/guix/current/share/guix/ci.guix.gnu.org.pub
For dongcarl's substitute server at https://guix.carldong.io, run as root:
wget -qO- 'https://guix.carldong.io/signing-key.pub' | guix archive --authorize
Step 2: Specify the substitute servers
The official Guix build farm at https://ci.guix.gnu.org is automatically used
unless the --no-substitutes
flag is supplied.
This can be overridden for all guix
invocations by passing the
--substitute-urls
option to your invocation of guix-daemon
. This can also be
overridden on a call-by-call basis by passing the same --substitute-urls
option to client tools such at guix environment
.
To use dongcarl's substitute server for Bitcoin Core builds after having authorized his signing key:
export SUBSTITUTE_URLS='https://guix.carldong.io https://ci.guix.gnu.org'
Troubleshooting
Derivation failed to build
When you see a build failure like below:
building /gnu/store/...-foo-3.6.12.drv...
/ 'check' phasenote: keeping build directory `/tmp/guix-build-foo-3.6.12.drv-0'
builder for `/gnu/store/...-foo-3.6.12.drv' failed with exit code 1
build of /gnu/store/...-foo-3.6.12.drv failed
View build log at '/var/log/guix/drvs/../...-foo-3.6.12.drv.bz2'.
cannot build derivation `/gnu/store/...-qux-7.69.1.drv': 1 dependencies couldn't be built
cannot build derivation `/gnu/store/...-bar-3.16.5.drv': 1 dependencies couldn't be built
cannot build derivation `/gnu/store/...-baz-2.0.5.drv': 1 dependencies couldn't be built
guix time-machine: error: build of `/gnu/store/...-baz-2.0.5.drv' failed
It means that guix
failed to build a package named foo
, which was a
dependency of qux
, bar
, and baz
. Importantly, note that the last "failed"
line is not necessarily the root cause, the first "failed" line is.
Most of the time, the build failure is due to a spurious test failure or the package's build system/test suite breaking when running multi-threaded. To rebuild just this derivation in a single-threaded fashion:
$ guix build --cores=1 /gnu/store/...-foo-3.6.12.drv
If the single-threaded rebuild stil did not succeed, you may need to dig deeper.
You may view foo
's build logs in less
like so (please replace paths with the
path you see in the build failure output):
$ bzcat /var/log/guix/drvs/../...-foo-3.6.12.drv.bz2 | less
foo
's build directory is also preserved and available at
/tmp/guix-build-foo-3.6.12.drv-0
. However, if you fail to build foo
multiple
times, it may be /tmp/...drv-1
or /tmp/...drv-2
. Always consult the build
failure output for the most accurate, up-to-date information.
python(-minimal): [Errno 84] Invalid or incomplete multibyte or wide character
This error occurs when your $TMPDIR
(default: /tmp) exists on a filesystem
which rejects characters not present in the UTF-8 character code set. An example
is ZFS with the utf8only=on option set.
More information: https://bugs.python.org/issue37584
FAQ
How can I trust the binary installation?
As mentioned at the bottom of this manual page:
The binary installation tarballs can be (re)produced and verified simply by running the following command in the Guix source tree:
make guix-binary.x86_64-linux.tar.xz
Is Guix packaged in my operating system?
Guix is shipped starting with Debian Bullseye and Ubuntu 21.04 "Hirsute Hippo". Other operating systems are working on packaging Guix as well.