dev-build-run-ci

# dev_build run_ci: validate a package or a tree `package:dev_build` runs the standard validation steps of a Dart or Flutter package: `pub get`, format check, analyze, tests on every supported platform, and an optional web build. It works on a single package or recursively on every package found under a folder. Same code drives the `run_ci` executable and the `packageRunCi()` API. VM only (it spawns `dart`/`flutter` processes). ```dart // tool/run_ci.dart import 'package:dev_build/package.dart'; Future<void> main() async { await packageRunCi('.'); } ``` ```bash dart run dev_build:run_ci # same steps from the command line ``` ## Guidelines ### Setup * Add `dev_build` to `dev_dependencies`. Import `package:dev_build/package.dart` for `packageRunCi`, `PackageRunCiOptions`, `recursivePackagesRun`, `recursivePubPath`, `SinglePackageCiRunner`. * Put the script in `tool/run_ci.dart` (repository convention) and run it with `dart run tool/run_ci.dart`. * From the command line, all these ways are supported: * `dart run dev_build:run_ci [<path>] [<flags>]` in a package that depends on `dev_build`. * `dart run dev_build:run_ci@ [<path>] [<flags>]` anywhere, no dependency nor install: runs the latest stable `dev_build` from pub.dev (`dart run dev_build:run_ci@^1.1.10` for a constraint), resolved again on each run. * `dart install dev_build` once (Dart 3.10+, run it again to upgrade) installs a compiled `run_ci` in the `dart install` bin folder (`~/.local/state/Dart/install/bin` on Linux, must be on the PATH), then `run_ci [<path>] [<flags>]`. Best for repeated use. `dart installed` lists the installed tools, `dart uninstall dev_build` removes it. * Legacy: `dart pub global activate dev_build` once, then `run_ci` (with `~/.pub-cache/bin` on the PATH) or `dart pub global run dev_build:run_ci`. ### What a run does, in order * `dart pub get` (or `flutter pub get` when the package, or any package of its pub workspace, depends on `flutter`). `--offline` adds `--offline`. * Format check: `dart format --set-exit-if-changed <top level dirs that contain dart files>` (`lib test bin tool example ...`). Nested packages, hidden dirs, `build`, `deploy`, `node_modules`, `.dart_tool` are excluded. * Analyze: `dart analyze --fatal-warnings --fatal-infos .` for Dart, `flutter analyze --no-pub .` for Flutter. Infos fail the build: keep `analysis_options.yaml` clean. * Test: `flutter test --no-pub` for Flutter. For Dart, `dart test` is run once per platform: `vm` always, `chrome` when `build_web_compilers` is a dependency, `node` when `build_node_compilers` is a dependency and `node` is installed. Skipped entirely when there is no `test/` folder. * Build: `flutter build web --no-pub` when `web/index.html` and `lib/main.dart` exist; `dart pub global run webdev build` for a Dart package that depends on `build_web_compilers` + `build_runner` and has `web/index.html`. * A `dart_test.yaml` `platforms:` list restricts the platforms above, `compilers:` (`dart2js`, `dart2wasm`) adds `--compiler` for browser runs. ### Options (`PackageRunCiOptions` / flags) * Skip a step: `noPubGet`, `noFormat`, `noAnalyze`, `noTest`, `noBuild` (`--no-pub-get`, `--no-format`, `--no-analyze`, `--no-test`, `--no-build`). * Run only one step: `formatOnly`, `analyzeOnly`, `testOnly`, `buildOnly`, `pubGetOnly`, `pubUpgradeOnly`, `pubDowngradeOnly`, `fixOnly` (`--format`, `--analyze`, `--test`, `--build`, `--pub-get`, `--pub-upgrade`, `--pub-downgrade`, `--fix`). An "only" option turns every other step off; `analyzeOnly` still runs `pub get` first unless `noPubGet: true`. * Test platforms: `vmTestOnly` (`--vm-test`), `noVmTest`, `noBrowserTest`, `chromeJsTestOnly` (`--chrome-js-test`, dart2js only), `noNodeTest`, `noNpmInstall`. * `fixOnly` runs `dart format <dirs>` then `dart fix --apply` and stops. * `recursive: true` (`--recursive`, the CLI default; API default is `false`) finds every package below `path`, links followed, and runs them through a pool of `poolSize` (default 4 in the API, `-j`/`--concurrency` default 1 in the CLI). * `ignoreErrors` (`--ignore-errors`, `-i`): a failing package is reported and the run continues with the next one, instead of throwing. * `dryRun` (`--dry-run`) prints the shell lines instead of running them. `prjInfo` (`--prj-info`) prints the sdk constraint and flutter tag, `noRunCi` (`--no-run-ci`) stops after that, `printPath` (`--print-path`) only prints the package path. `verbose` (`-v`). * `filterDartProjectOptions: FilterDartProjectOptions(minSdk:, maxSdk:, ignoreSdkConstraints:)` (`--min-sdk '>=3.0.0'`, `--max-sdk`, `--ignore-sdk-constraints`) selects which packages are considered. By default a package whose `environment: sdk:` does not match the running `dart` is skipped. * `noOverride` (`--no-override`) ignores `tool/run_ci_override.dart` and `.local/.skip_run_ci`. ### Repository conventions the runner honours * `tool/run_ci_override.dart` in a package: run with `dart run` instead of the standard steps (use `noOverride`/`--no-override` from inside it or the run recurses). Use it for a package that needs custom steps. * `.local/.skip_run_ci` (empty file) skips the package in recursive runs. Create it with `run_ci config --skip-run-ci [<path>]`; git-ignore `.local`. * `dev_build_run_ci_config.yaml` (committed) filters its folder and sub folders in recursive runs: `include: [packages]` scans only these, `exclude: [example]` skips these, `exclude: [.]` skips the folder itself, paths relative to the file. Read in every visited folder, not above the path passed to `run_ci`. * A package whose name starts with `_` only gets `pub get`. * A pub workspace root gets `pub get` once for the whole workspace, then is skipped for format/analyze/test; members are run individually. * Everything under a hidden folder, `build`, `deploy` or `node_modules` is never visited. ### Custom actions over a tree * `recursivePubPath(['.'])` returns every package folder (sorted, links resolved). `dependencies: ['sembast']` keeps packages depending on it, with `direct:`/`dev:`/`override:` prefixes to narrow the kind, and `readConfig: true` also matches transitive dependencies through `.dart_tool/package_config.json`. * `recursivePackagesRun(['.'], action: (dir) async {...}, poolSize: 1)` runs a callback per package. Combine with `Shell(workingDirectory: dir)` from `package:dev_build/shell.dart`. * `SinglePackageCiRunner(PubIoPackage(path), options)` (`PubIoPackage` from `package:dev_build/menu/menu_run_ci.dart`) exposes the individual steps: `init()`, then `format()`, `analyze()`, `runTest(testOptions: [...])`, `fix()`. Use it to pass extra `dart test` arguments. * `runCiInitPubWorkspacesCache()` is called by `packageRunCi` so a workspace gets one `pub get`; call it yourself before looping with `singlePackageRunCi`-style code. ## Examples ### tool/run_ci.dart for a repository ```dart import 'package:dev_build/package.dart'; Future<void> main() async { // Every package under the repo root, one at a time. await packageRunCi('..', options: PackageRunCiOptions(recursive: true)); } ``` ### Analyze only, without touching the network ```dart import 'package:dev_build/package.dart'; Future<void> main() async { await packageRunCi( '.', options: PackageRunCiOptions( recursive: true, analyzeOnly: true, noPubGet: true, ), ); } ``` ### Check minimum dependency versions ```dart import 'package:dev_build/package.dart'; Future<void> main() async { // pub downgrade + analyze on every package, ignoring tool/run_ci_override.dart await packageRunCi( '.', options: PackageRunCiOptions( recursive: true, pubDowngradeOnly: true, analyzeOnly: true, noOverride: true, ), ); } ``` ### Fix formatting and lints recursively ```dart import 'package:dev_build/package.dart'; Future<void> main() async { await packageRunCi( '.', options: PackageRunCiOptions(recursive: true, fixOnly: true), ); } ``` ### tool/run_ci_override.dart with custom steps ```dart import 'package:dev_build/package.dart'; import 'package:dev_build/shell.dart'; Future<void> main() async { // noOverride is required, otherwise this file runs itself again. await packageRunCi( '.', options: PackageRunCiOptions(noOverride: true, noTest: true), ); await Shell().run('dart test --platform vm --exclude-tags slow'); } ``` ### Extra test arguments with SinglePackageCiRunner ```dart import 'package:dev_build/menu/menu_run_ci.dart' show PubIoPackage; import 'package:dev_build/package.dart'; Future<void> main() async { var package = PubIoPackage('.'); var runner = SinglePackageCiRunner(package, PackageRunCiOptions()); await runner.init(); await package.pubGet(); await runner.analyze(); await runner.runTest(testOptions: ['--reporter', 'expanded']); } ``` ### Run a shell command in every package that depends on a package ```dart import 'package:dev_build/package.dart'; import 'package:dev_build/shell.dart'; Future<void> main() async { await recursivePackagesRun( ['.'], dependencies: ['direct:sembast'], poolSize: 1, action: (dir) async { await Shell(workingDirectory: dir).run('dart pub upgrade sembast'); }, ); } ``` ### Command line ```bash dart run dev_build:run_ci@ # from pub.dev, no dependency dart install dev_build # once, then run `run_ci` run_ci --version # check which one is on PATH dart pub global activate dev_build # legacy install, then `run_ci` dart run dev_build:run_ci # this package and nested ones dart run dev_build:run_ci --no-test ../other # skip tests, other folder dart run dev_build:run_ci --analyze --no-pub-get dart run dev_build:run_ci --pub-downgrade --analyze --no-override --recursive dart run dev_build:run_ci --fix --recursive dart run dev_build:run_ci --vm-test --offline dart run dev_build:run_ci --prj-info --no-run-ci # list packages and sdk dart run dev_build:run_ci config --skip-run-ci packages/legacy dart run dev_build:run_ci menu # interactive console menu ``` ## Common mistakes * Expecting `packageRunCi('.')` to recurse: the API default is `recursive: false`; the executable defaults to `--recursive`. * Writing `tool/run_ci_override.dart` that calls `packageRunCi` without `noOverride: true`. * Relying on `--no-analyze` to hide lints: the standard analyze uses `--fatal-infos`, fix the code or the `analysis_options.yaml`. * Adding `build_web_compilers` to a package that has no browser tests: it turns on `dart test --platform chrome` for every run. * Using `packageRunCi` from a web or Flutter app: it needs `dart:io` and the `dart`/`flutter` executables on the PATH. * Installing `run_ci` with both `dart install` and `dart pub global activate`: the first bin folder on the PATH wins, check with `run_ci --version` after upgrading one of them. ## More See [references/cli-options.md](references/cli-options.md) for the complete flag list of the `run_ci` executable and the exact commands executed per package type.