Build tools are the command-line machinery that develops, builds, tests, documents, and deploys the Tom framework and the applications made with it. This area is the DevOps line of the framework — one of its seven building blocks — and it runs more or less parallel to the application architecture: it is how Tom is worked on and shipped, rather than part of any single running app.

Everything in this area shares one foundation and one principle: all Tom CLI tools are built on tom_build_base. Shared command-line infrastructure is never reimplemented per tool; it is added to the base, published, and consumed. That keeps argument parsing, help, exit-code conventions, configuration, and console output uniform across every tool a developer touches.

The two pillars

The build tools centre on two modules of the basics component: the shared CLI framework tom_build_base and the build orchestrator tom_build_kit (the buildkit command) built on top of it.

tom_build_base — the foundation

tom_build_base is the declarative CLI framework every Tom tool stands on. A tool author declares what their tool does — a ToolDefinition of commands and options — and the framework supplies how it runs: argument parsing, help and shell completion, the standard navigation flags, console output, and the two-tier YAML configuration model. It also owns workspace traversal — detecting each folder's natures (Dart project, git repo, buildkit folder…), filtering by project/module selectors, and ordering by dependency build order — which is why every tool agrees on what the workspace is. New shared capability lands here first, is published, and is then consumed; it is never duplicated downstream.

tom_build_kit — the orchestrator

tom_build_kit is the package behind the buildkit command: the pipeline-based orchestrator for the whole Tom workspace, and the workhorse a developer drives day to day. It is the main build tool for Tom, and the intention is to make it usable for all kinds of projects, not just the framework itself.

From a single invocation buildkit runs named build pipelines (sequences of steps defined in buildkit_master.yaml) and invokes individual build commands with :command syntax — :versioner, :compiler, :runner, :cleanup, :dependencies, :publisher, :pubget/:pubupdate — across a selection of projects in dependency order. It also drives git across every repository in the workspace with one command (:gitstatus, :gitcommit, :gitsync, branch/tag management and more), with a safe inner-/outer-first traversal order for nested repositories. A second, smaller binary — findproject — resolves a project by name, ID or folder and prints its path, so a shell wrapper can cd to it.

Like every Tom tool, buildkit is a thin command catalogue over tom_build_base: it declares what the commands are (buildkitTool) and how each one runs (its CommandExecutors), and hands both to a ToolRunner from the base, which decides where they run (traversal) and when (pipeline order). It depends on the hosted tom_build_base from pub.dev — never a path override.

How it fits the rest of Tom

The build tools are the operations and development surface that surrounds the framework. Alongside them sit the VS Code extension (for authoring) and a cloud provisioning layer (for operations) — together they are the parallel tooling lines in the framework overview. buildkit builds and publishes the very components the other six areas are made of. None of this ships inside a running Tom application, but all of it is what makes the rest of the framework buildable, testable, and shippable in a uniform way.

> Maturity note. tom_build_base and tom_build_kit have real, documented code > and are in daily use across the workspace. The wider DevOps tool set is not yet > published — and which parts of it will be is still open — so it is intentionally > left out of this area until that is settled.