Review (typos & minor improvements)

[alecandido]

Sorry to bother again: this time, I decided to avoid filing many more issues, and to collect feedback in a single evolving one.
Maybe it will end up being a list of one element, but I want to prevent large noise generation.

Moreover, now I'd prefer reading your book cover-to-cover. When I'll approach the end, I hope I will have some time left and author a PR myself (or multiple, if needed) to fix anything that is still on this list.

Minor improvements

NixOS with flakes enabled

• (Fixed by 0091296 ) I guess it's a typo, but the first occurrence of nixpkgs.pkgs should be just pkgs, isn't it?
  

  nixos-and-flakes-book/docs/nixos-with-flakes/nixos-with-flakes-enabled.md

  Line 258 in 6754096

  - At the beginner stage, you can consider its default value to be `nixpkgs.legacyPackages."${system}"`, and the value of `nixpkgs.pkgs` can be customized through the `nixpkgs.pkgs` option.

• it would be nice to link an example of hardware-configuration.nix in
  

  nixos-and-flakes-book/docs/nixos-with-flakes/nixos-with-flakes-enabled.md

  Line 261 in 6754096

  - It is typically used to import additional NixOS modules and can be found in most NixOS auto-generated `hardware-configuration.nix` files.

  
  but I found no authoritative examples, and most of the people end up customizing it (so it is unreliable to link personal configs)
  currently, the best alternative I can propose is to link the (almost empty) nixos-generate-config wiki page
• (Fixed by a15b7c7) _module.args is actually documented in each appendix (of NixOS, nix-darwin, and home manager), cf. https://nixos.org/manual/nixos/stable/options#opt-_module.args
  

  nixos-and-flakes-book/docs/nixos-with-flakes/nixos-with-flakes-enabled.md

  Lines 278 to 279 in 6754096

  	1. `_module.args`: Its only official documentation is in the source code below.
  	- [nixpkgs/nixos-23.11/lib/modules.nix - _module.args]

  
  this documentation is exactly the one extracted from the description, but I would say is a better reference
• a reference to some discussion could be appreciated here:
  

  nixos-and-flakes-book/docs/nixos-with-flakes/nixos-with-flakes-enabled.md

  Line 286 in 6754096

  The NixOS community generally recommends prioritizing the use of the `_module.args` option and resorting to `specialArgs` only when `_module.args` cannot be used.

Custom cache servers

• (Fixed by Fix ordered list numerals #117 ) a lump of markup issues
  

  nixos-and-flakes-book/docs/nixos-with-flakes/add-custom-cache-servers.md

  Lines 13 to 17 in 6754096

  	2. Add cache servers for some third-party projects, such as the nix-community cache server [https://nix-community.cachix.org](https://nix-community.cachix.org), which can significantly improve the build speed of these third-party projects.
  	1. Adding a mirrored cache server to accelerate downloads.
  	1. The access speed of the official cache server in China is slow. Without a local global proxy, it is almost unusable. Adding Chinese Nix cache mirrors like ustc/sjtu/tuna can alleviate this issue.
  	How to Add Custom Cache Servers {#how-to-add-custom-cache-servers}

  • the first item is marked as 2., while the second as 1. -> md takes the freedom of making them sequential, and it renders the 1. as 3. 🤦
  • the nested 1. is a list of one item - I'd suggest making it unsorted
  • (Fixed by 0c21b86 ) How to Add ... appears like a section title, but it's a plain paragraph
• maybe it's just personal preference, but I'd make unsorted even this other nested list
  

  nixos-and-flakes-book/docs/nixos-with-flakes/add-custom-cache-servers.md

  Lines 23 to 24 in 6754096

  1. cache mirror's data are directly synchronized from the official cache server. Therefore, their public keys are the same as those of the official cache server, and you can use the public key of the official cache server without additional configuration.

  2. This entirely trust-based public key verification mechanism transfers the security responsibility to users. If users want to use a third-party cache server to speed up the build process of a certain library, they must take on the corresponding security risks and decide whether to add the public key of that cache server to `trusted-public-keys`. To completely solve this trust issue, Nix has introduced the experimental feature [ca-derivations](https://nixos.wiki/wiki/Ca-derivations), which does not depend on `trusted-public-keys` for signature verification. Interested users can explore it further.

  
  (I usually go for numbering only when I want to reference it later, or when I want to stress the count)
• while the CA blog posts by Tweag, linked on the cited wiki page, have been an incredibly interesting reading
  

  nixos-and-flakes-book/docs/nixos-with-flakes/add-custom-cache-servers.md

  Line 52 in 490be22

  experimental feature [ca-derivations](https://nixos.wiki/wiki/Ca-derivations), which

  
  there is not much about trust, that is instead cited here. Maybe a better reference could be https://github.com/nix-community/trustix
• trivial typo
  

  nixos-and-flakes-book/docs/nixos-with-flakes/add-custom-cache-servers.md

  Line 165 in 490be22

  ai = nixpkgs.lib.nixosSystem {

  
  

  nixos-and-flakes-book/docs/nixos-with-flakes/add-custom-cache-servers.md

  Lines 195 to 197 in 490be22

  	> If your system hostname is not `my-nixos`, you need to modify the name of
  	> `nixosConfigurations` in `flake.nix` or use `--flake /etc/nixos#my-nixos` to specify the
  	> configuration name.

  
  I woud just replace ai with my-nixos, since more explicitn (though Ai Hoshino is great :P)

Modularize the configuration

• it is true that modules are defined in nixpkgs (as mostly the rest of NixOS), but I believe the canonical reference about modules to be in the NixOS docs (in particular the dedicated, extended, writing modules section)
  

  nixos-and-flakes-book/docs/nixos-with-flakes/modularize-the-configuration.md

  Line 27 in 6754096

  > I only found a description of `imports` in [Nixpkgs-Unstable Official Manual - evalModules Parameters](https://nixos.org/manual/nixpkgs/unstable/#module-system-lib-evalModules-parameters): `A list of modules. These are merged together to form the final configuration.` It's a bit ambiguous...

  
  in particular, there is an explicit section about imports (not that contains much more information, but it is definitely more friendly)
• once more: the docs are provided in the NixOS manual, ordering section
  

  nixos-and-flakes-book/docs/nixos-with-flakes/modularize-the-configuration.md

  Line 188 in 6754096

  > I haven't found the official documentation for list-type options, but I simply understand that they are types whose merge results are related to the order of merging. According to this understanding, both `list` and `string` types are list-type options, and these functions can indeed be used on these two types in practice.

• (Fixed by dfc73a8 ) broken link:
  

  nixos-and-flakes-book/docs/nixos-with-flakes/modularize-the-configuration.md

  Line 299 in 6754096

  - [Module System - Nixpkgs](https://github.com/NixOS/nixpkgs/blob/eab660d/doc/module-system/module-system.chapter.md)

Downgrading or Upgrading Packages

• I would add a footnote (or disclaimer paragraph) about the use of import with flakes
  

  nixos-and-flakes-book/docs/nixos-with-flakes/downgrade-or-upgrade-packages.md

  Line 39 in 4536260

  pkgs-stable = import nixpkgs-stable {

  
  it is true that is ubiquitous, especially for nixpkgs, but you're implicitly relying on the presence of the legacy default.nix (the flake way would be nixpkgs.legacyPackages...)
  it is a nice workaround even in other situations, but it's better that you know what you're doing
  Ah, actually there was a related not here
  

  nixos-and-flakes-book/docs/nixos-with-flakes/downgrade-or-upgrade-packages.md

  Line 100 in 4536260

  > According to [1000 instances of nixpkgs](https://discourse.nixos.org/t/1000-instances-of-nixpkgs/17347), it's not a good practice to use `import` in submodules or subflakes to customize `nixpkgs`. Each `import` creates a new instance of nixpkgs, which increases build time and memory usage as the configuration grows. To avoid this problem, we create all nixpkgs instances in `flake.nix`.

  
  but I would explain that with import you're essentially taking the path, and relying on default.nix (btw, it's legacy only top-level, and perfectly fine elsewhere)
• (Fixed by 6d986d7 ) Maybe use inherit? It doesn't change anything, but it is idiomatic, and I believe could be good for a beginners' book
  

  nixos-and-flakes-book/docs/nixos-with-flakes/downgrade-or-upgrade-packages.md

  Line 42 in 4536260

  system = system;

Module System and Custom Options

• I would mention nix-darwin at the same level of NixOS and home manager
  

  nixos-and-flakes-book/docs/other-usage-of-flakes/module-system.md

  Line 8 in 6754096

  > If you are using nix-darwin too, its configuration is similar, and its module system is implemented in [nix-darwin/modules](https://github.com/LnL7/nix-darwin/tree/master/modules).

  
  and it also has its online docs (though not a search engine, to the best of my knowledge, but you can use "find in the page")
  https://daiderd.com/nix-darwin/manual/index.html
• while it is certainly true that modules are implemented in Nixpkgs,
  

  nixos-and-flakes-book/docs/other-usage-of-flakes/module-system.md

  Lines 10 to 16 in 6754096

  	The foundation of the aforementioned NixOS Modules and Home Manager Modules is a universal module system implemented in Nixpkgs, found in [lib/modules.nix][lib/modules.nix]. The official documentation for this module system is provided below (even for experienced NixOS users, understanding this can be a challenging task):
  	- [Module System - Nixpkgs]
  	Because the documentation for Nixpkgs' module system is lacking, it directly recommends reading another writing guide specifically for NixOS module system, which is clearer but might still be challenging for newcomers:
  	- [Writing NixOS Modules - Nixpkgs]

  
  I would still refer the reader (even in this section) to the NixOS docs first, section "Writing modules", and then also the corresponding nixpkgs "Modules system" section as a further reading (and pointing to the rendered docs)
• here there is some confusion, since the shortcut is not related to a pure declaration, but a missing one
  

  nixos-and-flakes-book/docs/other-usage-of-flakes/module-system.md

  Line 161 in 6754096

  In the example above, the way we assign values to `options` is actually a kind of **abbreviation**. When a module declares only `options` without `config` (and other special parameters of the module system), we can omit the `config` prefix and directly use the name of `options` for assignment.

  
  I would rephrase to make it clear that you're setting config, omitting it, since you do not need to declare any option
• here I'd avoid => config, since it never needs to evaluate the full config object, and thus config.foo is already enough
  

  nixos-and-flakes-book/docs/other-usage-of-flakes/module-system.md

  Line 208 in 6754096

  1. Example 1 evaluation flow: `config.warnings` => `config.foo` => `config`

  
  I'd rephrase even the nested points, since the moment you arrive to config.foo you find out that is a leaf, and you conclude the execution, no dependency on the outer config, that's just a value (ok, it is for sure an attribute set because of lib.mkOption, but you could pretend it's the default value...)
• here, instead, I would add an initial config.warnings =>, since the starting point (CLI invocation) is always the same
  

  nixos-and-flakes-book/docs/other-usage-of-flakes/module-system.md

  Line 215 in 6754096

  2. Example 2: `config` => `config.foo` => `config`

  
  explaining it as a 0th point (i.e. point 1, and shift the others)
• (Related to Module system's merging algorithm and differences between lib.mkMerge, lib.mkIf & lib.attrsets.mergeAttrsList, lib.optionals. #106 ) and here it could be worth to explain the difference between if ... then ... else and lib.mkIf in greater details, possibly going through the implementation
  

  nixos-and-flakes-book/docs/other-usage-of-flakes/module-system.md

  Line 223 in 6754096

  The key lies in the function `lib.mkIf`. When using `lib.mkIf` to define `config`, it will be lazily evaluated by Nix. This means that the calculation of `config = lib.mkIf ...` will only occur after the evaluation of `config.foo` is completed.

• migrate all links to the rendered docs
  

  nixos-and-flakes-book/docs/other-usage-of-flakes/module-system.md

  Lines 357 to 361 in 6754096

  	[Module System - Nixpkgs]: https://github.com/NixOS/nixpkgs/blob/23.11/doc/module-system/module-system.chapter.md
  	[Writing NixOS Modules - Nixpkgs]: https://github.com/NixOS/nixpkgs/blob/nixos-23.11/nixos/doc/manual/development/writing-modules.chapter.md
  	[Option Definitions - NixOS]: https://github.com/NixOS/nixpkgs/blob/nixos-23.11/nixos/doc/manual/development/option-def.section.md
  	[Option Declarations - NixOS]: https://github.com/NixOS/nixpkgs/blob/nixos-23.11/nixos/doc/manual/development/option-declarations.section.md
  	[Options Types - NixOS]: https://github.com/NixOS/nixpkgs/blob/nixos-23.11/nixos/doc/manual/development/option-types.section.md

Overriding

• there is an abrupt switch from the description of .override to .overrideAttrs, without an explicit comparison (nor any introduction)
• a reference to the official docs could be valuable
  https://nixos.org/manual/nixpkgs/stable/#chap-overrides
• the description of nix repl usage is interspersed and redundant

Overlays

• stress that self: super: and final: prev: are equivalent, and that the latter is the "modern" terminology, while the first is still present in many places
  https://nixos.wiki/wiki/Overlays

Custom NIX_PATH and Flake Registry

• Not the best example
  

  nixos-and-flakes-book/docs/best-practices/nix-path-and-flake-registry.md

  Lines 16 to 18 in 490be22

  	However, in certain scenarios, we still need to use `NIX_PATH`, such as when we frequently
  	use the command `nix repl '<nixpkgs>'`, which utilizes the Nixpkgs found through
  	`NIX_PATH` search.

  
  since, if flakes are enabled, you can just do nix repl nixpkgs (that is a strict subset of the characters above, and makes use of flakes)
  but the true question is: do you really need NIX_PATH at all with flakes?

The Ingenious Uses of Multiple nixpkgs Instances

• considering this is a book about flakes, it is a bit controversial to have all these import nixpkgs around (in this and previous sections), and then cite the 1000 instances of nixpkgs
  • I don't have a clear-cut solution, but a proposal could be to turn all the import nixpkgs in inputs, possibly differently named inputs with the same URL (I have to check that this actually works, but I don't see why it should not)
• btw, better to link directly the blog post, rather than the forum post advertising it

Packaging 101

• This post by Serokell is worth a mention, given the scope of the book (flakes) and the introductory nature
  https://serokell.io/blog/practical-nix-flakes#packaging-existing-applications
• I would keep it simple, and provide a few opinionated examples, including
  • a straightforward example with trivial builders https://nixos.org/manual/nixpkgs/stable/#chap-trivial-builders
  • a Python example with Poetry (using poetry2nix, it can be really trivial)
  • a Rust example with Cargo (using crane, it can also be quite straightforward)
  • Serokell's Haskell is simple, but I'm not enough opinionated on Haskell to include it myself
    • it is using Cabal, but even Stack is quite popular, and I guess it be could more aligned to the flakes experience...
    • it is using cabal2nix (an official NixOS project), but haskell.nix seems to have enough momentum as well, and even better docs, supporting both Cabal and Stack...
    • I'm not enough opinionated on Haskell to suggest anything for an introduction...

Development Environments on NixOS

• it is worth mentioning direnv, since it is useful, but it could also handle automatically nix develop shell behavior https://discourse.nixos.org/t/using-nix-develop-opens-bash-instead-of-zsh/25075/6

Dev Environments

• devenv supports flakes, and it's pretty convenient (I will shamelessly link my templates)
• "Dev Environment for Python" -> I mostly write Python code (not my favorite language, but widespread enough) and devenv saved me the day (works with virtualenv and Poetry out of the box)

[ryan4yin]

Thank you very much for your review. I have just fixed some of the problems and updated them on this issue, and I will continue this work later in my free time.

[alecandido]

@ryan4yin as I wrote above, I wanted to first go through the book, to have a full overview (there are different things that you note during the first reading, or after completion - this issue is to save the first kind).

However, for the remaining ones I will contribute myself :)

This is a great collection, since Nix has valuable docs, but the information is scattered in infinite places, and there is so little for the entry level...
So, I found out that I really like to contribute to the book, because then I'll be more confident to tell other people to start using Nix ("it's simple, there's a great book explaining it!").

The only piece I won't be able to contribute to for sure will be the Chinese translation, I'm sorry 😓

[ryan4yin]

I wanted to first go through the book, to have a full overview (there are different things that you note during the first reading, or after completion - this issue is to save the first kind).

Got it.

However, for the remaining ones I will contribute myself :)

This is a great collection, since Nix has valuable docs, but the information is scattered in infinite places, and there is so little for the entry level... So, I found out that I really like to contribute to the book, because then I'll be more confident to tell other people to start using Nix ("it's simple, there's a great book explaining it!").

Very much looking forward to your contribution! ❤️

The only piece I won't be able to contribute to for sure will be the Chinese translation, I'm sorry 😓

It's not a problem. I'll take care of the Chinese part.

[ryan4yin]

FYI: I have just fixed a lot of markup issues & typos via spellchecker & code formatter: #122 #123 #124 #125

[alecandido]

FYI: I have just fixed a lot of markup issues & typos via spellchecker & code formatter: #122 #123 #124 #125

That is great. For ease of writing (and referencing) I would also suggest formatting the files on 80-100 columns.
I know this could be controversial, and most editors are able to wrap the lines. But, e.g., the preview of GitHub is not wrapping at all...

[ryan4yin]

I would also suggest formatting the files on 80-100 columns.

Done, Everything seems to be fine after the change. #126

[thngz]

helix example of flake and module system chapter has a small typo in the comment, you probably meant "choose" not "chose"

[ryan4yin]

you probably meant "choose" not "chose"

@thngz Fixed by dae7350

[iambeingtracked]

nixos-and-flakes-book/docs/nixos-with-flakes/introduction-to-flakes.md

Line 83 in 359c119

the New CLI, which Flakes relies on, and the old CLI.

Shouldn't it say "which Flakes rely on"? Is "Flakes" used as the name of the feature in Nix or as a plural noun?

[iedame]

Some small nits I found while translating the book to Portuguese:

1. docs/en/development/intro.md
In this page you have an example that uses nix shell nixpkgs#hello nixpkgs#cowsay, but in the comments it still says: ponysay is also available.

I suppose the example was changed from ponysay to cowsay and the comment needs to be updated.

2. docs/en/nixos-with-flakes/modularize-the-configuration.md
There is a typo in the word "attribute". It's currently written as attritbute.

[ryan4yin]

@iedame Thanks for the correction; the update has been applied.