2023-07-13 Documentation team meeting notes #63

Agenda

  • updates
  • module system walkthrough

Notes

Updates

  • @henrik-ch: Working on reviewing Raspberry Pi Tutorial and documentation survey
  • @fricklerhandwerk: Have some work that can be taken apart and put into PRs, will note this down somewhere
  • @roberth: Writing about things coming up in Nixpkgs reviews, not much to share right now
  • @zmitchell:
  • @mightyiam: Working on web-devmode PR, could use some help to get it working on Darwin. Got feedback from @pennae
  • @proofconstruction: Working on Raspberry Pi documentation updates, some problems with nixos-hardware modules. Working with @henrik-ch. Works now, but removed graphical support (which most people don’t use anyways).
    • More generally, what to do if something we recommend is broken?
    • @fricklerhandwerk: Be clear about it, say that it doesn’t work, link to hints, encourage PRs. Don’t bother fixing it ourselves
    • @proofconstruction: There was a note for a nix.dev tutorial that it was probably broken, not a great experience
    • @proofconstruction: This tutorial has a recommendation for verbatim configuration.nix that we promote. Updating it requires copying it into gist, tinyurl, copy back
    • @fricklerhandwerk: Let’s not spend too much time on Raspberry Pi work
    • @infinisil: I think it’s fine as it is, could be improved, but better than not working
    • @mightyiam: Why would Raspberry Pi instructions not be in the NixOS manual?
      • @proofconstruction: A bit complicated, can’t work by default. I’m in favor of moving this there, but we’d need to discuss that separately.
  • @alejandrosame:
    • Can we make draft issues?
    • Strategies of better conveying what we do? How to give other people context on what we do? Requires effort but maybe worth it because more people can get involved. Getting pushback from people sometimes
      • @fricklerhandwerk: Can’t get rid of this problem in principle. Load should be on contributors, because maintainers are constrained on time. Spend a bit more time to explain context. Make it reviewable at a glance.
      • @infinisil: I recommend linking to as many things as relevant
      • @fricklerhandwerk: Stop opening new own PR’s, focus on getting your old ones done. It’s hard, but the burden should be on contributors
  • @infinisil: Started writing file structure documentation for Nixpkgs in https://github.com/NixOS/nixpkgs/pull/237439, considering taking ownership of the general structure of the Nixpkgs manual

Module system dive by @roberth

  • @fricklerhandwerk: Generic code to evaluate options, part of lib, used for NixOS, home-manager, nix-darwin, etc. Let’s try to understand the core of it

  • @roberth: Module system evaluation is a fixed-point, so there’s no clear start or end

  • What is a fixed-point? Let’s look at the WIP documentation for it in lib.fix: Improve doc by roberth · Pull Request #242318 · NixOS/nixpkgs · GitHub

    • @fricklerhandwerk: A particular value x for a function f such that f x = x
    • @roberth: Recursion, but factoring out the recursion into a function
    • Laziness makes it work, e.g. allowing attributes from x to depend on other attributes
    • The result of fix f is the fixed-point of f, same as the result from above, x
  • evalModules plays the point of fix, but instead of just tying the know of a single function, it can tie it on multiple, the modules functions

  • The outcome of the module system is a nested attribute set data structure. The module system takes care of enforcing the shape of that attribute set, and the rules for how to merge them.

  • Validation and merging

  • Allows for aspect-oriented programming: Idea to have a program that hooks into another program, every option is like a hook that modules can use, makes it composable

  • The module system doesn’t care where modules come from, but for specific use cases like NixOS, the user modules (configuration.nix), get combined with the base modules provided by NixOS

  • The module system doesn’t have a “default config”, but options can have defaults (these are just definitions with a lower priority though)

  • @infinisil:

    • I recommend watching Nix Hour #19, where I build up a very simple module system
    • I also recommend going through the commit history (in chronological order) here, where every commit shows a practical example of another module system feature being used
  • Team discussion about structure of the module system and evaluation behavior

A typed lazy value lattice tree with docs.

I understand the module system as a configuration data structure producer. In other words, I think the data aspect is priming over the functional aspect.

I also find that focus helps to easier build a mental model.