aboutsummaryrefslogtreecommitdiff
path: root/doc/manual
diff options
context:
space:
mode:
Diffstat (limited to 'doc/manual')
-rw-r--r--doc/manual/generate-manpage.nix32
-rw-r--r--doc/manual/generate-xp-features-shortlist.nix9
-rw-r--r--doc/manual/generate-xp-features.nix11
-rw-r--r--doc/manual/local.mk23
-rw-r--r--doc/manual/src/SUMMARY.md.in2
-rw-r--r--doc/manual/src/command-ref/experimental-commands.md2
-rw-r--r--doc/manual/src/command-ref/nix-shell.md3
-rw-r--r--doc/manual/src/contributing/experimental-features.md95
-rw-r--r--doc/manual/src/glossary.md34
-rw-r--r--doc/manual/src/language/advanced-attributes.md26
-rw-r--r--doc/manual/src/quick-start.md12
-rw-r--r--doc/manual/src/release-notes/rl-2.15.md58
-rw-r--r--doc/manual/src/release-notes/rl-next.md39
-rw-r--r--doc/manual/utils.nix33
14 files changed, 294 insertions, 85 deletions
diff --git a/doc/manual/generate-manpage.nix b/doc/manual/generate-manpage.nix
index 86f2ca567..d04eecf55 100644
--- a/doc/manual/generate-manpage.nix
+++ b/doc/manual/generate-manpage.nix
@@ -10,7 +10,9 @@ let
result = ''
> **Warning** \
- > This program is **experimental** and its interface is subject to change.
+ > This program is
+ > [**experimental**](@docroot@/contributing/experimental-features.md#xp-feature-nix-command)
+ > and its interface is subject to change.
# Name
@@ -29,19 +31,18 @@ let
showSynopsis = command: args:
let
- showArgument = arg: "*${arg.label}*" + (if arg ? arity then "" else "...");
+ showArgument = arg: "*${arg.label}*" + optionalString (! arg ? arity) "...";
arguments = concatStringsSep " " (map showArgument args);
in ''
`${command}` [*option*...] ${arguments}
'';
- maybeSubcommands = if details ? commands && details.commands != {}
- then ''
+ maybeSubcommands = optionalString (details ? commands && details.commands != {})
+ ''
where *subcommand* is one of the following:
${subcommands}
- ''
- else "";
+ '';
subcommands = if length categories > 1
then listCategories
@@ -63,12 +64,11 @@ let
* [`${command} ${name}`](./${appendName filename name}.md) - ${subcmd.description}
'';
- maybeDocumentation =
- if details ? doc
- then replaceStrings ["@stores@"] [storeDocs] details.doc
- else "";
+ maybeDocumentation = optionalString
+ (details ? doc)
+ (replaceStrings ["@stores@"] [storeDocs] details.doc);
- maybeOptions = if details.flags == {} then "" else ''
+ maybeOptions = optionalString (details.flags != {}) ''
# Options
${showOptions details.flags toplevel.flags}
@@ -78,15 +78,19 @@ let
let
allOptions = options // commonOptions;
showCategory = cat: ''
- ${if cat != "" then "**${cat}:**" else ""}
+ ${optionalString (cat != "") "**${cat}:**"}
${listOptions (filterAttrs (n: v: v.category == cat) allOptions)}
'';
listOptions = opts: concatStringsSep "\n" (attrValues (mapAttrs showOption opts));
showOption = name: option:
let
- shortName = if option ? shortName then "/ `-${option.shortName}`" else "";
- labels = if option ? labels then (concatStringsSep " " (map (s: "*${s}*") option.labels)) else "";
+ shortName = optionalString
+ (option ? shortName)
+ ("/ `-${option.shortName}`");
+ labels = optionalString
+ (option ? labels)
+ (concatStringsSep " " (map (s: "*${s}*") option.labels));
in trim ''
- `--${name}` ${shortName} ${labels}
diff --git a/doc/manual/generate-xp-features-shortlist.nix b/doc/manual/generate-xp-features-shortlist.nix
new file mode 100644
index 000000000..30e211c96
--- /dev/null
+++ b/doc/manual/generate-xp-features-shortlist.nix
@@ -0,0 +1,9 @@
+with builtins;
+with import ./utils.nix;
+
+let
+ showExperimentalFeature = name: doc:
+ ''
+ - [`${name}`](@docroot@/contributing/experimental-features.md#xp-feature-${name})
+ '';
+in xps: indent " " (concatStrings (attrValues (mapAttrs showExperimentalFeature xps)))
diff --git a/doc/manual/generate-xp-features.nix b/doc/manual/generate-xp-features.nix
new file mode 100644
index 000000000..adb94355c
--- /dev/null
+++ b/doc/manual/generate-xp-features.nix
@@ -0,0 +1,11 @@
+with builtins;
+with import ./utils.nix;
+
+let
+ showExperimentalFeature = name: doc:
+ squash ''
+ ## [`${name}`]{#xp-feature-${name}}
+
+ ${doc}
+ '';
+in xps: (concatStringsSep "\n" (attrValues (mapAttrs showExperimentalFeature xps)))
diff --git a/doc/manual/local.mk b/doc/manual/local.mk
index df941d460..63e7e61e4 100644
--- a/doc/manual/local.mk
+++ b/doc/manual/local.mk
@@ -81,19 +81,20 @@ $(d)/%.8: $(d)/src/command-ref/%.md
$(d)/nix.conf.5: $(d)/src/command-ref/conf-file.md
@printf "Title: %s\n\n" "$$(basename $@ .5)" > $^.tmp
@cat $^ >> $^.tmp
+ @$(call process-includes,$^,$^.tmp)
$(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@
@rm $^.tmp
-$(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/command-ref/new-cli
+$(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md
@cp $< $@
@$(call process-includes,$@,$@)
-$(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/generate-manpage.nix $(bindir)/nix
+$(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/utils.nix $(d)/generate-manpage.nix $(bindir)/nix
@rm -rf $@ $@.tmp
$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-manpage.nix (builtins.readFile $<)'
@mv $@.tmp $@
-$(d)/src/command-ref/conf-file.md: $(d)/conf-file.json $(d)/utils.nix $(d)/src/command-ref/conf-file-prefix.md $(bindir)/nix
+$(d)/src/command-ref/conf-file.md: $(d)/conf-file.json $(d)/utils.nix $(d)/src/command-ref/conf-file-prefix.md $(d)/src/command-ref/experimental-features-shortlist.md $(bindir)/nix
@cat doc/manual/src/command-ref/conf-file-prefix.md > $@.tmp
$(trace-gen) $(nix-eval) --expr '(import doc/manual/utils.nix).showSettings { useAnchors = true; } (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp;
@mv $@.tmp $@
@@ -106,6 +107,20 @@ $(d)/conf-file.json: $(bindir)/nix
$(trace-gen) $(dummy-env) $(bindir)/nix show-config --json --experimental-features nix-command > $@.tmp
@mv $@.tmp $@
+$(d)/src/contributing/experimental-feature-descriptions.md: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features.nix $(bindir)/nix
+ @rm -rf $@ $@.tmp
+ $(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-xp-features.nix (builtins.fromJSON (builtins.readFile $<))'
+ @mv $@.tmp $@
+
+$(d)/src/command-ref/experimental-features-shortlist.md: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features-shortlist.nix $(bindir)/nix
+ @rm -rf $@ $@.tmp
+ $(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-xp-features-shortlist.nix (builtins.fromJSON (builtins.readFile $<))'
+ @mv $@.tmp $@
+
+$(d)/xp-features.json: $(bindir)/nix
+ $(trace-gen) $(dummy-env) NIX_PATH=nix/corepkgs=corepkgs $(bindir)/nix __dump-xp-features > $@.tmp
+ @mv $@.tmp $@
+
$(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;
@@ -145,7 +160,7 @@ doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
done
@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
+$(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/contributing/experimental-feature-descriptions.md $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md
$(trace-gen) \
tmp="$$(mktemp -d)"; \
cp -r doc/manual "$$tmp"; \
diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 4b654567f..f783d5908 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -95,9 +95,11 @@
- [Glossary](glossary.md)
- [Contributing](contributing/contributing.md)
- [Hacking](contributing/hacking.md)
+ - [Experimental Features](contributing/experimental-features.md)
- [CLI guideline](contributing/cli-guideline.md)
- [Release Notes](release-notes/release-notes.md)
- [Release X.Y (202?-??-??)](release-notes/rl-next.md)
+ - [Release 2.15 (2023-04-11)](release-notes/rl-2.15.md)
- [Release 2.14 (2023-02-28)](release-notes/rl-2.14.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)
diff --git a/doc/manual/src/command-ref/experimental-commands.md b/doc/manual/src/command-ref/experimental-commands.md
index cfa6f8b73..286ddc6d6 100644
--- a/doc/manual/src/command-ref/experimental-commands.md
+++ b/doc/manual/src/command-ref/experimental-commands.md
@@ -1,6 +1,6 @@
# Experimental Commands
-This section lists experimental commands.
+This section lists [experimental commands](@docroot@/contributing/experimental-features.md#xp-feature-nix-command).
> **Warning**
>
diff --git a/doc/manual/src/command-ref/nix-shell.md b/doc/manual/src/command-ref/nix-shell.md
index 9f36929f7..576e5ba0b 100644
--- a/doc/manual/src/command-ref/nix-shell.md
+++ b/doc/manual/src/command-ref/nix-shell.md
@@ -120,7 +120,8 @@ shell in which to build it:
```console
$ nix-shell '<nixpkgs>' -A pan
[nix-shell]$ eval ${unpackPhase:-unpackPhase}
-[nix-shell]$ cd pan-*
+[nix-shell]$ cd $sourceRoot
+[nix-shell]$ eval ${patchPhase:-patchPhase}
[nix-shell]$ eval ${configurePhase:-configurePhase}
[nix-shell]$ eval ${buildPhase:-buildPhase}
[nix-shell]$ ./pan/gui/pan
diff --git a/doc/manual/src/contributing/experimental-features.md b/doc/manual/src/contributing/experimental-features.md
new file mode 100644
index 000000000..ad5cffa91
--- /dev/null
+++ b/doc/manual/src/contributing/experimental-features.md
@@ -0,0 +1,95 @@
+This section describes the notion of *experimental features*, and how it fits into the big picture of the development of Nix.
+
+# What are experimental features?
+
+Experimental features are considered unstable, which means that they can be changed or removed at any time.
+Users must explicitly enable them by toggling the associated [experimental feature flags](@docroot@/command-ref/conf-file.md#conf-experimental-features).
+This allows accessing unstable functionality without unwittingly relying on it.
+
+Experimental feature flags were first introduced in [Nix 2.4](@docroot@/release-notes/rl-2.4.md).
+Before that, Nix did have experimental features, but they were not guarded by flags and were merely documented as unstable.
+This was a source of confusion and controversy.
+
+# When should a new feature be marked experimental?
+
+A change in the Nix codebase should be guarded by an experimental feature flag if it is considered likely to be reverted or adapted in a backwards-incompatible manner after gathering more experience with it in practice.
+
+Examples:
+
+- Changes to the Nix language, such as new built-ins, syntactic or semantic changes, etc.
+- Changes to the command-line interface
+
+# Lifecycle of an experimental feature
+
+Experimental features have to be treated on a case-by-case basis.
+However, the standard workflow for an experimental feature is as follows:
+
+- A new feature is implemented in a *pull request*
+ - It is guarded by an experimental feature flag that is disabled by default
+- The pull request is merged, the *experimental* feature ends up in a release
+ - Using the feature requires explicitly enabling it, signifying awareness of the potential risks
+ - Being experimental, the feature can still be changed arbitrarily
+- The feature can be *removed*
+ - The associated experimental feature flag is also removed
+- The feature can be declared *stable*
+ - The associated experimental feature flag is removed
+ - There should be enough evidence of users having tried the feature, such as feedback, fixed bugs, demonstrations of how it is put to use
+ - Maintainers must feel confident that:
+ - The feature is designed and implemented sensibly, that it is fit for purpose
+ - Potential interactions are well-understood
+ - Stabilising the feature will not incur an outsized maintenance burden in the future
+
+The following diagram illustrates the process:
+
+```
+ .------.
+ | idea |
+ '------'
+ |
+ discussion, design, implementation
+ |
+ | .-------.
+ | | |
+ v v |
+ .--------------. review
+ | pull request | |
+ '--------------' |
+ | ^ | |
+ | | '-------'
+ .---' '----.
+ | |
+ merge user feedback,
+ | (breaking) changes
+ | |
+ '---. .----'
+ | |
+ v |
+ +--------------+
+ .---| experimental |----.
+ | +--------------+ |
+ | |
+decision to stabilise decision against
+ | keeping the feature
+ | |
+ v v
+ +--------+ +---------+
+ | stable | | removed |
+ +--------+ +---------+
+```
+
+# Relation to the RFC process
+
+Experimental features and [RFCs](https://github.com/NixOS/rfcs/) both allow approaching substantial changes while minimizing the risk.
+However they serve different purposes:
+
+- An experimental feature enables developers to iterate on and deliver a new idea without committing to it or requiring a costly long-running fork.
+ It is primarily an issue of *implementation*, targeting Nix developers and early testers.
+- The goal of an RFC is to make explicit all the implications of a change:
+ Explain why it is wanted, which new use-cases it enables, which interface changes it requires, etc.
+ It is primarily an issue of *design* and *communication*, targeting the broader community.
+
+This means that experimental features and RFCs are orthogonal mechanisms, and can be used independently or together as needed.
+
+# Currently available experimental features
+
+{{#include ./experimental-feature-descriptions.md}}
diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index b56d857d1..a9782be5c 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -15,7 +15,7 @@
Example: `/nix/store/g946hcz4c8mdvq2g8vxx42z51qb71rvp-git-2.38.1.drv`
- See [`nix show-derivation`](./command-ref/new-cli/nix3-show-derivation.md) (experimental) for displaying the contents of store derivations.
+ See [`nix derivation show`](./command-ref/new-cli/nix3-derivation-show.md) (experimental) for displaying the contents of store derivations.
[store derivation]: #gloss-store-derivation
@@ -54,7 +54,7 @@
invoked, the Nix store can be referred to
as a "_local_" or a "_remote_" one:
- + A *local store* exists on the filesystem of
+ + A [local store]{#gloss-local-store} exists on the filesystem of
the machine where Nix is invoked. You can use other
local stores by passing the `--store` flag to the
`nix` command. Local stores can be used for building derivations.
@@ -65,17 +65,17 @@
served by the `nix-serve` Perl script.
[store]: #gloss-store
+ [local store]: #gloss-local-store
- [chroot store]{#gloss-chroot-store}\
- A local store whose canonical path is anything other than `/nix/store`.
+ A [local store] whose canonical path is anything other than `/nix/store`.
- [binary cache]{#gloss-binary-cache}\
A *binary cache* is a Nix store which uses a different format: its
metadata and signatures are kept in `.narinfo` files rather than in a
- Nix database. This different format simplifies serving store objects
- over the network, but cannot host builds. Examples of binary caches
- include S3 buckets and the [NixOS binary
- cache](https://cache.nixos.org).
+ [Nix database]. This different format simplifies serving store objects
+ over the network, but cannot host builds. Examples of binary caches
+ include S3 buckets and the [NixOS binary cache](https://cache.nixos.org).
- [store path]{#gloss-store-path}\
The location of a [store object] in the file system, i.e., an
@@ -108,7 +108,7 @@
[fixed-output derivations](#gloss-fixed-output-derivation).
- [substitute]{#gloss-substitute}\
- A substitute is a command invocation stored in the Nix database that
+ A substitute is a command invocation stored in the [Nix database] that
describes how to build a store object, bypassing the normal build
mechanism (i.e., derivations). Typically, the substitute builds the
store object by downloading a pre-built version of the store object
@@ -127,6 +127,14 @@
builder can rely on external inputs such as the network or the
system time) but the Nix model assumes it.
+ - Nix database{#gloss-nix-database}\
+ An SQlite database to track [reference]s between [store object]s.
+ This is an implementation detail of the [local store].
+
+ Default location: `/nix/var/nix/db`.
+
+ [Nix database]: #gloss-nix-database
+
- [Nix expression]{#gloss-nix-expression}\
A high-level description of software packages and compositions
thereof. Deploying software using Nix entails writing Nix
@@ -175,9 +183,9 @@
- [validity]{#gloss-validity}\
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:
+ 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.
+ - The store path is listed in the [Nix database] as being valid.
- All paths in the store path's [closure] are valid.
[validity]: #gloss-validity
@@ -217,3 +225,9 @@
[string]: ./language/values.md#type-string
[path]: ./language/values.md#type-path
[attribute name]: ./language/values.md#attribute-set
+
+ - [experimental feature]{#gloss-experimental-feature}\
+ Not yet stabilized functionality guarded by named experimental feature flags.
+ These flags are enabled or disabled with the [`experimental-features`](./command-ref/conf-file.html#conf-experimental-features) setting.
+
+ See the contribution guide on the [purpose and lifecycle of experimental feaures](@docroot@/contributing/experimental-features.md).
diff --git a/doc/manual/src/language/advanced-attributes.md b/doc/manual/src/language/advanced-attributes.md
index 3e8c48890..307971434 100644
--- a/doc/manual/src/language/advanced-attributes.md
+++ b/doc/manual/src/language/advanced-attributes.md
@@ -208,12 +208,26 @@ Derivations can declare some infrequently used optional attributes.
about converting to and from base-32 notation.)
- [`__contentAddressed`]{#adv-attr-__contentAddressed}
- If this **experimental** attribute is set to true, then the derivation
+ > **Warning**
+ > This attribute is part of an [experimental feature](@docroot@/contributing/experimental-features.md).
+ >
+ > To use this attribute, you must enable the
+ > [`ca-derivations`](@docroot@/contributing/experimental-features.md#xp-feature-ca-derivations) experimental feature.
+ > For example, in [nix.conf](../command-ref/conf-file.md) you could add:
+ >
+ > ```
+ > extra-experimental-features = ca-derivations
+ > ```
+
+ If this attribute is set to `true`, then the derivation
outputs will be stored in a content-addressed location rather than the
traditional input-addressed one.
- This only has an effect if the `ca-derivations` experimental feature is enabled.
- Setting this attribute also requires setting `outputHashMode` and `outputHashAlgo` like for *fixed-output derivations* (see above).
+ Setting this attribute also requires setting
+ [`outputHashMode`](#adv-attr-outputHashMode)
+ and
+ [`outputHashAlgo`](#adv-attr-outputHashAlgo)
+ like for *fixed-output derivations* (see above).
- [`passAsFile`]{#adv-attr-passAsFile}\
A list of names of attributes that should be passed via files rather
@@ -307,9 +321,11 @@ Derivations can declare some infrequently used optional attributes.
- [`unsafeDiscardReferences`]{#adv-attr-unsafeDiscardReferences}\
> **Warning**
- > This is an experimental feature.
+ > This attribute is part of an [experimental feature](@docroot@/contributing/experimental-features.md).
>
- > To enable it, add the following to [nix.conf](../command-ref/conf-file.md):
+ > To use this attribute, you must enable the
+ > [`discard-references`](@docroot@/contributing/experimental-features.md#xp-feature-discard-references) experimental feature.
+ > For example, in [nix.conf](../command-ref/conf-file.md) you could add:
>
> ```
> extra-experimental-features = discard-references
diff --git a/doc/manual/src/quick-start.md b/doc/manual/src/quick-start.md
index 651134c25..1d2688ede 100644
--- a/doc/manual/src/quick-start.md
+++ b/doc/manual/src/quick-start.md
@@ -19,7 +19,7 @@ to subsequent chapters.
channel:
```console
- $ nix-env -qaP
+ $ nix-env --query --available --attr-path
nixpkgs.docbook_xml_dtd_43 docbook-xml-4.3
nixpkgs.docbook_xml_dtd_45 docbook-xml-4.5
nixpkgs.firefox firefox-33.0.2
@@ -31,7 +31,7 @@ to subsequent chapters.
1. Install some packages from the channel:
```console
- $ nix-env -iA nixpkgs.hello
+ $ nix-env --install --attr nixpkgs.hello
```
This should download pre-built packages; it should not build them
@@ -49,13 +49,13 @@ to subsequent chapters.
1. Uninstall a package:
```console
- $ nix-env -e hello
+ $ nix-env --uninstall hello
```
1. You can also test a package without installing it:
```console
- $ nix-shell -p hello
+ $ nix-shell --packages hello
```
This builds or downloads GNU Hello and its dependencies, then drops
@@ -76,7 +76,7 @@ to subsequent chapters.
```console
$ nix-channel --update nixpkgs
- $ nix-env -u '*'
+ $ nix-env --upgrade '*'
```
The latter command will upgrade each installed package for which
@@ -95,5 +95,5 @@ to subsequent chapters.
them:
```console
- $ nix-collect-garbage -d
+ $ nix-collect-garbage --delete-old
```
diff --git a/doc/manual/src/release-notes/rl-2.15.md b/doc/manual/src/release-notes/rl-2.15.md
new file mode 100644
index 000000000..133121999
--- /dev/null
+++ b/doc/manual/src/release-notes/rl-2.15.md
@@ -0,0 +1,58 @@
+# Release 2.15 (2023-04-11)
+
+* Commands which take installables on the command line can now read them from the standard input if
+ passed the `--stdin` flag. This is primarily useful when you have a large amount of paths which
+ exceed the OS argument limit.
+
+* The `nix-hash` command now supports Base64 and SRI. Use the flags `--base64`
+ or `--sri` to specify the format of output hash as Base64 or SRI, and `--to-base64`
+ or `--to-sri` to convert a hash to Base64 or SRI format, respectively.
+
+ As the choice of hash formats is no longer binary, the `--base16` flag is also added
+ to explicitly specify the Base16 format, which is still the default.
+
+* The special handling of an [installable](../command-ref/new-cli/nix.md#installables) with `.drv` suffix being interpreted as all of the given [store derivation](../glossary.md#gloss-store-derivation)'s output paths is removed, and instead taken as the literal store path that it represents.
+
+ The new `^` syntax for store paths introduced in Nix 2.13 allows explicitly referencing output paths of a derivation.
+ Using this is better and more clear than relying on the now-removed `.drv` special handling.
+
+ For example,
+ ```shell-session
+ $ nix path-info /nix/store/gzaflydcr6sb3567hap9q6srzx8ggdgg-glibc-2.33-78.drv
+ ```
+
+ now gives info about the derivation itself, while
+
+ ```shell-session
+ $ nix path-info /nix/store/gzaflydcr6sb3567hap9q6srzx8ggdgg-glibc-2.33-78.drv^*
+ ```
+ provides information about each of its outputs.
+
+* The experimental command `nix describe-stores` has been removed.
+
+* Nix stores and their settings are now documented in [`nix help-stores`](@docroot@/command-ref/new-cli/nix3-help-stores.md).
+
+* Documentation for operations of `nix-store` and `nix-env` are now available on separate pages of the manual.
+ They include all common options that can be specified and common environment variables that affect these commands.
+
+ These pages can be viewed offline with `man` using
+
+ * `man nix-store-<operation>` and `man nix-env-<operation>`
+ * `nix-store --help --<operation>` and `nix-env --help --<operation>`.
+
+* Nix when used as a client now checks whether the store (the server) trusts the client.
+ (The store always had to check whether it trusts the client, but now the client is informed of the store's decision.)
+ This is useful for scripting interactions with (non-legacy-ssh) remote Nix stores.
+
+ `nix store ping` and `nix doctor` now display this information.
+
+* The new command `nix derivation add` allows adding derivations to the store without involving the Nix language.
+ It exists to round out our collection of basic utility/plumbing commands, and allow for a low barrier-to-entry way of experimenting with alternative front-ends to the Nix Store.
+ It uses the same JSON layout as `nix derivation show`, and is its inverse.
+
+* `nix show-derivation` has been renamed to `nix derivation show`.
+ This matches `nix derivation add`, and avoids bloating the top-level namespace.
+ The old name is still kept as an alias for compatibility, however.
+
+* The `nix derivation {add,show}` JSON format now includes the derivation name as a top-level field.
+ This is useful in general, but especially necessary for the `add` direction, as otherwise we would need to pass in the name out of band for certain cases.
diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index ae159de8f..78ae99f4b 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -1,41 +1,2 @@
# Release X.Y (202?-??-??)
-* Commands which take installables on the command line can now read them from the standard input if
- passed the `--stdin` flag. This is primarily useful when you have a large amount of paths which
- exceed the OS arg limit.
-
-* The `nix-hash` command now supports Base64 and SRI. Use the flags `--base64`
- or `--sri` to specify the format of output hash as Base64 or SRI, and `--to-base64`
- or `--to-sri` to convert a hash to Base64 or SRI format, respectively.
-
- As the choice of hash formats is no longer binary, the `--base16` flag is also added
- to explicitly specify the Base16 format, which is still the default.
-
-* The special handling of an [installable](../command-ref/new-cli/nix.md#installables) with `.drv` suffix being interpreted as all of the given [store derivation](../glossary.md#gloss-store-derivation)'s output paths is removed, and instead taken as the literal store path that it represents.
-
- The new `^` syntax for store paths introduced in Nix 2.13 allows explicitly referencing output paths of a derivation.
- Using this is better and more clear than relying on the now-removed `.drv` special handling.
-
- For example,
- ```shell-session
- $ nix path-info /nix/store/gzaflydcr6sb3567hap9q6srzx8ggdgg-glibc-2.33-78.drv
- ```
-
- now gives info about the derivation itself, while
-
- ```shell-session
- $ nix path-info /nix/store/gzaflydcr6sb3567hap9q6srzx8ggdgg-glibc-2.33-78.drv^*
- ```
- provides information about each of its outputs.
-
-* The experimental command `nix describe-stores` has been removed.
-
-* Nix stores and their settings are now documented in [`nix help-stores`](@docroot@/command-ref/new-cli/nix3-help-stores.md).
-
-* Documentation for operations of `nix-store` and `nix-env` are now available on separate pages of the manual.
- They include all common options that can be specified and common environment variables that affect these commands.
-
- These pages can be viewed offline with `man` using
-
- * `man nix-store-<operation>` and `man nix-env-<operation>`
- * `nix-store --help --<operation>` and `nix-env --help --<operation>`.
diff --git a/doc/manual/utils.nix b/doc/manual/utils.nix
index 5eacce0dd..9043dd8cd 100644
--- a/doc/manual/utils.nix
+++ b/doc/manual/utils.nix
@@ -5,6 +5,9 @@ rec {
concatStrings = concatStringsSep "";
+ attrsToList = a:
+ map (name: { inherit name; value = a.${name}; }) (builtins.attrNames a);
+
replaceStringsRec = from: to: string:
# recursively replace occurrences of `from` with `to` within `string`
# example:
@@ -39,7 +42,9 @@ rec {
filterAttrs = pred: set:
listToAttrs (concatMap (name: let v = set.${name}; in if pred name v then [(nameValuePair name v)] else []) (attrNames set));
- showSetting = { useAnchors }: name: { description, documentDefault, defaultValue, aliases, value }:
+ optionalString = cond: string: if cond then string else "";
+
+ showSetting = { useAnchors }: name: { description, documentDefault, defaultValue, aliases, value, experimentalFeature }:
let
result = squash ''
- ${if useAnchors
@@ -49,10 +54,28 @@ rec {
${indent " " body}
'';
+ experimentalFeatureNote = optionalString (experimentalFeature != null) ''
+ > **Warning**
+ > This setting is part of an
+ > [experimental feature](@docroot@/contributing/experimental-features.md).
+
+ To change this setting, you need to make sure the corresponding experimental feature,
+ [`${experimentalFeature}`](@docroot@/contributing/experimental-features.md#xp-feature-${experimentalFeature}),
+ is enabled.
+ For example, include the following in [`nix.conf`](#):
+
+ ```
+ extra-experimental-features = ${experimentalFeature}
+ ${name} = ...
+ ```
+ '';
+
# separate body to cleanly handle indentation
body = ''
${description}
+ ${experimentalFeatureNote}
+
**Default:** ${showDefault documentDefault defaultValue}
${showAliases aliases}
@@ -71,13 +94,13 @@ rec {
else "*machine-specific*";
showAliases = aliases:
- if aliases == [] then "" else
+ optionalString (aliases != [])
"**Deprecated alias:** ${(concatStringsSep ", " (map (s: "`${s}`") aliases))}";
- indent = prefix: s:
- concatStringsSep "\n" (map (x: if x == "" then x else "${prefix}${x}") (splitLines s));
-
in result;
+ indent = prefix: s:
+ concatStringsSep "\n" (map (x: if x == "" then x else "${prefix}${x}") (splitLines s));
+
showSettings = args: settingsInfo: concatStrings (attrValues (mapAttrs (showSetting args) settingsInfo));
}
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-22 13:37:07 +0000