ToolCacheLocator class abstract final

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.

Analyzer summaries are the first (and today the only) artefact stored here, but the directory is deliberately generic so other Tom build tools can share it for their own reusable outputs. Consumers should write their artefacts into a named sub-directory of the resolved root (the analyzer summary cache uses analyzer-cache/) so different artefact kinds never collide.

Resolution order

The first branch that applies wins:

1. TOM_TOOL_CACHE environment variable. When set to a non-empty value it is used verbatim (normalised to an absolute path). This is the explicit override — point it at a fast disk, a shared CI cache, or a RAM-backed directory.
2. The workspace-root .tom directory. Walking up from resolve's startDirectory, the first ancestor that is a workspace root — a directory containing one of the workspaceRootMarkers (tom_workspace.yaml or .tom_metadata/tom_master.yaml) — wins, and its .tom sub-directory is the cache root. This deliberately identifies the workspace root rather than the nearest .tom, so nested project-level .tom directories never fragment the cache: every tool in the tree shares the one <workspace>/.tom/analyzer-cache/.
3. Workspace-local fallback. When no workspace-root ancestor is found the cache root is <startDirectory>/.tom. The resolver never falls back to a machine-global location such as ~/.config/dart — the cache is always inside the workspace tree.

resolve only reads the filesystem (existence checks for branch 2); it never creates a directory. Callers create the resolved directory lazily the first time they write to it.

Properties

hashCode → int

The hash code for this object.

no setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Methods

resolve({String? startDirectory, Map<String, String>? environment}) → String

Resolves the tool-cache root directory.

Constants

envVariable → const String

Environment variable that overrides the tool-cache location (branch 1).

workspaceCacheDirName → const String

Name of the cache-root sub-directory inside a workspace root (branch 2) and of the workspace-local fallback directory (branch 3).

workspaceRootMarkers → const List<String>

Marker files whose presence in a directory identifies it as a workspace root (branch 2). Any one of them is sufficient. Both are committed at the Tom workspace root, so the search reliably resolves to the workspace's .tom cache and skips nested project-level .tom directories.