dartHooks.dartConfigHook: Add packageRun utility

doc/languages-frameworks/dart.section.md

@@ -45,17 +45,18 @@ Many Dart applications require executables from the `dev_dependencies` section i
 This can be done in `preBuild`, in one of two ways:
 
 1. Packaging the tool with `buildDartApplication`, adding it to Nixpkgs, and running it like any other application
-2. Running the tool from the Pub cache
+2. Running the tool from the package cache
 
 Of these methods, the first is recommended when using a tool that does not need
 to be of a specific version.
 
-To use the second method, first make the derivation accessible within itself (e.g. `let self = ...; in self`), and then run it from the Pub cache in `preBuild`.
+For the second method, the `packageRun` function from the `dartConfigHook` can be used.
+This is an alternative to `dart run` that does not rely on Pub.
 
 e.g., for `build_runner`:
 
 ```bash
-dart --packages=.dart_tool/package_config.json ${self.pubspecLock.dependencySources.build_runner.packagePath}/bin/build_runner.dart build
+packageRun build_runner -- build
 ```
 
 Do _not_ use `dart run <package_name>`, as this will attempt to download dependencies with Pub.

pkgs/build-support/dart/build-dart-application/hooks/dart-config-hook.sh

@@ -10,6 +10,36 @@ dartConfigHook() {
     mkdir -p .dart_tool
     cp "$packageConfig" .dart_tool/package_config.json
 
+    # Runs a Dart executable from a package.
+    #
+    # Usage:
+    # packageRun <package> [executable] [bin_dir]
+    #
+    # By default, [bin_dir] is "bin", and [executable] is <package>.
+    # i.e. `packageRun build_runner` is equivalent to `packageRun build_runner build_runner bin`, which runs `bin/build_runner.dart` from the build_runner package.
+    packageRun() {
+        local args=()
+        local passthrough=()
+
+        while [ $# -gt 0 ]; do
+            if [ "$1" != "--" ]; then
+                args+=("$1")
+                shift
+            else
+                shift
+                passthrough=("$@")
+                break
+            fi
+        done
+
+        local name="${args[0]}"
+        local path="${args[1]:-$name}"
+        local prefix="${args[2]:-bin}"
+
+        local packagePath="$(jq --raw-output --arg name "$name" '.packages.[] | select(.name == $name) .rootUri | sub("file://"; "")' .dart_tool/package_config.json)"
+        dart --packages=.dart_tool/package_config.json "$packagePath/$prefix/$path.dart" "${passthrough[@]}"
+    }
+
     echo "Generating the dependency list"
     dart pub deps --json | @jq@ .packages > deps.json