Review (typos & minor improvements)
alecandido opened this issue · comments
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 justpkgs
, isn't it?
- it would be nice to link an example of
hardware-configuration.nix
in
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
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:
Custom cache servers
- (Fixed by #117 ) a lump of markup issues
- the first item is marked as
2.
, while the second as1.
-> md takes the freedom of making them sequential, and it renders the1.
as3.
🤦 - 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
- the first item is marked as
- maybe it's just personal preference, but I'd make unsorted even this other nested list
(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
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
Lines 195 to 197 in 490be22
I woud just replaceai
withmy-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)
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
- (Fixed by dfc73a8 ) broken link:
Downgrading or Upgrading Packages
- I would add a footnote (or disclaimer paragraph) about the use of
import
with flakes
it is true that is ubiquitous, especially fornixpkgs
, but you're implicitly relying on the presence of the legacydefault.nix
(the flake way would benixpkgs.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
but I would explain that withimport
you're essentially taking the path, and relying ondefault.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
Module System and Custom Options
- I would mention
nix-darwin
at the same level of NixOS and home manager
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
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
I would rephrase to make it clear that you're settingconfig
, omitting it, since you do not need to declare anyoption
- here I'd avoid
=> config
, since it never needs to evaluate the fullconfig
object, and thusconfig.foo
is already enough
I'd rephrase even the nested points, since the moment you arrive toconfig.foo
you find out that is a leaf, and you conclude the execution, no dependency on the outerconfig
, that's just a value (ok, it is for sure an attribute set because oflib.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
explaining it as a 0th point (i.e. point 1, and shift the others) - (Related to #106 ) and here it could be worth to explain the difference between
if ... then ... else
andlib.mkIf
in greater details, possibly going through the implementation
- 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
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:
andfinal: 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
since, if flakes are enabled, you can just donix repl nixpkgs
(that is a strict subset of the characters above, and makes use of flakes)
but the true question is: do you really needNIX_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)
- I don't have a clear-cut solution, but a proposal could be to turn all the
- 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), buthaskell.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 automaticallynix 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)
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.
@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 😓
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.
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...