docs: clarify which characters are allowed in a derivation name

Although the fact that some characters are illegal in derivation names
was referenced in some parts of the docs, the actual list was not
documented anywhere, and the only source of truth seems to be the
[store source code](lix/libstore/path.cc).

This adds an admonition in the `derivation` docs that specifies which
characters and strings are actually allowed (especially since some
of them can be somewhat surprising, like the string "..-foo" not
being a valid name because of `..`).

Change-Id: Ibc4b4a141e262c21306ce9c0392f92cf0abe610a
This commit is contained in:
blokyk
2026-04-14 14:52:08 +00:00
parent 08d1e0c140
commit 526bcac44a
2 changed files with 8 additions and 1 deletions
+6
View File
@@ -17,6 +17,12 @@ the attributes of which specify the inputs of the build.
string. This is used as a symbolic name for the package by
`nix-env`, and it is appended to the output paths of the derivation.
> **Note**
>
> Names can only contain alphanumerical characters (0-9, a-z, A-Z)
> as well as `+`, `-`, `.`, `_`, `?` and `=`. Names must be neither
> `.` nor `..`, and must not start with `.-` or `..-`.
- There must be an attribute named [`builder`]{#attr-builder} that identifies the
program that is executed to perform the build. It can be either a
derivation or a source (a local file reference, e.g.,
+2 -1
View File
@@ -10,7 +10,8 @@ present in *args*. All are optional except `path`:
- name\
The name of the path when added to the store. This can used to
reference paths that have nix-illegal characters in their names,
reference paths that have
[nix-illegal characters in their names](./derivations.md),
like `@`.
- filter\