| 12 Jan 2024 |
 @qyriad:matrix.org | In reply to @asymmetric:matrix.dapp.org.uk
feel free to share what your experience has been like, i'm sure we can learn from it. either here or in private if you prefer I can't speak for Chris McDonough, but I can't imagine this conversation inspires much faith in this Nix community's friendliness. | 00:52:11 |
 @9999years:matrix.org | In reply to @qyriad:matrix.org
Last time I checked there surprisingly was not a single book which covers nix. I feel like a comprehensive book which teaches nix from the ground up and explains all the different ways of using nix would really help me and I would purchase such a book without hesitation if it existed.
There really does need to be a document you can read cover to cover to understand the Nix ecosystem. Nix itself, Nixpkgs, and NixOS modules can't really be understood independently in any kind of useful way. Obviously it can't cover the entire API surface of Nixpkgs, but programming books don't cover the entire API surface of the standard library either — but they should teach you enough to be able to read std docs and — critically — read and understand source code in the ecosystem!
the fact that the nix docs, the nixpkgs docs, and the nixos docs are not allowed to refer to concepts from their siblings is a big part of this -- it would be quite nice, for instance, if the nix manual explained that derivations are packages, as was proposed here https://github.com/NixOS/nix/pull/9378#discussion_r1401478906 | 01:02:17 |
| @9999years:matrix.org | this is the sort of connective tissue that's missing -- all the information is there, but users have a hard time finding it, and part of the reason for that is there's so many places to look for any given piece of information | 01:02:58 |
 infinisil | 9999years: I think it's more that Nix is the underlying foundation, Nixpkgs is based on Nix, and NixOS is based on Nixpkgs | 01:10:06 |
| infinisil | So the dependency chain is strictly NixOS -> Nixpkgs -> Nix. There's no arrows back | 01:11:00 |
| infinisil | So generally I don't think there should be explanations of concepts making use of such back-arrows.
However, in order to find information, I'd be in favor of a mechanism that automatically inserts back-links in all documentation | 01:12:06 |
| infinisil | So if Nixpkgs links from stdenv.mkDerivation's docs to the ones for derivation, in the derivation docs you'd see a little "this page is linked to from the stdenv.mkDerivation docs" link | 01:12:48 |
| @qyriad:matrix.org | In reply to @infinisil:matrix.org
9999years: I think it's more that Nix is the underlying foundation, Nixpkgs is based on Nix, and NixOS is based on Nixpkgs this helps you understand how the Nix ecosystem is implemented, not how it's used or how and why it's useful | 01:13:33 |
| @9999years:matrix.org | i mean it would certainly be useful to say in the nix manual "derivation is used to implement higher-level packaging tools like stdenv.mkDerivation in nixpkgs" | 01:13:47 |
| @9999years:matrix.org | having recently helped several beginners get started with nix i can confirm this sort of thing trips new users up pretty consistently | 01:14:18 |
| infinisil | 9999years: Maybe yeah, but also, I've thought multiple times before to just ditch builtins.derivation and use builtins.strictDerivation instead in Nixpkgs, which would then outdate the docs on the Nix side | 01:15:08 |
| infinisil | The Nix codebase generally really doesn't know how it's used. And there could be various Nixpkgs versions that are each implemented differently | 01:16:11 |
| @9999years:matrix.org | yeah i mean, this is one of the issues with nix's docs -- nixpkgs and nix are deeply intertwined, but they can't be versioned together, even trivial stuff like lib | 01:16:47 |
| infinisil | I think such automated back-links might be a good compromise tbh | 01:17:01 |
| infinisil | Needs a unified docs building infrastructure though | 01:17:11 |
| @9999years:matrix.org | yeah automated back-links would be great. i still think additional human-written context would be useful but back-links would be a fantastic start | 01:17:28 |
| @9999years:matrix.org | (and lots more backlinks) | 01:17:42 |
| @qyriad:matrix.org | agreed | 01:17:50 |
| @qyriad:matrix.org | automated backlinks would be great, but why should we compromise on providing clear, understandable information in documentation? | 01:18:18 |
| infinisil | Wrong docs are imo worse than missing docs | 01:18:35 |
| @9999years:matrix.org | e.g. the stdenv.mkDerivation docs don't actually link to builtins.derivation or explain that mkDerivation is a wrapper around builtins.derivation and not a separate thing
https://nixos.org/manual/nixpkgs/unstable/#sec-using-stdenv | 01:18:48 |
| infinisil | And if we write information about Nixpkgs in Nix, that can easily become wrong | 01:18:53 |
| @qyriad:matrix.org | In reply to @9999years:matrix.org
e.g. the stdenv.mkDerivation docs don't actually link to builtins.derivation or explain that mkDerivation is a wrapper around builtins.derivation and not a separate thing
https://nixos.org/manual/nixpkgs/unstable/#sec-using-stdenv oh wow it doesn't even do that? o.o | 01:19:03 |
| @9999years:matrix.org | i'm not saying we should have a ton of nixpkgs docs, but we should feel comfortable referring to high-level nixpkgs concepts that are unlikely to change (like mkDerivation, the override and overlay systems, etc.) | 01:19:33 |
| infinisil | I'd be okay with that yeah | 01:19:51 |
| @9999years:matrix.org | explaining that things like overlays are just implemented as regular nix expressions would help users understand that they're not magical features or hard-coded into nix | 01:20:09 |
| @9999years:matrix.org | but right now you basically just have to ask an expert or read the source code, and the nixpkgs source code for the stdenv stuff, overlays, overrides, and so on is gnarly especially for beginners | 01:20:33 |
| @qyriad:matrix.org | In reply to @infinisil:matrix.org
And if we write information about Nixpkgs in Nix, that can easily become wrong vice versa is also true. certainly what's cross-explained can be limited, but something as simple as "derivation is used to implement higher-level packaging tools like stdenv.mkDerivation in Nixpkgs. See link for more information" | 01:20:38 |
| infinisil | In reply to @9999years:matrix.org
explaining that things like overlays are just implemented as regular nix expressions would help users understand that they're not magical features or hard-coded into nix Reminds me of https://github.com/NixOS/nixpkgs/pull/248220 and https://github.com/NixOS/nixpkgs/pull/255132 | 01:20:58 |
| @qyriad:matrix.org | In reply to @9999years:matrix.org
explaining that things like overlays are just implemented as regular nix expressions would help users understand that they're not magical features or hard-coded into nix this would be fantastic | 01:21:54 |
