mirror of
https://github.com/NixOS/nix.dev.git
synced 2024-10-18 00:06:26 -04:00
Merge pull request #764 from fricklerhandwerk/add-manuals
host Nix reference manual on nix.dev
This commit is contained in:
Robert Hensing
GitHub
commit
9cc2ddd16a
|
|
@ -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?
|
||||
|
|
|
|||
27
default.nix
27
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
|
||||
];
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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/<owner>/<repo>/archive/<rev>.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/<owner>/<repo>/archive/<rev>.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/<owner>/<repo>/archive/<rev>.tar.gz"
|
||||
},
|
||||
"nixpkgs": {
|
||||
"branch": "nixos-23.05",
|
||||
"description": "Nix Packages collection & NixOS",
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -423,6 +423,11 @@ linkcheck_ignore = [
|
|||
# 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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -119,7 +119,7 @@ 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#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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
:::
|
||||
```
|
||||
|
|
|
|||
|
|
@ -7,9 +7,9 @@ These sections contains collections of detailed technical descriptions.
|
|||
:glob:
|
||||
:maxdepth: 2
|
||||
|
||||
Nix Reference Manual <https://nixos.org/manual/nix/stable/>
|
||||
Nixpkgs Manual <https://nixos.org/manual/nixpkgs/stable/>
|
||||
NixOS Manual <https://nixos.org/manual/nixos/stable/>
|
||||
./nix-manual.md
|
||||
Nixpkgs manual <https://nixos.org/manual/nixpkgs/stable/>
|
||||
NixOS manual <https://nixos.org/manual/nixos/stable/>
|
||||
Recommended support tools <https://github.com/nix-community/awesome-nix>
|
||||
../recommended-reading.md
|
||||
pinning-nixpkgs.md
|
||||
|
|
|
|||
36
source/reference/nix-manual.md
Normal file
36
source/reference/nix-manual.md
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
(nix-manual)=
|
||||
# Nix reference manual
|
||||
|
||||
```{toctree}
|
||||
:hidden:
|
||||
|
||||
Nix pre-release (development) <https://hydra.nixos.org/job/nix/master/build.x86_64-linux/latest/download>
|
||||
Nix 2.19 (latest) <https://nix.dev/manual/nix/2.19/>
|
||||
Nix 2.18 (rolling) <https://nix.dev/manual/nix/2.18/>
|
||||
Nix 2.18 (stable 23.11) <https://nix.dev/manual/nix/2.18/>
|
||||
Nix 2.13 (stable 23.05) <https://nix.dev/manual/nix/2.13/>
|
||||
```
|
||||
|
||||
- [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)
|
||||
:::
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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, `<nixpkgs/lib>` 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
|
|||
<PRIMOP>
|
||||
```
|
||||
|
||||
[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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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,
|
|||
|
||||
<details><summary> Detailed explanation </summary>
|
||||
|
||||
- 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) `<nixpkgs/nixos>`.
|
||||
|
||||
- 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 `<nixpkgs/nixos>`.
|
||||
- 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 `<nixpkgs/nixos>`.
|
||||
|
||||
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).
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue