update all links to the Nix manual

NixOS · Oct 27, 2023 · 3fea7ff · 3fea7ff
1 parent a8e403a
commit 3fea7ff
Show file tree

Hide file tree

Showing 18 changed files with 88 additions and 70 deletions.
diff --git a/flake.lock b/flake.lock
diff --git a/flake.nix b/flake.nix
@@ -4,7 +4,8 @@
   inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.05";
   inputs.flake-utils.url = "github:numtide/flake-utils";
   inputs.nix_2-13.url = "github:NixOS/nix/2.13-maintenance";
-  inputs.nix_2-18.url = "github:NixOS/nix/2.18-maintenance";
+  # FIXME: the tip of the branch fails to build on Hydra, but we need it chached
+  inputs.nix_2-18.url = "github:NixOS/nix/f5f4de6a550327b4b1a06123c2e450f1b92c73b6";
 
   outputs = { self, nixpkgs, flake-utils, nix_2-13, nix_2-18 }:
     flake-utils.lib.eachDefaultSystem (system:

diff --git a/maintainers/working_groups/learning_journey/documentation-survey.md b/maintainers/working_groups/learning_journey/documentation-survey.md
@@ -236,13 +236,13 @@ To better navigate the material and judge its relevance, every entry should prov
 
 ### Nix
 
-- https://nixos.org/manual/nix/stable/command-ref/command-ref.html
+- https://nix.dev/manual/nix/2.18/command-ref/command-ref.html
 - https://edolstra.github.io/pubs/phd-thesis.pdf
 
 ### Nix language
 
 - https://edolstra.github.io/pubs/phd-thesis.pdf
-- https://nixos.org/manual/nix/stable/expressions/writing-nix-expressions.html
+- https://nix.dev/manual/nix/2.18/expressions/writing-nix-expressions.html
 - https://github.com/tazjin/nix-1p
 
 ### Nixpkgs

diff --git a/source/concepts/faq.md b/source/concepts/faq.md
@@ -14,16 +14,16 @@ The Nix logo is inspired by [an idea for the Haskell logo](https://wiki.haskell.
 {ref}`Flakes <flakes>` were originally proposed in [RFC 49](https://github.com/NixOS/rfcs/pull/49), and have been in development since 2019.
 Nix introduced the implementation as its first [experimental feature] in 2021.
 
-[experimental feature]: https://nixos.org/manual/nix/unstable/contributing/experimental-features.html
+[experimental feature]: https://nix.dev/manual/nix/2.18/contributing/experimental-features.html
 
 The subject is considered controversial among Nix users and developers in terms of design, development processes, and community governance.
 In particular:
 - The RFC was closed without conclusion, and some design and implementation issues are not yet resolved.
   Examples include the notion of a global [flake registry], the [impossibility of parameterising flakes](https://github.com/NixOS/nix/issues/2861), and the [new command line interface and flakes being closely tied to each other](https://discourse.nixos.org/t/2023-03-06-nix-team-meeting-minutes-38/26056#cli-stabilisation-announcement-draft-4).
-- The original implementation introduced [regressions](https://discourse.nixos.org/t/nix-2-4-and-what-s-next/16257) in the [Nix 2.4 release](https://nixos.org/manual/nix/stable/release-notes/rl-2.4.html), breaking some stable functionality without a [major version](https://semver.org/) increment.
+- The original implementation introduced [regressions](https://discourse.nixos.org/t/nix-2-4-and-what-s-next/16257) in the [Nix 2.4 release](https://nix.dev/manual/nix/2.18/release-notes/rl-2.4.html), breaking some stable functionality without a [major version](https://semver.org/) increment.
 - New Nix users were and still are encouraged by various individuals to adopt flakes despite there being no concrete plan or timeline for stabilisation.
 
-[flake registry]: https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-registry.html
+[flake registry]: https://nix.dev/manual/nix/2.18/command-ref/new-cli/nix3-registry.html
 
 This led to a situation where the stable interface was only sparsely maintained for multiple years, and repeatedly suffered breakages due to ongoing development.
 Meanwhile, the new interface was adopted widely enough for evolving its design without negatively affecting users to become very challenging.
@@ -50,7 +50,7 @@ Both paradigms have their own set of unique concepts and support tooling that ha
 At the moment, neither the stable nor the experimental interface is clearly superior to the other in all aspects.
 While flakes reduce complexity in some regards, they also introduce additional mechanisms and you will have to learn more about the system to fully understand how it works.
 
-There are downsides to relying on [experimental features](https://nixos.org/manual/nix/stable/command-ref/conf-file.html#conf-experimental-features) in general:
+There are downsides to relying on [experimental features](https://nix.dev/manual/nix/2.18/command-ref/conf-file.html#conf-experimental-features) in general:
 
 - Interfaces and behaviour of experimental features could still be changed by Nix developers.
   This may require you to adapt your code at some point in the future, which will be more effort when it has grown in complexity.
@@ -66,7 +66,7 @@ Yes. There is:
 
 - CPU architecture—great effort being made to avoid compilation of native instructions in favour of hardcoded supported ones.
 - System's current time/date.
-- The filesystem used for building (see also [`TMPDIR`](https://nixos.org/manual/nix/stable/command-ref/env-common.html#env-TMPDIR)).
+- The filesystem used for building (see also [`TMPDIR`](https://nix.dev/manual/nix/2.18/command-ref/env-common.html#env-TMPDIR)).
 - Linux kernel parameters, such as:
   - [IPv6 capabilities](https://github.com/NixOS/nix/issues/5615).
   - binfmt interpreters, e.g., those configured with [`boot.binfmt.emulatedSystems`](https://search.nixos.org/options?show=boot.binfmt.emulatedSystems).

diff --git a/source/concepts/flakes.md b/source/concepts/flakes.md
@@ -5,25 +5,25 @@ What is usually referred to as "flakes" is:
 - A policy for managing dependencies between {term}`Nix expressions<Nix expression>`.
 - An [experimental feature] in Nix, implementing that policy and supporting functionality.
 
-[experimental feature]: https://nixos.org/manual/nix/unstable/contributing/experimental-features.html
+[experimental feature]: https://nix.dev/manual/nix/2.18/contributing/experimental-features.html
 
-Technically, a [flake](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#description) is a file system tree that contains a file named `flake.nix` in its root directory.
+Technically, a [flake](https://nix.dev/manual/nix/2.18/command-ref/new-cli/nix3-flake.html#description) is a file system tree that contains a file named `flake.nix` in its root directory.
 
 Flakes add the following behavior to Nix:
 
-1. A `flake.nix` file offers a uniform [schema](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-format) , where:
+1. A `flake.nix` file offers a uniform [schema](https://nix.dev/manual/nix/2.18/command-ref/new-cli/nix3-flake.html#flake-format) , where:
    - Other flakes can be referenced as dependencies providing {term}`Nix language` code or other files.
    - The values produced by the {term}`Nix expression`s in `flake.nix` are structured according to pre-defined use cases.
 
-1. References to other flakes can be specified using a dedicated [URL-like syntax](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-references).
+1. References to other flakes can be specified using a dedicated [URL-like syntax](https://nix.dev/manual/nix/2.18/command-ref/new-cli/nix3-flake.html#flake-references).
    A [flake registry] allows using symbolic identifiers for further brevity.
    References can be automatically locked to their current specific version and later updated programmatically.
 
-   [flake registry]: https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-registry.html
+   [flake registry]: https://nix.dev/manual/nix/2.18/command-ref/new-cli/nix3-registry.html
 
 1. A [new command line interface], implemented as a separate experimental feature, leverages flakes by accepting flake references in order to build, run, or deploy software defined as a flake.
 
-   [new command line interface]: https://nixos.org/manual/nix/stable/command-ref/new-cli/nix.html
+   [new command line interface]: https://nix.dev/manual/nix/2.18/command-ref/new-cli/nix.html
 
 Nix handles flakes differently than regular {term}`Nix file`s in the following ways:
 

diff --git a/source/install-nix.md b/source/install-nix.md
@@ -81,5 +81,5 @@ $ nix --version
 nix (Nix) 2.11.0
 ```
 
-[multi-user installation]: https://nixos.org/manual/nix/stable/installation/multi-user.html
-[single-user installation]: https://nixos.org/manual/nix/stable/installation/single-user.html
+[multi-user installation]: https://nix.dev/manual/nix/2.18/installation/multi-user.html
+[single-user installation]: https://nix.dev/manual/nix/2.18/installation/single-user.html
diff --git a/source/recipes/best-practices.md b/source/recipes/best-practices.md
@@ -117,15 +117,15 @@ You will often encounter Nix language code samples that refer to `<nixpkgs>`.
 `<...>` is special syntax that was [introduced in 2011] to conveniently access values from the environment variable [`$NIX_PATH`].
 
 [introduced in 2011]: https://github.com/NixOS/nix/commit/1ecc97b6bdb27e56d832ca48cdafd3dbb5185a04
-[`$NIX_PATH`]: https://nixos.org/manual/nix/unstable/command-ref/env-common.html?highlight=nix_path#env-NIX_PATH
+[`$NIX_PATH`]: https://nix.dev/manual/nix/2.18/command-ref/env-common.html?highlight=nix_path#env-NIX_PATH
 
 This means, the value of a search path depends on external system state.
 When using search paths, the same Nix expression can produce different results.
 
 In most cases, `$NIX_PATH` is set to the latest channel when Nix is installed, and is therefore likely to differ from machine to machine.
 
 :::{note}
-[Channels](https://nixos.org/manual/nix/stable/command-ref/nix-channel.html) are a mechanism for referencing remote Nix expressions and retrieving their latest version.
+[Channels](https://nix.dev/manual/nix/2.18/command-ref/nix-channel.html) are a mechanism for referencing remote Nix expressions and retrieving their latest version.
 :::
 
 The state of a subscribed channel is external to the Nix expressions relying on it.
@@ -153,7 +153,7 @@ On NixOS, `$NIX_PATH` can be set permanently with the [`nix.nixPath`](https://se
 
 ## Updating nested attribute sets
 
-The [attribute set update operator](https://nixos.org/manual/nix/stable/language/operators.html#update) merges two attribute sets.
+The [attribute set update operator](https://nix.dev/manual/nix/2.18/language/operators.html#update) merges two attribute sets.
 
 Example:
 
@@ -219,7 +219,7 @@ If someone builds the project in a directory with a different name, they will ge
 This can be the cause of needless rebuilds.
 
 :::{tip}
-Use [`builtins.path`](https://nixos.org/manual/nix/stable/language/builtins.html#builtins-path) with the `name` attribute set to something fixed.
+Use [`builtins.path`](https://nix.dev/manual/nix/2.18/language/builtins.html#builtins-path) with the `name` attribute set to something fixed.
 
 This will derive the symbolic name of the store path from `name` instead of the working directory:
 

diff --git a/source/recipes/troubleshooting.md b/source/recipes/troubleshooting.md
@@ -2,7 +2,7 @@
 
 ## What to do if a binary cache is down or unreachable?
 
-Pass [`--option substitute false`](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-substitute) to Nix commands.
+Pass [`--option substitute false`](https://nix.dev/manual/nix/2.18/command-ref/conf-file#conf-substitute) to Nix commands.
 
 ### How to fix: `error: querying path in database: database disk image is malformed`
 
@@ -13,7 +13,7 @@ Try:
 $ sqlite3 /nix/var/nix/db/db.sqlite "pragma integrity_check"
 ```
 
-Which will print the errors in the [database](https://nixos.org/manual/nix/stable/glossary#gloss-nix-database).
+Which will print the errors in the [database](https://nix.dev/manual/nix/2.18/glossary#gloss-nix-database).
 If the errors are due to missing references, the following may work:
 
 ```shell-session
@@ -25,7 +25,7 @@ $ sqlite3 /nix/var/nix/db/db.sqlite-bkp ".dump" | sqlite3 /nix/var/nix/db/db.sql
 
 This is a [known issue](https://github.com/NixOS/nix/issues/1251).
 
-It means that using a new version of Nix upgraded the SQLite schema of the [database](https://nixos.org/manual/nix/stable/glossary#gloss-nix-database), and then you tried to use an older version Nix.
+It means that using a new version of Nix upgraded the SQLite schema of the [database](https://nix.dev/manual/nix/2.18/glossary#gloss-nix-database), and then you tried to use an older version Nix.
 
 The solution is to dump the database, use the old Nix version to initialize it, and then re-import the data:
 
@@ -39,6 +39,6 @@ $ nix-store --load-db < /tmp/db.dump
 
 ### How to fix: `writing to file: Connection reset by peer`
 
-This may mean you are trying to import a too large file or directory into the [Nix store](https://nixos.org/manual/nix/stable/glossary#gloss-store), or your machine is running out of resources, such as disk space or memory.
+This may mean you are trying to import a too large file or directory into the [Nix store](https://nix.dev/manual/nix/2.18/glossary#gloss-store), or your machine is running out of resources, such as disk space or memory.
 
-Try to reduce the size of the directory to import, or run [garbage collection](https://nixos.org/manual/nix/stable/command-ref/nix-collect-garbage).
+Try to reduce the size of the directory to import, or run [garbage collection](https://nix.dev/manual/nix/2.18/command-ref/nix-collect-garbage).
diff --git a/source/reference/glossary.md b/source/reference/glossary.md
@@ -16,7 +16,7 @@ Nix language
 
     :::{seealso}
     - [](reading-nix-language)
-    - [Nix language reference](https://nixos.org/manual/nix/stable/language)
+    - [Nix language reference](https://nix.dev/manual/nix/2.18/language)
     :::
 
 Nix expression

diff --git a/source/reference/nix-manual.md b/source/reference/nix-manual.md
@@ -1,6 +1,23 @@
 (nix-manual)=
-# Nix Reference Manual
+# Nix reference manual
+
+```{toctree}
+:hidden:
+
+Nix latest (master) <https://hydra.nixos.org/job/nix/master/build.x86_64-linux/latest/download>
+Nix 2.18 (Nixpkgs unstable) <https://nix.dev/manual/nix/2.13/>
+Nix 2.13 (NixOS 23.05) <https://nix.dev/manual/nix/2.18/>
+```
+
+- [Nix latest](https://hydra.nixos.org/job/nix/master/build.x86_64-linux/latest/download)
+
+  The latest working build from the `master` branch of the [Nix repository](https://github.com/NixOS/nix)
+
+- [Nix 2.18](https://nix.dev/manual/nix/2.13/)
+
+  The latest Nix version shipped with Nixpkgs unstable
+
+- [Nix 2.13 ](https://nix.dev/manual/nix/2.18/)
+
+  The Nix version shipped with NixOS 23.05
 
-- [Nix latest (master)](https://hydra.nixos.org/job/nix/master/build.x86_64-linux/latest/download)
-- [Nix 2.18 (Nixpkgs unstable)](https://nix.dev/manual/nix/2.13/)
-- [Nix 2.13 (NixOS 23.05)](https://nix.dev/manual/nix/2.18/)
diff --git a/source/reference/pinning-nixpkgs.md b/source/reference/pinning-nixpkgs.md
@@ -4,9 +4,9 @@
 
 Specifying remote Nix expressions, such as the one provided by Nixpkgs, can be done in several ways:
 
-- [`$NIX_PATH` environment variable](https://nixos.org/manual/nix/stable/command-ref/env-common.html#env-NIX_PATH)
-- [`-I` option](https://nixos.org/manual/nix/stable/command-ref/opt-common.html#opt-I) to most of commands like `nix-build`, `nix-shell`, etc.
-- [`fetchurl`](https://nixos.org/manual/nix/stable/language/builtins.html#builtins-fetchurl), [`fetchTarball`](https://nixos.org/manual/nix/stable/language/builtins.html#builtins-fetchTarball), [`fetchGit`](https://nixos.org/manual/nix/stable/language/builtins.html#builtins-fetchGit) or [Nixpkgs fetchers](https://nixos.org/manual/nixpkgs/stable/#chap-pkgs-fetchers) in Nix expressions
+- [`$NIX_PATH` environment variable](https://nix.dev/manual/nix/2.18/command-ref/env-common.html#env-NIX_PATH)
+- [`-I` option](https://nix.dev/manual/nix/2.18/command-ref/opt-common.html#opt-I) to most of commands like `nix-build`, `nix-shell`, etc.
+- [`fetchurl`](https://nix.dev/manual/nix/2.18/language/builtins.html#builtins-fetchurl), [`fetchTarball`](https://nix.dev/manual/nix/2.18/language/builtins.html#builtins-fetchTarball), [`fetchGit`](https://nix.dev/manual/nix/2.18/language/builtins.html#builtins-fetchGit) or [Nixpkgs fetchers](https://nixos.org/manual/nixpkgs/stable/#chap-pkgs-fetchers) in Nix expressions
 
 ## Possible URL values
 

diff --git a/source/tutorials/first-steps/ad-hoc-shell-environments.md b/source/tutorials/first-steps/ad-hoc-shell-environments.md
@@ -181,8 +181,8 @@ There are three things going on here:
 
 ## References
 
-- [Nix manual: `nix-shell`](https://nixos.org/manual/nix/stable/command-ref/nix-shell) (or run `man nix-shell`)
-- [Nix manual: `-I` option](https://nixos.org/manual/nix/unstable/command-ref/opt-common.html#opt-I)
+- [Nix manual: `nix-shell`](https://nix.dev/manual/nix/2.18/command-ref/nix-shell) (or run `man nix-shell`)
+- [Nix manual: `-I` option](https://nix.dev/manual/nix/2.18/command-ref/opt-common.html#opt-I)
 
 ## Next steps
 

diff --git a/source/tutorials/first-steps/declarative-shell.md b/source/tutorials/first-steps/declarative-shell.md
@@ -165,5 +165,5 @@ Set `shellHook` to output the current repository status:
 
 - [`mkShell` documentation](https://nixos.org/manual/nixpkgs/stable/#sec-pkgs-mkShell)
 - Nixpkgs [shell functions and utilities](https://nixos.org/manual/nixpkgs/stable/#ssec-stdenv-functions) documentation
-- [`nix-shell` documentation](https://nixos.org/manual/nix/stable/command-ref/nix-shell)
+- [`nix-shell` documentation](https://nix.dev/manual/nix/2.18/command-ref/nix-shell)
 
diff --git a/source/tutorials/first-steps/reproducible-scripts.md b/source/tutorials/first-steps/reproducible-scripts.md
@@ -47,10 +47,10 @@ It takes the following parameters relevant for our use case:
 - `-p` lists packages that should be present in the interpreter's environment
 - `-I` explicitly sets [the search path] for packages
 
-More details on the options can be found in the [`nix-shell` reference documentation](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html#options).
+More details on the options can be found in the [`nix-shell` reference documentation](https://nix.dev/manual/nix/2.18/command-ref/nix-shell.html#options).
 
-[`nix-shell` as a shebang interpreter]: https://nixos.org/manual/nix/stable/command-ref/nix-shell.html#use-as-a--interpreter
-[the search path]: https://nixos.org/manual/nix/unstable/command-ref/opt-common.html#opt-I
+[`nix-shell` as a shebang interpreter]: https://nix.dev/manual/nix/2.18/command-ref/nix-shell.html#use-as-a--interpreter
+[the search path]: https://nix.dev/manual/nix/2.18/command-ref/opt-common.html#opt-I
 
 Create a file named `nixpkgs-releases.sh` with the following content:
 
@@ -92,4 +92,4 @@ Run the script:
 
 - {ref}`reading-nix-language` to learn about the Nix language, which is used to declare packages and configurations.
 - {ref}`declarative-reproducible-envs` to create reproducible shell environments with a declarative configuration file.
-- [Garbage Collection](https://nixos.org/manual/nix/stable/package-management/garbage-collection.html) – free up storage used by the programs made available through Nix
+- [Garbage Collection](https://nix.dev/manual/nix/2.18/package-management/garbage-collection.html) – free up storage used by the programs made available through Nix
diff --git a/source/tutorials/learning-journey/packaging-existing-software.md b/source/tutorials/learning-journey/packaging-existing-software.md
@@ -88,7 +88,7 @@ error: cannot evaluate a function that has an argument without a value ('lib')
        Nix attempted to evaluate a function as a top level expression; in
        this case it must have its arguments supplied either by default
        values, or passed explicitly with '--arg' or '--argstr'. See
-       https://nixos.org/manual/nix/stable/language/constructs.html#functions.
+       https://nix.dev/manual/nix/2.18/language/constructs.html#functions.
 
        at /home/nix-user/hello.nix:2:3: