2023-06-22 - Learning Journey Working Group - Meeting Notes #14

2023-06-19 Documentation team meeting notes #56


Last week came up with 4 ideas about tutorials to write github tracking issue

  • Tutorial for building a simple Builder (e.g. buildPythonApplication)

    • @zmitchell Picking a language to build for
      • @brianmcgee Python dependency management is painful
      • But it’s ubiquitous! Lots of people know it (data scientists etc)
      • Should pick a language with a not-too-difficult build/dependency system
    • @brianmcgee Valuable to do this because:
      • Shows how to package dependencies
      • Shows different phases (checkPhase, buildPhase)
    • writeTextFile
      • writeScriptBin makes it easier
      • writeShellApplication has dependencies
    • @brianmcgee Building a (modular) devShell
      • Cleaning it up, making it more modular, decomposing complexity
      • Breaking long in-line script sections up
  • Packaging existing software

    • @proofconstruction Don’t want to use C/C++/Fortran
    • Go look at nixpkgs, find a similar package, copy from it!
    • @zmitchell differences in building Rust packages for aarch64-darwin (Foundation libraries, libiconv, etc)
    • @brianmcgee Using ~nix-locate~ (from nix-index in nix-community)
    • @zmitchell Maybe we should browse packages in nixpkgs to find a “simple” one
      • This turns out to be harder than expected.
      • Lots of Rust packages only have Rust deps
  • Sharing dependencies between default.nix and shell.nix

    • @zmitchell Less complicated than the other tutorials, can use a dummy package
    • buildPythonApplication
    • maybe Go?
    • @zmitchell making a separate repo for code used in the tutorials

Action items

  • Assigning tutorial outlines
  • Someone needs to get input on which builder to use for the derivation phases tutorial
1 Like

Another thing we talked about before we started taking notes:

I made a post asking for tutorial feedback (see here) and we got precisely zero feedback. It could be that I didn’t post early enough, but it’s more likely that I should just post in the “Help” section next time since we’re actively looking for help/input/visibility.

1 Like

We also talked about:

  • Derivation phases
    • We want to illustrate build phases by building our own builder
    • Need to pick a builder (buildPythonApplication, buildRustPackage, etc)
      • Needs to be in the sweet spot of interesting/instructive and not too complicated
    • We need input on which one would be a good example, none of the attendees know the internals all that well

I personally would enjoy an introduction to nix that branches off before hitting package management use cases: it’s a data description language. That is not unique, but it is. It is unique in that it has string contexts (tightly coupled to derivation).

I feel by bypassing that primordial branch in the mental model, we foreclosure an entire use case class to the nix learner.


Totally agree…

Personally I don’t like the strong focus on package management in general.

Many things about nix and using it are so much easier if you stop thinking of it as a package manager, but instead as data description language like cue, dhall, or yaml even and/or a build tool with extended functionality.

There are several ways on top of the build tool which are more or less suitable for “package management”.

  • NixOS configuration
  • System manager
  • Nix Darwin
  • Home manager
  • nix-env
  • nix profile

Some of these do a bit more than just package management, but at the same they work by using nix as build tool and data language.


I fully agree, and as I have noted in a previous post-meeting discussion, there is a lot of resistance to acknowledging that, taking a few steps back, and teaching Nix principles from the ground up. The reason is that configuration (or package) management is one of the most popular use cases for Nix, and many people are naturally interested in just getting things done. Which is exactly the point of view nix.dev as high-level documentation is catering to, and that is fine.

We can still do more of the ground work in the Nix manual, and some of that is happening continuously in the background. For instance, @ericson2314, @roberth and me have recently merged a description of the Nix simplified file system model.


Yeah quite simply, the future is beating Bazel. We’ve already beaten APT and RPM.

I suspect that many people will only come around to this view once there is a new killer-app. Everyone is used to package manager stuff, Flakes promotes package manager stuff. The Nix community is rather resigned to slow rebuilds and hacking around that with impure things inside Nix shells.

But once there is a working demo of “flawless incremental nix-build” the more practical minded-people will see there is a whole new very useful thing that should be taught early on.


So sorry that I missed all of this discussion, not sure how I didn’t get a notification for it.

Many things about nix and using it are so much easier if you stop thinking of it as a package manager, but instead as data description language like cue, dhall, or yaml

This is a good point that I hadn’t really grokked before, and I think presenting the Nix language this way to beginners would be really helpful. It may even be described this way already, but it’s only just now that it sunk in for me (sorry, maybe I’m dense :slight_smile: ). I think until now I’ve thought of Nix as a language for describing build instructions.

I think it would be valuable to have a “Concepts” document along the lines of “Nix as a data description language” that goes like this (idea shamelessly stolen from a talk @garbas recently gave):

  • Start with a Dockerfile for a development environment (installs some packages, sets environment variables, etc).
  • Convert the Dockerfile to JSON to show how you would represent the environment declaratively while still using a format most developers are familiar with.
  • Convert the JSON to Nix, demonstrating that Nix is primarily a data format (plus functions), and incidentally that this data can be used to build software.

There’s something like this in the Nix language basics guide, but I think a page dedicated to this idea would help to illustrate the point.

1 Like