Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

host Nix reference manual on nix.dev #764

Merged
merged 6 commits into from
Dec 4, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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?
Expand Down
27 changes: 23 additions & 4 deletions default.nix
Original file line number Diff line number Diff line change
Expand Up @@ -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 =
Expand Down Expand Up @@ -68,6 +86,7 @@ in
inputsFrom = [ nix-dev ];
packages = [
devmode
pkgs.niv
pkgs.python310.pkgs.black
pkgs.vale
];
Expand Down
4 changes: 2 additions & 2 deletions maintainers/documentation-survey.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
36 changes: 36 additions & 0 deletions nix/sources.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
11 changes: 6 additions & 5 deletions source/concepts/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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).
Expand Down
12 changes: 6 additions & 6 deletions source/concepts/flakes.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
5 changes: 5 additions & 0 deletions source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 1 addition & 2 deletions source/contributing/documentation/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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
Expand Down
8 changes: 4 additions & 4 deletions source/guides/best-practices.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,15 +119,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#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.

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.
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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:

Expand Down
10 changes: 5 additions & 5 deletions source/guides/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand All @@ -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
Expand All @@ -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:

Expand All @@ -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).
4 changes: 2 additions & 2 deletions source/install-nix.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
8 changes: 4 additions & 4 deletions source/reference/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
:::

Expand All @@ -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
Expand All @@ -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)
:::

Expand All @@ -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)
:::
```
Loading