nix.dev/maintainers/documentation-survey.md

Documentation survey

To better navigate the material and judge its relevance, every entry should provide

• Title (URL)
• Brief summary
• Video length or estimated reading time
• Principal Author(s)
• Year created (last update or maintenance status)

Tutorials

Nix

• Nix Pills Chapter 3: Enter the Environment

  Installation with nix-env, rollback and switching generations, showing references and closures.

  • Reading time: 7 min
  • Author: Luca Bruno
  • Created: 2015 (effectively unmaintained since 2017)

• Nix Pills Chapter 6. Our First Derivation

  Fundamentals of Nix derivations, function and concept, nix show-derivation. Derivation set and its attributes.

  • Reading time: 20 min
  • Author: Luca Bruno
  • Created: 2015 (effectively unmaintained since 2017)

• Nix Pills Chapter 7. Working Derivation

  Fundamentals of Nix derivations, bash, nix repl, nix-store, nix-instantiate, nix show-derivation . Packaging a simple C program, inherit keyword.

  • Reading time: 16 min
  • Author: Luca Bruno
  • Created: 2015 (effectively unmaintained since 2017)

• Nix Pills Chapter 11. Garbage Collector

  Fundamentals of Nix garbage collection, nix-collect-garbage, nix-env, nix-store, nix-build.

  • Reading time: 14 min
  • Author: Luca Bruno
  • Created: 2015 (effectively unmaintained since 2017)

• https://nixos.org/guides/nix-pills/nix-search-paths.html

• https://nixos.org/guides/nix-pills/nix-store-paths.html

  Store paths and how they are computed, nix-store, nix-hash, nix derivation show, nix repl.

  • Reading time: 6 min
  • Author: Luca Bruno
  • Created: 2015 (effectively unmaintained since 2017)

Nix language

• https://learnxinyminutes.com/docs/nix/

• https://nixcloud.io/tour/?id=1

• https://medium.com/@MrJamesFisher/nix-by-example-a0063a1a4c55

• https://www.youtube.com/watch?v=eCapIx9heBw&list=PL-saUBvIJzOkjAw_vOac75v-x6EzNzZq-&index=5

• https://nixos.org/guides/nix-pills/basics-of-language.html

• Nix Pills Chapter 4. The basics of the language

  Fundamentals of Nix language, types, expressions nix repl.

  • Reading time: 16 min
  • Author: Luca Bruno
  • Created: 2015 (effectively unmaintained since 2017)

• https://nixos.org/guides/nix-pills/functions-and-imports.html

Nixpkgs

• https://www.youtube.com/watch?v=SGekN4pDExY&list=PL-saUBvIJzOkjAw_vOac75v-x6EzNzZq-&index=6

• https://www.youtube.com/watch?v=m4sv2M9jRLg

• https://nixos.org/guides/nix-pills/generic-builders.html

• Nix Pills Chapter 8. Generic Builders

  Generalized building process (C language), derivation, nix repl, nix-build.

  • Reading time: 14 min
  • Author: Luca Bruno
  • Created: 2015 (effectively unmaintained since 2017)

• https://nixos.org/guides/nix-pills/automatic-runtime-dependencies.html

• https://nixos.org/guides/nix-pills/developing-with-nix-shell.html

• Nix Pills Chapter 10. Developing with nix-shell

  Making a development environment from a derivation that can be launched with nix-shell, builtins.derivation.

  • Reading time: 9 min
  • Author: Luca Bruno
  • Created: 2015 (effectively unmaintained since 2017)

• https://nixos.org/guides/nix-pills/inputs-design-pattern.html

• https://nixos.org/guides/nix-pills/callpackage-design-pattern.html

• https://nixos.org/guides/nix-pills/override-design-pattern.html

• https://nixos.org/guides/nix-pills/nixpkgs-parameters.html

• https://nixos.org/guides/nix-pills/nixpkgs-overriding-packages.html

• https://nixos.org/guides/nix-pills/fundamentals-of-stdenv.html

• https://nixos.org/guides/nix-pills/basic-dependencies-and-hooks.html

NixOS

• https://www.youtube.com/watch?v=jf0nIn2oS8A&list=PL-saUBvIJzOkjAw_vOac75v-x6EzNzZq-&index=4

How-to guides

Nix

• https://nix.dev/tutorials/ad-hoc-developer-environments#what-is-a-shell-environment
• https://nixos.wiki/wiki/Nix_Cookbook#Managing_storage

Nix language

• https://nix.dev/anti-patterns/language.html

Nixpkgs

• https://nixos.wiki/wiki/FAQ
• https://www.youtube.com/watch?v=D_IZ2EfW_8U
• https://www.youtube.com/watch?v=5K_2RSjbdXc
• https://www.youtube.com/watch?v=dGAL3gMXvug
• https://nix.dev/tutorials/towards-reproducibility-pinning-nixpkgs
• https://nix.dev/tutorials/declarative-and-reproducible-developer-environments
• https://nix.dev/tutorials/cross-compilation.html
• https://nixos.org/manual/nixpkgs/stable

NixOS

• https://nix.dev/tutorials/building-bootable-iso-image.html
• https://nix.dev/tutorials/deploying-nixos-using-terraform.html
• https://nix.dev/tutorials/installing-nixos-on-a-raspberry-pi.html
• https://www.youtube.com/watch?v=bkDYmvKINm8
• https://www.youtube.com/watch?v=Zi_vbddNXtg
• https://github.com/noteed/nix-notes
• https://nixos.org/manual/nixos/stable/

Explanation

Nix

• https://nixos.org/guides/nix-pills/index.html
• partially in chapter https://nixos.org/guides/nix-pills/automatic-runtime-dependencies.html
• https://nixos.org/guides/nix-pills/garbage-collector.html
• https://edolstra.github.io/pubs/phd-thesis.pdf

Nix language

• https://edolstra.github.io/pubs/phd-thesis.pdf

  Chapter 1: Existing software deployment models and issues faced with them; motivation for developing Nix, features of the Nix deployment system

  • Reading time: 15 min
  • Author: Eelco Dolstra
  • Created: 2006

  Chapter 2:

  2.1: The Nix Store, isolation of components, cryptographic hashes, non-destructive upgrades, prevention of undeclared dependencies, closures

  2.2: Use of Nix expressions to build software, structure of Nixpkgs collection, Hello and SUbversion as examples of derivations.

  2.3: Package Management: Installations, updates and rollbacks, user environments, uninstalling, garbage collection

  2.4: Store derivations: Definition, .drv files in Nix store. nix-instantiate, nix-store --realise. Allows various deployment policies, including source and binary.

  2.5. Deployment models. Mechanisms nix-instantiate and nix-store. Models: Manual download; vesion management system; channels; one-click installation

  2.6: Transparent source/binary deployment: nix-push and nix-pull. Pre-built substitutes.

  • Reading time: 30 min

  Chapter 3: Relates deployment issues to memory management issues in programming languages. Relates files to objects in memory. Describes closures, discusses pointer discipline and conservative garbage collection, shows that persistence is achieved by cryptographic hashes.

  • Reading time: 25 min

  Chapter 4: The Nix language: Functional languages; lazy languages. Lexical syntax of Nix language. Semantics: Basic and compound values, substitutions, function calls, conditionals, assertions, with, operators, evaluation rules. Implementation using ATerm library.

  • Reading time: 60 min

  Chapter 5: Extensional vs intensional. The Nix extensional model: cryptographic hashing; file system objects and the Nix store; adding atomic values to the store; translating Nix expressions to derivations; garbage collection

  • Reading time: 60 min

Nixpkgs

• Nix Pills Chapter 6: Our First Derivation

  Explains derivations; the derivation function, its attribute set, .drv and 'out' files. Explains outpath. Regarding nixpkgs, shows how to bring nixpkgs into scope and how to refer to a package using its outpath. Accessing files underneath a package's out.

  • Reading time: 25 min
  • Author: Luca Bruno
  • Created: 2015
  • Updated 2017

• Nix Pills Chapter 7: Working Derivation

  Creating a working derivation. Using nix repl: bash as a builder; the args attribute; creating in $out; the builder environment; packaging a C program. Using a .nix file to define the derivation: import function; inherit keyword; using nix-build. Explains how to use gcc, bash and coreutils from nixpkgs.

  • Reading time: 15 min
  • Author: Luca Bruno
  • Created: 2015 (effectively unmaintained since 2017)

• https://nixos.org/guides/nix-pills/inputs-design-pattern.html

  Explains the inputs design pattern as used by nixpkgs. A single customizable repository having a top-level Nix expression, with one expression for each package.

  • Reading time: 20 min
  • Author: Luca Bruno
  • Created: 2015 (effectively unmaintained since 2017)

• https://nixos.org/guides/nix-pills/callpackage-design-pattern.html

  Introduces the callPackage pattern used extensively in Nixpkgs. Shows how to write and use the function; use builtins.functionArgs to determine arguments, use builtins.intersectAttrs to combine attributes, and override arguments when needed.

  • Reading time: 15 min
  • Author: Luca Bruno
  • Created: 2015 (effectively unmaintained since 2017)

• partially in https://edolstra.github.io/pubs/phd-thesis.pdf

• Connecting Bash to Nix

  Configure derivation using only Bash and builtins. Explains builtins.derivation, attributes, nix build, store path hierarchy, imports. Relates this to `stdenv.mkDerivation.

  • Reading time: 10 min
  • Author: Ross Light
  • Created: 2023

NixOS

• https://nixos.org/docs/SCR-2005-091.pdf (2006)

Reference

Nix

• https://nix.dev/manual/nix/2.18/command-ref/command-ref.html
• https://edolstra.github.io/pubs/phd-thesis.pdf

Nix language

• https://edolstra.github.io/pubs/phd-thesis.pdf
• https://nix.dev/manual/nix/2.18/expressions/writing-nix-expressions.html
• https://github.com/tazjin/nix-1p

Nixpkgs

• https://nixos.org/manual/nixpkgs/stable

NixOS

• https://nixos.org/manual/nixos/stable