Skip to content

Commit

Permalink
Update dependencies and documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
Sukant Hajra committed Dec 10, 2024
1 parent 1d6db2f commit 36e094a
Show file tree
Hide file tree
Showing 8 changed files with 55 additions and 71 deletions.
2 changes: 2 additions & 0 deletions doc/nix-installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -149,3 +149,5 @@ Then you should see that the appropriate features are enabled:
```sh
nix show-config experimental-features
```

Note that the `fetch-tree` experimental feature is required and automatically enabled with the enablement of `flakes`.
5 changes: 4 additions & 1 deletion doc/nix-installation.org
View file
Original file line number Diff line number Diff line change
Expand Up @@ -217,4 +217,7 @@ nix show-config experimental-features
#+end_src

#+RESULTS: nix-show-config
: flakes nix-command
: fetch-tree flakes nix-command

Note that the =fetch-tree= experimental feature is required and automatically
enabled with the enablement of =flakes=.
16 changes: 2 additions & 14 deletions doc/nix-language.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -105,10 +105,8 @@ nix eval --expr 'let a = 1; a = 2; in a' 2>&1 || true
```

error: attribute 'a' already defined at «string»:1:5

at «string»:1:12:

1| let a = 1; a = 2;
1| let a = 1; a = 2; in a
| ^

Note that semicolons are mandatory in all Nix forms that have them, including let-expressions. Because of Nix's strict parsing, you can neither elide semicolons nor put extra ones.
Expand Down Expand Up @@ -138,14 +136,12 @@ nix eval --expr '

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
error: cannot coerce an integer to a string: 42

We can use a builtin `toString` function to coerce types to strings:

Expand Down Expand Up @@ -176,9 +172,7 @@ nix eval --expr "''In $FROM_SHELL expansion still happens.''" 2>&1 || true
```

error: undefined variable 'EXPANDED_BY_NIX'

at «string»:1:8:

1| ''In ${EXPANDED_BY_NIX} expansion still happens.''
| ^

Expand Down Expand Up @@ -271,9 +265,7 @@ nix eval --expr '{ a = b; b = 2; }.a' 2>&1 || true
```

error: undefined variable 'b'

at «string»:1:7:

1| { a = b; b = 2; }.a
| ^

Expand All @@ -293,16 +285,12 @@ nix eval --expr '({ a }: a + 2 ) { a = 3; b = 4; }' 2>&1 || true

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?
Expand Down
32 changes: 9 additions & 23 deletions doc/nix-language.org
View file
Original file line number Diff line number Diff line change
Expand Up @@ -132,10 +132,8 @@ nix eval --expr 'let a = 1; a = 2; in a' 2>&1 || true

#+RESULTS:
: error: attribute 'a' already defined at «string»:1:5
:
: at «string»:1:12:
:
: 1| let a = 1; a = 2;
: 1| let a = 1; a = 2; in a
: | ^

Note that semicolons are mandatory in all Nix forms that have them, including
Expand Down Expand Up @@ -170,18 +168,14 @@ nix eval --expr '
#+end_src

#+RESULTS:
#+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
: 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: 42

We can use a builtin =toString= function to coerce types to strings:

Expand Down Expand Up @@ -223,9 +217,7 @@ nix eval --expr "''In $FROM_SHELL expansion still happens.''" 2>&1 || true

#+RESULTS:
: error: undefined variable 'EXPANDED_BY_NIX'
:
: at «string»:1:8:
:
: 1| ''In ${EXPANDED_BY_NIX} expansion still happens.''
: | ^

Expand Down Expand Up @@ -341,9 +333,7 @@ nix eval --expr '{ a = b; b = 2; }.a' 2>&1 || true

#+RESULTS:
: error: undefined variable 'b'
:
: at «string»:1:7:
:
: 1| { a = b; b = 2; }.a
: | ^

Expand All @@ -368,16 +358,12 @@ nix eval --expr '({ a }: a + 2 ) { a = 3; b = 4; }' 2>&1 || true
#+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?
Expand Down
10 changes: 5 additions & 5 deletions doc/nix-usage-flakes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,7 @@ For commands accepting installables as an argument, if none are provided, then `
We can use the `nix search` command to see what package derivations a flake contains. For example, from the root directory of this project, we can execute:

```sh
nix search .
nix search . ^
```

* packages.x86_64-linux.nix-scaffold
Expand All @@ -186,7 +186,7 @@ nix search .
* packages.x86_64-linux.org2gfm
Script to export Org-mode files to GitHub Flavored Markdown (GFM)

If a flake has a lot of packages, you can pass regexes to prune down the search. Returned values will match all the regexes provided.
We're required to pass regexes as final arguments to prune down the search. Above we've passed `^` to match everything and return all results.

We can also search a remote repository for packages to install. For example, Nixpkgs is a central repository for Nix, providing several thousand packages. We can search the “nixpkgs-unstable” branch of [Nixpkgs' GitHub repository](https://github.com/NixOS/nixpkgs) for packages that match both “gpu|opengl|accel” and “terminal” as follows:

Expand Down Expand Up @@ -223,7 +223,7 @@ nix search nixpkgs 'gpu|opengl|accel' terminal | ansifilter
If we're curious about what version of WezTerm is available in NixOS's latest release, we can specialize the installable we're searching as follows:

```sh
nix search nixpkgs/nixos-24.11#wezterm
nix search nixpkgs/nixos-24.11#wezterm ^
```

* legacyPackages.x86_64-linux.wezterm (20240203-110809-5046fc22)
Expand Down Expand Up @@ -364,7 +364,7 @@ nix run .#org2gfm -- --help
We can see some of the metadata of this package with the `--json` switch of `nix search`:

```sh
nix search --json .#org2gfm | jq .
nix search --json .#org2gfm ^ | jq .
```

{
Expand Down Expand Up @@ -425,7 +425,7 @@ We can see this installation by querying what's been installed:
nix profile list
```

Index: 0
Name: org2gfm
Flake attribute: packages.x86_64-linux.org2gfm
Original flake URL: git+file:///home/shajra/src/nix-project
Locked flake URL: git+file:///home/shajra/src/nix-project
Expand Down
16 changes: 8 additions & 8 deletions doc/nix-usage-flakes.org
View file
Original file line number Diff line number Diff line change
Expand Up @@ -290,12 +290,12 @@ We can use the =nix search= command to see what package derivations a flake
contains. For example, from the root directory of this project, we can execute:

#+begin_src sh :eval no
nix search .
nix search . ^
#+end_src

#+name: nix-search-local
#+begin_src sh :dir .. :results output :exports results :post crop(text=*this*, first-n=9, last-n=0)
nix search . | ansifilter
nix search . ^ | ansifilter
#+end_src

#+results: nix-search-local
Expand All @@ -305,8 +305,8 @@ nix search . | ansifilter
: * packages.x86_64-linux.org2gfm
: Script to export Org-mode files to GitHub Flavored Markdown (GFM)

If a flake has a lot of packages, you can pass regexes to prune down the search.
Returned values will match all the regexes provided.
We're required to pass regexes as final arguments to prune down the search.
Above we've passed =^= to match everything and return all results.

We can also search a remote repository for packages to install. For example,
Nixpkgs is a central repository for Nix, providing several thousand packages. We
Expand Down Expand Up @@ -353,12 +353,12 @@ If we're curious about what version of WezTerm is available in NixOS's latest
release, we can specialize the installable we're searching as follows:

#+begin_src sh :eval no :noweb yes
nix search nixpkgs/nixos-<<get("nixos-latest")>>#wezterm
nix search nixpkgs/nixos-<<get("nixos-latest")>>#wezterm ^
#+end_src

#+name: nix-search-remote-wezterm
#+begin_src sh :dir .. :results output :exports results :noweb yes
nix search nixpkgs/nixos-<<get("nixos-latest")>>#wezterm | ansifilter
nix search nixpkgs/nixos-<<get("nixos-latest")>>#wezterm ^ | ansifilter
#+end_src

#+RESULTS: nix-search-remote-wezterm
Expand Down Expand Up @@ -577,7 +577,7 @@ search=:

#+name: nix-search-details
#+begin_src sh :dir .. :results output :exports both :noweb yes :post crop(text=*this*, first-n=5, last-n=0)
nix search --json .#<<get("run-attr-short")>> | jq .
nix search --json .#<<get("run-attr-short")>> ^ | jq .
#+end_src

#+RESULTS: nix-search-details
Expand Down Expand Up @@ -676,7 +676,7 @@ nix profile list --profile /tmp/nix-profile | ansifilter
#+end_src

#+RESULTS: nix-profile-list
: Index: 0
: Name: org2gfm
: Flake attribute: packages.x86_64-linux.org2gfm
: Original flake URL: git+file:///home/shajra/src/nix-project
: Locked flake URL: git+file:///home/shajra/src/nix-project
Expand Down
17 changes: 10 additions & 7 deletions doc/nix-usage-noflakes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ Though experimental, the command `nix search` is safe and helpful. Just be aware
We can use an `--extra-experimental-features nix-command` switch to use an experimental feature with `nix` for a single call. Putting this all together, this is how we'd search the provided `default.nix` file:

```sh
nix --extra-experimental-features nix-command search --file . ''
nix --extra-experimental-features nix-command search --file . '' ^
```

* packages.aarch64-darwin.nix-scaffold
Expand All @@ -97,11 +97,13 @@ If you have disabled the `nix-command` feature, and typing out `nix --extra-expe
alias nix-new = nix --extra-experimental-features 'nix-command'
```

Passing in `--file .` tells `nix search` to get the attribute tree to search from the `default.nix` file in the current directory. The positional argument is the attribute path to start the search from within this tree. An empty string indicates to start at the root of the tree.
Passing in `--file .` tells `nix search` to get the attribute tree to search from the `default.nix` file in the current directory.

Note, there are some projects for which `nix search` won't work. These projects require extra approaches to work with `nix search` that are beyond the scope of this document. You can still navigate these projects' attribute tree with `nix repl`. Or you can try to read the source code of the Nix expressions.
The first positional argument is the attribute path to start the search from within this tree. An empty string indicates to start at the root of the tree.

Remaining arguments are regexes to filter our search results with. Above we've passed `^` to match everything and return all results.

We can filter search results down by supplying regexes as an additional position parameters:
Note, there are some projects for which `nix search` won't work. These projects require extra approaches to work with `nix search` that are beyond the scope of this document. You can still navigate these projects' attribute tree with `nix repl`. Or you can try to read the source code of the Nix expressions.

```sh
nix --extra-experimental-features nix-command \
Expand All @@ -115,7 +117,7 @@ We can also use `--json` to get more details about found packages:

```sh
nix --extra-experimental-features \
nix-command search --json --file . '' | jq .
nix-command search --json --file . '' ^ | jq .
```

{
Expand Down Expand Up @@ -234,11 +236,11 @@ Remember, the package's *name* is not the same as the *attribute* used to select

```sh
nix --extra-experimental-features \
nix-command search --file . '' --json 'packages.x86_64-linux.org2gfm' | jq .
nix-command search --file . --json 'packages.x86_64-linux.org2gfm' ^ | jq .
```

{
"packages.x86_64-linux.org2gfm": {
"": {
"description": "Script to export Org-mode files to GitHub Flavored Markdown (GFM)",
"pname": "org2gfm",
"version": ""
Expand Down Expand Up @@ -305,6 +307,7 @@ 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
Loading

0 comments on commit 36e094a

Please sign in to comment.