make:fast-cli
Scaffold a POSIX shell wrapper (bin/dowel) and AOT-compiled dowel binary for a startup of about 0.2 s, against 0.4 to 2.7 s for dart run, which resolves and runs its build hooks on every cold start.
On this page
Basic Usage#
dart run dowel make:fast-cli
Writes bin/dowel (POSIX shell wrapper, executable), .dowel/cli-bundle/ (compiled binary + runtime libraries) and .dowel/build.stamp (staleness marker), and patches .gitignore to ignore that cache. Caches the build result so subsequent invocations are cached (about 0.2 s on a hit).
Synopsis#
make:fast-cli {--force : Overwrite bin/dowel even when it already exists}
| Option | Description |
|---|---|
--force |
Rewrite bin/dowel and recompile the binary, even if a cached version exists. |
What It Does#
-
Validates the project structure. Checks for
pubspec.yamlandbin/dispatcher.dart; errors with actionable guidance if either is missing. -
Scaffolds the wrapper script. Writes a POSIX
shscript atbin/dowelthat resolves symlinks via a portablefollow_links()subshell and derives the project root at runtime. -
Computes a staleness key. Captures the SHA256 hash of
pubspec.lockand the Dart SDK version string, storing both in.dowel/build.stampfor later comparison. -
Compiles the binary. Runs
dart build cli -t bin/dispatcher.dart -o .dowel/cli-bundle, producing an AOT-native binary at.dowel/cli-bundle/bundle/bin/dispatcher. -
Patches
.gitignore. Appends the cache entries.dowel/cli-bundle*,.dowel/build.stamp*and.dowel/.dowel.lock/when they are missing, so the compiled cache is never tracked. The globs also cover the scratch paths of a build:bin/dowelcompiles into.dowel/cli-bundle.build.<pid>, parks the old bundle at.dowel/cli-bundle.old.<pid>and stages the stamp at.dowel/build.stamp.tmp. The rest of.dowel/is source of truth and stays trackable:plugins.jsonis the registrylib/app/_plugins.g.dartis generated from,installed/holds the install records andmcp.jsonis the tool filter. A bare.dowel/line, which earlier versions wrote, is replaced by the three entries, because it also ignoredplugins.json. Idempotent.
Output#
bin/dowel(executable, ~50 LoC): shell wrapper that checks staleness, auto-recompiles if needed, then execs into the binary..dowel/cli-bundle/bundle/bin/dispatcher: AOT-compiled native executable..dowel/cli-bundle/bundle/lib/*.dylib(on macOS;.soon Linux): runtime libraries bundled with the binary..dowel/build.stamp: one-line file with<pubspec_lock_sha256>:<dart_sdk_version>. Lets the wrapper detect when to rebuild.
Re-running#
Run make:fast-cli again without --force: the wrapper detects bin/dowel already exists and skips the override.
Run with --force: rewrites the wrapper and recompiles.
The wrapper script itself is the source of truth for staleness detection. When the user runs ./bin/dowel <cmd> and the Dart SDK updates or pubspec.lock changes, the wrapper notices (inside the lock-acquire section) and transparently rebuilds. No manual re-run needed.
Staleness Detection#
The wrapper's needs_build() function triggers a rebuild when any of these conditions hold:
-
Binary missing. The compiled executable at
.dowel/cli-bundle/bundle/bin/dispatcherdoes not exist. -
Stamp file missing or empty. The
.dowel/build.stampfile is absent or has zero size. -
Stamp file content mismatches. The stored compile key (format:
<sha256-of-pubspec.lock>:<dart-sdk-version>) differs from the current key, meaning either the lock or the SDK changed. -
pubspec.yamlmodified since last build. The mtime ofpubspec.yamlis newer than the stamp file's mtime, detected via the-nt(newer than) operator. -
lib/app/_plugins.g.dartmodified since last build. The mtime oflib/app/_plugins.g.dartis newer than the stamp file's mtime. It invalidates the cache whenplugin:installorplugins:refreshregenerates the file. -
lib/app/commands/_index.g.dartmodified since last build. The mtime of the commands index is newer than the stamp file's mtime. It catches a hand-edited index.commands:refreshandmake:commandalso delete.dowel/build.stampafter writing the index, so the next./bin/dowelcall rebuilds under condition 2 even in the same second; the compiled bundle stays until the rebuild replaces it.
Any match triggers a recompile inside the lock-acquire section. The re-check inside the lock prevents redundant builds when multiple invocations race.
The build lock#
.dowel/.dowel.lock/ is a directory created with an atomic mkdir and holds the owner's pid. It is held only while building: the wrapper removes it and clears its trap before execing the binary, because exec replaces the shell and a trap would never run, which used to leave a long-lived mcp:serve holding the lock for its whole life. A dead owner's lock is reclaimed through a kill -0 probe; a live owner is waited on for at most DOWEL_LOCK_TIMEOUT seconds (default 600), after which the call fails and names the pid. A build compiles into .dowel/cli-bundle.build.<pid> and is swapped in by rename, so a binary another process is running is never overwritten; leftovers from a killed build are removed by the next build.
Performance#
Cache hit (wrapper runs existing binary)#
time ./bin/dowel status
# real 0m0.170s
# user 0m0.010s
# sys 0m0.010s
About 0.2 s round-trip (0.17 to 0.35 s over six runs of status on the example app) on a modern machine (no dart run, no "Running build hooks..." overhead).
Cache miss (first run or staleness detected)#
time dart run dowel make:fast-cli
# Building dowel CLI (one-time, ~5s)...
# real 0m8.234s
~8 seconds (depends on machine and dependency size). The wrapper prints "Building dowel CLI..." so users know a compile is in progress and not to interrupt.
Comparison with dart run#
time dart run dowel status
# real 0m0.650s
# (warm; the first run after a dependency change took 1.7 s for `status` and 2.7 s for `list`)
time ./bin/dowel status
# real 0m0.170s
# (cached; about 4x faster than a warm `dart run`, about 10x faster than a first run)
Caveats#
POSIX only (macOS and Linux). Windows users use dart run dowel <cmd>; there is no .cmd variant.
No cross-compilation. The compiled binary targets the local machine architecture and OS. Distributing the binary to a different architecture or OS requires re-running make:fast-cli on that target.
Related Documentation#
- make:command: scaffold a single
DowelCommandsubclass. - make:plugin: scaffold a full plugin package.
- install: initialise a dowel consumer project structure.