# How to build the Nix manual? (not the Nix man pages)
**URL:** https://discourse.nixos.org/t/how-to-build-the-nix-manual-not-the-nix-man-pages/20508
**Category:** Documentation
**Created:** [July 22, 2022, 5:01am UTC](https://discourse.nixos.org/t/how-to-build-the-nix-manual-not-the-nix-man-pages/20508 "2022-07-22T05:01:43Z")
**Posts on this page:** 6
**Page:** 1
### Author:  [@toraritte](https://discourse.nixos.org/u/toraritte)
#### Post date: [July 22, 2022, 5:01am UTC](https://discourse.nixos.org/t/how-to-build-the-nix-manual-not-the-nix-man-pages/20508/1 "2022-07-22T05:01:43Z")
The [implementation of `fetchGit` primop](https://github.com/NixOS/nix/blob/6cb41288ac8df00328865f4c66c324452e5a961c/src/libexpr/primops/fetchTree.cc#L337) shows a `.doc` attribute **1** (see snippet below) that is rendered in the [“_5.2.1 Values_” section](https://nixos.org/manual/nix/stable/expressions/language-values.html#:~:text=Paths,%20e.g) of the Nix manual.
[1]: Or key? My C++ knowledge is almost nonexistent…
```cpp
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](https://github.com/NixOS/nix) with `nix-build` (following the instructions in [9.1 Hacking](https://nixos.org/manual/nix/stable/contributing/hacking.html)), I couldn’t find the manual in the [build result](https://gist.github.com/toraritte/220cc2c1e87ae1ef8783a41d88439519). 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`](https://github.com/NixOS/nix/blob/fbd0a6c6e2e87f6679fe5cabaddaa877cf3e5a90/flake.nix) which should build the manual (unless I misinterpreted commands - which is highly likely)
- Listing [`.gitignore`](https://github.com/NixOS/nix/blob/fbd0a6c6e2e87f6679fe5cabaddaa877cf3e5a90/.gitignore#L14-L25) references a `doc/manual/src/expressions/builtins.md`, but it is not there after `nix-build`
- The [`doc/manual`](https://github.com/NixOS/nix/blob/fbd0a6c6e2e87f6679fe5cabaddaa877cf3e5a90/doc/manual/) has a makefile (`local.mk`) that refers to `builtins.md` ([here](https://github.com/NixOS/nix/blob/fbd0a6c6e2e87f6679fe5cabaddaa877cf3e5a90/doc/manual/local.mk#L64-L68)) and I can see a bunch of Nix expressions, but couldn’t figure out how to use them yet…
Thanks for any help!
---
### Author:  [@toraritte](https://discourse.nixos.org/u/toraritte)
#### Post date: [July 22, 2022, 11:43am UTC](https://discourse.nixos.org/t/how-to-build-the-nix-manual-not-the-nix-man-pages/20508/2 "2022-07-22T11:43:43Z")
@NobbZ to the rescue from chat - thanks again!
> _NobbZ_:
>
> > ```auto
> > $ 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)](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix.html?highlight=installable#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](https://discourse.nixos.org/t/nix-2-9-0-released/19407)
---
### Author:  [@NobbZ](https://discourse.nixos.org/u/NobbZ)
#### Post date: [July 22, 2022, 11:52am UTC](https://discourse.nixos.org/t/how-to-build-the-nix-manual-not-the-nix-man-pages/20508/3 "2022-07-22T11:52:44Z")
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.
---
### Author:  [@toraritte](https://discourse.nixos.org/u/toraritte)
#### Post date: [July 23, 2022, 4:39am UTC](https://discourse.nixos.org/t/how-to-build-the-nix-manual-not-the-nix-man-pages/20508/4 "2022-07-23T04:39:28Z")
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 changes **1** (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)](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix.html?highlight=installable#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:` explicitly;
It feels like I actulally need `path:`, but wasn’t able to decipher how to use it yet.
---
### Author:  [@TLATER](https://discourse.nixos.org/u/TLATER)
#### Post date: [July 24, 2022, 10:31am UTC](https://discourse.nixos.org/t/how-to-build-the-nix-manual-not-the-nix-man-pages/20508/5 "2022-07-24T10:31:32Z")
> [@toraritte](#):
>
> It feels like I actulally need `path:` , but wasn’t able to decipher how to use it yet.
`nix build path:/home/toraritte/repos/nixpkgs#nix^doc`, should do the trick, substituting your path, of course 😉
Uncommitted changes shouldn’t be ignored though, as long as you don’t make changes to files in `.gitignore`.
---
### Author:  [@toraritte](https://discourse.nixos.org/u/toraritte)
#### Post date: [July 24, 2022, 2:11pm UTC](https://discourse.nixos.org/t/how-to-build-the-nix-manual-not-the-nix-man-pages/20508/6 "2022-07-24T14:11:49Z")
> [@TLATER](#):
>
> `nix build path:/home/toraritte/repos/nixpkgs#nix^doc`
Thank you! I guess I was overthinking it…
> [@TLATER](#):
>
> Uncommitted changes shouldn’t be ignored though, as long as you don’t make changes to files in `.gitignore` .
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…)