From 334e6c668d4039a0f3358da86920e141da59e47a Mon Sep 17 00:00:00 2001 From: Sukant Hajra Date: Fri, 15 Dec 2023 19:13:56 -0600 Subject: [PATCH] Update documentation --- doc/internal/nix-usage-flakes-optional.org | 4 +- doc/internal/nix-usage-flakes-required.org | 2 +- doc/nix-installation.md | 2 +- doc/nix-installation.org | 2 +- doc/nix-language.md | 19 ++++++++-- doc/nix-language.org | 43 +++++++++++++++------- doc/nix-usage-flakes.md | 35 ++++++++---------- doc/nix-usage-flakes.org | 31 ++++++++-------- doc/nix-usage-noflakes.md | 1 - doc/nix-usage-noflakes.org | 1 - 10 files changed, 80 insertions(+), 60 deletions(-) diff --git a/doc/internal/nix-usage-flakes-optional.org b/doc/internal/nix-usage-flakes-optional.org index 39a4f65..38d2a94 100644 --- a/doc/internal/nix-usage-flakes-optional.org +++ b/doc/internal/nix-usage-flakes-optional.org @@ -5,11 +5,11 @@ project-dependent. #+end_comment This project supports a still-experimental feature of Nix called /flakes/, which -this guide shows users how to use. [[file:../nix-usage-noflakes.org][Another guide]] explains how to do +this guide shows users how to use. [[file:nix-usage-noflakes.org][Another guide]] explains how to do everything illustrated in this document, but without flakes. #+begin_quote -*_NOTE:_* If you're new to flakes, please read the provided [[file:../nix-introduction.org][supplemental +*_NOTE:_* If you're new to flakes, please read the provided [[file:nix-introduction.org][supplemental introduction to Nix]] to understand the experimental nature of flakes and how it may or may not affect you. Hopefully you'll find these trade-offs acceptable so you can take advantage of the improved experience flakes offer. diff --git a/doc/internal/nix-usage-flakes-required.org b/doc/internal/nix-usage-flakes-required.org index 2272bc3..72ee6fb 100644 --- a/doc/internal/nix-usage-flakes-required.org +++ b/doc/internal/nix-usage-flakes-required.org @@ -6,4 +6,4 @@ project-dependent. This project requires an experimental feature of Nix called /flakes/. To understand more about what flakes are and the consequences of using a -still-experimental feature of Nix, please see the provided [[file:../nix-introduction.org][introduction to Nix]]. +still-experimental feature of Nix, please see the provided [[file:nix-introduction.org][introduction to Nix]]. diff --git a/doc/nix-installation.md b/doc/nix-installation.md index 38e67db..607bca3 100644 --- a/doc/nix-installation.md +++ b/doc/nix-installation.md @@ -103,7 +103,7 @@ Since the latest release of Nix is already at 2.19, if you installed Nix recentl nix --version ``` - nix (Nix) 2.13.6 + nix (Nix) 2.18.1 The easiest way to turn on experimental features is to create a file `~/.config/nix/nix.conf` if it doesn't already exist, and in it put the following line: diff --git a/doc/nix-installation.org b/doc/nix-installation.org index 88ab00d..9f29613 100644 --- a/doc/nix-installation.org +++ b/doc/nix-installation.org @@ -166,7 +166,7 @@ nix --version #+end_src #+RESULTS: nix-version -: nix (Nix) 2.13.6 +: nix (Nix) 2.18.1 The easiest way to turn on experimental features is to create a file =~/.config/nix/nix.conf= if it doesn't already exist, and in it put the diff --git a/doc/nix-language.md b/doc/nix-language.md index 88dc642..1b92432 100644 --- a/doc/nix-language.md +++ b/doc/nix-language.md @@ -136,13 +136,16 @@ nix eval --expr ' in "${a_number} is a terrible number"' 2>&1 || true ``` - error: cannot coerce an integer to a string + error: + … while evaluating a path segment - at «string»:3:9: + at «string»:3:9: 2| let a_number = 42; 3| in "${a_number} is a terrible number" | ^ + + error: cannot coerce an integer to a string We can use a builtin `toString` function to coerce types to strings: @@ -288,12 +291,20 @@ This basic pattern syntax is rigid, and we can't pass in a attribute set with at nix eval --expr '({ a }: a + 2 ) { a = 3; b = 4; }' 2>&1 || true ``` - error: anonymous function at «string»:1:2 called with unexpected argument 'b' + error: + … from call site - at «string»:1:1: + at «string»:1:1: 1| ({ a }: a + 2 ) { a = 3; b = 4; } | ^ + + error: function 'anonymous lambda' called with unexpected argument 'b' + + at «string»:1:2: + + 1| ({ a }: a + 2 ) { a = 3; b = 4; } + | ^ Did you mean a? If we want to relax the destructuring to accept sets with other attributes we can use a “…” form: diff --git a/doc/nix-language.org b/doc/nix-language.org index 98f64ab..7fcdadf 100644 --- a/doc/nix-language.org +++ b/doc/nix-language.org @@ -170,13 +170,18 @@ nix eval --expr ' #+end_src #+RESULTS: -: error: cannot coerce an integer to a string -: -: at «string»:3:9: -: -: 2| let a_number = 42; -: 3| in "${a_number} is a terrible number" -: | ^ +#+begin_example +error: + … while evaluating a path segment + + at «string»:3:9: + + 2| let a_number = 42; + 3| in "${a_number} is a terrible number" + | ^ + + error: cannot coerce an integer to a string +#+end_example We can use a builtin =toString= function to coerce types to strings: @@ -359,13 +364,23 @@ nix eval --expr '({ a }: a + 2 ) { a = 3; b = 4; }' 2>&1 || true #+end_src #+RESULTS: -: error: anonymous function at «string»:1:2 called with unexpected argument 'b' -: -: at «string»:1:1: -: -: 1| ({ a }: a + 2 ) { a = 3; b = 4; } -: | ^ -: Did you mean a? +#+begin_example +error: + … from call site + + at «string»:1:1: + + 1| ({ a }: a + 2 ) { a = 3; b = 4; } + | ^ + + error: function 'anonymous lambda' called with unexpected argument 'b' + + at «string»:1:2: + + 1| ({ a }: a + 2 ) { a = 3; b = 4; } + | ^ + Did you mean a? +#+end_example If we want to relax the destructuring to accept sets with other attributes we can use a “...” form: diff --git a/doc/nix-usage-flakes.md b/doc/nix-usage-flakes.md index 59c5b9c..94ae7ab 100644 --- a/doc/nix-usage-flakes.md +++ b/doc/nix-usage-flakes.md @@ -19,9 +19,9 @@ This document explains how to take advantage of software provided by Nix for people new to [the Nix package manager](https://nixos.org/nix). This guide uses this project for examples, but it focused on introducing general Nix usage, which applies to other projects using Nix as well. -This project supports a still-experimental feature of Nix called *flakes*, which this guide shows users how to use. [Another guide](../nix-usage-noflakes.md) explains how to do everything illustrated in this document, but without flakes. +This project supports a still-experimental feature of Nix called *flakes*, which this guide shows users how to use. [Another guide](nix-usage-noflakes.md) explains how to do everything illustrated in this document, but without flakes. -> **NOTE:** If you're new to flakes, please read the provided [supplemental introduction to Nix](../nix-introduction.md) to understand the experimental nature of flakes and how it may or may not affect you. Hopefully you'll find these trade-offs acceptable so you can take advantage of the improved experience flakes offer. +> **NOTE:** If you're new to flakes, please read the provided [supplemental introduction to Nix](nix-introduction.md) to understand the experimental nature of flakes and how it may or may not affect you. Hopefully you'll find these trade-offs acceptable so you can take advantage of the improved experience flakes offer. # How this project uses Nix @@ -115,21 +115,21 @@ nix flake show . ├───apps │ ├───aarch64-darwin … + ├───flakeModules: unknown + ├───legacyPackages │ ├───aarch64-darwin omitted (use '--legacy' to show) │ ├───x86_64-darwin omitted (use '--legacy' to show) │ └───x86_64-linux omitted (use '--legacy' to show) ├───lib: unknown - ├───nixosConfigurations - ├───nixosModules ├───overlays │ └───default: Nixpkgs overlay ├───packages │ ├───aarch64-darwin - │ │ ├───nix-scaffold: package 'nix-scaffold' - │ │ └───org2gfm: package 'org2gfm' + │ │ ├───nix-scaffold omitted (use '--all-systems' to show) + │ │ └───org2gfm omitted (use '--all-systems' to show) │ ├───x86_64-darwin - │ │ ├───nix-scaffold: package 'nix-scaffold' - │ │ └───org2gfm: package 'org2gfm' + │ │ ├───nix-scaffold omitted (use '--all-systems' to show) + │ │ └───org2gfm omitted (use '--all-systems' to show) │ └───x86_64-linux │ ├───nix-scaffold: package 'nix-scaffold' │ └───org2gfm: package 'org2gfm' @@ -211,7 +211,7 @@ nix search nixpkgs 'gpu|opengl|accel' terminal * legacyPackages.x86_64-linux.kitty (0.31.0) A modern, hackable, featureful, OpenGL based terminal emulator - * legacyPackages.x86_64-linux.rio (0.0.29) + * legacyPackages.x86_64-linux.rio (0.0.32) A hardware-accelerated GPU terminal emulator powered by WebGPU * legacyPackages.x86_64-linux.wezterm (20230712-072601-f4abf8fd) @@ -422,22 +422,19 @@ We can see this installation by querying what's been installed: nix profile list ``` - 0 git+file:///home/tnks/src/shajra/nix-project#packages.x86_64-linux.org2gfm git+file:///home/tnks/src/shajra/nix-project#packages.x86_64-linux.org2gfm /nix/store/sn8kmywg7kp4z6d467h92b0p5xdyvlhd-org2gfm + Index: 0 + Flake attribute: packages.x86_64-linux.org2gfm + Original flake URL: git+file:///home/tnks/src/shajra/nix-project + Locked flake URL: git+file:///home/tnks/src/shajra/nix-project + Store paths: /nix/store/sn8kmywg7kp4z6d467h92b0p5xdyvlhd-org2gfm -The output of `nix profile list` is a bit verbose, but each line has three parts: - -- an index to use with other `nix profile` subcommands (like `nix profile remove`) -- the specified installable reference -- the resolved reference actually installed -- the store path in `/nix/store` - -And if we want to uninstall a program from our profile, we do so by the index +If we want to uninstall a program from our profile, we do so by the index from this list: ```sh nix profile remove 0 ``` -we can also provide a regex matching the full attribute path of the flake: +We can also provide a regex matching the full attribute path of the flake: ```sh nix profile remove '.*org2gfm' diff --git a/doc/nix-usage-flakes.org b/doc/nix-usage-flakes.org index 683533a..93e36c3 100644 --- a/doc/nix-usage-flakes.org +++ b/doc/nix-usage-flakes.org @@ -202,21 +202,21 @@ git+file:///home/tnks/src/shajra/nix-project ├───apps │ ├───aarch64-darwin … +├───flakeModules: unknown +├───legacyPackages │ ├───aarch64-darwin omitted (use '--legacy' to show) │ ├───x86_64-darwin omitted (use '--legacy' to show) │ └───x86_64-linux omitted (use '--legacy' to show) ├───lib: unknown -├───nixosConfigurations -├───nixosModules ├───overlays │ └───default: Nixpkgs overlay ├───packages │ ├───aarch64-darwin -│ │ ├───nix-scaffold: package 'nix-scaffold' -│ │ └───org2gfm: package 'org2gfm' +│ │ ├───nix-scaffold omitted (use '--all-systems' to show) +│ │ └───org2gfm omitted (use '--all-systems' to show) │ ├───x86_64-darwin -│ │ ├───nix-scaffold: package 'nix-scaffold' -│ │ └───org2gfm: package 'org2gfm' +│ │ ├───nix-scaffold omitted (use '--all-systems' to show) +│ │ └───org2gfm omitted (use '--all-systems' to show) │ └───x86_64-linux │ ├───nix-scaffold: package 'nix-scaffold' │ └───org2gfm: package 'org2gfm' @@ -344,7 +344,7 @@ nix search nixpkgs 'gpu|opengl|accel' terminal | ansifilter ,* legacyPackages.x86_64-linux.kitty (0.31.0) A modern, hackable, featureful, OpenGL based terminal emulator -,* legacyPackages.x86_64-linux.rio (0.0.29) +,* legacyPackages.x86_64-linux.rio (0.0.32) A hardware-accelerated GPU terminal emulator powered by WebGPU ,* legacyPackages.x86_64-linux.wezterm (20230712-072601-f4abf8fd) @@ -677,22 +677,21 @@ nix profile list --profile /tmp/nix-profile #+end_src #+RESULTS: nix-profile-list -: 0 git+file:///home/tnks/src/shajra/nix-project#packages.x86_64-linux.org2gfm git+file:///home/tnks/src/shajra/nix-project#packages.x86_64-linux.org2gfm /nix/store/sn8kmywg7kp4z6d467h92b0p5xdyvlhd-org2gfm +: Index: 0 +: Flake attribute: packages.x86_64-linux.org2gfm +: Original flake URL: git+file:///home/tnks/src/shajra/nix-project +: Locked flake URL: git+file:///home/tnks/src/shajra/nix-project +: Store paths: /nix/store/sn8kmywg7kp4z6d467h92b0p5xdyvlhd-org2gfm -The output of =nix profile list= is a bit verbose, but each line has three parts: -- an index to use with other =nix profile= subcommands (like =nix profile remove=) -- the specified installable reference -- the resolved reference actually installed -- the store path in =/nix/store= - -And if we want to uninstall a program from our profile, we do so by the index +If we want to uninstall a program from our profile, we do so by the index from +this list: #+name: nix-profile-remove #+begin_src sh :eval no :noweb yes nix profile remove 0 #+end_src -we can also provide a regex matching the full attribute path of the flake: +We can also provide a regex matching the full attribute path of the flake: #+begin_src sh :eval no :noweb yes nix profile remove '.*<>' diff --git a/doc/nix-usage-noflakes.md b/doc/nix-usage-noflakes.md index b03b8b9..a114353 100644 --- a/doc/nix-usage-noflakes.md +++ b/doc/nix-usage-noflakes.md @@ -305,7 +305,6 @@ nix-env --install --file . --attr packages.x86_64-linux.org2gfm 2>&1 ``` installing 'org2gfm' - building '/nix/store/hs9xz17vlb2m4qn6kxfmccgjq4jyrvqg-user-environment.drv'... We can see this installation by querying what's been installed: diff --git a/doc/nix-usage-noflakes.org b/doc/nix-usage-noflakes.org index 11075d7..f56943d 100644 --- a/doc/nix-usage-noflakes.org +++ b/doc/nix-usage-noflakes.org @@ -554,7 +554,6 @@ nix-env --profile /tmp/nix-profile \ #+RESULTS: nix-env-install : installing 'org2gfm' -: building '/nix/store/hs9xz17vlb2m4qn6kxfmccgjq4jyrvqg-user-environment.drv'... We can see this installation by querying what's been installed: