@@ -78,10 +78,41 @@ import '../validation.dart';
7878/// }
7979/// ```
8080///
81- /// If the [builder] fails, it must `throw` a [HookError] . Build hooks are
82- /// guaranteed to be invoked with a process invocation and should return a
83- /// non-zero exit code on failure. Throwing will lead to an uncaught exception,
84- /// causing a non-zero exit code.
81+ /// ## Environment
82+ ///
83+ /// Build hooks are executed in a semi-hermetic environment. This means that
84+ /// `Platform.environment` does not expose all environment variables from the
85+ /// parent process. This ensures that hook invocations are reproducible and
86+ /// cacheable, and do not depend on accidental environment variables.
87+ ///
88+ /// However, some environment variables are necessary for locating tools (like
89+ /// compilers) or configuring network access. The following environment
90+ /// variables are passed through to the hook process:
91+ ///
92+ /// * **Path and system roots:**
93+ /// * `PATH`: Invoke native tools.
94+ /// * `HOME`, `USERPROFILE`: Find tools in default install locations.
95+ /// * `SYSTEMDRIVE`, `SYSTEMROOT`, `WINDIR`: Process invocations and CMake
96+ /// on Windows.
97+ /// * `PROGRAMDATA`: For `vswhere.exe` on Windows.
98+ /// * **Temporary directories:**
99+ /// * `TEMP`, `TMP`, `TMPDIR`: Temporary directories.
100+ /// * **HTTP proxies:**
101+ /// * `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`: Network access behind
102+ /// proxies.
103+ /// * **Clang/LLVM:**
104+ /// * `LIBCLANG_PATH`: Rust's `bindgen` + `clang-sys`.
105+ /// * **Android NDK:**
106+ /// * `ANDROID_HOME`: Standard location for the Android SDK/NDK.
107+ /// * `ANDROID_NDK`, `ANDROID_NDK_HOME`, `ANDROID_NDK_LATEST_HOME`,
108+ /// `ANDROID_NDK_ROOT`: Alternative locations for the NDK.
109+ /// * **Nix:**
110+ /// * Any variable starting with `NIX_`.
111+ ///
112+ /// Any changes to these environment variables will cause cache invalidation for
113+ /// hooks.
114+ ///
115+ /// All other environment variables are stripped.
85116///
86117/// ## Debugging
87118///
@@ -213,6 +244,42 @@ Future<void> build(
213244/// non-zero exit code on failure. Throwing will lead to an uncaught exception,
214245/// causing a non-zero exit code.
215246///
247+ /// ## Environment
248+ ///
249+ /// Link hooks are executed in a semi-hermetic environment. This means that
250+ /// `Platform.environment` does not expose all environment variables from the
251+ /// parent process. This ensures that hook invocations are reproducible and
252+ /// cacheable, and do not depend on accidental environment variables.
253+ ///
254+ /// However, some environment variables are necessary for locating tools (like
255+ /// compilers) or configuring network access. The following environment
256+ /// variables are passed through to the hook process:
257+ ///
258+ /// * **Path and system roots:**
259+ /// * `PATH`: Invoke native tools.
260+ /// * `HOME`, `USERPROFILE`: Find tools in default install locations.
261+ /// * `SYSTEMDRIVE`, `SYSTEMROOT`, `WINDIR`: Process invocations and CMake
262+ /// on Windows.
263+ /// * `PROGRAMDATA`: For `vswhere.exe` on Windows.
264+ /// * **Temporary directories:**
265+ /// * `TEMP`, `TMP`, `TMPDIR`: Temporary directories.
266+ /// * **HTTP proxies:**
267+ /// * `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`: Network access behind
268+ /// proxies.
269+ /// * **Clang/LLVM:**
270+ /// * `LIBCLANG_PATH`: Rust's `bindgen` + `clang-sys`.
271+ /// * **Android NDK:**
272+ /// * `ANDROID_HOME`: Standard location for the Android SDK/NDK.
273+ /// * `ANDROID_NDK`, `ANDROID_NDK_HOME`, `ANDROID_NDK_LATEST_HOME`,
274+ /// `ANDROID_NDK_ROOT`: Alternative locations for the NDK.
275+ /// * **Nix:**
276+ /// * Any variable starting with `NIX_`.
277+ ///
278+ /// Any changes to these environment variables will cause cache invalidation for
279+ /// hooks.
280+ ///
281+ /// All other environment variables are stripped.
282+ ///
216283/// ## Debugging
217284///
218285/// When a link hook doesn't work as expected, you can investigate the
0 commit comments