doc/rl-next/shebang-relative: Update with example

This commit is contained in:
Robert Hensing 2024-07-11 13:51:03 +02:00
parent c4e3e2dc27
commit 6f5f741157

View file

@ -1,10 +1,62 @@
synopsis: ensure nix-shell shebang uses relative path ---
prs: #5088 synopsis: "`nix-shell` shebang uses relative path"
description: { prs:
- 5088
- 11058
issues:
- 4232
---
`nix-shell` shebangs use the script file's relative location to resolve relative paths to files passed as command line arguments, but expression arguments were still evaluated using the current working directory as a base path. <!-- unfortunately no link target for the specific syntax -->
The new behavior is that evaluations are performed relative to the script. Relative [path](@docroot@/language/values.md#type-path) literals in `nix-shell` shebang scripts' options are now resolved relative to the [script's location](@docroot@/glossary?highlight=base%20directory#gloss-base-directory).
Previously they were resolved relative to the current working directory.
For example, consider the following script in `~/myproject/say-hi`:
```shell
#!/usr/bin/env nix-shell
#!nix-shell --expr 'import ./shell.nix'
#!nix-shell --arg toolset './greeting-tools.nix'
#!nix-shell -i bash
hello
```
Older versions of `nix-shell` would resolve `shell.nix` relative to the current working directory; home in this example:
```console
[hostname:~]$ ./myproject/say-hi
error:
… while calling the 'import' builtin
at «string»:1:2:
1| (import ./shell.nix)
| ^
error: path '/home/user/shell.nix' does not exist
```
Since this release, `nix-shell` resolves `shell.nix` relative to the script's location, and `~/myproject/shell.nix` is used.
```console
$ ./myproject/say-hi
Hello, world!
```
**Opt-out**
This is technically a breaking change, so we have added an option so you can adapt independently of your Nix update.
The old behavior can be opted into by setting the option [`nix-shell-shebang-arguments-relative-to-script`](@docroot@/command-ref/conf-file.md#conf-nix-shell-shebang-arguments-relative-to-script) to `false`. The old behavior can be opted into by setting the option [`nix-shell-shebang-arguments-relative-to-script`](@docroot@/command-ref/conf-file.md#conf-nix-shell-shebang-arguments-relative-to-script) to `false`.
This option will be removed in a future release.
} **`nix` command shebang**
The experimental [`nix` command shebang](@docroot@/command-ref/new-cli/nix.md?highlight=shebang#shebang-interpreter) already behaves in this script-relative manner.
Example:
```shell
#!/usr/bin/env nix
#!nix develop
#!nix --expr ``import ./shell.nix``
#!nix -c bash
hello
```