Skip to content

Commit

Permalink
doc: shebang release notes, docs, tests
Browse files Browse the repository at this point in the history
fix: release notes
  • Loading branch information
tomberek committed Nov 7, 2023
1 parent eea5a00 commit bfcbf3b
Show file tree
Hide file tree
Showing 3 changed files with 174 additions and 0 deletions.
44 changes: 44 additions & 0 deletions doc/manual/src/release-notes/rl-next.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,49 @@
# Release X.Y (202?-??-??)

- The experimental nix command is now a `#!-interpreter` by appending the
contents of any `#! nix` lines and the script's location to a single call.
Some examples:
```
#!/usr/bin/env nix
#! nix shell --file "<nixpkgs>" hello --command bash
hello | cowsay
```
or with flakes:
```
#!/usr/bin/env nix
#! nix shell nixpkgs#bash nixpkgs#hello nixpkgs#cowsay --command bash
hello | cowsay
```
or
```bash
#! /usr/bin/env nix
#! nix shell --impure --expr
#! nix "with (import (builtins.getFlake ''nixpkgs'') {}); terraform.withPlugins (plugins: [ plugins.openstack ])"
#! nix --command bash

terraform "$@"
```
or
```
#!/usr/bin/env nix
//! ```cargo
//! [dependencies]
//! time = "0.1.25"
//! ```
/*
#!nix shell nixpkgs#rustc nixpkgs#rust-script nixpkgs#cargo --command rust-script
*/
fn main() {
for argument in std::env::args().skip(1) {
println!("{}", argument);
};
println!("{}", std::env::var("HOME").expect(""));
println!("{}", time::now().rfc822z());
}
// vim: ft=rust
```
- [URL flake references](@docroot@/command-ref/new-cli/nix3-flake.md#flake-references) now support [percent-encoded](https://datatracker.ietf.org/doc/html/rfc3986#section-2.1) characters.
- [Path-like flake references](@docroot@/command-ref/new-cli/nix3-flake.md#path-like-syntax) now accept arbitrary unicode characters (except `#` and `?`).
Expand Down
117 changes: 117 additions & 0 deletions src/nix/shell.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,4 +51,121 @@ R""(
provides the specified [*installables*](./nix.md#installable). If no command is specified, it starts the
default shell of your user account specified by `$SHELL`.

# Use as a `#!`-interpreter

You can use `nix` as a script interpreter to allow scripts written
in arbitrary languages to obtain their own dependencies via Nix. This is
done by starting the script with the following lines:

```bash
#! /usr/bin/env nix
#! nix shell installables --command real-interpreter
```

where *real-interpreter* is the “real” script interpreter that will be
invoked by `nix shell` after it has obtained the dependencies and
initialised the environment, and *installables* are the attribute names of
the dependencies in Nixpkgs.

The lines starting with `#! nix` specify options (see above). Note that you
cannot write `#! /usr/bin/env nix shell -i ...` because many operating systems
only allow one argument in `#!` lines.

For example, here is a Python script that depends on Python and the
`prettytable` package:

```python
#! /usr/bin/env nix
#! nix shell github:tomberek/-#python3With.prettytable --command python

import prettytable

# Print a simple table.
t = prettytable.PrettyTable(["N", "N^2"])
for n in range(1, 10): t.add_row([n, n * n])
print t
```

Similarly, the following is a Perl script that specifies that it
requires Perl and the `HTML::TokeParser::Simple` and `LWP` packages:

```perl
#! /usr/bin/env nix
#! nix shell github:tomberek/-#perlWith.HTMLTokeParserSimple.LWP --command perl -x

use HTML::TokeParser::Simple;

# Fetch nixos.org and print all hrefs.
my $p = HTML::TokeParser::Simple->new(url => 'http:https://nixos.org/');

while (my $token = $p->get_tag("a")) {
my $href = $token->get_attr("href");
print "$href\n" if $href;
}
```

Sometimes you need to pass a simple Nix expression to customize a
package like Terraform:

```bash
#! /usr/bin/env nix
#! nix shell --impure --expr
#! nix "with (import (builtins.getFlake ''nixpkgs'') {}); terraform.withPlugins (plugins: [ plugins.openstack ])"
#! nix --command bash

terraform "$@"
```

> **Note**
>
> You must use double quotes (`"`) when passing a simple Nix expression
> in a nix shell shebang.
Finally, using the merging of multiple nix shell shebangs the following
Haskell script uses a specific branch of Nixpkgs/NixOS (the 21.11 stable
branch):

```haskell
#!/usr/bin/env nix
#!nix shell --override-input nixpkgs github:NixOS/nixpkgs/nixos-21.11
#!nix github:tomberek/-#haskellWith.download-curl.tagsoup --command runghc

import Network.Curl.Download
import Text.HTML.TagSoup
import Data.Either
import Data.ByteString.Char8 (unpack)

-- Fetch nixos.org and print all hrefs.
main = do
resp <- openURI "https://nixos.org/"
let tags = filter (isTagOpenName "a") $ parseTags $ unpack $ fromRight undefined resp
let tags' = map (fromAttrib "href") tags
mapM_ putStrLn $ filter (/= "") tags'
```

If you want to be even more precise, you can specify a specific revision
of Nixpkgs:

#!nix shell --override-input nixpkgs github:NixOS/nixpkgs/eabc38219184cc3e04a974fe31857d8e0eac098d

The examples above all used `-p` to get dependencies from Nixpkgs. You
can also use a Nix expression to build your own dependencies. For
example, the Python example could have been written as:

```python
#! /usr/bin/env nix
#! nix shell --impure --file deps.nix -i python
```

where the file `deps.nix` in the same directory as the `#!`-script
contains:

```nix
with import <nixpkgs> {};
python3.withPackages (ps: with ps; [ prettytable ])
```




)""
13 changes: 13 additions & 0 deletions tests/functional/flakes/flakes.sh
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,18 @@ chmod +x "$nonFlakeDir/shebang.sh"
git -C "$nonFlakeDir" add README.md shebang.sh
git -C "$nonFlakeDir" commit -m 'Initial'

cat > $nonFlakeDir/shebang-perl.sh <<EOF
#! $(type -P env) nix
#! nix run nixpkgs#perl
## Modules used
use strict;
use warnings;
# Print function
print("Hello World\n");
EOF
chmod +x $nonFlakeDir/shebang-perl.sh

# Construct a custom registry, additionally test the --registry flag
nix registry add --registry "$registry" flake1 "git+file:https://$flake1Dir"
nix registry add --registry "$registry" flake2 "git+file:https://$percentEncodedFlake2Dir"
Expand Down Expand Up @@ -526,3 +538,4 @@ expectStderr 1 nix flake metadata "$flake2Dir" --no-allow-dirty --reference-lock
# Test shebang
[[ $($nonFlakeDir/shebang.sh) = "foo" ]]
[[ $($nonFlakeDir/shebang.sh "bar") = "foo"$'\n'"bar" ]]
[[ $($nonFlakeDir/shebang-perl.sh ) = "Hello World!" ]]

0 comments on commit bfcbf3b

Please sign in to comment.