[native_assets_cli] Protocol environment variables

[dcharkes]

Leaning towards passing in all environment variables, and reinvoking the hooks on any environment variable change.

• This needs to be documented somewhere.

Problem

With what environment variables should we invoke build.dart?

build.dart is invoked with a BuildConfig (which is read from args/env/file), but the CLI itself most likely invokes other processes (for example a C compiler). These processes are influenced by which environment variables are set.

Minimum env variables

Let's say we get rust_compiler package that tries to find rustc on PATH, then we must at least pass through PATH on our build.dart invocation.

On Windows, various tools rely on a host of other environment variables as well:

• SYSTEMROOT is required for cl.exe from MSVC
• TMP and TEMP are required for cl.exe in some cases in order to be able to write temporary files.

So the minimum list of environment variables we should pass through are the ones mentioned above.

Maximum environment variables

Conversely, there are also environment variables which are conflicting with the Dart ecosystem and native tooling.

• SDKROOT is set by tools/test.py which breaks xcodebuild invocations as it interprets the SDKROOT as a path for the iOS or MacOS SDK rather than the Dart SDK.

Caching correctness and cache misses

If any of the environment variables influences the build, it could throw off caching of builds:

• If we ignore all environment variables when determining whether a cache can be reused, we might accidentally not rebuild leading to stale builds. (Currently the only way for a user to fix that is to find the folder in which the build has happened and delete it.)
• If we take all environment variables into account when determining if a cache can be reused, we might throw away build caches too often.

Possible solutions

We could consider listing the environment variables we pass through, making an allow list.
Or we could consider listing the environment variables we use for caching, but passing through all except for a deny list.

1. SDK: Pass through everything except deny list + use these for caching

Pros:

• Correct caching
• Users using new environment variables not blocked

Cons:

• We might throw out valid cached for spurious environment changes.

(We should probably change SDKROOT to DARTSDKROOT in test.py and it's users.)

Even when implementing the env-filtering in the Dart and Flutter SDK, we should probably make the deny list (or allow list) part of this package, so that this package contains the whole protocol spec.

2. SDK: Pass through only an allow list + use these for caching

Pros:

• Correct caching
• Efficient caching

Cons:

• If users want rely on a new environment variable, they need make an SDK PR and wait for the next Dart SDK release.

3. SDK: Pass through everything except for deny list + use allowlist for caching

Pros:

• Users using new environment variables not blocked
• Efficient caching

Cons:

• Potentially incorrect caching. Users would need to make a PR to the Dart SDK to make it work.

4. package:native_assets_cli solution

Always just invoke build.dart with all environment variables, but add the allowList or denyList to package:native_assets_cli.

There would be an .environment getter on BuildConfig likely.

Pro:

• Updating allowList/denyList does not require Dart SDK / Flutter updates.
• We could potentially Isolate.spawnUri to run build rather than Process.run (but that would mean no exit(int) calling in any build.dart script, and tougher handling of unhandled exceptions etc.) [native_assets_cli] Protocol exit codes / unhandled exceptions #33

Con:

• Every process invocation in build.dart requires explicitly passing environment and includeParentEnvironment: false.
• Incorrect caching until that version of native_assets_cli rolls into the Dart SDK.

Maybe there are solutions I haven't thought about yet. I'm open to suggestions. (Otherwise I might lean towards solution 1 or 2.)

internal design doc with some initial discussion about the env vars

cc @mkustermann @liamappelbe @HosseinYousefi