Shell Scripts with Nix

We’ll go over this example in a moment, but before that, you’ll probably want to test out your script, to make sure it works before you build it into your system. There are various ways to do this:

# Let's get our bearings first:
$ pwd
~/code
$ ls ./simple-script/
flake.nix

# Execute the "default package" of ./simple-script/flake.nix
$ nix run ./simple-script#
# or...
$ cd ./simple-script && nix run .#

# Execute a named package of ./simple-script/flake.nix
$ nix run ./simple-script#my-script
# or...
$ cd ./simple-script && nix run .#my-script

Regardless of how you ran the script, you should eventually see output like:

 ____________________________________ 
/ Hello, world! Today is the 25th of \
\ Chaos 3190.                        /
 ------------------------------------ 
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

5: defaultPackage.x86_64-linux = self.packages.x86_64-linux.my-script;

On line 5, we specify that this derivation has a default app, named my-script. We haven’t yet said what my-script is, but when we do, you better believe that it’ll be the default!

The default package is optional, but when present it identifies the derivation’s “main app.” Packages can come with only a single executable or a suite of them, but even with many, typically there is a single flagship app that defines the package. Consider ffmpeg. The titular ffmpeg is clearly the primary executable, but most package managers also include the utility apps, ffplay and ffprobe.

Not every derivation will have a default package, but it’s more convenient to use when available.

7: packages.x86_64-linux.my-script = { ... };

At line 7, we begin to define the my-script derivation. This was previous referenced on line 5, where we declared that it’ll be our default package. Our package will only include 1 script, but you can define a bunch here.

The name used here, my-script is arbitrary; it won’t be used as the name of the executable script that will eventually be installed on our system. It’s more of a variable name, or the key in a dictionary⁵. We only use it to refer to this derivation within our Nix code.

9: pkgs = import nixpkgs { system = "x86_64-linux"; };

Here we’re importing the entire upstream “nixpkgs” repository and storing the entire set in the pkgs variable. We can later reference upstream derivations with pkgs.foo-bar. There are all the derivations managed by the NixOS maintainers and community⁶.

11: pkgs.writeShellScriptBin "my-script" ''
12:   DATE="$(${pkgs.ddate}/bin/ddate +'the %e of %B%, %Y')"
13:   ${pkgs.cowsay}/bin/cowsay Hello, world! Today is $DATE.
14: '';

On line 11, we actually define packages.x86_64-linux.my-script. ie: what actually gets installed on the system. This is easy for us, as we farm out this work to writeShellScriptBin⁴, provided by nixpkgs. This function takes two arguments: the filename for your script and its contents. It then takes care of the packaging for us! It will also run a linter across our script, to help us avoid installing busted trash on our system.

You’ll have noticed that our two-line script has changed slightly. For instance, the reference to cowsay, on line 13, now looks like "${pkgs.cowsay}/bin/cowsay". When Nix builds our script, ${pkgs.cowsay} will be replaced with the absolute path of the cowsay package’s root directory, so we’re referencing the cowsay executable by it’s absolute path: no need to worry about PATH at all here!

11: my-name = "my-script";
12: my-script = pkgs.writeShellScriptBin my-name ''
13:   DATE=$(ddate +'the %e of %B%, %Y')
14:   cowsay Hello, world! Today is $DATE.
15: '';

On lines 11-15, we create a derivation for our script⁷. This version is exactly the same as the very first one we created back in 3.1. This isn’t the end of the story though, as we once again have lost track of what our dependencies (cowsay and ddate) are! This version of the script assumes these apps will be available on the PATH.

16: my-buildInputs = with pkgs; [ cowsay ddate ];

On line 16, we create a variable to store the list of dependencies our script has. Now we just need to deploy our script in such a way that these are available in its PATH at runtime.

17: pkgs.symlinkJoin {
18:   name = my-name;
19:   paths = [ my-script ] ++ my-buildInputs;
20:   buildInputs = [ pkgs.makeWrapper ];
21:   postBuild = "wrapProgram $out/bin/${my-name} --prefix PATH : $out/bin";
22: };

symlinkJoin is where the magic happens. This Nix function creates a derivation that combines the files of several different packages into a single package. You can see on line 19, we provide a list of all the packages to join together (our script, plus our two dependencies). This will ensure that all of our dependencies are installed when our script is installed, but we still need to arrange things so these apps are on the PATH at runtime.

The NixOS package makeWrapper provides a very handy shell script, wrapProgram, that will let us specify our script’s PATH. On line 20 we let Nix know that makeWrapper is needed to build this package, and line 21 instructs wrapProgram to append $out/bin to our script’s PATH. $out/bin is the directory where our shell script is installed to and, thanks to symlinkJoin, also where cowsay and ddate live!

Build this puppy and let’s have a look at what we’ve actually built here.

$ nix build
$ ls -ogA result/bin

total 16
lrwxrwxrwx 1  66 Dec 31  1969 cowsay -> /nix/store/qznd0pqdw925g7vz0iaynbszlvypdcvq-cowsay-3.04/bin/cowsay
lrwxrwxrwx 1  65 Dec 31  1969 ddate -> /nix/store/g9prmy4a60khk5021w2awrzzfr1fkpgq-ddate-0.2.2/bin/ddate
-r-xr-xr-x 1 259 Dec 31  1969 my-script
lrwxrwxrwx 1  67 Dec 31  1969 .my-script-wrapped -> /nix/store/x6j48dklxm9d7cjwga5arzpcq6n2w461-my-script/bin/my-script

cowsay and ddate are here as promised, but note that we also have two versions of my-script. These two files are the result of wrapProgram:

.my-script-wrapped

This hidden file is a symlink to the script we created on lines 12-15 above (using writeShellScriptBin). If you cat it, you’ll see it’s our shell script, verbatim.

my-script

This is the script users will actually call. If you cat this file, you’ll see a very small shell script that updates the PATH, as we’ve instructed, then replaces itself (exec) with .my-script-wrapped. Magic!

First thing’s first: Let’s extract our script to its own file:

#!/usr/bin/env bash
DATE=$(ddate +'the %e of %B%, %Y')
cowsay Hello, world! Today is $DATE.

This is the same script from the beginning of this article… except we’ve added in a shebang on the first line. Now that we’ve specified the script’s interpreter, it’s a proper shell script in its own right!

The reason why we’re adding the shebang at this point is to fully decouple the script from our Nix package. You can run it directly (assuming cowsay and ddate are available on your system) or package it for another OS.

The only part of our package we need to change is our my-script variable. The original (inline) definition of this variable is:

12: my-script = pkgs.writeShellScriptBin my-name ''
13:   DATE=$(ddate +'the %e of %B%, %Y')
14:   cowsay Hello, world! Today is $DATE.
15: '';

Our new definition of this variable is:

12: my-src = builtins.readFile ./simple-script.sh;
13: my-script = (pkgs.writeScriptBin my-name my-src).overrideAttrs(old: {
14:   buildCommand = "${old.buildCommand}\n patchShebangs $out";
15: });

We’ve got three changes here:

1. Instead of our script being inline, we read it from ./simple-script.sh.
2. We use writeScriptBin instead of writeShellScriptBin. writeShellScriptBin prepends a shebang line, but our script already has one.
3. We update our package’s buildCommand by appending patchShebangs .. This command will update our script’s interpreter to point to the correct binary on the system. ie: #!/usr/bin/env bash will be replaced with something like #!/nix/store/1flh34xxg9q3fpc88xyp2qynxpkfg8py-bash-4.4-p23/bin/bash.