Nix language deep dive (with `nix repl`)

[zmitchell]

As part of the tutorial series being worked on by the Learning Journey WG we need a tutorial going over the Nix language. We recognize that there's an existing tutorial on nix.dev (Nix language basics). The existing guide is very thorough and we don't want to supplant that guide, but for the purposes of a quick introduction we want a short guide motivated by explaining a real piece of Nix code such as a functioning shell.nix.

• [ ] Prepare an outline of the tutorial
• [ ] Prepare a draft of the tutorial
• [ ] Submit the draft as a PR

Tutorial contents

• Provide the reader with a functioning shell.nix that builds a Python environment
• This example should have enough complexity to illustrate basic language features:
  • Function definitions (the whole file is a function definition)
  • Function application
  • Passing anonymous functions as arguments via python.withPackages
  • Variables, lists, attribute sets, etc
  • Navigating attribute sets via the dot operator
  • etc

How

• Where to put the result: A new file in https://github.com/NixOS/nix.dev/tree/master/source/tutorials
• Person to contact for help:
  • Technical: @infinisil
  • Editorial: @zmitchell

[zmitchell]

@roberth assigned to you for feedback

[roberth]

for the purposes of a quick introduction we want a short guide motivated by explaining a real piece of Nix code such as a functioning shell.nix.

We have another tutorial for that, and editing a file isn't particularly inviting. I think in this tutorial we should teach readers how to learn the language and the library. For this I think the nix repl is a great vehicle.

To make this nicely hands-on, we could start with

nix repl <nixpkgs>

and then introduce concepts in a way they can follow along.

This way we can both teach the fundamental principles, and teach them how to experimentally write solutions for their configuration needs.

• language basics

  • bindings in the repl vs let
    • start with this. The repl is the first instance of a scope they'll see, and we can take it from there
  • (as listed in the issue description)

• discovering functions

  • lib.strings.<TAB>, etc
  • noogle

• finding documentation

  • Nixpkgs manual
  • doc via source with ctrl+click in IDE terminal (e.g. vscode)

    nix-repl> lib.fix
    «lambda @ /home/user/h/nixpkgs/lib/fixed-points.nix:19:9»
    

    ctrl+click the file:line string
  • :doc for primops, or maybe that's redundant if we also mention...
  • noogle

• generate a config file

  • pkgs.formats
  • almost an end goal? While they could use the generated file from the CLI, they'll want to use it in e.g. a NixOS module instead.

[fricklerhandwerk]

That sounds good, as the repl is traditionally extremely underexposed, and there are many nice little tricks one can cover to make life easier. We'd need to frame it within an achievable goal though, and possibly chunk it into multiple parts that @roberth outlined.

[fricklerhandwerk]

Given we're still lacking a thorough introduction to the language, I renamed the issue to be the equivalent of the module system deep dive tutorial. I imagine this would be a good place for nix repl, debugging https://github.com/NixOS/nix.dev/issues/774, and thunks https://github.com/NixOS/nix.dev/pull/824