Merge pull request #9114 from fricklerhandwerk/lookup-path

introduce lookup paths as a distinct language construct

doc/manual/src/SUMMARY.md.in

@@ -30,6 +30,7 @@
   - [Data Types](language/values.md)
   - [Language Constructs](language/constructs.md)
     - [String interpolation](language/string-interpolation.md)
+    - [Lookup path](language/constructs/lookup-path.md)
   - [Operators](language/operators.md)
   - [Derivations](language/derivations.md)
     - [Advanced Attributes](language/advanced-attributes.md)

doc/manual/src/language/constructs/lookup-path.md

@@ -0,0 +1,27 @@
+# Lookup path
+
+> **Syntax**
+>
+> *lookup-path* = `<` *identifier* [ `/` *identifier* `]`... `>`
+
+A lookup path is an identifier with an optional path suffix that resolves to a [path value](@docroot@/language/values.md#type-path) if the identifier matches a search path entry.
+
+The value of a lookup path is determined by [`builtins.nixPath`](@docroot@/language/builtin-constants.md#builtins-nixPath).
+
+See [`builtins.findFile`](@docroot@/language/builtins.md#builtins-findFile) for details on lookup path resolution.
+
+> **Example**
+>
+> ```nix
+> <nixpkgs>
+>```
+>
+>     /nix/var/nix/profiles/per-user/root/channels/nixpkgs
+
+> **Example**
+>
+> ```nix
+> <nixpkgs/nixos>
+>```
+>
+>     /nix/var/nix/profiles/per-user/root/channels/nixpkgs/nixos

doc/manual/src/language/values.md

@@ -107,11 +107,6 @@
   e.g. `~/foo` would be equivalent to `/home/edolstra/foo` for a user
   whose home directory is `/home/edolstra`.
 
-  Paths can also be specified between angle brackets, e.g.
-  `<nixpkgs>`. This means that the directories listed in the
-  environment variable `NIX_PATH` will be searched for the given file
-  or directory name.
-
   For instance, evaluating `"${./foo.txt}"` will cause `foo.txt` in the current directory to be copied into the Nix store and result in the string `"/nix/store/<hash>-foo.txt"`.
 
   Note that the Nix language assumes that all input files will remain _unchanged_ while  evaluating a Nix expression.
@@ -120,14 +115,16 @@
 
   [store path]: ../glossary.md#gloss-store-path
 
-  Paths, except those in angle brackets (`< >`), support [string interpolation] and can be used in [interpolated expressions].
-  [interpolated expressions]: ./string-interpolation.md#interpolated-expressions
+  Paths can include [string interpolation] and can themselves be [interpolated in other expressions].
+  [interpolated in other expressions]: ./string-interpolation.md#interpolated-expressions
 
   At least one slash (`/`) must appear *before* any interpolated expression for the result to be recognized as a path.
 
   `a.${foo}/b.${bar}` is a syntactically valid division operation.
   `./a.${foo}/b.${bar}` is a path.
 
+  [Lookup paths](./constructs/lookup-path.md) such as `<nixpkgs>` resolve to path values.
+
 - <a id="type-boolean" href="#type-boolean">Boolean</a>
 
   *Booleans* with values `true` and `false`.

src/libexpr/primops.cc

@@ -1730,7 +1730,7 @@ static RegisterPrimOp primop_findFile(PrimOp {
       If the suffix is found inside that directory, then the entry is a match;
       the combined absolute path of the directory (now downloaded if need be) and the suffix is returned.
 
-      The syntax
+      [Lookup path](@docroot@/language/constructs/lookup-path.md) expressions can be [desugared](https://en.wikipedia.org/wiki/Syntactic_sugar) using this and [`builtins.nixPath`](@docroot@/language/builtin-constants.md#builtins-nixPath):
 
       ```nix
       <nixpkgs>
@@ -4396,9 +4396,9 @@ void EvalState::createBaseEnv()
     addConstant("__nixPath", v, {
         .type = nList,
         .doc = R"(
-          The search path used to resolve angle bracket path lookups.
+          List of search path entries used to resolve [lookup paths](@docroot@/language/constructs/lookup-path.md).
 
-          Angle bracket expressions can be
+          Lookup path expressions can be
           [desugared](https://en.wikipedia.org/wiki/Syntactic_sugar)
           using this and
           [`builtins.findFile`](./builtins.html#builtins-findFile):