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/35375.

Reviews

See the guideline for information on the review process.

If your review is incorrectly listed, please copy-paste <!--meta-tag:bot-skip--> into the comment that the bot should ignore.

Thank you for your contribution. Some developers working on this project maintain https://github.com/bitcoin-dev-tools/bix , which defines a fairly comprehensive nix dev environment. I think the utility for documenting a slimmer setup, like done here, is rather limited, so I'm tending towards Concept NACK here.

@sedited Thanks for the quick reply! I simply was not aware of that project. If that's the preferred way of building using Nix, I think it should be linked in the documentation. AFAICT, there are no references to bix as of now. When I wanted to build Core, I followed the README at the root of the project and only found info for various OSes.

I've looked at their flake file. It's still somewhat "arbitrary" as it uses Clang and not GCC, for example. It's also way more complicated than the code I'm proposing here, which mainly aims to teach a person how to create their own env quickly.

What do you think would be the best way to proceed?

1. Do nothing, not add any documentation, and close this PR.
2. Document bix instead.
3. Extend the current document with a bix section.

I'm personally in favor of (3). Not because I've already written this, but because it's the most flexible:

• It gives context on Nix for users who might be new
• Points to a simple recipe that is easy to understand
• Would point to a more realistic recipe that's maintained by developers, via bix
• In the future, if more workflows related to Nix are created, it can be all listed there. For example, I mention in the doc how you can use Nix to swap between GCC and Clang, or do ASan builds. This can be provided later.

WDYT?

I think setting up a simple environment is pretty trivial. Anybody who is already motivated enough to read a nix documentation section, can probably do so with minimal effort anyway. Maybe @willcl-ark has an opinion on how and whether we should give some guidance to nix users.

Sure, happy to hear @willcl-ark's opinion on this. In general, I'm OK with this not being merged if people don't want this. Not trying to be pushy in any way, just trying to clarify.

I just think it is quite arbitrary not to include Nix if there are instructions on how to install via apt, etc. Yet Nix is a much more powerful tool allowing for use cases I mentioned above. So it's not simply about this basic recipe and more about having a place to collect future advanced use cases. But I'd be also happy to do so in my own repo somewhere.

I also could have waited and collected those locally and then submitting, but I'm worried that it'll turn a simple doc change into a monumental task and it never gets done. In my experience, small incremental steps are easier.

I am also thinking if the existing doc/build-unix.md could be stripped down to remove Fedora, Alpine and Arch. The only difference is the name of the package manager program and possibly the names of the packages themselves.

If we want to keep them, a simple table with the package manager name and package name should be sufficient (with or without nix).

Something Nix related in this repo could be useful, but the current text is too verbose. If somebody wants to learn about Nix, what it is, how it works, or how to install it, they can go to https://nix.dev/ or https://nixos.org/. We don't need to repeat documentation/context from those websites here, content in this repo should stay specific to Bitcoin Core.

Yes I think we should consider carfeully what we want to add here, nix-wise, as there are many possibilites.

1. A build derivation (flake or default) could live at the root of the repo. Note that this is already in nixpkgs here in some form, although this can't easily be used to build a checked out tree. An in-tree (flake) version might look like this (ignoring the static packageSet which I was playing with).
2. a devShell/shell.nix. This is useful for developers, but we don't usually add tooling-specific stuff here which makes sense, as there are infinite numbers of tools.
3. We could also combine both of the above, into a package derivation and devShell

These might cater to different crowds; it's quite nice to say to users "to build the binary run nix build .". Devs may appreciate a standardised dev environment to use, as well as build functionality.

I suppose this comes down to "what problem are we trying to solve here".

I am also thinking if the existing doc/build-unix.md could be stripped down to remove Fedora, Alpine and Arch. The only difference is the name of the package manager program and possibly the names of the packages themselves.

In any case, I do like the idea of simpler table naming package manager and package names, and not repeating the instructions ~verbatim multiple times.

There are several comments and proposals, let me try to summarize them to make them actionable:

1. @sedited leans negative, has concerns about duplication of the Bix effort and the basic env being too simple.
2. @maflcko proposes to simplify the distro section of unix notes (potentially integrating Nix there), 👍 by @stickies-v.
3. @fanquake is positive on Nix notes but wants shorter text, 👍 by me.
4. @willcl-ark shares options on various build recipes we could add, likes the idea of a table for unix as well.

Comments to the above:

1. I would like to have Nix included because we have instructions for other package managers. The purpose of docs is to help people get started quickly. I'm okay with linking to Bix and dropping the simple shell.nix. Bix uses nix develop and a lockfile, so it should help with reproducibility. It also creates one space for Nix users to collaborate.
2. I'm okay with this in general, but I think it should be a separate PR. However, it needs to be done such that important context is not dropped. For example, there are useful comments there right now explaining why each dependency is needed.
3. Agreed on verbosity, will just link to upstream docs.
4. I would be glad if we had top-level build files, but they would need to be flexible enough to serve various use cases. It also endorses one particular package manager, which people might not want to do. I think it's better to focus on docs for now, there is very little downside or risk with adding them as opposed to code that needs to work and be tested. We cannot even agree on a simple doc change, the build recipes will be a huge discussion. I think it's better to focus on polishing Bix for now and having docs pointing there.

My refined proposal:

• I will keep this file as separate and avoid refactoring the Unix distro section.
• I will shorten the Nix description and point to the upstream docs instead.
• I will remove the sample shell.nix file and link to Bix instead.
• I will verify that Bix works as of now and allows me to build the project and run tests as with the original shell.nix file.

Could you please react with 👍 or 👎 to this proposal? If 👎 , please share why.

In general, I would like to make a small step to having better documentation instead of having a huge discussion about it. Let's make this first step and then we can separately discuss other things on other PRs. Again, not trying to be pushy, but it's very hard to make progress when we're discussing multiple things at the same time or have conflicting opinions. I hope that the plan presented above is a good compromise.

Simplified according to the refined proposal above, confirmed that Bix works as of today.

I think this is ready to be merged and looks way better than the original version.

Ah, one second, let me edit the PR description as well to match the new doc structure.

Updated, ready for review.

If that's the preferred way of building using Nix, I think it should be linked in the documentation. AFAICT, there are no references to bix as of now. When I wanted to build Core, I followed the README at the root of the project and only found info for various OSes

Concept ACK on linking to bix. Fwiw, I also didn't know about it. I have been using uncomputable/bitcoin-nix-tools.

I suppose this comes down to "what problem are we trying to solve here".

I think a minimal nix section with a link to bix would be nice to solve the problem of not knowing about it.

I am also thinking if the existing doc/build-unix.md could be stripped down to remove Fedora, Alpine and Arch. The only difference is the name of the package manager program and possibly the names of the packages themselves.

If we want to keep them, a simple table with the package manager name and package name should be sufficient (with or without nix).

Fixed in #35402