diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5c5fc4d2f..25b80267b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,6 +22,39 @@ Adapted from the [Contributor Covenant] and [The Carpentries Code of Conduct]: [Contributor Covenant]: https://github.com/EthicalSource/contributor_covenant/blob/cd7fcf684249786b7f7d47ba49c23a6bcb3233eb/content/version/2/1/code_of_conduct.md [The Carpentries Code of Conduct]: https://github.com/carpentries/docs.carpentries.org/blob/4691971d9f49544054410334140a4fd391a738da/topic_folders/policies/code-of-conduct.md +## Updating reference manuals + +With the current setup, the Nix manual hosted on nix.dev does not get updated automatically with new releases. +The following manual steps are required: + +- Regularly update the inputs to use the latest versions of the Nix release branches with `nix shell --run "niv update"` + + To avoid long build times, make sure Nix can be fetched from the cache. + If it doesn't, find the latest commit that is [built by Hydra](https://hydra.nixos.org/project/nix). For example, to pin Nix 2.18: + + ```bash + niv update nix_2-18 -r f5f4de6a550327b4b1a06123c2e450f1b92c73b6 + ``` + +- On each new Nix release: + + 1. Add the latest version in [`default.nix`](./default.nix). + For example, to add Nix 2.19: + + ```bash + niv add nixos/nix -n nix_2-19 -b 2.19-maintenance + ``` + + 2. Reference the latest version in [`source/reference/nix-manual.md`](./source/reference/nix-manual.md). + +- If an unstable or stable release of Nixpkgs adopt a new version of Nix, update the corresponding references here. + + Also update URLs to the the Nix manual to the version used by Nixpkgs unstable. + For example, if one wants to move from 2.18 to 2.19: + ```bash + sed -i 's#https://nix.dev/manual/nix/2.18/#https://nix.dev/manual/nix/2.19/#g' $(ls **/*.md) + ``` + ## What you can do ### You want to learn and use Nix? diff --git a/default.nix b/default.nix index d2b28f5ec..250c04145 100644 --- a/default.nix +++ b/default.nix @@ -25,10 +25,28 @@ let buildPhase = '' make html ''; - installPhase = '' - mkdir -p $out - cp -R build/html/* $out/ - ''; + installPhase = + let + # Various versions of the Nix manuals, grep for (nix-manual)= + # FIXME: This requires human interaction to update! + # See ./CONTRIBUTING.md for details. + releases = [ + "2.19" + "2.18" + "2.13" + ]; + inputName = version: pkgs.lib.strings.replaceStrings [ "." ] [ "-" ] version; + src = version: (import inputs."nix_${inputName version}").default.doc; + copy = version: '' + cp -R ${src version}/share/doc/nix/manual/* $out/manual/nix/${version} + ''; + in + with pkgs.lib.strings; + '' + mkdir -p $out/manual/nix/{${concatStringsSep "," releases}} + ${concatStringsSep "\n" (map copy releases)} + cp -R build/html/* $out/ + ''; }; devmode = @@ -81,6 +99,7 @@ in inputsFrom = [ nix-dev ]; packages = [ devmode + pkgs.niv pkgs.python310.pkgs.black pkgs.vale ]; diff --git a/maintainers/documentation-survey.md b/maintainers/documentation-survey.md index 0cccf4c75..90b1cf64c 100644 --- a/maintainers/documentation-survey.md +++ b/maintainers/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/nix/sources.json b/nix/sources.json index 3befd57a4..fbb593fb4 100644 --- a/nix/sources.json +++ b/nix/sources.json @@ -1,4 +1,40 @@ { + "nix_2-13": { + "branch": "2.13-maintenance", + "description": "Nix, the purely functional package manager", + "homepage": "https://nixos.org/", + "owner": "nixos", + "repo": "nix", + "rev": "56eb17906822f14bb348017315cb1ca643da900a", + "sha256": "1k0x63l9crkrhdgdclcx8mp6r9mcp4brs67l6hsii1ag8gy2gmj4", + "type": "tarball", + "url": "https://github.com/nixos/nix/archive/56eb17906822f14bb348017315cb1ca643da900a.tar.gz", + "url_template": "https://github.com///archive/.tar.gz" + }, + "nix_2-18": { + "branch": "2.18-maintenance", + "description": "Nix, the purely functional package manager", + "homepage": "https://nixos.org/", + "owner": "nixos", + "repo": "nix", + "rev": "f5f4de6a550327b4b1a06123c2e450f1b92c73b6", + "sha256": "1g23sxsh9aj7sard5d3ijqfjqbh4fvlvyr73sj3dcdzcqiys5naq", + "type": "tarball", + "url": "https://github.com/nixos/nix/archive/f5f4de6a550327b4b1a06123c2e450f1b92c73b6.tar.gz", + "url_template": "https://github.com///archive/.tar.gz" + }, + "nix_2-19": { + "branch": "2.19-maintenance", + "description": "Nix, the purely functional package manager", + "homepage": "https://nixos.org/", + "owner": "nixos", + "repo": "nix", + "rev": "33bacbe220b49ceaaeb817354592a0102fbae087", + "sha256": "17fjz3mxqcszxfzpj48f8rqzdqavnnpibpi0ssw7vxmyybrqsqly", + "type": "tarball", + "url": "https://github.com/nixos/nix/archive/33bacbe220b49ceaaeb817354592a0102fbae087.tar.gz", + "url_template": "https://github.com///archive/.tar.gz" + }, "nixpkgs": { "branch": "nixos-23.05", "description": "Nix Packages collection & NixOS", diff --git a/source/concepts/faq.md b/source/concepts/faq.md index 8793f3504..7b9d379ff 100644 --- 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 ` 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. @@ -60,6 +60,7 @@ There are downsides to relying on [experimental features](https://nixos.org/manu - The [Nix documentation team](https://nixos.org/community/teams/documentation.html) focuses on improving documentation and learning materials for stable features and common principles. When using flakes, you will have to rely more heavily on user-to-user support, third-party documentation, and the source code. +(channel-branches)= ## Which channel branch should I use? Nixpkgs and NixOS have both stable and rolling releases. @@ -102,7 +103,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 index a8f4f5ec9..462903b97 100644 --- 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`. - 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/conf.py b/source/conf.py index a53ae29fd..82117e9f7 100644 --- a/source/conf.py +++ b/source/conf.py @@ -423,6 +423,11 @@ # Linkcheck fails on anchors in GH browser/file viewer, see https://github.com/sphinx-doc/sphinx/issues/11484 r"https://github\.com/.+/.+/blob/.*#.*$", r"https://github\.com/.+/.+/tree/.*#.*$", + # XXX: we use the web URL to the manuals we host within the build output, + # because Sphinx does not have facilities to deploy arbitrary files. + # since linkchecking those URLs will fail before actually deploying them, + # we ignore them here. + r"https://nix.dev/manual/.*$", ] # Anchors are not present in HTML diff --git a/source/contributing/documentation/index.md b/source/contributing/documentation/index.md index b5d1cb86f..e1910be2a 100644 --- a/source/contributing/documentation/index.md +++ b/source/contributing/documentation/index.md @@ -11,7 +11,7 @@ If you cannot contribute time, consider [donating to the NixOS Foundation's docu ## Reference manuals -The manuals for [Nix][nix manual] ([source][nix manual src]), [Nixpkgs][Nixpkgs manual] ([source][nixpkgs manual src]), and [NixOS][NixOS manual] ([source][nixos manual src]) are purely reference documentation, specifying interfaces and behavior. +The manuals for [Nix](nix-manual) ([source][nix manual src]), [Nixpkgs][Nixpkgs manual] ([source][nixpkgs manual src]), and [NixOS][NixOS manual] ([source][nixos manual src]) are purely reference documentation, specifying interfaces and behavior. They also show example interactions which demonstrate how to use its components, and explain mechanisms where necessary. @@ -31,7 +31,6 @@ You can help by - expanding on sections that appear incomplete - identifying sections that are not reference documentation and should be moved to nix.dev -[Nix manual]: https://nixos.org/manual/nix [nix manual src]: https://github.com/NixOS/nix/tree/master/doc/manual [Nixpkgs manual]: https://nixos.org/manual/nixpkgs [nixpkgs manual src]: https://github.com/NixOS/nixpkgs/tree/master/doc diff --git a/source/guides/best-practices.md b/source/guides/best-practices.md index f0f7c47bc..a4fd0079e 100644 --- a/source/guides/best-practices.md +++ b/source/guides/best-practices.md @@ -119,7 +119,7 @@ You will often encounter Nix language code samples that refer to ``. `<...>` 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#env-NIX_PATH +[`$NIX_PATH`]: https://nix.dev/manual/nix/2.18/command-ref/env-common.html#env-NIX_PATH This means, the value of a lookup path depends on external system state. When using lookup paths, the same Nix expression can produce different results. @@ -127,7 +127,7 @@ When using lookup 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. @@ -184,7 +184,7 @@ We skip it in minimal examples reduce distractions. ## 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: @@ -250,7 +250,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/guides/troubleshooting.md b/source/guides/troubleshooting.md index 3261f62e3..e56e15188 100644 --- a/source/guides/troubleshooting.md +++ b/source/guides/troubleshooting.md @@ -4,7 +4,7 @@ This page is a collection of tips to solve problems you may encounter using Nix. ## 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 force Nix to re-check if something exists in the binary cache? @@ -22,7 +22,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 @@ -34,7 +34,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: @@ -48,6 +48,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/install-nix.md b/source/install-nix.md index 3ab6e3281..15f242ab9 100644 --- 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/reference/glossary.md b/source/reference/glossary.md index d04aab4b6..5724ffcfe 100644 --- a/source/reference/glossary.md +++ b/source/reference/glossary.md @@ -7,7 +7,7 @@ Nix Read /nɪks/ ("Niks"). :::{seealso} - - [Nix Reference Manual](https://nixos.org/manual/nix) + - [Nix reference manual](./nix-manual.md) - [Nix source code](https://github.com/NixOS/nix) ::: @@ -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 @@ -31,7 +31,7 @@ Nixpkgs Read /nɪks ˈpækɪʤɪz/ ("Nix packages"). :::{seealso} - - [Nixpkgs Reference Manual](https://nixos.org/manual/nixpkgs) + - [Nixpkgs reference manual](https://nixos.org/manual/nixpkgs) - [Nixpkgs source code](https://github.com/NixOS/nixpkgs) ::: @@ -41,7 +41,7 @@ NixOS Read /nɪks oʊ ɛs/ ("Niks Oh Es"). :::{seealso} - - [NixOS Reference Manual](https://nixos.org/manual/nixos) + - [NixOS reference manual](https://nixos.org/manual/nixos) - [NixOS source code](https://github.com/NixOS/nixpkgs/tree/master/nixos) ::: ``` diff --git a/source/reference/index.md b/source/reference/index.md index 00dffe4ec..2329ac3ad 100644 --- a/source/reference/index.md +++ b/source/reference/index.md @@ -7,9 +7,9 @@ These sections contains collections of detailed technical descriptions. :glob: :maxdepth: 2 -Nix Reference Manual -Nixpkgs Manual -NixOS Manual +./nix-manual.md +Nixpkgs manual +NixOS manual Recommended support tools ../recommended-reading.md pinning-nixpkgs.md diff --git a/source/reference/nix-manual.md b/source/reference/nix-manual.md new file mode 100644 index 000000000..7e67a08cf --- /dev/null +++ b/source/reference/nix-manual.md @@ -0,0 +1,36 @@ +(nix-manual)= +# Nix reference manual + +```{toctree} +:hidden: + +Nix pre-release (development) +Nix 2.19 (latest) +Nix 2.18 (rolling) +Nix 2.18 (stable 23.11) +Nix 2.13 (stable 23.05) +``` + +- [Nix pre-release](https://hydra.nixos.org/job/nix/master/build.x86_64-linux/latest/download) + + Reference documentation for the latest build from the `master` branch of the [Nix repository](https://github.com/NixOS/nix) + +- [Nix 2.19](https://nix.dev/manual/nix/2.19/) + + Reference documentation for the latest Nix release + +- [Nix 2.18](https://nix.dev/manual/nix/2.18/) + + Reference documentation for the Nix version shipped with the {term}`Nixpkgs` and {term}`NixOS` rolling release + +- [Nix 2.18](https://nix.dev/manual/nix/2.18/) + + Reference documentation for the Nix version shipped with the current {term}`Nixpkgs` and {term}`NixOS` stable release + +- [Nix 2.13](https://nix.dev/manual/nix/2.13/) + + Reference documentation for the Nix version shipped with the previous {term}`Nixpkgs` and {term}`NixOS` stable release + +:::{tip} +More information on Nixpkgs and NixOS releases: [](channel-branches) +::: diff --git a/source/reference/pinning-nixpkgs.md b/source/reference/pinning-nixpkgs.md index 723a20fd5..cc745b642 100644 --- 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 index f086e5e59..5696aec2b 100644 --- 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 index 4ed39ea7d..0d74cf882 100644 --- 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 index da7659576..37e0b1d8f 100644 --- 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/nix-language.md b/source/tutorials/nix-language.md index 92639563c..41cdf9c92 100644 --- a/source/tutorials/nix-language.md +++ b/source/tutorials/nix-language.md @@ -64,7 +64,7 @@ This tutorial *does not* explain all Nix language features in detail and *does n See the [Nix manual][manual-language] for a full language reference. ::: -[manual-language]: https://nixos.org/manual/nix/stable/language/index.html +[manual-language]: https://nix.dev/manual/nix/2.18/language/index.html ### What do you need? @@ -139,7 +139,7 @@ Type `:q` to exit [`nix repl`]. ::: -[`nix repl`]: https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-repl.html +[`nix repl`]: https://nix.dev/manual/nix/2.18/command-ref/new-cli/nix3-repl.html #### Evaluating Nix files @@ -201,7 +201,7 @@ $ nix-instantiate --eval --strict file.nix ::: -[nix-instantiate]: https://nixos.org/manual/nix/stable/command-ref/nix-instantiate.html +[nix-instantiate]: https://nix.dev/manual/nix/2.18/command-ref/nix-instantiate.html ### Notes on whitespace @@ -314,8 +314,8 @@ Nix language data types *without functions* work just like their counterparts in - List elements are separated by white space.[^list-whitespace] ::: -[^attrnames]: Details: [Nix manual - attribute set](https://nixos.org/manual/nix/stable/language/values.html#attribute-set) -[^list-whitespace]: Details: [Nix manual - list](https://nixos.org/manual/nix/stable/language/values.html#list) +[^attrnames]: Details: [Nix manual - attribute set](https://nix.dev/manual/nix/2.18/language/values.html#attribute-set) +[^list-whitespace]: Details: [Nix manual - list](https://nix.dev/manual/nix/2.18/language/values.html#list) (rec-attrset)= #### Recursive attribute set `rec { ... }` @@ -971,9 +971,9 @@ For example, `` points to the subdirectory `lib` of that file syste While you will encounter many such examples, we recommend to [avoid lookup paths](search-path) in production code, as they are [impurities](impurities) which are not reproducible. -[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 [nixpkgs]: https://github.com/NixOS/nixpkgs -[manual-primitives]: https://nixos.org/manual/nix/stable/language/values.html#primitives +[manual-primitives]: https://nix.dev/manual/nix/2.18/language/values.html#primitives (indented-strings)= ### Indented strings @@ -1480,7 +1480,7 @@ You need to know about both to understand and navigate Nix language code. We recommend to at least skim them to familiarise yourself with what is available. -[operators]: https://nixos.org/manual/nix/stable/language/operators.html +[operators]: https://nix.dev/manual/nix/2.18/language/operators.html (builtins)= ### `builtins` @@ -1508,8 +1508,8 @@ builtins.toString ``` -[nix-operators]: https://nixos.org/manual/nix/unstable/language/operators.html -[nix-builtins]: https://nixos.org/manual/nix/stable/language/builtins.html +[nix-operators]: https://nix.dev/manual/nix/2.18/language/operators.html +[nix-builtins]: https://nix.dev/manual/nix/2.18/language/builtins.html (reading-nix-language-import)= #### `import` @@ -1812,10 +1812,10 @@ Files to be used as build inputs do not have to come from the file system. The Nix language provides built-in impure functions to fetch files over the network during evaluation: -- [`builtins.fetchurl`](https://nixos.org/manual/nix/stable/language/builtins.html#builtins-fetchurl) -- [`builtins.fetchTarball`](https://nixos.org/manual/nix/stable/language/builtins.html#builtins-fetchTarball) -- [`builtins.fetchGit`](https://nixos.org/manual/nix/stable/language/builtins.html#builtins-fetchGit) -- [`builtins.fetchClosure`](https://nixos.org/manual/nix/stable/language/builtins.html#builtins-fetchClosure) +- [`builtins.fetchurl`](https://nix.dev/manual/nix/2.18/language/builtins.html#builtins-fetchurl) +- [`builtins.fetchTarball`](https://nix.dev/manual/nix/2.18/language/builtins.html#builtins-fetchTarball) +- [`builtins.fetchGit`](https://nix.dev/manual/nix/2.18/language/builtins.html#builtins-fetchGit) +- [`builtins.fetchClosure`](https://nix.dev/manual/nix/2.18/language/builtins.html#builtins-fetchClosure) These functions evaluate to a file system path in the Nix store. @@ -2030,14 +2030,14 @@ Explanation: - [Nixpkgs manual: Functions reference][nixpkgs-functions] - [Nixpkgs manual: Fetchers][nixpkgs-fetchers] -[manual-string-interpolation]: https://nixos.org/manual/nix/stable/language/string-interpolation.html +[manual-string-interpolation]: https://nix.dev/manual/nix/2.18/language/string-interpolation.html ## Next steps ### Get things done - [](declarative-reproducible-envs) – create reproducible shell environments from a Nix file -- [Garbage Collection](https://nixos.org/manual/nix/stable/package-management/garbage-collection.html) – remove unused build results from the Nix store +- [Garbage Collection](https://nix.dev/manual/nix/2.18/package-management/garbage-collection.html) – remove unused build results from the Nix store ### Learn more diff --git a/source/tutorials/nixos/deploying-nixos-using-terraform.md b/source/tutorials/nixos/deploying-nixos-using-terraform.md index 184f03c44..c93d98faa 100644 --- a/source/tutorials/nixos/deploying-nixos-using-terraform.md +++ b/source/tutorials/nixos/deploying-nixos-using-terraform.md @@ -157,7 +157,7 @@ $ terraform apply ## Caveats - The `deploy_nixos` module requires NixOS to be installed on the target machine and Nix on the host machine. -- The `deploy_nixos` module doesn't work when the client and target architectures are different (unless you use [distributed builds](https://nixos.org/manual/nix/unstable/advanced-topics/distributed-builds.html)). +- The `deploy_nixos` module doesn't work when the client and target architectures are different (unless you use [distributed builds](https://nix.dev/manual/nix/2.18/advanced-topics/distributed-builds.html)). - If you need to inject a value into Nix, there is no elegant solution. - Each machine is evaluated separately, so note that your memory requirements will grow linearly with the number of machines. diff --git a/source/tutorials/nixos/nixos-configuration-on-vm.md b/source/tutorials/nixos/nixos-configuration-on-vm.md index 8f36786f4..4ceca652b 100644 --- a/source/tutorials/nixos/nixos-configuration-on-vm.md +++ b/source/tutorials/nixos/nixos-configuration-on-vm.md @@ -17,7 +17,7 @@ Virtual machines are a practical tool for debugging NixOS configurations. ## What do you need? -- A working [Nix installation](https://nixos.org/manual/nix/stable/installation/installation.html) on Linux, or [NixOS](https://nixos.org/manual/nixos/stable/index.html#sec-installation), with a graphical environment +- A working [Nix installation](https://nix.dev/manual/nix/2.18/installation/installation.html) on Linux, or [NixOS](https://nixos.org/manual/nixos/stable/index.html#sec-installation), with a graphical environment - Basic knowledge of the [Nix language](reading-nix-language) ## Starting from a default NixOS configuration @@ -171,17 +171,17 @@ This command builds the attribute `vm` from the `nixos-23.11` release of NixOS,
Detailed explanation -- The positional argument to [`nix-build`](https://nixos.org/manual/nix/stable/command-ref/nix-build.html) is a path to the derivation to be built. +- The positional argument to [`nix-build`](https://nix.dev/manual/nix/2.18/command-ref/nix-build.html) is a path to the derivation to be built. That path can be obtained from [a Nix expression that evaluates to a derivation](derivations). The virtual machine build helper is defined in NixOS, which is part of the [`nixpkgs` repository](https://github.com/NixOS/nixpkgs). Therefore we use the [lookup path](lookup-path-tutorial) ``. -- The [`-A` option](https://nixos.org/manual/nix/stable/command-ref/opt-common.html#opt-attr) specifies the attribute to pick from the provided Nix expression ``. +- The [`-A` option](https://nix.dev/manual/nix/2.18/command-ref/opt-common.html#opt-attr) specifies the attribute to pick from the provided Nix expression ``. To build the virtual machine, we choose the `vm` attribute as defined in [`nixos/default.nix`](https://github.com/NixOS/nixpkgs/blob/7c164f4bea71d74d98780ab7be4f9105630a2eba/nixos/default.nix#L19). -- The [`-I` option](https://nixos.org/manual/nix/stable/command-ref/opt-common.html#opt-I) prepends entries to the search path. +- The [`-I` option](https://nix.dev/manual/nix/2.18/command-ref/opt-common.html#opt-I) prepends entries to the search path. Here we set `nixpkgs` to refer to a [specific version of Nixpkgs](ref-pinning-nixpkgs) and set `nix-config` to the `configuration.nix` file in the current directory. @@ -239,6 +239,6 @@ rm nixos.qcow2 - [NixOS Manual: Changing the configuration](https://nixos.org/manual/nixos/stable/#sec-changing-config). - [NixOS source code: `configuration template` in `tools.nix`](https://github.com/NixOS/nixpkgs/blob/4e0525a8cdb370d31c1e1ba2641ad2a91fded57d/nixos/modules/installer/tools/tools.nix#L122-L226). - [NixOS source code: `vm` attribute in `default.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/default.nix). -- [Nix manual: `nix-build`](https://nixos.org/manual/nix/stable/command-ref/nix-build.html). -- [Nix manual: common command-line options](https://nixos.org/manual/nix/stable/command-ref/opt-common.html). -- [Nix manual: `NIX_PATH` environment variable](https://nixos.org/manual/nix/stable/command-ref/env-common.html#env-NIX_PATH). +- [Nix manual: `nix-build`](https://nix.dev/manual/nix/2.18/command-ref/nix-build.html). +- [Nix manual: common command-line options](https://nix.dev/manual/nix/2.18/command-ref/opt-common.html). +- [Nix manual: `NIX_PATH` environment variable](https://nix.dev/manual/nix/2.18/command-ref/env-common.html#env-NIX_PATH). diff --git a/source/tutorials/packaging-existing-software.md b/source/tutorials/packaging-existing-software.md index 9557fc3fe..dfc5d15eb 100644 --- a/source/tutorials/packaging-existing-software.md +++ b/source/tutorials/packaging-existing-software.md @@ -85,7 +85,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: