There are patterns throughout the shell scripts in Nixpkgs (particularly those involving ELF files and CUDA) which can/should be componentized and made into a rigorous, tested library of functions. Given the push for __structuredAttrs, it makes sense to offer high(er)-level array utilities rather than rely on each individual's knowledge of Bash. Promoting code-reuse in this way avoids disparate re-implementations of common patterns which introducing bugs, reduces line count, and makes intent unambiguous.

This PR is the beginning of such re-usable library of Bash functions. Currently, it includes:

• isDeclaredArray: a function which tests whether a nameref refers to a declared, indexed array
• isDeclaredMap: a function which tests whether a nameref refers to a declared, associative array
• sortArray: a function which lexicographically sorts the contents of an indexed array
• getSortedMapKeys: a function which populates an indexed array with the keys of an associative array, sorted in lexicographic order

Functions in (and to be added to) this library are largely written in destination-passing style, where the final arguments are the outputs in which the result of calling the function will be stored. (This is enabled by heavy use of namerefs.) Constraints on whether arguments may alias each other are documented for each relevant function.

The bulk of this PR is dedicated to testing these bash functions (generated with cloc pkgs/build-support/setup-hooks/arrayUtilities --md):

The second commit of this PR shows where such functionality would have been useful in implementing testers.testEqualArrayOrMap.

isDeclaredArray and isDeclaredMap

These two functions underpin the library and allow testing the type of variable to which a nameref refers.

sortArray

This function performs a stable-sort of an indexed array passed by reference, storing the results to the second argument, which is also an indexed array passed by reference.

Two points of note in the implementation:

1. When the number of directives in the format string does not match the number of arguments provided to printf, the format string is applied to each argument. In this way, we produce a NULL-delimited list of values for consumption by sort.
2. Since the locale changes the behavior of sort, we specify it in a sub-shell to avoid polluting the enclosing environment.

getSortedMapKeys

This function accepts an associative array by reference and stores the lexicographically sorted keys in the second argument, an indexed array passed by reference. Since order of traversal of associative arrays in Bash is not guaranteed to be consistent and Nix pursues reproducibility, being able to iterate over the values of a map in a deterministic fashion is a boon -- especially for test scripts.

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandboxing enabled in nix.conf? (See Nix manual)
  • sandbox = relaxed
  • sandbox = true
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 25.05 Release Notes (or backporting 24.11 and 25.05 Release notes)
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
• Fits CONTRIBUTING.md.

Add a 👍 reaction to pull requests you find important.