Add a "pub workspace" to the root of the engine repository

pubspec.yaml

@@ -0,0 +1,175 @@
+# This file represents a "workspace" that applies to the whole repository.
+#
+# See <https://flutter.dev/go/pub-workspace> for details.
+#
+# The `flutter/engine` repository is a quasi-monorepo, with multiple Dart tools
+# and packages that are all interdependent. Third party dependencies are managed
+# by the `DEPS` file in the root of the repository, and are synced to either the
+# `third_party` (i.e. `//flutter/third_party`) or `../third_party` (i.e.
+# `//third_party`) directories by `gclient sync`.
+#
+# Every dependency declared here are dependencies used by _one or more_ of the
+# packages in the repository (though there is no enforcement of this). This file
+# then generates a `.dart_tool/package_config.json` file that is used by the
+# rest of the repository to resolve dependencies.
+#
+# ==============================================================================
+# WORKFLOWS
+# ==============================================================================
+#
+# ------------------------------------------------------------------------------
+# (1) ADDING A NEW DEPENDENCY
+# ------------------------------------------------------------------------------
+# Dependencies need to be added either via the DEPS file, or by checking the are
+# available in the vendored Dart SDK (see notes below on library locations). If
+# they are available, do the following.
+#
+# See (4) for how to add dependencies to a package in the workspace.
+#
+# ------------------------------------------------------------------------------
+# (2) CREATING A NEW PACKAGE
+# ------------------------------------------------------------------------------
+# If creating a package, say in ./tools or ./tools/pkg, ensure the following
+# header in it's respective `pubspec.yaml`:
+# ```
+# # We don't publish packages to pub.dev from the engine repository.
+# publish_to: none
+#
+# # Required for workspace support.
+# environment:
+#   sdk: ^3.5.0-294.0.dev
+#
+# # This package is managed as part of the engine workspace.
+# resolution: workspace
+# ```
+#
+# See (4) for how to add dependencies to a package in the workspace.
+#
+# ------------------------------------------------------------------------------
+# (3) MIGRATING A NON-WORKSPACE PACKAGE TO USING THE WORKSPACE
+# ------------------------------------------------------------------------------
+# Many packages in this repo are still using a pre-workspace style pubspec.yaml,
+# either with manually declared `dependency_overrides` (much of ./tools) or by
+# using pub (./web_sdk, ./lib/web_ui). To migrate a package to the workspace:
+#
+# A. Add the `resolution: workspace` field to the pubspec.yaml.
+# B. Update the minimum SDK version to at least `^3.5.0-294.0.dev`.
+# C. Add the package to the `workspace` field in this file.
+# D. Ensure every dependency in the package is added to the `dependencies` field
+#    in this file, following instructions in (4).
+#
+# Once `dart pub get` is run on the workspace, the package will be resolved as
+# part of the workspace, and the `dependency_overrides` in this file will be
+# applied to the package.
+#
+# ------------------------------------------------------------------------------
+# (4) ADDING DEPENDENCIES TO A PACKAGE IN THIS WORKSPACE
+# ------------------------------------------------------------------------------
+# When adding a dependency to a package in the workspace, add the dependency to
+# the `dependencies` field in this file. If the dependency is located within
+# the repository, use the `path` field to point to the package.
+#
+# If the dependency is a third party package, add it to the
+# `dependency_overrides` field in this file. The `any` version constraint is
+# used to indicate that the version of the package is not important, as it is
+# managed by the `DEPS` file.
+
+name: _engine_workspace
+
+# Required for workspace support.
+environment:
+  sdk: ^3.5.0-294.0.dev
+
+# Declare all packages that are part of the workspace.
+workspace:
+  - tools/engine_tool
+
+# Declare all dependencies that are used by one or more packages.
+#
+# A few notes:
+# 1. There is no distinction between "dependencies" and "dev_dependencies";
+#    those notions are for *publishing* packages, not for managing a workspace.
+#    Specific packages in the workspace itself will declare whether they are
+#    dependencies or dev_dependencies, but here it is a union of both.
+#
+# 2. The `any` version constraint is used to indicate that the version of the
+#    package is not important, as it is managed by the `DEPS` file. In other
+#    words, "if the test pass, ship it".
+#
+# While not enforced by tooling, try to keep this list in alphabetical order.
+# TODO(matanlurey): https://dart.dev/tools/linter-rules/sort_pub_dependencies.
+dependencies:
+  args: any
+  async_helper: any
+  expect: any
+  file: any
+  logging: any
+  meta: any
+  path: any
+  platform: any
+  process_runner: any
+  smith: any
+
+# Instructs pub on how to resolve the dependencies that are part of "DEPS".
+#
+# For historic reasons, there are ~3 or so places packages might be located:
+#
+# - `./third_party/pkg/{name}`: for packages vended directly as part of "DEPS".
+#    Usually these are Flutter engine specific packages, i.e. they did not exist
+#    in the Dart vended SDK (the other options below). Typically these originate
+#    from pub (https://pub.dev) and are mirrored into a Google Git repository:
+#    <https://flutter.googlesource.com/>.
+#
+# - `./third_party/dart/pkg/{name}`: for packages that lives *in* the Dart SDK,
+#    which is in turn vendored into the Flutter engine repository. You can see
+#    a full list of available packages here:
+#    <https://github.com/dart-lang/sdk/tree/main/pkg>.
+#
+# - `./third_party/dart/third_party/pkg/{name}`: for packages that are vendored
+#    into the Dart SDK from pub.dev. These are often first-party packages from
+#    the Dart team, but not part of the Dart SDK itself. You can see a full list
+#    of available packages here:
+#    <https://github.com/dart-lang/sdk/blob/main/DEPS>.
+dependency_overrides:
+  args:
+    path: ./third_party/dart/third_party/pkg/args
+  async:
+    path: ./third_party/dart/third_party/pkg/async
+  async_helper:
+    path: ./third_party/dart/pkg/async_helper
+  collection:
+    path: ./third_party/dart/third_party/pkg/collection
+  engine_build_configs:
+    path: ./tools/pkg/engine_build_configs
+  engine_repo_tools:
+    path: ./tools/pkg/engine_repo_tools
+  expect:
+    path: ./third_party/dart/pkg/expect
+  file:
+    path: ./third_party/dart/third_party/pkg/file/packages/file
+  litetest:
+    path: ./testing/litetest
+  logging:
+    path: ./third_party/dart/third_party/pkg/logging
+  meta:
+    path: ./third_party/dart/pkg/meta
+  path:
+    path: ./third_party/dart/third_party/pkg/path
+  platform:
+    path: ./third_party/pkg/platform
+  process:
+    path: ./third_party/pkg/process
+  process_fakes:
+    path: ./tools/pkg/process_fakes
+  process_runner:
+    path: ./third_party/pkg/process_runner
+  smith:
+    path: ./third_party/dart/pkg/smith
+  source_span:
+    path: ./third_party/dart/third_party/pkg/source_span
+  string_scanner:
+    path: ./third_party/dart/third_party/pkg/string_scanner
+  term_glyph:
+    path: ./third_party/dart/third_party/pkg/term_glyph
+  yaml:
+    path: ./third_party/dart/third_party/pkg/yaml

tools/engine_tool/pubspec.yaml

@@ -4,18 +4,13 @@
 
 name: engine_tool
 publish_to: none
-environment:
-  # Required for extension types.
-  sdk: ^3.3.0
 
-# Do not add any dependencies that require more than what is provided in
-# //third_party/pkg, //third_party/dart/pkg, or
-# //third_party/dart/third_party/pkg. In particular, package:test is not usable
-# here.
+# Required for workspace support.
+environment:
+  sdk: ^3.5.0-294.0.dev
 
-# If you do add packages here, make sure you can run `pub get --offline`, and
-# check the .packages and .package_config to make sure all the paths are
-# relative to this directory into //third_party/dart
+# This package is managed as part of the engine workspace.
+resolution: workspace
 
 dependencies:
   args: any
@@ -31,47 +26,7 @@ dependencies:
   process_runner: any
 
 dev_dependencies:
-  async_helper: any
-  expect: any
-  litetest: any
-  process_fakes:
-    path: ../pkg/process_fakes
-  smith: any
-
-dependency_overrides:
-  args:
-    path: ../../third_party/dart/third_party/pkg/args
-  async:
-    path: ../../third_party/dart/third_party/pkg/async
-  async_helper:
-    path: ../../third_party/dart/pkg/async_helper
-  collection:
-    path: ../../third_party/dart/third_party/pkg/collection
-  expect:
-    path: ../../third_party/dart/pkg/expect
-  file:
-    path: ../../third_party/dart/third_party/pkg/file/packages/file
   litetest:
     path: ../../testing/litetest
-  logging:
-    path: ../../third_party/dart/third_party/pkg/logging
-  meta:
-    path: ../../third_party/dart/pkg/meta
-  path:
-    path: ../../third_party/dart/third_party/pkg/path
-  platform:
-    path: ../../third_party/pkg/platform
-  process:
-    path: ../../third_party/pkg/process
-  process_runner:
-    path: ../../third_party/pkg/process_runner
-  smith:
-    path: ../../third_party/dart/pkg/smith
-  source_span:
-    path: ../../third_party/dart/third_party/pkg/source_span
-  string_scanner:
-    path: ../../third_party/dart/third_party/pkg/string_scanner
-  term_glyph:
-    path: ../../third_party/dart/third_party/pkg/term_glyph
-  yaml:
-    path: ../../third_party/dart/third_party/pkg/yaml
+  process_fakes:
+    path: ../pkg/process_fakes

tools/pub_get_offline.py

@@ -18,6 +18,7 @@
 ENGINE_DIR = os.path.join(SRC_ROOT, 'flutter')
 
 ALL_PACKAGES = [
+    os.path.join(ENGINE_DIR),
     os.path.join(ENGINE_DIR, 'ci'),
     os.path.join(ENGINE_DIR, 'flutter_frontend_server'),
     os.path.join(ENGINE_DIR, 'impeller', 'tessellator', 'dart'),
@@ -119,6 +120,9 @@ def find_unlisted_packages():
 
 
 def main():
+  # Intentionally use the Dart SDK prebuilt instead of the Flutter prebuilt
+  # (i.e. prebuilts/{platform}/dart-sdk/bin/dart) because the script has to run
+  # in a monorepo build *before* the newer Dart SDK has been built from source.
   dart_sdk_bin = os.path.join(
       SRC_ROOT, 'flutter', 'third_party', 'dart', 'tools', 'sdks', 'dart-sdk', 'bin'
   )