From 526bcac44a365648acf5302c147772e40cff6b89 Mon Sep 17 00:00:00 2001 From: blokyk Date: Tue, 14 Apr 2026 10:39:31 +0200 Subject: [PATCH] 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 --- doc/manual/src/language/derivations.md | 6 ++++++ lix/libexpr/builtins/path.md | 3 ++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/doc/manual/src/language/derivations.md b/doc/manual/src/language/derivations.md index 28e686889..4b430c2be 100644 --- a/doc/manual/src/language/derivations.md +++ b/doc/manual/src/language/derivations.md @@ -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., diff --git a/lix/libexpr/builtins/path.md b/lix/libexpr/builtins/path.md index de1f335cc..1cba378b0 100644 --- a/lix/libexpr/builtins/path.md +++ b/lix/libexpr/builtins/path.md @@ -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\