Nix language primer with `shell.nix`

[zmitchell]

The Learning Journey WG identified that the second tutorial in the learning journey should be a tutorial walking the user through creating a shell.nix. This is the tracking issue for discussion on this tutorial and related work.

• [x] Compile a survey of shell.nix tutorials (@khaled)
• [x] Consider if there are elements of existing tutorials that we should include
• [ ] 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 small, functioning shell.nix installing Python
• Explain that once you've experimented with packages via nix-shell -p you can enter the same environment repeatedly by declaring it in a shell.nix file.
• You can also use shell.nix to configure other aspects of the environment:
  • Environment variables
  • Shell hooks
  • Shell prompts
• Illustrate how to add packages to the shell, explaining the basic differences between buildInputs and packages
• This shell.nix will just grab nixpkgs from <nixpkgs>, leaving pinning, channels, etc to later tutorials

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

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-04-13-learning-journey-working-group-meeting-notes-4/27255/1

[khaled]

A collection of existing tutorials with notes about what they cover:

Posts

• An introduction to nix-shell (2020/07/08)

  • Compares with language specific version managers such as Rvm, nvm and asdf
  • Gets right into Python, Rust, NodeJS, Ruby examples
  • Pinning & channels
  • Per-user extensions
  • Platform specific stuff for Darwin
  • Use with Docker (previous linked post)
    • Points out benefits over Docker

• Effortless dev environments with Nix and direnv (2022/10/23) (flakes)

  • Direnv
  • External environments (use flake <url>)
  • Layered environments via multiple use flakes

• How Nix-Shell Saved Our Team’s Sanity (2021/10/27)

  • Benefits for multi-language apps
  • Pinning

• A Tutorial Introduction To Nix (2020/08/18)

  • Pinning with Niv
  • Lorri + Direnv
  • Purity
  • Shell Hooks
  • Project-local Python
  • Custom Packages
  • --argstr

• Howto manage shareable, reproducible Nix environments via nix-shell (2023/01/09)

  • Pinning
  • Python + pythonPackages

• Environments with Nix Shell - Learning Nix pt 1 (2018/01/29)

  • Explains subset of nixlang used in basic shell.nix

• Tools You Should Know About: nix-shell (2021/12/19)

  • Good writeup on the why of nix/nix-shell
  • Pinning with Niv
  • Direnv
  • How to figure out package names
  • nix-shell shebang

Videos

• Nixpkgs - nix-shell basic usage (2020/08/09)
• Nixpkgs - nix-shell intermediate usage (2020/08/09)
• Nix Shell (2021/04/14)

---

From existing doc survey:

Tutorials

Ad hoc Shell Environments

• Finding packages given a program name
• Nesting shells
• Pinning within adhoc shell
  Declarative and reproducible developer environments
• Why
• Pinning
• Direnv Developing with nix-shell
• From first principles
• Custom builder for nix-shell

References

Comand Reference -> Main Commands -> nix-shell Nix-shell shebang

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-04-20-learning-journey-working-group-meeting-notes-5/27460/1

[alper]

I have a flake.nix with a mkShell in it. Is that equivalent?

The tutorial also does not mention whether shell.nix is a hard convention or something.

[fricklerhandwerk]

The agreed-upon tenet at the moment is to only teach using the stable interface, and Flakes are an experimental feature. Other than that, yes, it's equivalent.

shell.nix is the default filename taken by nix-shell (see the Nix manual).

[alper]

OK. In his tutorial here Amos focuses heavily on flake: https://fasterthanli.me/series/building-a-rust-service-with-nix/part-9

[zmitchell]

@roberth assigned to you for feedback

[bew]

• This shell.nix will just grab nixpkgs from <nixpkgs>, leaving pinning, channels, etc to later tutorials

I think the guide should still mention this in a warning / note, or at least the kind of issues that comes from not pinning

[roberth]

Regarding not using flakes, it would be beneficial to make clear in the tutorial which parts of the file are about bring things into scope, and which part is the actual shell expression. As this is "First steps" they're not too familiar with the language yet, so some extra guidance as to what's what will help them transfer this knowledge to a flake context.

Furthermore some of these points apply; some context to keep in mind while writing this tutorial

• https://github.com/NixOS/nix.dev/issues/498#issuecomment-1613163481

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-07-13-learning-journey-working-group-meeting-notes-17/30393/1

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-07-17-tutorial-series-call-for-feedback/30616/1

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-07-27-learning-journey-working-group-meeting-notes-19/31151/1

[fricklerhandwerk]

Cleaning out issues and compiling a refreshed overview, I think what we're still missing is a smooth transition between a very superficial look at Nix expressions (e.g. in the context of shell.nix) and the hefty Nix language basics tutorial. I renamed the issue accordingly to make it fit into the new overview.