Skip to content

Commit 4c03068

Browse files
authored
[hooks] Document hook env vars (dart-lang#3034)
1 parent 39e3e71 commit 4c03068

5 files changed

Lines changed: 114 additions & 8 deletions

File tree

‎pkgs/hooks/CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
## 1.0.1
2+
3+
- Update documentation about environment variables.
4+
15
## 1.0.0
26

37
- Stable release.

‎pkgs/hooks/lib/hooks.dart‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,42 @@
7272
///
7373
/// For more information see
7474
/// [dart.dev/tools/hooks](https://dart.dev/tools/hooks).
75+
///
76+
/// ## Environment
77+
///
78+
/// Hooks are executed in a semi-hermetic environment. This means that
79+
/// `Platform.environment` does not expose all environment variables from the
80+
/// parent process. This ensures that hook invocations are reproducible and
81+
/// cacheable, and do not depend on accidental environment variables.
82+
///
83+
/// However, some environment variables are necessary for locating tools (like
84+
/// compilers) or configuring network access. The following environment
85+
/// variables are passed through to the hook process:
86+
///
87+
/// * **Path and system roots:**
88+
/// * `PATH`: Invoke native tools.
89+
/// * `HOME`, `USERPROFILE`: Find tools in default install locations.
90+
/// * `SYSTEMDRIVE`, `SYSTEMROOT`, `WINDIR`: Process invocations and CMake
91+
/// on Windows.
92+
/// * `PROGRAMDATA`: For `vswhere.exe` on Windows.
93+
/// * **Temporary directories:**
94+
/// * `TEMP`, `TMP`, `TMPDIR`: Temporary directories.
95+
/// * **HTTP proxies:**
96+
/// * `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`: Network access behind
97+
/// proxies.
98+
/// * **Clang/LLVM:**
99+
/// * `LIBCLANG_PATH`: Rust's `bindgen` + `clang-sys`.
100+
/// * **Android NDK:**
101+
/// * `ANDROID_HOME`: Standard location for the Android SDK/NDK.
102+
/// * `ANDROID_NDK`, `ANDROID_NDK_HOME`, `ANDROID_NDK_LATEST_HOME`,
103+
/// `ANDROID_NDK_ROOT`: Alternative locations for the NDK.
104+
/// * **Nix:**
105+
/// * Any variable starting with `NIX_`.
106+
///
107+
/// Any changes to these environment variables will cause cache invalidation for
108+
/// hooks.
109+
///
110+
/// All other environment variables are stripped.
75111
library;
76112

77113
export 'src/api/build_and_link.dart' show build, link;

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

Lines changed: 71 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -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

‎pkgs/hooks/pubspec.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ description: >-
33
A library that contains a Dart API for the JSON-based protocol for
44
`hook/build.dart` and `hook/link.dart`.
55
6-
version: 1.0.0
6+
version: 1.0.1
77

88
repository: https://github.com/dart-lang/native/tree/main/pkgs/hooks
99

‎pkgs/hooks_runner/lib/src/utils/run_process.dart‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,9 +45,8 @@ Future<RunProcessResult> runProcess({
4545
arguments: {
4646
'executable': executable.toFilePath(),
4747
'arguments': arguments,
48-
if (workingDirectory != null)
49-
'workingDirectory': workingDirectory.toFilePath(),
50-
if (environment != null) 'environment': environment,
48+
'workingDirectory': ?workingDirectory?.toFilePath(),
49+
'environment': ?environment,
5150
},
5251
);
5352
try {

0 commit comments

Comments
 (0)