add tutorial for nix-shell in shebang

[rapenne-s]

This explains how to use nix-shell in a shebang.

I'm open to changes to better fit nix.dev style 👍

[github-actions]

CLA Assistant Lite bot All contributors have signed the CLA ✍️ ✅

[fricklerhandwerk]

Note that there already is a section on shellbang in the article on ad hoc environments. I would like to move it out into a separate article, because I noticed that people seem not to find it on their own (including you, apparently, but also me when I had needed something like that in the past).

Also the Python example there was very confusing to every beginner I discussed it with.

I would like you to clarify more strongly if you want this to be a Guide (clear-cut recipe for people who know that they want this feature and why/when to use it, but need a summary or reminder) or a Tutorial (motivating introduction to a concept, which teaches a skill).

I think for shellbang we may actually want a tutorial to introduce beginners, as this still appears to be a fairly obscure feature although it is so powerful. It is hard to find the feature if you don't know the right search keywords. Googling "nix shell shebang" produces good results, and some very nice third-party posts the spirit of which we should definitely incorporate at some point. Googling "nix wrap shell script" leads to seemingly random stuff, and only one result is relevant, but will probably look shady to most people. We want people to find the manual or nix.dev (and tell them nix.dev is legit).

Here is a rundown of what is out there after a quick search:

• https://gist.github.com/travisbhartwell/f972aab227306edfcfea
• https://nixos.wiki/wiki/Nix-shell_shebang
• https://notes.yukiisbo.red/posts/2021/07/Spice_up_with_Nix_Scripts.html
• https://t-ravis.com/post/nix/nix-make/

[rapenne-s]

I have read the CLA Document and I hereby sign the CLA

[rapenne-s]

I've not been able to use nix-index without locking up my laptop twice due to a lack of memory, it seems 9 GB wasn't enough. I think finding which package is providing a binary should be another tutorial.

[fricklerhandwerk]

In this review I focused on structure. Please also add a References section that shows the relevant reference documentation in an overview. You started the NixOS Wiki article on searching packages, that may be a good entry point for people to solve that problem on their own.

There should also be a section on next steps - the natural successor would be setting up declarative environments, and depending on who gets merged first, the article on wrapping scripts in Nix derivations.

[rapenne-s]

Ping :)

[fricklerhandwerk]

Almost perfect now, thanks for fixing up and reminding me.

While this is still missing the steps to figure out mappings of binaries and package names, and how to find recent commit hashes, that should be an independent guide we can link to later. Even if the latter will mostly be made obsolete by flakes, until then people will have that issue.

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/nix-shell-shebang-default-nix-no-such-file-or-directory/24246/6

[n8henrie]

Consider adding the --pure flag, which ensures that the packages being used are from the env specified; I happen to have jq, bash, and curl in my PATH, so mine runs without error if I omit several of those, but might fail on another system.

For example, running printf '%b\n' "${PATH//:/\\n}" | wc -l as the script in question, my PATH is about 3 times as long without the --pure.

Further, with --pure, the script fails on my system due to absence of cacert; consider adding pkgs.cacert to the list of dependencies.

[fricklerhandwerk]

@n8henrie Thanks for the review. For the sake of clarity in this tutorial maybe we could add this as an additional step, to make the script "more pure"? Although to relieve @rapenne-s from this long-standing open PR I suggest to merge it after fixing the build error (the new tutorial needs a place in the table of contents). @n8henrie would you be interested in doing the follow-up as you described?

[n8henrie]

Sure! Would love to help. Hope to work on this within the next week 🤞 #todo

[n8henrie]

"Within the next week" was definitely optimistic, but it's on the todo list.

[n8henrie]

It also may be worth mentioning the use of nix-locate as a handy and efficient way to determine which -p packages must be added when converting an existing script to nix-shell --pure.

[fricklerhandwerk]

Please rebase, the broken link was fixed in #438.

[fricklerhandwerk]

Awesome! Thanks a lot for pulling through with this.