How to build the Nix manual? (not the Nix man pages)

Development Documentation
1

The implementation of fetchGit primop shows a .doc attribute1 (see snippet below) that is rendered in the “5.2.1 Values” section of the Nix manual.

[1]: Or key? My C++ knowledge is almost nonexistent…

static RegisterPrimOp primop_fetchGit({
    .name = "fetchGit",
    .args = {"args"},
    .doc = R"(
      Fetch a path from git. *args* can be a URL, in which case the HEAD
      of the repo at that URL is fetched. Otherwise, it can be an
      attribute with the following attributes (all except `url` optional):

After building the cloned Nix repo with nix-build (following the instructions in 9.1 Hacking), I couldn’t find the manual in the build result. Was it in one of the man pages and I just missed it?

Am probably missing something basic, but can’t put 2 and 2 together:

  • As far as I can tell, any build command will result in evaluating flake.nix which should build the manual (unless I misinterpreted commands - which is highly likely)

  • Listing .gitignore references a doc/manual/src/expressions/builtins.md, but it is not there after nix-build

  • The doc/manual has a makefile (local.mk) that refers to builtins.md (here) and I can see a bunch of Nix expressions, but couldn’t figure out how to use them yet…

Thanks for any help!

2

@NobbZ to the rescue from chat - thanks again!

NobbZ:

$ nix build nix/2.10.2\#nix^doc
$ ll result-doc/share/doc/nix/manual/ | head
Permissions Links  Size User Group Date Modified    Name
dr-xr-xr-x     13     - root root  1970-01-01 01:00 ./
dr-xr-xr-x      3     - root root  1970-01-01 01:00 ../
dr-xr-xr-x      2     - root root  1970-01-01 01:00 advanced-topics/
dr-xr-xr-x      3     - root root  1970-01-01 01:00 command-ref/
dr-xr-xr-x      2     - root root  1970-01-01 01:00 contributing/
dr-xr-xr-x      2     - root root  1970-01-01 01:00 css/
dr-xr-xr-x      2     - root root  1970-01-01 01:00 expressions/
dr-xr-xr-x      2     - root root  1970-01-01 01:00 figures/
dr-xr-xr-x      4     - root root  1970-01-01 01:00 FontAwesome/

I built from the tag to leverage the cache, as it is a multi-output derivation, building the manual also requires building nix

toraritte:

Thank you! Will give it a try as soon as I can. As for the args nix/2.10.2\#nix^doc - where can I read about this syntax? 2.10.2 is the git tag, but the rest is a bit of a mystery.

NobbZ:

The Nix manual’s “7.5.1.” section (Installables) covers parts of it. The caret ( ^ ) is only mentioned in a recent release note though
It’s the 2.9 release that introduced it: Nix 2.9.0 released

3

Just for completeness, with nix versions prior to 2.9 nix build nix/2.10.2#nix.doc would be the most appropriate replacement.

Without flakes at all I have no clue how to build a “sub output” of a multi-output-derivation though.

2 Likes
4

Note to self: I asked the wrong question in the title instead of what I needed; that is,

How to build the Nix manual that reflects the local changes to the clone NixOS/nix repo?

NobbZ’s answers were spot on on both counts,

Nix version 2.9 or higher: nix build nix/2.10.2\#nix^doc
Nix versions prior 2.9:       nix build nix/2.10.2#nix.doc

but these would build the manual at the commit tagged with 2.10.2 and would thus ignore my local git branch and any changes that have been made. I’m still struggling to understand the flakeRef schemes, but simply using the following worked:

  1. Committing changes1 (TODO: is git add enough?)
  2. nix build .#nix^doc

[1]: Not committed changes will be ignored (at least, they have been in my case). From the Nix manual’s “7.5.1.” section (Installables) again:

Note that the search will only include files indexed by git. In particular, files which are matched by .gitignore or have never been git add-ed will not be available in the flake. If this is undesirable, specify path:<directory> explicitly;

It feels like I actulally need path:<directory>, but wasn’t able to decipher how to use it yet.

1 Like
5

nix build path:/home/toraritte/repos/nixpkgs#nix^doc, should do the trick, substituting your path, of course :wink:

Uncommitted changes shouldn’t be ignored though, as long as you don’t make changes to files in .gitignore.

1 Like
6

Thank you! I guess I was overthinking it…

I did some changes to part of the Nix source that gets pulled into the Nix manual, and none of them showed up after compilation, but once I committed them, they did. Although, as the the quoted section says, git add may be enough. (Will give it a try today, but building the Nix source takes ~30 mins on my laptop so…)