Skip to content

Commit

Permalink
Update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
Sukant Hajra committed Dec 16, 2023
1 parent e4b47ff commit 334e6c6
Show file tree
Hide file tree
Showing 10 changed files with 80 additions and 60 deletions.
4 changes: 2 additions & 2 deletions doc/internal/nix-usage-flakes-optional.org
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion doc/internal/nix-usage-flakes-required.org
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]].
2 changes: 1 addition & 1 deletion doc/nix-installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
2 changes: 1 addition & 1 deletion doc/nix-installation.org
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
19 changes: 15 additions & 4 deletions doc/nix-language.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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:
Expand Down
43 changes: 29 additions & 14 deletions doc/nix-language.org
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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:
Expand Down
35 changes: 16 additions & 19 deletions doc/nix-usage-flakes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

> **<span class="underline">NOTE:</span>** 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.
> **<span class="underline">NOTE:</span>** 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<a id="sec-2"></a>

Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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'
Expand Down
31 changes: 15 additions & 16 deletions doc/nix-usage-flakes.org
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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 '.*<<get("package-attr-short")>>'
Expand Down
1 change: 0 additions & 1 deletion doc/nix-usage-noflakes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
1 change: 0 additions & 1 deletion doc/nix-usage-noflakes.org
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down

0 comments on commit 334e6c6

Please sign in to comment.