Learning Journey tutorial - pinning nixpkgs

[zmitchell]

There are various levels of reproducibility in Nix and it may be surprising that a build could fail after some period of time because nixpkgs has evolved over time. In this tutorial we introduce the idea that packages have to come from somewhere and that we can accept different levels of reproducibility.

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

Tutorial contents

• Packages come from nixpkgs
• Packages can be found on search.nixos.org
• What is <nixpkgs>?
• Where does NIX_PATH point?
• You can "pin" to a specific branch. A release branch will move slower than unstable.
• You can pin to a specific revision.

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

Open questions

• Subsequent calls to nix-build can trigger a full rebuild due to nixpkgs changing, which can be surprising. Should we use this as a motivating example for pinning nixpkgs? If you pin to a specific revision you'll never need to rebuild given that your source doesn't change?
• Should we also go into how to change which channel your default profile follows?

[zmitchell]

@roberth assigned to you for feedback

[roberth]

Pinning is somewhat of a rabbit hole, which doesn't seem super productive when it appears that most of the community is converging on flakes.
Perhaps worth considering is that flakes can be used as a "pin manager" or "sources manager" like niv. You don't have to use the outputs. Instead, you can use inputs and getFlake or flake-compat to then just use the sources.
However, this solution is about as non-standard as any of the other non-standard pinning solutions, plus you have to enable the experimental feature to generate a lock.

I'd almost say the title should be "First steps tutorial - not pinning nixpkgs". It's just not a beginner friendly topic. We should explain somewhere where <nixpkgs> comes from though.

[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

[matu3ba]

@infinisil I disagree with the scope, as there is no description of how to "keep dependencies fixed" with "what stuff might break" for folks coming from language package managers.
Please let me know your feedback, what or where this could be adjusted and ideally brief pointers to technical solutions for 3+6.

1. Pinning means "to fix it", which implies not following "moving targets". Use a better phrase, if you want to describe the moving targets with <>-brackets.
2. getting from cli the latest good revision for pinning nixpkgs is not possible, which feels bad to use. I did copy local nixpkgs to git rev-parse nixpkgs-unstable for the commit. Is that the only approach?
3. What design flaws or shortcomings exist regarding pinning?

• list known global system properties here
• show best practice how to keep things working, ie how to avoid opengl / mesa version mismatches, see also https://ryantm.github.io/nixpkgs/builders/packages/opengl/, https://discourse.nixos.org/t/design-discussion-about-nixgl-opengl-cuda-opencl-wrapper-for-nix/2453 and libGL not working on non-NixOS (without setting up) nixpkgs#9415

4. explain pattern to pin individual packages with overlays
5. explain how to bump package version globally on system to prevent runtime/compiletime abi mismatches and/or what methods exist
6. Please let me know how nix allows runtime configuration introspection, which means how I can configure (semi-)automatic rebuilds of development packages, if for example the opengl version has an abi mismatch.
7. Summary

[fricklerhandwerk]

@matu3ba the purpose of this tutorial would be to introduce new users to the whole notion of being able to pin down remote sources, and provide a known-good default procedure on how to do it that won't run them into trouble long enough to get proficient with the system and solve problems on their own. Overlays and global configuration are orthogonal to this and should primarily be expanded upon in the reference documentation rather than here, and treated in an overview-style manner here, again to introduce the notion and a rough but sustainable mental model or basic patterns to work with. The runtime introspection is way to deep for nix.dev to handle at this time, it should go to a more appropriate place such as the Nixpkgs manual.

[fricklerhandwerk]

Closing this, since most of the original questions are by now answered in the Nix manual, and IMO pinning should - just like installation - not be something one has to think or even know about. Alas, we may be arbitrarily far away from that, so in the mean time let's just reflect the state of affairs: #907