doc: add a guide covering basic rules_nixpkgs use + Nix prerequisites #294
Conversation
evertedsphere
force-pushed
the
es/guide
branch
from
c265953 to
6a4c9e6
Compare
evertedsphere
force-pushed
the
es/guide
branch
5 times, most recently
from
ef4c5fc to
fb5b8f8
Compare
There was a problem hiding this comment.
I left some comments. Great job, I enjoyed going through this! I feel like the beginning of the guide is more polished and you probably spent more time working on it and its wording. There is a noticeable difference in sophistication of writing, which gets simpler and more sketchy towards the end. It would be nice to bring the second half to the same level as the first.
guide.md
Outdated
|
|
||
| TODO: does use flake work with vanilla direnv? nix-direnv is just an improvement over that, i believe | ||
| TODO: use the same nixpkgs.nix for nixpkgs_git_repository and shell.nix | ||
| TODO: is the flake shell pure? because if this is run on a non-nixos system, and /usr/bin/gcc continues to be visible, that messes things up |
There was a problem hiding this comment.
I think it's not, at least not by default.
Generally, the correctness of the described Nix+Bazel setup should not hinge on the purity of the Nix shell.
There was a problem hiding this comment.
If the Nix shell isn't pure, some of the stuff I've written about @local_config_cc not working when in the shell and having that extra insulation from accidentally using the non-hermetic toolchain becomes false, doesn't it?
There was a problem hiding this comment.
True, best to double check with #nix. I don't see --pure flag similar to the nix-shell one on nix develop, only --impure, but IIUC that is about Nix evaluation rather than the resulting shell environment.
| It is entirely possible to make the use of Nix optional in a Bazel setup. To do | ||
| so, we use `bazelrc` configs to only enable Nix-specific configuration when a | ||
| `--config` flag is provided, like so: |
There was a problem hiding this comment.
Additionally, the WORKSPACE file needs to configure both a nix provided toolchain and a non-nix alternative, e.g. the default bindist. It is important that the nix provided one is registered first, meaning before the non-nix one. The reason is that the nix one is marked with an additional execution platform constraint, which is provided by the nixpkgs platform defined with the --host_platform flag. However, the default bindist toolchain typically has no corresponding platform constraint indicating a non-nix platform, and would therefore also be a valid choice on the nix platform. If the nix toolchain is defined after the non-nix when, then it would never be selected by Bazel.
There was a problem hiding this comment.
Hadn't thought about that, I'll make a note of this.
As for defining a non-Nix toolchain, the rules_cc_toolchains() call takes care of that, right?
There was a problem hiding this comment.
I've added a note about this; could you check that it makes sense? (I wasn't really sure what the "default bindist" specifically referred to.)
There was a problem hiding this comment.
Thanks, yes, that makes sense. The exact shape of the "default bindist" depends on the language. With cc its implicit since it's builtin to Bazel. With other languages it would be your rules_XXX_toolchains call, or similar that sets this up, e.g. here for Go.
evertedsphere
force-pushed
the
es/guide
branch
5 times, most recently
from
c5b2877 to
f9fd614
Compare
|
IIUC https://github.com/tweag/rules_nixpkgs_cc_template is the worked example for this user-guide, correct? Could you pull it into the rules_nixpkgs repository and add a test for it to CI? (Probably best in its own PR). rules_haskell does the same with its tutorial. That makes sure that the example is tested in CI, and that changes to the example can happen along-side the relevant changes to the guide and vice-versa. |
guide.md
Outdated
| it wants and will fail to work. | ||
|
|
||
| Now developers on different platforms can enter a development environment by | ||
| running `nix develop`, and this environment will be identical across platforms. |
There was a problem hiding this comment.
this environment will be identical across platforms
Nit: I think I know what you're getting at, but it's a bit ambiguous. Is the user-guide only targeting Linux or is it also expected to work on MacOS? The reason I'm asking: Arguably "across platforms" would also mean across Linux and MacOS. But, in that case the environment is not identical, on MacOS it'll include Darwin executables instead of Linux ones.
There was a problem hiding this comment.
I've changed this to "consistent" instead of "identical".
As for the first question: I wrote the guide with Linux in mind. Not sure if it would work elsewhere, but perhaps we can investigate macOS compatibility and try to make it work if we have a reasonable number of macOS users.
There was a problem hiding this comment.
Makes sense. Focusing on Linux first seems perfectly fair and I'm happy to leave MacOS for follow-up work. In that case it should just be stated somewhere that this guide is only targeting Linux and we'd also need an issue on rules_nixpkgs to track the MacOS support.
evertedsphere
force-pushed
the
es/guide
branch
6 times, most recently
from
cf250bd to
371c842
Compare
If direnv creates a .direnv directory to link in Nix store paths then we need to instruct Bazel to ignore that tree. Otherwise, commands like `bazel build //...` lead to very confusing errors about failing to load packges underneath `.direnv/...`.
evertedsphere
changed the title
|
Should be mergeable now. Let me know if any more changes are necessary. |
Add an initial version of a rules_nixpkgs guide (fix #269)
The target audience is Bazel users new to Nix, so I've taken care to not assume Nix-related knowledge and to introduce the minimum amount of information required to be able to start using the ruleset.
For the purposes of this version, we only target Linux; #371 tracks macOS support.