aboutsummaryrefslogtreecommitdiff
path: root/doc/manual
diff options
context:
space:
mode:
Diffstat (limited to 'doc/manual')
-rw-r--r--doc/manual/book.toml9
-rw-r--r--doc/manual/local.mk21
-rw-r--r--doc/manual/src/SUMMARY.md.in1
-rw-r--r--doc/manual/src/architecture/architecture.md2
-rw-r--r--doc/manual/src/command-ref/env-common.md2
-rw-r--r--doc/manual/src/command-ref/nix-copy-closure.md2
-rw-r--r--doc/manual/src/command-ref/nix-store.md23
-rw-r--r--doc/manual/src/contributing/hacking.md33
-rw-r--r--doc/manual/src/glossary.md25
-rw-r--r--doc/manual/src/language/index.md4
-rw-r--r--doc/manual/src/language/operators.md8
-rw-r--r--doc/manual/src/package-management/binary-cache-substituter.md8
-rw-r--r--doc/manual/src/release-notes/rl-2.13.md40
-rw-r--r--doc/manual/src/release-notes/rl-next.md21
14 files changed, 148 insertions, 51 deletions
diff --git a/doc/manual/book.toml b/doc/manual/book.toml
index 46ced7ff7..73fb7e75e 100644
--- a/doc/manual/book.toml
+++ b/doc/manual/book.toml
@@ -10,3 +10,12 @@ git-repository-url = "https://github.com/NixOS/nix"
[preprocessor.anchors]
renderers = ["html"]
command = "jq --from-file doc/manual/anchors.jq"
+
+[output.linkcheck]
+# no Internet during the build (in the sandbox)
+follow-web-links = false
+
+# mdbook-linkcheck does not understand [foo]{#bar} style links, resulting in
+# excessive "Potential incomplete link" warnings. No other kind of warning was
+# produced at the time of writing.
+warning-policy = "ignore"
diff --git a/doc/manual/local.mk b/doc/manual/local.mk
index c0f69e00f..190f0258a 100644
--- a/doc/manual/local.mk
+++ b/doc/manual/local.mk
@@ -50,11 +50,16 @@ $(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/command-ref/new-cli
$(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/generate-manpage.nix $(bindir)/nix
@rm -rf $@
- $(trace-gen) $(nix-eval) --write-to $@ --expr 'import doc/manual/generate-manpage.nix { toplevel = builtins.readFile $<; }'
+ $(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-manpage.nix { toplevel = builtins.readFile $<; }'
+ # @docroot@: https://nixos.org/manual/nix/unstable/contributing/hacking.html#docroot-variable
+ $(trace-gen) sed -i $@.tmp/*.md -e 's^@docroot@^../..^g'
+ @mv $@.tmp $@
$(d)/src/command-ref/conf-file.md: $(d)/conf-file.json $(d)/generate-options.nix $(d)/src/command-ref/conf-file-prefix.md $(bindir)/nix
@cat doc/manual/src/command-ref/conf-file-prefix.md > $@.tmp
- $(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-options.nix (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp
+ # @docroot@: https://nixos.org/manual/nix/unstable/contributing/hacking.html#docroot-variable
+ $(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-options.nix (builtins.fromJSON (builtins.readFile $<))' \
+ | sed -e 's^@docroot@^..^g'>> $@.tmp
@mv $@.tmp $@
$(d)/nix.json: $(bindir)/nix
@@ -67,7 +72,9 @@ $(d)/conf-file.json: $(bindir)/nix
$(d)/src/language/builtins.md: $(d)/builtins.json $(d)/generate-builtins.nix $(d)/src/language/builtins-prefix.md $(bindir)/nix
@cat doc/manual/src/language/builtins-prefix.md > $@.tmp
- $(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp
+ # @docroot@: https://nixos.org/manual/nix/unstable/contributing/hacking.html#docroot-variable
+ $(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<))' \
+ | sed -e 's^@docroot@^..^g' >> $@.tmp
@cat doc/manual/src/language/builtins-suffix.md >> $@.tmp
@mv $@.tmp $@
@@ -102,6 +109,12 @@ doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
@touch $@
$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/command-ref/new-cli $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md
- $(trace-gen) RUST_LOG=warn mdbook build doc/manual -d $(DESTDIR)$(docdir)/manual
+ $(trace-gen) \
+ set -euo pipefail; \
+ RUST_LOG=warn mdbook build doc/manual -d $(DESTDIR)$(docdir)/manual.tmp 2>&1 \
+ | { grep -Fv "because fragment resolution isn't implemented" || :; }
+ @rm -rf $(DESTDIR)$(docdir)/manual
+ @mv $(DESTDIR)$(docdir)/manual.tmp/html $(DESTDIR)$(docdir)/manual
+ @rm -rf $(DESTDIR)$(docdir)/manual.tmp
endif
diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 4f1fc34ce..b1c551969 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -67,6 +67,7 @@
- [CLI guideline](contributing/cli-guideline.md)
- [Release Notes](release-notes/release-notes.md)
- [Release X.Y (202?-??-??)](release-notes/rl-next.md)
+ - [Release 2.13 (2023-01-17)](release-notes/rl-2.13.md)
- [Release 2.12 (2022-12-06)](release-notes/rl-2.12.md)
- [Release 2.11 (2022-08-25)](release-notes/rl-2.11.md)
- [Release 2.10 (2022-07-11)](release-notes/rl-2.10.md)
diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index 2d1b26558..e51958052 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -68,7 +68,7 @@ It can also execute build plans to produce new data, which are made available to
A build plan itself is a series of *build tasks*, together with their build inputs.
> **Important**
-> A build task in Nix is called [derivation](../glossary#gloss-derivation).
+> A build task in Nix is called [derivation](../glossary.md#gloss-derivation).
Each build task has a special build input executed as *build instructions* in order to perform the build.
The result of a build task can be input to another build task.
diff --git a/doc/manual/src/command-ref/env-common.md b/doc/manual/src/command-ref/env-common.md
index 5845bdc43..bb85a6b07 100644
--- a/doc/manual/src/command-ref/env-common.md
+++ b/doc/manual/src/command-ref/env-common.md
@@ -11,7 +11,7 @@ Most Nix commands interpret the following environment variables:
expressions using [paths](../language/values.md#type-path)
enclosed in angle brackets (i.e., `<path>`),
e.g. `/home/eelco/Dev:/etc/nixos`. It can be extended using the
- [`-I` option](./opt-common#opt-I).
+ [`-I` option](./opt-common.md#opt-I).
- [`NIX_IGNORE_SYMLINK_STORE`]{#env-NIX_IGNORE_SYMLINK_STORE}\
Normally, the Nix store directory (typically `/nix/store`) is not
diff --git a/doc/manual/src/command-ref/nix-copy-closure.md b/doc/manual/src/command-ref/nix-copy-closure.md
index 83e8a2936..cd8e351bb 100644
--- a/doc/manual/src/command-ref/nix-copy-closure.md
+++ b/doc/manual/src/command-ref/nix-copy-closure.md
@@ -49,7 +49,7 @@ authentication, you can avoid typing the passphrase with `ssh-agent`.
- `--include-outputs`\
Also copy the outputs of [store derivation]s included in the closure.
- [store derivation]: ../../glossary.md#gloss-store-derivation
+ [store derivation]: ../glossary.md#gloss-store-derivation
- `--use-substitutes` / `-s`\
Attempt to download missing paths on the target machine using Nix’s
diff --git a/doc/manual/src/command-ref/nix-store.md b/doc/manual/src/command-ref/nix-store.md
index 6d0e02ca5..f6017481c 100644
--- a/doc/manual/src/command-ref/nix-store.md
+++ b/doc/manual/src/command-ref/nix-store.md
@@ -66,11 +66,11 @@ The operation `--realise` essentially “builds” the specified store
paths. Realisation is a somewhat overloaded term:
- If the store path is a *derivation*, realisation ensures that the
- output paths of the derivation are [valid](../glossary.md) (i.e.,
+ output paths of the derivation are [valid] (i.e.,
the output path and its closure exist in the file system). This
can be done in several ways. First, it is possible that the
outputs are already valid, in which case we are done
- immediately. Otherwise, there may be [substitutes](../glossary.md)
+ immediately. Otherwise, there may be [substitutes]
that produce the outputs (e.g., by downloading them). Finally, the
outputs can be produced by running the build task described
by the derivation.
@@ -82,6 +82,9 @@ paths. Realisation is a somewhat overloaded term:
produced through substitutes. If there are no (successful)
substitutes, realisation fails.
+[valid]: ../glossary.md#validity
+[substitutes]: ../glossary.md#substitute
+
The output path of each derivation is printed on standard output. (For
non-derivations argument, the argument itself is printed.)
@@ -295,8 +298,8 @@ error: cannot delete path `/nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4'
## Description
-The operation `--query` displays various bits of information about the
-store paths . The queries are described below. At most one query can be
+The operation `--query` displays information about [store path]s.
+The queries are described below. At most one query can be
specified. The default query is `--outputs`.
The paths *paths* may also be symlinks from outside of the Nix store, to
@@ -316,12 +319,12 @@ symlink.
## Queries
- `--outputs`\
- Prints out the [output paths](../glossary.md) of the store
+ Prints out the [output path]s of the store
derivations *paths*. These are the paths that will be produced when
the derivation is built.
- `--requisites`; `-R`\
- Prints out the [closure](../glossary.md) of the store path *paths*.
+ Prints out the [closure] of the given *paths*.
This query has one option:
@@ -338,10 +341,12 @@ symlink.
derivation and specifying the option `--include-outputs`.
- `--references`\
- Prints the set of [references](../glossary.md) of the store paths
+ Prints the set of [references]s of the store paths
*paths*, that is, their immediate dependencies. (For *all*
dependencies, use `--requisites`.)
+ [reference]: ../glossary.md#gloss-reference
+
- `--referrers`\
Prints the set of *referrers* of the store paths *paths*, that is,
the store paths currently existing in the Nix store that refer to
@@ -356,11 +361,13 @@ symlink.
in the Nix store that are dependent on *paths*.
- `--deriver`; `-d`\
- Prints the [deriver](../glossary.md) of the store paths *paths*. If
+ Prints the [deriver] of the store paths *paths*. If
the path has no deriver (e.g., if it is a source file), or if the
deriver is not known (e.g., in the case of a binary-only
deployment), the string `unknown-deriver` is printed.
+ [deriver]: ../glossary.md#gloss-deriver
+
- `--graph`\
Prints the references graph of the store paths *paths* in the format
of the `dot` tool of AT\&T's [Graphviz
diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
index c9da1962f..aeb0d41b3 100644
--- a/doc/manual/src/contributing/hacking.md
+++ b/doc/manual/src/contributing/hacking.md
@@ -249,3 +249,36 @@ search/replaced in it for each new build.
The installer now supports a `--tarball-url-prefix` flag which _may_ have
solved this need?
-->
+
+### Checking links in the manual
+
+The build checks for broken internal links.
+This happens late in the process, so `nix build` is not suitable for iterating.
+To build the manual incrementally, run:
+
+```console
+make html -j $NIX_BUILD_CORES
+```
+
+In order to reflect changes to the [Makefile], clear all generated files before re-building:
+
+[Makefile]: https://github.com/NixOS/nix/blob/master/doc/manual/local.mk
+
+```console
+rm $(git ls-files doc/manual/ -o | grep -F '.md') && rmdir doc/manual/src/command-ref/new-cli && make html -j $NIX_BUILD_CORES
+```
+
+[`mdbook-linkcheck`] does not implement checking [URI fragments] yet.
+
+[`mdbook-linkcheck`]: https://github.com/Michael-F-Bryan/mdbook-linkcheck
+[URI fragments]: https://en.m.wikipedia.org/wiki/URI_fragment
+
+#### `@docroot@` variable
+
+`@docroot@` provides a base path for links that occur in reusable snippets or other documentation that doesn't have a base path of its own.
+
+If a broken link occurs in a snippet that was inserted into multiple generated files in different directories, use `@docroot@` to reference the `doc/manual/src` directory.
+
+If the `@docroot@` literal appears in an error message from the `mdbook-linkcheck` tool, the `@docroot@` replacement needs to be applied to the generated source file that mentions it.
+See existing `@docroot@` logic in the [Makefile].
+Regular markdown files used for the manual have a base path of their own and they can use relative paths instead of `@docroot@`.
diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index e63f6becc..5a49af8dc 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -19,6 +19,17 @@
[store derivation]: #gloss-store-derivation
+ - [realise]{#gloss-realise}, realisation\
+ Ensure a [store path] is [valid][validity].
+
+ This means either running the `builder` executable as specified in the corresponding [derivation] or fetching a pre-built [store object] from a [substituter].
+
+ See [`nix-build`](./command-ref/nix-build.md) and [`nix-store --realise`](./command-ref/nix-store.md#operation---realise).
+
+ See [`nix build`](./command-ref/new-cli/nix3-build.md) (experimental).
+
+ [realise]: #gloss-realise
+
- [content-addressed derivation]{#gloss-content-addressed-derivation}\
A derivation which has the
[`__contentAddressed`](./language/advanced-attributes.md#adv-attr-__contentAddressed)
@@ -101,6 +112,8 @@
copy store objects it doesn't have. For details, see the
[`substituters` option](./command-ref/conf-file.md#conf-substituters).
+ [substituter]: #gloss-substituter
+
- [purity]{#gloss-purity}\
The assumption that equal Nix derivations when run always produce
the same output. This cannot be guaranteed in general (e.g., a
@@ -149,13 +162,15 @@
[output path]: #gloss-output-path
- [deriver]{#gloss-deriver}\
- The deriver of an *output path* is the store
- derivation that built it.
+ The [store derivation] that produced an [output path].
- [validity]{#gloss-validity}\
- A store path is considered *valid* if it exists in the file system,
- is listed in the Nix database as being valid, and if all paths in
- its closure are also valid.
+ A store path is valid if all [store object]s in its [closure] can be read from the [store].
+
+ For a local store, this means:
+ - The store path leads to an existing [store object] in that [store].
+ - The store path is listed in the Nix database as being valid.
+ - All paths in the store path's [closure] are valid.
- [user environment]{#gloss-user-env}\
An automatically generated store object that consists of a set of
diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md
index db34fde75..31300631c 100644
--- a/doc/manual/src/language/index.md
+++ b/doc/manual/src/language/index.md
@@ -191,12 +191,12 @@ This is an incomplete overview of language features, by example.
<tr>
<td>
- <nixpkgs>
+ `<nixpkgs>`
</td>
<td>
- Search path. Value determined by [`$NIX_PATH` environment variable](../command-ref/env-common.md#env-NIX_PATH).
+ Search path for Nix files. Value determined by [`$NIX_PATH` environment variable](../command-ref/env-common.md#env-NIX_PATH).
</td>
</tr>
diff --git a/doc/manual/src/language/operators.md b/doc/manual/src/language/operators.md
index 797f13bd3..1f918bd4d 100644
--- a/doc/manual/src/language/operators.md
+++ b/doc/manual/src/language/operators.md
@@ -24,7 +24,7 @@
| [Equality] | *expr* `==` *expr* | none | 11 |
| Inequality | *expr* `!=` *expr* | none | 11 |
| Logical conjunction (`AND`) | *bool* `&&` *bool* | left | 12 |
-| Logical disjunction (`OR`) | *bool* `||` *bool* | left | 13 |
+| Logical disjunction (`OR`) | *bool* `\|\|` *bool* | left | 13 |
| [Logical implication] | *bool* `->` *bool* | none | 14 |
[string]: ./values.md#type-string
@@ -120,12 +120,12 @@ The result is a string.
## Update
-> *attrset1* + *attrset2*
+> *attrset1* // *attrset2*
Update [attribute set] *attrset1* with names and values from *attrset2*.
-The returned attribute set will have of all the attributes in *e1* and *e2*.
-If an attribute name is present in both, the attribute value from the former is taken.
+The returned attribute set will have of all the attributes in *attrset1* and *attrset2*.
+If an attribute name is present in both, the attribute value from the latter is taken.
[Update]: #update
diff --git a/doc/manual/src/package-management/binary-cache-substituter.md b/doc/manual/src/package-management/binary-cache-substituter.md
index ef738794b..5befad9f8 100644
--- a/doc/manual/src/package-management/binary-cache-substituter.md
+++ b/doc/manual/src/package-management/binary-cache-substituter.md
@@ -32,13 +32,13 @@ which should print something like:
Priority: 30
On the client side, you can tell Nix to use your binary cache using
-`--option extra-binary-caches`, e.g.:
+`--substituters`, e.g.:
```console
-$ nix-env -iA nixpkgs.firefox --option extra-binary-caches http://avalon:8080/
+$ nix-env -iA nixpkgs.firefox --substituters http://avalon:8080/
```
-The option `extra-binary-caches` tells Nix to use this binary cache in
+The option `substituters` tells Nix to use this binary cache in
addition to your default caches, such as <https://cache.nixos.org>.
Thus, for any path in the closure of Firefox, Nix will first check if
the path is available on the server `avalon` or another binary caches.
@@ -47,4 +47,4 @@ If not, it will fall back to building from source.
You can also tell Nix to always use your binary cache by adding a line
to the `nix.conf` configuration file like this:
- binary-caches = http://avalon:8080/ https://cache.nixos.org/
+ substituters = http://avalon:8080/ https://cache.nixos.org/
diff --git a/doc/manual/src/release-notes/rl-2.13.md b/doc/manual/src/release-notes/rl-2.13.md
new file mode 100644
index 000000000..2b79620be
--- /dev/null
+++ b/doc/manual/src/release-notes/rl-2.13.md
@@ -0,0 +1,40 @@
+# Release 2.13 (2023-01-17)
+
+* The `repeat` and `enforce-determinism` options have been removed
+ since they had been broken under many circumstances for a long time.
+
+* You can now use [flake references] in the [old command line interface], e.g.
+
+ [flake references]: ../command-ref/new-cli/nix3-flake.md#flake-references
+ [old command line interface]: ../command-ref/main-commands.md
+
+ ```shell-session
+ # nix-build flake:nixpkgs -A hello
+ # nix-build -I nixpkgs=flake:github:NixOS/nixpkgs/nixos-22.05 \
+ '<nixpkgs>' -A hello
+ # NIX_PATH=nixpkgs=flake:nixpkgs nix-build '<nixpkgs>' -A hello
+ ```
+
+* Instead of "antiquotation", the more common term [string interpolation](../language/string-interpolation.md) is now used consistently.
+ Historical release notes were not changed.
+
+* Allow explicitly selecting outputs in a store derivation installable, just like we can do with other sorts of installables.
+ For example,
+ ```shell-session
+ # nix-build /nix/store/gzaflydcr6sb3567hap9q6srzx8ggdgg-glibc-2.33-78.drv^dev
+ ```
+ now works just as
+ ```shell-session
+ # nix-build glibc^dev
+ ```
+ does already.
+
+* On Linux, `nix develop` now sets the
+ [*personality*](https://man7.org/linux/man-pages/man2/personality.2.html)
+ for the development shell in the same way as the actual build of the
+ derivation. This makes shells for `i686-linux` derivations work
+ correctly on `x86_64-linux`.
+
+* You can now disable the global flake registry by setting the `flake-registry`
+ configuration option to an empty string. The same can be achieved at runtime with
+ `--flake-registry ""`.
diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 9f491efc8..78ae99f4b 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -1,23 +1,2 @@
# Release X.Y (202?-??-??)
-* The `repeat` and `enforce-determinism` options have been removed
- since they had been broken under many circumstances for a long time.
-
-* You can now use [flake references] in the [old command line interface], e.g.
-
- [flake references]: ../command-ref/new-cli/nix3-flake.md#flake-references
- [old command line interface]: ../command-ref/main-commands.md
-
- ```
- # nix-build flake:nixpkgs -A hello
- # nix-build -I nixpkgs=flake:github:NixOS/nixpkgs/nixos-22.05 \
- '<nixpkgs>' -A hello
- # NIX_PATH=nixpkgs=flake:nixpkgs nix-build '<nixpkgs>' -A hello
- ```
-
-* Instead of "antiquotation", the more common term [string interpolation](../language/string-interpolation.md) is now used consistently.
- Historical release notes were not changed.
-
-* Error traces have been reworked to provide detailed explanations and more
- accurate error locations. A short excerpt of the trace is now shown by
- default when an error occurs.
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-23 08:28:49 +0000