mirror of
https://github.com/NixOS/nix
synced 2024-09-19 23:03:53 -04:00
Merge pull request #10560 from hercules-ci/doc-path-value
Improve path value documentation
This commit is contained in:
commit
cbafa1ba2d
|
@ -92,39 +92,50 @@
|
||||||
|
|
||||||
- <a id="type-path" href="#type-path">Path</a>
|
- <a id="type-path" href="#type-path">Path</a>
|
||||||
|
|
||||||
*Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at
|
*Paths* are distinct from strings and can be expressed by path literals such as `./builder.sh`.
|
||||||
least one slash to be recognised as such. For instance, `builder.sh`
|
|
||||||
is not a path: it's parsed as an expression that selects the
|
|
||||||
attribute `sh` from the variable `builder`. If the file name is
|
|
||||||
relative, i.e., if it does not begin with a slash, it is made
|
|
||||||
absolute at parse time relative to the [base directory](@docroot@/glossary.md#gloss-base-directory).
|
|
||||||
For instance, if a Nix expression in
|
|
||||||
`/foo/bar/bla.nix` refers to `../xyzzy/fnord.nix`, the absolute path
|
|
||||||
is `/foo/xyzzy/fnord.nix`.
|
|
||||||
|
|
||||||
If the first component of a path is a `~`, it is interpreted as if
|
Paths are suitable for referring to local files, and are often preferable over strings.
|
||||||
the rest of the path were relative to the user's home directory.
|
- Path values do not contain trailing slashes, `.` and `..`, as they are resolved when evaluating a path literal.
|
||||||
e.g. `~/foo` would be equivalent to `/home/edolstra/foo` for a user
|
- Path literals are automatically resolved relative to their [base directory](@docroot@/glossary.md#gloss-base-directory).
|
||||||
whose home directory is `/home/edolstra`.
|
- The files referred to by path values are automatically copied into the Nix store when used in a string interpolation or concatenation.
|
||||||
|
- Tooling can recognize path literals and provide additional features, such as autocompletion, refactoring automation and jump-to-file.
|
||||||
|
|
||||||
For instance, evaluating `"${./foo.txt}"` will cause `foo.txt` in the base directory to be copied into the Nix store and result in the string `"/nix/store/<hash>-foo.txt"`.
|
A path literal must contain at least one slash to be recognised as such.
|
||||||
|
For instance, `builder.sh` is not a path:
|
||||||
|
it's parsed as an expression that selects the attribute `sh` from the variable `builder`.
|
||||||
|
|
||||||
Note that the Nix language assumes that all input files will remain _unchanged_ while evaluating a Nix expression.
|
Path literals may also refer to absolute paths by starting with a slash.
|
||||||
|
|
||||||
|
> **Note**
|
||||||
|
>
|
||||||
|
> Absolute paths make expressions less portable.
|
||||||
|
> In the case where a function translates a path literal into an absolute path string for a configuration file, it is recommended to write a string literal instead.
|
||||||
|
> This avoids some confusion about whether files at that location will be used during evaluation.
|
||||||
|
> It also avoids unintentional situations where some function might try to copy everything at the location into the store.
|
||||||
|
|
||||||
|
If the first component of a path is a `~`, it is interpreted such that the rest of the path were relative to the user's home directory.
|
||||||
|
For example, `~/foo` would be equivalent to `/home/edolstra/foo` for a user whose home directory is `/home/edolstra`.
|
||||||
|
Path literals that start with `~` are not allowed in [pure](@docroot@/command-ref/conf-file.md#conf-pure-eval) evaluation.
|
||||||
|
|
||||||
|
Paths can be used in [string interpolation] and string concatenation.
|
||||||
|
For instance, evaluating `"${./foo.txt}"` will cause `foo.txt` from the same 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.
|
||||||
For example, assume you used a file path in an interpolated string during a `nix repl` session.
|
For example, assume you used a file path in an interpolated string during a `nix repl` session.
|
||||||
Later in the same session, after having changed the file contents, evaluating the interpolated string with the file path again might not return a new [store path], since Nix might not re-read the file contents.
|
Later in the same session, after having changed the file contents, evaluating the interpolated string with the file path again might not return a new [store path], since Nix might not re-read the file contents. Use `:r` to reset the repl as needed.
|
||||||
|
|
||||||
[store path]: @docroot@/glossary.md#gloss-store-path
|
[store path]: @docroot@/glossary.md#gloss-store-path
|
||||||
|
|
||||||
Paths can include [string interpolation] and can themselves be [interpolated in other expressions].
|
Path literals can also include [string interpolation], besides being [interpolated into other expressions].
|
||||||
|
|
||||||
[interpolated in other expressions]: ./string-interpolation.md#interpolated-expressions
|
[interpolated into 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.
|
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 syntactically valid number division operation.
|
||||||
`./a.${foo}/b.${bar}` is a path.
|
`./a.${foo}/b.${bar}` is a path.
|
||||||
|
|
||||||
[Lookup paths](./constructs/lookup-path.md) such as `<nixpkgs>` resolve to path values.
|
[Lookup path](./constructs/lookup-path.md) literals such as `<nixpkgs>` also resolve to path values.
|
||||||
|
|
||||||
- <a id="type-boolean" href="#type-boolean">Boolean</a>
|
- <a id="type-boolean" href="#type-boolean">Boolean</a>
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue