[hooks] Document caching (#3404)

Author: dcharkes

pkgs/hooks/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2.0.1
+
+- Updated documentation for hook caching behavior and semi-hermetic environment variables.
+
 ## 2.0.0
 
 - **Breaking change**: Turned `ProtocolExtension` into a base class instead of an interface, with default implementations for all methods including the newly added `outputFiles`.

pkgs/hooks/lib/src/api/build_and_link.dart

@@ -92,9 +92,12 @@ import '../validation.dart';
 /// *   **Path and system roots:**
 ///     *   `PATH`: Invoke native tools.
 ///     *   `HOME`, `USERPROFILE`: Find tools in default install locations.
+///     *   `APPDATA`, `LOCALAPPDATA`: NuGet, dart_data_home, and pub on
+///         Windows.
 ///     *   `SYSTEMDRIVE`, `SYSTEMROOT`, `WINDIR`: Process invocations and CMake
 ///         on Windows.
 ///     *   `PROGRAMDATA`: For `vswhere.exe` on Windows.
+///     *   `PROCESSOR_ARCHITECTURE`: CMake Android on Windows.
 /// *   **Temporary directories:**
 ///     *   `TEMP`, `TMP`, `TMPDIR`: Temporary directories.
 /// *   **HTTP proxies:**
@@ -110,12 +113,52 @@ import '../validation.dart';
 ///     *   Any variable starting with `CCACHE_`.
 /// *   **Nix:**
 ///     *   Any variable starting with `NIX_`.
+/// *   **.NET and NuGet:**
+///     *   Any variable starting with `DOTNET_`.
+///     *   Any variable starting with `NUGET_`.
 ///
 /// Any changes to these environment variables will cause cache invalidation for
 /// hooks.
 ///
 /// All other environment variables are stripped.
 ///
+/// ## Caching
+///
+/// Hook execution is automatically cached by the hooks runner to avoid
+/// unnecessary runs.
+///
+/// An execution of this hook is skipped, and the cached output is reused, if
+/// and only if:
+///
+/// * The input to the hook didn't change (including the configuration fields
+///   in [BuildConfig] and the `user-defines` in the workspace `pubspec.yaml`).
+/// * No environment variables (that are not filtered out) changed.
+/// * None of the files or directories declared in
+///   [HookOutputBuilder.dependencies] changed.
+/// * None of the transitive Dart sources of the hook script itself changed.
+/// * The workspace `package_config.json` didn't change.
+/// * The Dart SDK version didn't change.
+///
+/// If any of these conditions are not met, the hook is re-run.
+///
+/// ### Hook Output Dependencies
+///
+/// To ensure cache correctness when external files or assets are modified,
+/// hooks must explicitly declare their file and directory dependencies using
+/// [HookOutputBuilder.dependencies] (e.g., via
+/// `output.dependencies.add(uri)`).
+///
+/// ### Cache Isolation
+///
+/// Outputs are cached in a configuration-specific subdirectory inside
+/// `.dart_tool/hooks_runner/`. This directory is unique per hook and is derived
+/// from the [HookConfig]/[BuildConfig] structure. Therefore, different
+/// configurations (e.g., building for a different target OS or architecture)
+/// do not collide.
+///
+/// The cache is reused for identical configurations across different builds,
+/// even when inputs outside the configuration or environment variables change.
+///
 /// ## Debugging
 ///
 /// When a build hook doesn't work as expected, you can investigate the
@@ -260,9 +303,12 @@ Future<void> build(
 /// *   **Path and system roots:**
 ///     *   `PATH`: Invoke native tools.
 ///     *   `HOME`, `USERPROFILE`: Find tools in default install locations.
+///     *   `APPDATA`, `LOCALAPPDATA`: NuGet, dart_data_home, and pub on
+///         Windows.
 ///     *   `SYSTEMDRIVE`, `SYSTEMROOT`, `WINDIR`: Process invocations and CMake
 ///         on Windows.
 ///     *   `PROGRAMDATA`: For `vswhere.exe` on Windows.
+///     *   `PROCESSOR_ARCHITECTURE`: CMake Android on Windows.
 /// *   **Temporary directories:**
 ///     *   `TEMP`, `TMP`, `TMPDIR`: Temporary directories.
 /// *   **HTTP proxies:**
@@ -278,12 +324,52 @@ Future<void> build(
 ///     *   Any variable starting with `CCACHE_`.
 /// *   **Nix:**
 ///     *   Any variable starting with `NIX_`.
+/// *   **.NET and NuGet:**
+///     *   Any variable starting with `DOTNET_`.
+///     *   Any variable starting with `NUGET_`.
 ///
 /// Any changes to these environment variables will cause cache invalidation for
 /// hooks.
 ///
 /// All other environment variables are stripped.
 ///
+/// ## Caching
+///
+/// Hook execution is automatically cached by the hooks runner to avoid
+/// unnecessary runs.
+///
+/// An execution of this hook is skipped, and the cached output is reused, if
+/// and only if:
+///
+/// * The input to the hook didn't change (including the configuration fields
+///   in [LinkConfig] and the `user-defines` in the workspace `pubspec.yaml`).
+/// * No environment variables (that are not filtered out) changed.
+/// * None of the files or directories declared in
+///   [HookOutputBuilder.dependencies] changed.
+/// * None of the transitive Dart sources of the hook script itself changed.
+/// * The workspace `package_config.json` didn't change.
+/// * The Dart SDK version didn't change.
+///
+/// If any of these conditions are not met, the hook is re-run.
+///
+/// ### Hook Output Dependencies
+///
+/// To ensure cache correctness when external files or assets are modified,
+/// hooks must explicitly declare their file and directory dependencies using
+/// [HookOutputBuilder.dependencies] (e.g., via
+/// `output.dependencies.add(uri)`).
+///
+/// ### Cache Isolation
+///
+/// Outputs are cached in a configuration-specific subdirectory inside
+/// `.dart_tool/hooks_runner/`. This directory is unique per hook and is derived
+/// from the [HookConfig]/[LinkConfig] structure. Therefore, different
+/// configurations (e.g., building for a different target OS or architecture)
+/// do not collide.
+///
+/// The cache is reused for identical configurations across different builds,
+/// even when inputs outside the configuration or environment variables change.
+///
 /// ## Debugging
 ///
 /// When a link hook doesn't work as expected, you can investigate the

pkgs/hooks/pubspec.yaml

@@ -3,7 +3,7 @@ description: >-
   A library that contains a Dart API for the JSON-based protocol for
   `hook/build.dart` and `hook/link.dart`.
 
-version: 2.0.0
+version: 2.0.1
 
 repository: https://github.com/dart-lang/native/tree/main/pkgs/hooks