[flutter_hook_config] Add the flutter_hook_config package #11701
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| # Libraries should not include pubspec.lock, per https://dart.dev/guides/libraries/private-files#pubspeclock. | ||
| /pubspec.lock | ||
| **/doc/api/ | ||
| .dart_tool/ | ||
| .packages | ||
| build/ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| # Below is a list of people and organizations that have contributed | ||
| # to the Flutter project. Names should be added to the list like so: | ||
| # | ||
| # Name/Organization <email address> | ||
|
|
||
| Google Inc. | ||
|
Member
Author
There was a problem hiding this comment. Added this following the template of other new packages. I assume this is correct but not 100% sure. I'm CLA signed of course, but I no longer work at Google. |
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| ## 0.1.0 | ||
|
|
||
| * Initial release of `flutter_hook_config`: a `package:hooks` protocol extension | ||
| that lets the Flutter SDK expose engine host-tool paths (`impellerc`, | ||
| `libtessellator`) to build and link hooks, including the `--local-engine` | ||
| override. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| Copyright 2013 The Flutter Authors | ||
|
|
||
| Redistribution and use in source and binary forms, with or without modification, | ||
| are permitted provided that the following conditions are met: | ||
|
|
||
| * Redistributions of source code must retain the above copyright | ||
| notice, this list of conditions and the following disclaimer. | ||
| * Redistributions in binary form must reproduce the above | ||
| copyright notice, this list of conditions and the following | ||
| disclaimer in the documentation and/or other materials provided | ||
| with the distribution. | ||
| * Neither the name of Google Inc. nor the names of its | ||
| contributors may be used to endorse or promote products derived | ||
| from this software without specific prior written permission. | ||
|
|
||
| THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND | ||
| ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED | ||
| WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE | ||
| DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR | ||
| ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES | ||
| (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; | ||
| LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON | ||
| ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | ||
| (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS | ||
| SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| # flutter_hook_config | ||
|
|
||
| A [`package:hooks`](https://pub.dev/packages/hooks) protocol extension that lets | ||
| the Flutter SDK pass Flutter-specific configuration to build and link hooks in a | ||
| typed way. | ||
|
|
||
| Today it exposes the absolute paths of the engine host tools a hook might need: | ||
|
|
||
| * `impellerc`, the offline shader compiler (used, for example, by | ||
| `flutter_gpu_shaders` to compile `.shaderbundle.json` files). | ||
| * `libtessellator`, the tessellation library. | ||
|
|
||
| The Flutter SDK (`flutter_tools`) resolves these through the same artifact | ||
| lookup it uses for its own build steps, so under `--local-engine` a hook gets | ||
| the locally built tools, matching the engine the app is being built against, | ||
| instead of the ones in the SDK cache. | ||
|
|
||
| ## For hook authors | ||
|
|
||
| Add `flutter_hook_config` to your hook's dependencies and read the config from | ||
| the `BuildInput` / `LinkInput` via `input.config.flutter`. Always check | ||
| `input.config.buildForFlutter` first: a hook may also be invoked by a plain | ||
| `dart` build, or by a Flutter SDK that predates this extension, in which case no | ||
| Flutter-specific config is available and you should fall back to your own tool | ||
| discovery. | ||
|
|
||
| See the [library documentation](https://pub.dev/documentation/flutter_hook_config/latest/) | ||
| for a usage example. | ||
|
|
||
| ## For the Flutter SDK | ||
|
|
||
| `flutter_tools` constructs a `FlutterExtension` (populated from | ||
| `Artifacts.getHostArtifact(...)`) and passes it to the hook runner alongside the | ||
| other protocol extensions (`CodeAssetExtension`, `DataAssetsExtension`), so the | ||
| configuration above becomes available to every build and link hook. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| # The tests use `dart:io` to construct absolute file paths, and build hooks | ||
| # themselves only run on the Dart VM, so there is no need to run on the web. | ||
| test_on: vm |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| // Copyright 2013 The Flutter Authors | ||
| // Use of this source code is governed by a BSD-style license that can be | ||
| // found in the LICENSE file. | ||
|
|
||
| /// A `package:hooks` protocol extension that exposes Flutter engine host-tool | ||
| /// paths (such as `impellerc` and `libtessellator`) to build and link hooks. | ||
| /// | ||
| /// Hook authors read the injected configuration via [HookConfigFlutterConfig], | ||
| /// checking [HookConfigFlutterConfig.buildForFlutter] first: | ||
| /// | ||
| /// ```dart | ||
| /// import 'package:flutter_hook_config/flutter_hook_config.dart'; | ||
| /// import 'package:hooks/hooks.dart'; | ||
| /// | ||
| /// void main(List<String> args) async { | ||
| /// await build(args, (input, output) async { | ||
| /// if (input.config.buildForFlutter) { | ||
| /// final impellerc = input.config.flutter.impellerc; | ||
| /// // ... invoke impellerc ... | ||
| /// } | ||
| /// }); | ||
| /// } | ||
| /// ``` | ||
| /// | ||
| /// The Flutter SDK (`flutter_tools`) populates the configuration by passing a | ||
| /// [FlutterExtension] to the hook runner. | ||
| library; | ||
|
|
||
| export 'src/config.dart' | ||
| show FlutterConfig, HookConfigBuilderFlutterConfig, HookConfigFlutterConfig; | ||
| export 'src/extension.dart' show FlutterExtension; |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,147 @@ | ||
| // Copyright 2013 The Flutter Authors | ||
| // Use of this source code is governed by a BSD-style license that can be | ||
| // found in the LICENSE file. | ||
|
|
||
| import 'package:hooks/hooks.dart'; | ||
|
|
||
| /// The hook config field that holds protocol-extension namespaces. | ||
| const String _extensionsKey = 'extensions'; | ||
|
|
||
| /// The key under which Flutter-specific configuration is stored inside the hook | ||
| /// config's [_extensionsKey] map. | ||
| const String _flutterExtensionKey = 'flutter'; | ||
|
|
||
| const String _engineVersionKey = 'engine_version'; | ||
| const String _impellercKey = 'impellerc'; | ||
| const String _libtessellatorKey = 'libtessellator'; | ||
|
|
||
| /// Flutter-specific configuration supplied to a build or link hook. | ||
| /// | ||
| /// Obtained via [HookConfigFlutterConfig.flutter]. Only available when the hook | ||
| /// is invoked by a Flutter SDK that supports this extension; check | ||
| /// [HookConfigFlutterConfig.buildForFlutter] before accessing it. | ||
| /// | ||
| /// `hooks_runner` keys the hook cache on the contents of this config, so | ||
| /// changes to any field here invalidate the cache and force the hook to be | ||
| /// re-run. In particular, [engineVersion] changes whenever the Flutter SDK is | ||
| /// upgraded, which is what causes hooks consuming engine host tools (such as | ||
| /// `impellerc`) to re-run with the new binaries even though [impellerc] and | ||
| /// [libtessellator] point at the same paths. | ||
| final class FlutterConfig { | ||
| FlutterConfig._(this._json); | ||
|
|
||
| final Map<String, Object?> _json; | ||
|
|
||
| /// An opaque identifier for the Flutter engine the invoking SDK targets. | ||
| /// | ||
| /// This is the Flutter engine revision under a normal `flutter` invocation, | ||
| /// or a stable identifier derived from the local engine output directory | ||
| /// under `--local-engine`. Treat the value as opaque: it is only meaningful | ||
| /// for equality comparison and for ensuring that a different Flutter SDK | ||
| /// produces a different value (so that the hook cache invalidates). | ||
| String get engineVersion => _string(_engineVersionKey); | ||
|
|
||
| /// The absolute path to the `impellerc` offline shader compiler that ships | ||
| /// with the engine artifacts of the invoking Flutter SDK. | ||
| /// | ||
| /// When the SDK is invoked with `--local-engine`, this points at the locally | ||
| /// built `impellerc`, matching the engine the app is being built against. | ||
| Uri get impellerc => _filePath(_impellercKey); | ||
|
Contributor
There was a problem hiding this comment. Are these two related? Do they change together? If yes they should maybe be nested in an object together. Also, does every Flutter have impeller? E.g. With third-party forks of Flutter is there ever a possibility there's no impeller? If yes, then that wrapper object should be nullable. And if it's not null both fields are non-nullably provided. Do we need a some kind of version number for this? e.g. if any of these files change or the underlying formats change, you'd want the hook to be rerun.
Member
Author
There was a problem hiding this comment.
The
Member
Author
There was a problem hiding this comment.
Hmm yes that's a good point and we should think about this... Since the artifacts are per-engine build, maybe the right thing to do would be to add a Does that seem right? |
||
|
|
||
| /// The absolute path to the `libtessellator` dynamic library that ships with | ||
| /// the engine artifacts of the invoking Flutter SDK. | ||
| /// | ||
| /// When the SDK is invoked with `--local-engine`, this points at the locally | ||
| /// built `libtessellator`. | ||
| Uri get libtessellator => _filePath(_libtessellatorKey); | ||
|
|
||
| Uri _filePath(String key) => Uri.file(_string(key)); | ||
|
|
||
| String _string(String key) { | ||
| final Object? value = _json[key]; | ||
| if (value is! String) { | ||
| throw FormatException( | ||
| 'Expected a String at ' | ||
| "'config.$_extensionsKey.$_flutterExtensionKey.$key' in the hook " | ||
| 'input, got: $value', | ||
| ); | ||
| } | ||
| return value; | ||
| } | ||
| } | ||
|
|
||
| /// Extension on [HookConfig] providing access to Flutter-specific | ||
| /// configuration. | ||
| extension HookConfigFlutterConfig on HookConfig { | ||
| /// Whether this hook is being invoked as part of a Flutter build. | ||
| /// | ||
| /// When `false`, the hook is being invoked by a plain `dart` build, or by a | ||
| /// Flutter SDK that predates the `flutter_hook_config` extension, and | ||
| /// [flutter] must not be accessed. Hooks that need Flutter-supplied | ||
| /// configuration should fall back to their own discovery logic in that case. | ||
| bool get buildForFlutter => _flutterExtensionJson != null; | ||
|
|
||
| /// The Flutter-specific configuration for this hook invocation. | ||
| /// | ||
| /// Only valid when [buildForFlutter] is `true`; throws a [StateError] | ||
| /// otherwise. | ||
| FlutterConfig get flutter { | ||
| final Map<String, Object?>? extensionJson = _flutterExtensionJson; | ||
| if (extensionJson == null) { | ||
| throw StateError( | ||
| 'No Flutter-specific hook configuration is available. The hook is not ' | ||
| 'being invoked by a Flutter SDK, or the Flutter SDK predates ' | ||
| 'flutter_hook_config support. Check `config.buildForFlutter` first.', | ||
| ); | ||
| } | ||
| return FlutterConfig._(extensionJson); | ||
| } | ||
|
|
||
| Map<String, Object?>? get _flutterExtensionJson { | ||
| final Object? extensions = json[_extensionsKey]; | ||
| if (extensions is! Map<String, Object?>) { | ||
| return null; | ||
| } | ||
| final Object? flutterJson = extensions[_flutterExtensionKey]; | ||
| return flutterJson is Map<String, Object?> ? flutterJson : null; | ||
| } | ||
| } | ||
|
|
||
| /// Extension on [HookConfigBuilder] for writing Flutter-specific configuration | ||
| /// onto a hook input. | ||
| /// | ||
| /// This is intended for use by the Flutter SDK (`flutter_tools`) via | ||
| /// [FlutterExtension]; ordinary hook authors do not call this directly. | ||
| extension HookConfigBuilderFlutterConfig on HookConfigBuilder { | ||
| /// Records the Flutter-specific configuration on a build or link hook input. | ||
| /// | ||
| /// [engineVersion] is an opaque identifier that must change whenever any | ||
| /// engine artifact exposed here can change (typically the engine revision | ||
| /// for a stock SDK; a stable identifier for the local engine output | ||
| /// directory under `--local-engine`). Surfacing it as part of the config | ||
| /// ensures the hook cache invalidates when the Flutter SDK is upgraded. | ||
| /// | ||
| /// [impellerc] and [libtessellator] must be absolute file URIs. | ||
| void setupFlutter({ | ||
| required String engineVersion, | ||
| required Uri impellerc, | ||
| required Uri libtessellator, | ||
| }) { | ||
| assert(engineVersion.isNotEmpty, 'engineVersion must not be empty'); | ||
| assert( | ||
| impellerc.isAbsolute && impellerc.isScheme('file'), | ||
| 'impellerc must be an absolute file URI', | ||
| ); | ||
| assert( | ||
| libtessellator.isAbsolute && libtessellator.isScheme('file'), | ||
| 'libtessellator must be an absolute file URI', | ||
| ); | ||
| final extensions = | ||
| (json[_extensionsKey] ??= <String, Object?>{}) as Map<String, Object?>; | ||
| extensions[_flutterExtensionKey] = <String, Object?>{ | ||
| _engineVersionKey: engineVersion, | ||
| _impellercKey: impellerc.toFilePath(), | ||
| _libtessellatorKey: libtessellator.toFilePath(), | ||
| }; | ||
| } | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,80 @@ | ||
| // Copyright 2013 The Flutter Authors | ||
| // Use of this source code is governed by a BSD-style license that can be | ||
| // found in the LICENSE file. | ||
|
|
||
| import 'dart:async'; | ||
|
|
||
| import 'package:hooks/hooks.dart'; | ||
|
|
||
| import 'config.dart'; | ||
|
|
||
| /// A [ProtocolExtension] that supplies Flutter-specific configuration to build | ||
| /// and link hooks. | ||
| /// | ||
| /// This is constructed by the Flutter SDK (`flutter_tools`) and passed to the | ||
| /// hook runner alongside the other protocol extensions. Hook authors consume | ||
| /// the data it injects via [HookConfigFlutterConfig.flutter] rather than using | ||
| /// this class directly. | ||
| final class FlutterExtension implements ProtocolExtension { | ||
| /// Creates a [FlutterExtension]. | ||
| /// | ||
| /// [engineVersion] is an opaque identifier that must change whenever any of | ||
| /// the exposed engine artifacts can change (typically the Flutter engine | ||
| /// revision; a stable identifier for the local engine output directory under | ||
| /// `--local-engine`). It is what causes hook caches to invalidate when the | ||
| /// Flutter SDK is upgraded. | ||
| /// | ||
| /// [impellerc] and [libtessellator] must be absolute file URIs pointing at | ||
| /// the corresponding engine host tools. | ||
| FlutterExtension({ | ||
| required this.engineVersion, | ||
| required this.impellerc, | ||
| required this.libtessellator, | ||
| }); | ||
|
|
||
| /// An opaque identifier for the Flutter engine the invoking SDK targets. | ||
| final String engineVersion; | ||
|
|
||
| /// The absolute path to the `impellerc` offline shader compiler. | ||
| final Uri impellerc; | ||
|
|
||
| /// The absolute path to the `libtessellator` dynamic library. | ||
| final Uri libtessellator; | ||
|
|
||
| void _setup(HookConfigBuilder config) => config.setupFlutter( | ||
| engineVersion: engineVersion, | ||
| impellerc: impellerc, | ||
| libtessellator: libtessellator, | ||
| ); | ||
|
|
||
| @override | ||
| void setupBuildInput(BuildInputBuilder input) => _setup(input.config); | ||
|
|
||
| @override | ||
| void setupLinkInput(LinkInputBuilder input) => _setup(input.config); | ||
|
|
||
| @override | ||
| Future<ValidationErrors> validateBuildInput(BuildInput input) async => | ||
| const <String>[]; | ||
|
|
||
| @override | ||
| Future<ValidationErrors> validateLinkInput(LinkInput input) async => | ||
| const <String>[]; | ||
|
|
||
| @override | ||
| Future<ValidationErrors> validateBuildOutput( | ||
| BuildInput input, | ||
| BuildOutput output, | ||
| ) async => const <String>[]; | ||
|
|
||
| @override | ||
| Future<ValidationErrors> validateLinkOutput( | ||
| LinkInput input, | ||
| LinkOutput output, | ||
| ) async => const <String>[]; | ||
|
|
||
| @override | ||
| Future<ValidationErrors> validateApplicationAssets( | ||
| List<EncodedAsset> assets, | ||
| ) async => const <String>[]; | ||
| } |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Note: label needs to be created