tom_analyzer_shared library
Shared analyzer-summary caching infrastructure for Tom code generators.
This library exposes:
- PackageDependency / DependencySet — resolved dependency metadata.
- DependencyResolver — parses
pubspec.lockand locates hosted/SDK package source trees in the pub cache and the Flutter SDK. - ToolCacheLocator — resolves the workspace-local Tom tool-cache directory
(
TOM_TOOL_CACHE→ the workspace-root marker's.tom→<start>/.tom; never a machine-global directory). - SummaryCacheManager — reads and writes
.sumfiles under the workspace tool cache'sanalyzer-cache/<analyzer-major>/sub-directory. - analyzerMajorVersion — the analyzer major this build targets; used to partition the cache so analyzer upgrades cannot read stale bundles.
- SummaryGenerator — generates the SDK summary and per-package summaries in topological order.
- GroupedPackageBundleBuilder — builds one grouped
packages.sumfrom the union of several package dependency closures (for embedded-editor runtime analysis). See mergePackageRootsForDirs / readPackageRoots. - runSummaryCacheStage / SummaryCacheResult — a reusable orchestration entry-point for CLIs and builders.
- resolveDartSdkPath — robust Dart SDK location for AOT-compiled tools (where executable-relative SDK detection fails).
- AnalyzerCacheGarbageCollector / AnalyzerCachePartition — opt-in
reclamation of orphaned
<analyzer-major>/<dart-sdk-version>cache partitions left behind by retired toolchains.
See the package README for motivation and examples.
Classes
- AnalyzerCacheGarbageCollector
- Opt-in garbage collector for orphaned analyzer-cache partitions.
- AnalyzerCachePartition
-
One
<analyzer-major>/<toolchain>partition in the shared cache. - CacheStats
- Statistics about the summary cache.
- DependencyResolver
- Resolves project dependencies with their versions from pubspec.lock.
- DependencySet
- Groups dependencies by their cacheability status.
- GroupedPackageBundle
-
Result of building a grouped
packages.sumbundle from several package closures. - GroupedPackageBundleBuilder
-
Builds one
packages.sumbundle from the union of several package dependency closures. - PackageDependency
- Represents a resolved package dependency with version information.
- SummaryCacheManager
- Manages the analyzer summary cache for a workspace.
- SummaryCacheResult
- Result of a summary-cache stage execution.
- SummaryGenerationResult
- Result of generating summaries for a batch of packages.
- SummaryGenerator
- Generates analyzer summaries for packages.
- SummaryStamp
-
What a summary file was written by, recorded in a stamp file beside it
(
<summary>.stamp): the toolchain (currentToolchainKey: the Dart SDK and the analyzer data version, the exact key of the summary format) and whether it was built with Flutter's embedder (dart:ui). The embedder is recorded by its presence, not its path: the Dart SDK version in the toolchain already names the Flutter release it ships with, and a path would make the stamp — committed beside a shipped summary — true on one machine only. - SweptCacheFile
- A file AnalyzerCacheGarbageCollector.sweepBundles removed (or, on a dry run, would remove).
- ToolCacheLocator
- Resolves the Tom tool-cache directory — a workspace-local location for build artefacts that can be reused across the projects and tools of a single workspace.
Extensions
-
DependencyListExtensions
on List<
PackageDependency> - Extension methods for working with dependency lists.
Constants
- analyzerDataVersion → const int
-
The data version of the
analyzerthis build is linked with (AnalysisDriver.DATA_VERSION): the analyzer raises it whenever what it stores — summary bundles among it — changes format. - analyzerMajorVersion → const int
-
The major version of the
analyzerpackage this build oftom_analyzer_sharedwas compiled against.
Functions
-
analyzerDataVersionInPackageRoots(
Map< String, String> packageRoots) → int? -
The data version of the analyzer resolved among
packageRoots(name → package root, asreadPackageRootsreturns them), read from itsAnalysisDriversource, or null when the packages resolve no analyzer or the constant cannot be found. Tells whether summaries this tool writes can be read by the analyzer another package (an app shipping them) runs on. -
currentDartSdkVersion(
) → String -
The
<major>.<minor>.<patch>Dart SDK version of the running toolchain. -
currentToolchainKey(
{String? dartSdkVersion, int? dataVersion}) → String -
The toolchain a summary was written by, as one path-safe key:
<dart-sdk-version>+d<analyzer-data-version>(e.g.3.13.7+d752). The second segment of the cache partition, and what a stamp beside a summary records. Both parts default to the running toolchain. -
dartSdkWithEmbedder(
ResourceProvider resourceProvider, {required String sdkPath, String? embedderYamlPath}) → FolderBasedDartSdk -
The Dart SDK at
sdkPathwith the libraries of the embedder atembedderYamlPathadded where the SDK lacks them — the same SDKbuildSdkSummary(embedderYamlPath: ...)summarises, for linking a package summary that is read against that SDK summary. WithoutembedderYamlPathit is the plain SDK. -
flutterEmbedderYamlInPackageRoots(
Map< String, String> packageRoots) → String? -
The embedder file of the
sky_enginepackage amongpackageRoots(name → package root, asreadPackageRootsreturns them): the embedder of the very Flutter the packages were resolved against. Null when the packages are no Flutter packages. -
flutterEmbedderYamlInSdk(
String flutterSdkPath) → String? -
The embedder file of the Flutter SDK at
flutterSdkPath(bin/cache/pkg/sky_engine/lib/_embedder.yaml), or null when it has none. -
looksLikeDartSdk(
String? dir) → bool -
Whether
dirlooks like a Dart SDK root. -
mergePackageRootsForDirs(
Iterable< String> packageDirs) → Map<String, String> -
Merges the package roots resolved from each given package directory's
.dart_tool/package_config.jsoninto a single name→root map. -
readPackageRoots(
File packageConfigFile) → Map< String, String> -
Reads a resolved
.dart_tool/package_config.jsonand returns a map of package-name → absolute package root directory (the directory that containslib/). -
resolveDartSdkPath(
) → String? -
Resolves the Dart SDK root directory, or
nullto let the analyzer fall back to its default (executable-relative) detection. -
runSummaryCacheStage(
String projectRoot, {bool verbose = false, bool rebuildCache = false, bool showCacheStatus = false, List< String> cacheOnlyPackages = const [], void log(String message)?, SummaryCacheManager? cacheManager}) → Future<SummaryCacheResult?> - Runs the summary-cache stage for a project.
-
summaryLibraryUris(
Uint8List summaryBytes) → List< String> -
The library URIs a summary holds (
dart:core,dart:ui,package:flutter/painting.dart...): whether an SDK summary holdsdart:ui, i.e. was built with Flutter's embedder, without the analyzer's internals at the caller.
Exceptions / Errors
- IncompleteSummaryException
- A package's summary could not be built completely, so it was not cached.
- SummaryConfigException
-
Raised when a package directory has no resolved
.dart_tool/package_config.json(i.e.pub gethas not been run there), or when a grouped bundle cannot be built (no SDK / no libraries).