Documentation: add guide for packaging shell scripts with dependencies

[lolbinarycat]

Problem

sometimes, a shell script (or rarely, another program that calls system()) depends on other executibles being in $PATH at runtime

nixpkgs should describe a standard way of patching these scripts

Proposal

there are several possible ways of solving this:

1. use nix-shell -i. (this is slow, although it doesn't have to be this slow if it's given a static path, but who knows if nix will optimize that usecase)
2. add an export "PATH=$PATH:/nix/store/.../bin" line at the start of the script
3. replace every occurence of the executable's name with an absolute path into the store

Checklist

• [x] checked latest Nixpkgs manual (source) and latest NixOS manual (source)
• [x] checked open documentation issues for possible duplicates
• [x] checked open documentation pull requests for possible solutions

---

Add a :+1: reaction to issues you find important.

[jpds]

A good example of this already exists at https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/interpreters/bats/default.nix

Through that, I found: https://github.com/nixos/nixpkgs/blob/master/pkgs/development/misc/resholve/README.md

[lolbinarycat]

hmm, that's nice, but it isn't really accessible to anyone who doesn't check that specific package, i checked a few other single file bash programs and none of them used them.

this should be documented in the Build Helpers section of the nixpkgs manual

[teto]

it is kinda documented with writeShellApplication. resholve is not documented though and it would be nice to know when to use it. Also it's best to refer to the unstable doc, since it could have been added since last release.

[lolbinarycat]

it is kinda documented with writeShellApplication. resholve is not documented though and it would be nice to know when to use it. Also it's best to refer to the unstable doc, since it could have been added since last release.

i'm not entirly sure where you think this is documented, since a search for nix "writeShellApplication" site:nixos.org/manual returns zero results.

[teto]

sry I should have linked it https://nixos.org/manual/nixpkgs/stable/#trivial-builder-writeShellApplication

[eclairevoyant]

Or alternatively, within this very repo:

Search link: https://github.com/search?q=repo%3ANixOS%2Fnixpkgs+writeshellapplication+path%3Adoc&type=code

MD link: https://github.com/NixOS/nixpkgs/blob/master/doc/build-helpers/trivial-build-helpers.chapter.md#writeshellapplication-trivial-builder-writeshellapplication

[lolbinarycat]

this raises a new question: why do we have two different ways of doing this one thing, with neither method mentioning the other?

[eclairevoyant]

Using something like patching or wrapProgram or writeShellApplication (as applicable) is more well-defined, easier to understand, and is better documented. Even after asking around, I've not found a good use case for resholve yet.

[avnik]

Resholve looks like funny solution, but too hacky implementation. I'd like to use something likewise, but written on top of shellcheck or gosh.

[abathur]

Problem

sometimes, a shell script (or rarely, another program that calls system()) depends on other executibles being in $PATH at runtime

nixpkgs should describe a standard way of patching these scripts

I agree this deserves a guide, but part of the problem with writing one is that there isn't "a" standard way to deal with this category of problem. Shell, in particular, is too messy for any existing approach to work if applied universally. An honest guide will have to give context on multiple approaches.

I may eventually write something here myself, but I also don't quite see it as my ~place since I develop one of the approaches here and can't be completely impartial. (That said, I have previously outlined the main approaches in a blog post: https://www.t-ravis.com/post/shell/no_look_no_leap_shell_with_nix/)

hmm, that's nice, but it isn't really accessible to anyone who doesn't check that specific package, i checked a few other single file bash programs and none of them used them.

this should be documented in the Build Helpers section of the nixpkgs manual

I think it's used in at least 20 packages at this point, but that doesn't invalidate your point. There are several reasons I haven't added it yet, but the most-direct is that I've been intentionally dodging some of the additional ~users that inevitably come with documenting resholve in the manual.

Some of the patterns resholve uses are still pretty provisional as we see how they work at scale and learn where the friction is. When most resholve usage is in Nixpkgs and repos run by myself or frequent nix/nixpkgs contributors, we can tack a new course with less pain and friction than we could if it were the default solution used in thousands of dotfile repos.

Some of these patterns (mainly relating to "lore" and not strictly within resholve itself) are not scaling well at the moment, so I'm not eager to pour gas on the fire until I can find the right amount of time/inspiration to find manageable approaches. Without many extra hands it's also helpful (for me, as a finite being) if resholve's usage doesn't grow faster than I can recover from some work-related burnout accrued during 2022-2023. It's also helpful if more of the pain-points get surfaced by community regulars who know where to find me and are more apt to research them and perhaps help fix them instead of just throwing work on my plate.

Resholve looks like funny solution, but too hacky implementation.

@avnik Any specific complaint I can address?