From 0536d0de90f7b56f914052cd86e42e2b105b79a8 Mon Sep 17 00:00:00 2001
From: benneti <benedikt.tissot@googlemail.com>
Date: Thu, 2 Sep 2021 11:37:21 +0200
Subject: [PATCH] update pkgs documentation

---
 doc/outputs/pkgs.md | 79 ++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 67 insertions(+), 12 deletions(-)

diff --git a/doc/outputs/pkgs.md b/doc/outputs/pkgs.md
index 548667ff..4de93a8d 100644
--- a/doc/outputs/pkgs.md
+++ b/doc/outputs/pkgs.md
@@ -13,18 +13,45 @@ the supported systems listed in the package's `meta.platforms` attribute.
 And, as usual, every package in the overlay is also available to any NixOS
 [host](../concepts/hosts.md).
 
+Another convenient difference is that it is possible to use 
+[nvfetcher](https://github.com/berberman/nvfetcher) to keep packages up to 
+date.
+This is best understood by the simple example below.
+
 ## Example
+It is possible to specify sources separately to keep them up to date semi 
+automatically.
+The basic rules are specified in pkgs/sources.toml:
+```toml
+# nvfetcher.toml
+[libinih]
+src.github = "benhoyt/inih"
+fetch.github = "benhoyt/inih"
+```
+After changes to this file as well as to update the packages specified in there run 
+nvfetcher (for more details see [nvfetcher](https://github.com/berberman/nvfetcher)).
+
+The pkgs overlay is managed in
+pkgs/default.nix:
+```nix
+final: prev: {
+  # keep sources first, this makes sources available to the pkgs
+  sources = prev.callPackage (import ./_sources/generated.nix) { };
+
+  # then, call packages with `final.callPackage`
+  libinih = prev.callPackage ./development/libraries/libinih { };
+}
+```
+
+Lastly the example package is in
 pkgs/development/libraries/libinih/default.nix:
 ```nix
-{ stdenv, meson, ninja, lib, srcs, ... }:
-let inherit (srcs) libinih; in
+{ stdenv, meson, ninja, lib, sources, ... }:
 stdenv.mkDerivation {
   pname = "libinih";
 
-  # version will resolve to 53, as specified in the final example below
-  inherit (libinih) version;
-
-  src = libinih;
+  # version will resolve to the latest available on gitub
+  inherit (sources.libinih) version src;
 
   buildInputs = [ meson ninja ];
 
@@ -32,12 +59,14 @@ stdenv.mkDerivation {
 }
 ```
 
-pkgs/default.nix:
-```nix
-final: prev: {
-  libinih = prev.callPackage ./development/libraries/libinih { };
-}
-```
+
+## Migration from flake based approach
+Previous to nvfetcher it was possible to manage sources via a pkgs/flake.nix, the main changes from there are that sources where in the attribute "srcs" (now "sources") and the contents of the sources where slightly different.
+In order to switch to the new system, rewrite pkgs/flake.nix to a pkgs/sources.toml file using the documentation of nvfetcher,
+add the line that calls the sources at the beginning of pkgs/default.nix, and 
+accomodate the small changes in the packages as can be seen from the example.
+
+The example package looked like:
 
 pkgs/flake.nix:
 ```nix
@@ -51,4 +80,30 @@ pkgs/flake.nix:
 }
 ```
 
+pkgs/default.nix:
+```nix
+final: prev: {
+  # then, call packages with `final.callPackage`
+  libinih = prev.callPackage ./development/libraries/libinih { };
+}
+```
+
+pkgs/development/libraries/libinih/default.nix:
+```nix
+{ stdenv, meson, ninja, lib, srcs, ... }:
+let inherit (srcs) libinih; in
+stdenv.mkDerivation {
+  pname = "libinih";
+
+  # version will resolve to 53, as specified in the flake.nix file
+  inherit (libinih) version;
+
+  src = libinih;
+
+  buildInputs = [ meson ninja ];
+
+  # ...
+}
+```
+
 [pkgs]: https://github.com/NixOS/nixpkgs/tree/master/pkgs