Reproducible interpreted scripts#
In this tutorial, you will learn how to use Nix to create and run reproducible interpreted scripts, also known as shebang scripts.
Requirements#
A working Nix installation
Familiarity with Bash
A trivial script with non-trivial dependencies#
Take the following script, which fetches the content XML of a URL, converts it to JSON, and formats it for better readability:
#! /bin/bash
curl https://github.com/NixOS/nixpkgs/releases.atom | xml2json | jq .
It requires the programs curl, xml2json, and jq.
It also requires the bash interpreter.
If any of these dependencies are not present on the system running the script, it will fail partially or altogether.
With Nix, we can declare all dependencies explicitly, and produce a script that will always run on any machine that supports Nix and the required packages taken from Nixpkgs.
The script#
A shebang determines which program to use for running an interpreted script.
We will use the shebang line #!/usr/bin/env nix-shell.
env is a program available on most modern Unix-like operating systems at the file system path /usr/bin/env.
It takes a command name as argument and will run the first executable by that name it finds in the directories listed in the environment variable $PATH.
We use nix-shell as a shebang interpreter.
It takes the following parameters relevant for our use case:
-itells which program to use for interpreting the rest of the file--pureexcludes most environment variables when the script is run-plists packages that should be present in the interpreter’s environment-Iexplicitly sets the search path for packages
More details on the options can be found in the nix-shell reference documentation.
Create a file named nixpkgs-releases.sh with the following content:
#!/usr/bin/env nix-shell
#! nix-shell -i bash --pure
#! nix-shell -p bash cacert curl jq python3Packages.xmljson
#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/2a601aafdc5605a5133a2ca506a34a3a73377247.tar.gz
curl https://github.com/NixOS/nixpkgs/releases.atom | xml2json | jq .
The first line is a standard shebang. The additional shebang lines are a Nix-specific construct:
With the
-ioption,bashis specified as the interpreter for the rest of the file.In this case, the
--pureoption is enabled to prevent the script from implicitly using programs that may already exist on the system on which the script is run.The
-poption lists the packages required for the script to run.The command
xml2jsonis provided by the packagepython3Packages.xmljson, whilebash,jq, andcurlare provided by packages of the same name.cacertmust be present for SSL authentication to work.Tip
Use search.nixos.org to find packages providing the program you need.
The parameter of
-Irefers to a specific Git commit of the Nixpkgs repository.This ensures that the script will always run with the exact same package versions, everywhere.
Make the script executable:
chmod +x nixpkgs-releases.sh
Run the script:
./nixpkgs-releases.sh
Next steps#
Nix language basics to learn about the Nix language, which is used to declare packages and configurations.
Declarative shell environments with shell.nix to create reproducible shell environments with a declarative configuration file.
Garbage Collection – free up storage used by the programs made available through Nix