Getting Started

Getting Started

Requirements

• Dart SDK ≥ 3.9 / Flutter ≥ 3.3

Installation

Install the CLI globally from pub.dev:

dart pub global activate spm

Or add SPM as a dev dependency in a Flutter project and run it locally:

flutter pub add dev:spm
dart run spm:spm analyze --output results.jsonl /path/to/flutter/project

To work on SPM itself, from the repo root:

dart pub get

A first end-to-end run

With a global activation, the three core commands form a pipeline. A typical session:

# 1. Static analysis: one JSONL record per State subclass
spm analyze --output results.jsonl /path/to/flutter/project

# 2a. Inject instrumentation and run in one step (recommended; always --profile)
spm run --jsonl results.jsonl --flutter run

#     …or do the two steps separately:
# 2b. Inject the SpmState base class into target State classes
spm inject --jsonl results.jsonl /path/to/flutter/project

# 3. Restore the original source when you're done
spm inject --jsonl results.jsonl --mode remove /path/to/flutter/project

Two commands stand outside the main pipeline:

# Extract rebuild scopes into standalone, compilable widgets
spm isolate --output-dir ./isolated_widgets /path/to/flutter/project

# Statically check that a mutation is a clean structural variant of a base file
spm validate --base base.dart --mutation mutation.dart

Where to next

• Per-command references: analyze · inject · run · isolate · validate
• Output Formats for what the JSONL actually contains.
• Architecture for how the code is organized.