diff --git a/source/index.rst b/source/index.rst index d8e3626..0214b6b 100644 --- a/source/index.rst +++ b/source/index.rst @@ -6,7 +6,7 @@ Welcome to nix.dev .. topic:: Introduction - Welcome to documentation for developers wanting to get things done with `Nix `_. + Welcome to the documentation for developers wanting to get things done using `the Nix ecosystem `_. Using Nix ecosystem you get: diff --git a/source/tutorials/ad-hoc-developer-environments.rst b/source/tutorials/ad-hoc-developer-environments.rst index 6875792..3d6b3a7 100644 --- a/source/tutorials/ad-hoc-developer-environments.rst +++ b/source/tutorials/ad-hoc-developer-environments.rst @@ -113,7 +113,7 @@ We create ad hoc environment with ``$PYTHONPATH`` set and ``python`` available w ``-p`` argument accepts Nix expression, but going into the Nix language is out of scope of this tutorial. -Towards reproducability +Towards reproducibility ----------------------- If you handed over these commands to another developer, they might get different results. @@ -164,7 +164,7 @@ This is essentially the same example as in previous section, but this time decla Going forward ------------- -.. - Where are these packages coming from? TODO: channels and pinning nixpkgs +- :ref:`pinning-nixpkgs` .. TODO: reproducible developer environments diff --git a/source/tutorials/index.rst b/source/tutorials/index.rst index a1af668..dd65752 100644 --- a/source/tutorials/index.rst +++ b/source/tutorials/index.rst @@ -6,6 +6,7 @@ Tutorials install-nix.rst ad-hoc-developer-environments.rst + towards-reproducibility-pinning-nixpkgs.rst declarative-and-reproducible-developer-environments.rst dev-environment.rst contributing.rst diff --git a/source/tutorials/towards-reproducibility-pinning-nixpkgs.rst b/source/tutorials/towards-reproducibility-pinning-nixpkgs.rst new file mode 100644 index 0000000..ca9152f --- /dev/null +++ b/source/tutorials/towards-reproducibility-pinning-nixpkgs.rst @@ -0,0 +1,78 @@ +.. _pinning-nixpkgs: + +Towards reproducibility: Pinning nixpkgs +======================================== + +In Nix snippets around the internet you'll often encounter the following: + +.. code:: nix + + { pkgs ? import {} + }: + + ... + +To quickly demonstrate and get a working Nix expression by importing Nix packages. + +But it doesn't make Nix expression reproducible. Two developers on different machines +are likely to have `` point to different revisions which will lead to getting different results. + +.. note:: + + ```` is syntax for looking up from shell environment variable ``$NIX_PATH``. + + It is always set at the installation time to point to ``nixpkgs-unstable`` channel. + + Channels are a way of distributing Nix software, but they are being phased out. + So even though they are still used by default, it's recommended to avoid channels + and ```` by always setting ``NIX_PATH=`` to be empty. + + +Pinning with URLs inside Nix expression +--------------------------------------- + +The simplest way to pin nixpkgs is to fetch them as a tarball specified via git commit: + +.. code:: nix + + { pkgs ? import (fetchTarball https://github.com/NixOS/nixpkgs/archive/3590f02e7d5760e52072c1a729ee2250b5560746.tar.gz) {}; + }: + + ... + +Picking the commit is easiest done via `status.nixos.org `_, +which lists all the releases and their latest commit that passed all the tests. + +It's recommended to either follow latest stable NixOS release such as ``nixos-20.03`` +or unstable via ``nixos-unstable``. + + +Dependency management with niv +------------------------------ + +If you'd like a bit more automation around bumping dependencies such as nixpkgs, +``niv`` is made for exactly that:: + + $ nix-shell -p niv --run "niv init" + +This command will generate ``nix/sources.json`` with information how and where +dependencies are fetched and ``nix/sources.nix`` that glues them together in Nix. + +By default ``niv`` will configure the latest stable NixOS release. + +You can use it as: + +.. code:: nix + + { sources ? import ./sources.nix + , pkgs ? import sources.nixpkgs {} + }: + + ... + +To update all dependencies:: + + $ nix-shell -p niv --run "niv update" + + +.. Reference: nix.nixPath = [ ("nixpkgs=" + toString pkgs.path) ];