temp

shell.nix

@@ -10,8 +10,8 @@ mkShell {
     # python311Packages.pygments don't need to install, asciidoctor includes it
     rubyPackages.rbs
     rubyPackages.racc
-    # rubyPackages.coderay
+    rubyPackages.coderay
-    # rubyPackages.rouge
+    rubyPackages.rouge
   ];
 #  outputs = [ "start-shell" ];
 }

source/book.adoc

@@ -4,10 +4,12 @@
 :sectnums:
 :toc: left
 :toclevels: 4
+// :source-highlighter: rouge
+// :rouge-style: monokai
 :source-highlighter: pygments
 :pygments-style: default
 :pygments-linenums-mode: table
-:pygments-css: style
+:pygments-css: class
 :!prewrap:
 :icons: font
 :title-logo-image: image::wombat.svg["wombat reclining against a lambda"]

source/flake-structure/main.adoc

@@ -12,8 +12,6 @@ The basic structure of a flake is shown below.
 }
 ....
 
-== Description
-
 The `description` part is self-explanatory; it's just a string. You
 probably won't need `nixConfig` unless you're doing something fancy. I'm
 going to focus on what goes into the `inputs` and `outputs` sections,

source/hello-flake-repo/main.adoc0

@@ -65,7 +65,7 @@ _depends_ on `nixpkgs` and `flake-utils`.
 
 Finally, let's look at `flake.lock`, or rather, just part of it.
 
-[source,linenums]
+[source,,linenums]
 .flake.lock
 ....
 $# head -n 40 flake.lock

source/hello-flake-return/main.adoc

@@ -5,7 +5,7 @@ let's have a look at the one we saw earlier, in the `hello-flake` repo.
 If you compare this flake definition to the colour-coded template
 presented in the previous section, most of it should look familiar.
 
-[subs=quotes]
+[source,nix,linenums]
 .flake.nix
 ....
 {
@@ -48,7 +48,7 @@ additional development tools.
 Now let's look at the section I labeled `SOME UNFAMILIAR STUFF` and
 see what it does.
 
-[subs=quotes]
+[source,nix,linenums,subs=quotes]
 ....
         packages = rec {
           hello = pkgs.stdenv.mkDerivation rec { ❶

source/modify-hello-flake/flake.nix.new

@@ -1,7 +1,4 @@
 {
-  # See https://github.com/mhwombat/nix-for-numbskulls/blob/main/flakes.md
-  # for a brief overview of what each section in a flake should or can contain.
-
   description = "a very simple and friendly flake";
 
   inputs = {
@@ -37,6 +34,8 @@
                 cp $src/hello-flake $out/bin/hello-flake
                 chmod +x $out/bin/hello-flake
               '';
+
+            buildInputs = [ pkgs.cowsay ];
           };
           default = hello;
         };

source/modify-hello-flake/main.adoc0

@@ -90,7 +90,7 @@ Here's the modified `hello-flake` file.
 $ sed -i 's/echo/cowsay/' hello-flake
 ////
 
-[source,nix,highlight=4]
+[source,nix,linenums,highlight=3]
 .hello-flake
 ....
 $# cat hello-flake
@@ -118,26 +118,63 @@ The highlighted modifications below will accomplish that.
 $ cp ../flake.nix.new flake.nix
 ////
 
-[source,nix,highlight=18..22]
+[source,nix,linenums,highlight=15..19]
 .flake.nix
 ....
 $# cat flake.nix
 ....
 
-Now we restart the development shell and see that the `cowsay` command is
+Now we restart the development shell and see that the `cowsay` command is available.
-available and the script works. Because we've updated source files
+Because we've updated source files but haven't ``git commit``ed the new version,
-but haven't ``git commit``ed the new version, we get a warning message
+we get a warning message about it being "`dirty`".
-about it being "`dirty`". It's just a warning, though; the script runs
+It's just a warning, though; the script runs correctly.
-correctly.
 
 ....
 $# echo '$ nix develop'
 $# nix develop --command sh
 $ which cowsay # is it available now?
 $ ./hello-flake
+$ exit
 ....
 
-Alternatively, we could use `nix run`.
+Let's try `nix run`.
+
+....
+$ nix run
+....
+
+What went wrong?
+Recall that we only added `cowsay` to the development environment;
+we didn't add it to the runtime environment.
+The modified flake below will fix that.
+
+////
+$ cp ../flake.nix.new.2 flake.nix
+////
+
+[source,nix,linenums,highlight='37..39,42']
+.flake.nix
+....
+$# cat flake.nix
+....
+
+Line 42 adds `cowsay` as a `buildInput` for the package.
+That does make it available at build and runtime, but it doesn’t put it on the path,
+so our hello-flake script wouldn’t be able to find it.
+There are various ways to deal with this problem.
+In this case we simply edited the script (lines 37-39) as we install it,
+specifying the full path to cowsay.
+
+[NOTE]
+====
+When you're packaging a program written in a more powerful language such as
+Haskell, Python, Java, C, C#, or Rust,
+the language build system will usually do all that is required
+to make the dependencies visible to the program at runtime.
+In this case, adding the dependency to `buildInputs` is sufficient.
+====
+
+This time `nix run` works.
 
 ....
 $ nix run

source/nix-language/strings.adoc

@@ -40,7 +40,8 @@ error:
 
        error: cannot coerce an integer to a string
 ....
-Nix does provide functions for converting between types; we'll see these in <<_built_in_functions>>.
+Nix does provide functions for converting between types; we'll see these in the 
+<<#convert-to-string,next section>>.
 ====
 
 == Useful built-in functions for strings
@@ -67,6 +68,7 @@ nix-repl> builtins.substring 3 6 "hayneedlestack"
 "needle"
 ....
 
+[#convert-to-string]
 Convert an expression to a string.
 
 [source]

source/recipes/build/nixpkg/tempwork/flake.lock

@@ -1,60 +0,0 @@
-{
-  "nodes": {
-    "flake-utils": {
-      "inputs": {
-        "systems": "systems"
-      },
-      "locked": {
-        "lastModified": 1731533236,
-        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
-        "owner": "numtide",
-        "repo": "flake-utils",
-        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
-        "type": "github"
-      },
-      "original": {
-        "owner": "numtide",
-        "repo": "flake-utils",
-        "type": "github"
-      }
-    },
-    "nixpkgs": {
-      "locked": {
-        "lastModified": 1757775813,
-        "narHash": "sha256-mHYalJeeuYTtJNPijlm4IqmxslIB+DTz/wQvz2EB/S4=",
-        "owner": "NixOS",
-        "repo": "nixpkgs",
-        "rev": "1fb62b80407f458b29ba8168c11095858a250687",
-        "type": "github"
-      },
-      "original": {
-        "owner": "NixOS",
-        "repo": "nixpkgs",
-        "type": "github"
-      }
-    },
-    "root": {
-      "inputs": {
-        "flake-utils": "flake-utils",
-        "nixpkgs": "nixpkgs"
-      }
-    },
-    "systems": {
-      "locked": {
-        "lastModified": 1681028828,
-        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
-        "owner": "nix-systems",
-        "repo": "default",
-        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
-        "type": "github"
-      },
-      "original": {
-        "owner": "nix-systems",
-        "repo": "default",
-        "type": "github"
-      }
-    }
-  },
-  "root": "root",
-  "version": 7
-}

source/recipes/build/nixpkg/tempwork/flake.nix

@@ -1,41 +0,0 @@
-{
-  inputs = {
-    nixpkgs.url = "github:NixOS/nixpkgs";
-    flake-utils.url = "github:numtide/flake-utils";
-  };
-
-  outputs = { self, nixpkgs, flake-utils }:
-    flake-utils.lib.eachDefaultSystem (system:
-      let
-        pkgs = import nixpkgs { inherit system; };
-      in
-      {
-        packages = rec {
-          hello = pkgs.stdenv.mkDerivation rec {
-            name = "hello-with-cow";
-
-            src = ./.;
-
-            unpackPhase = "true";
-
-            buildPhase = ":";
-
-            installPhase =
-              ''
-                mkdir -p $out/bin
-                cp $src/hello-with-cow $out/bin
-                chmod +x $out/bin/hello-with-cow
-              '';
-
-            buildInputs = [ pkgs.cowsay ];
-          };
-          default = hello;
-        };
-
-        apps = rec {
-          hello = flake-utils.lib.mkApp { drv = self.packages.${system}.hello; };
-          default = hello;
-        };
-      }
-    );
-}

source/recipes/build/nixpkg/tempwork/hello-with-cow

@@ -1,3 +0,0 @@
-#!/usr/bin/env sh
-
-cowsay "Hello from your flake!"

source/recipes/devshell/flake/main.adoc0

@@ -19,7 +19,7 @@ However, you can use any of the flake reference styles defined in <<#flakeref>>.
 $# cat flake.nix
 ....
 
-Let's take a closer look at the `buildInputs`.
+Let's take a closer look at the `buildInputs` from line 16.
 
 ....
 $# grep buildInputs flake.nix | sed 's/ //g'

source/recipes/devshell/flake/tempwork/flake.lock

@@ -0,0 +1,128 @@
+{
+  "nodes": {
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "flake-utils_2": {
+      "inputs": {
+        "systems": "systems_2"
+      },
+      "locked": {
+        "lastModified": 1681202837,
+        "narHash": "sha256-H+Rh19JDwRtpVPAWp64F+rlEtxUWBAQW28eAi3SRSzg=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "cfacdce06f30d2b68473a46042957675eebb3401",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "hello-flake": {
+      "inputs": {
+        "flake-utils": "flake-utils_2",
+        "nixpkgs": "nixpkgs"
+      },
+      "locked": {
+        "lastModified": 1684524031,
+        "narHash": "sha256-0DYX7S7u5S2no2e6jiIv7cRfbpM5JBJq7+/1CUKEGxA=",
+        "ref": "refs/heads/main",
+        "rev": "099bfadc43f79a8929809bd097d12ef5de73ef62",
+        "revCount": 24,
+        "type": "git",
+        "url": "https://codeberg.org/mhwombat/hello-flake"
+      },
+      "original": {
+        "type": "git",
+        "url": "https://codeberg.org/mhwombat/hello-flake"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1681665000,
+        "narHash": "sha256-hDGTR59wC3qrQZFxVi2U3vTY+r02+Okbq080hO1C4Nk=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "3a6205d9f79fe526be03d8c465403b118ca4cf37",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs_2": {
+      "locked": {
+        "lastModified": 1757790242,
+        "narHash": "sha256-53ib4nvwVVAYF1ipe7BBEwjvvBo0lEbQcsbCHPSfzAg=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "38cbd6b3be3ce84eb389eabb552dff8824019d2b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-utils": "flake-utils",
+        "hello-flake": "hello-flake",
+        "nixpkgs": "nixpkgs_2"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    },
+    "systems_2": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

source/recipes/devshell/flake/tempwork/flake.nix

@@ -0,0 +1,21 @@
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs";
+    flake-utils.url = "github:numtide/flake-utils";
+    hello-flake.url = "git+https://codeberg.org/mhwombat/hello-flake";
+  };
+
+  outputs = { self, nixpkgs, flake-utils, hello-flake }:
+    flake-utils.lib.eachDefaultSystem (system:
+      let
+        pkgs = import nixpkgs { inherit system; };
+      in
+      {
+        devShells = rec {
+          default = pkgs.mkShell {
+            buildInputs = [ hello-flake.packages.${system}.hello ];
+          };
+        };
+      }
+    );
+}