Run a Bazel workspace with Putnami
@putnami/bazel turns each package of a Bazel workspace into a Putnami
project and runs its tests and build through Bazel. Putnami selects what a
change affects and gives the verdict; Bazel keeps its own cache and remote
execution, so Putnami caches nothing for these tasks.
Adopt it
@putnami/bazel is not published yet: until its first release, putnami init --from bazel stops at the extension install, after it has written the
workspace files, and a workspace loads the extension from a source checkout.
At the root of the workspace, where MODULE.bazel, WORKSPACE or
WORKSPACE.bazel lies:
putnami init --from bazelinit writes a workspace that declares @putnami/bazel, installs it, and
runs putnami projects sync. Bazel must be on PATH, or the CI's export must
be at the root as bazel-graph.json
(bazel query 'deps(//...)' --output=streamed_jsonproto > bazel-graph.json).
A package is a directory whose BUILD.bazel or BUILD file declares a rule
the export lists. Without the export, the extension does not parse BUILD
files: a package is a directory whose putnami.json the sync wrote from
bazel query. Every other directory with a BUILD file, and the root
package, is a bare member: a project named by its directory, with no
extension, that runs no task. Directories under bazel-* links, hidden
directories, node_modules, the directories .bazelignore names and those an
ignore_directories glob of REPO.bazel matches are never read: Bazel loads
no package there, so a BUILD file under them, such as a test fixture's, is
no project.
Add .putnami/, .gen/ and /bazel-* to the repository's .gitignore:
init writes one only when the repository has none.
What the sync writes
putnami projects sync runs the extension's sync task. It reads
bazel-graph.json at the root, or runs
bazel query //... --output=streamed_jsonproto when there is none, and writes
in each package's putnami.json:
| Member | Value |
|---|---|
extensions |
@putnami/bazel, beside any other extension the file names |
dependencies |
The project ID of each package one of its rules reads a label of, such as /pricing; a label of an external repository is no edge, and a dependency on a project with no BUILD file is kept |
options.@putnami/bazel.filePatterns |
The files at the root that every package reads, relative to the package: MODULE.bazel, MODULE.bazel.lock, WORKSPACE, WORKSPACE.bazel, .bazelrc and .bazelversion, those that exist, and the root BUILD file when the package reads a target of the root package. A change to one selects the package |
disable.jobs |
test when the export lists no test rule of the package that //<package>:all selects (a class that ends in _test, or a test_suite, not tagged manual), so a package without such a test runs no test task, where bazel test would exit 4; the sync owns this entry and removes it from a package that has a test rule |
It keeps every other member, and rewrites a file only when a member it owns
changes, with two-space indentation and sorted keys. A package that left the
export loses the extension and its Bazel edges. Without the export and without
bazel, or with an export that lists no package, the sync warns with
bazel.sync_no_export and writes nothing.
Run the sync again after a BUILD change that alters the dependencies
between packages, and commit the result. putnami validate compares each
putnami.json with the export and fails with bazel.sync_stale when a sync
would change one. Keep it in the CI gate.
While bazel-graph.json lies at the root, the sync and putnami validate
read it and never run bazel query, so a stale export hides a new edge. Do
not commit it: write it in the CI job that runs the sync and the gate.
How Putnami judges the edges
The probe reports each package's edges as the Bazel graph's (build-graph):
those of the export, and each dependency of its putnami.json on a package or
another directory with a BUILD file, which is what the sync writes. Bazel
builds with them, so the declared-edge check counts them as real and warns no
workspace.declared_edge for them. Visibility does not judge them: Bazel's own
visibility attribute, not Putnami's scopes, says which package may depend on
which.
What each task runs
Each task first compares bazel --version with .bazelversion, then runs one
command at the workspace root, with no shell. //<package>:all names the
rules of the package, not those of the packages under it.
| Task | Command |
|---|---|
test |
bazel test --instrumentation_filter=^// --build_event_json_file=<output>/build-events.json //<package>:all |
build |
bazel build --instrumentation_filter=^// //<package>:all |
Every command passes the same --instrumentation_filter. Bazel discards its
analysis cache when a command's build options differ from the previous
command's, and a command that collects coverage with no filter derives one
from its target pattern, ^//<package>[/:], so each package would get its
own. ^// instruments every source of the main repository, and no external
repository. It overrides a filter that .bazelrc sets.
Bazel declares no lint convention, so a Bazel package has no lint task.
After the test command, whatever its outcome, the task copies into its
command output the test.xml and coverage.dat of each test run the
build-event file lists, from the file the event names or else from
bazel-testlogs/<package>/<target>/, and reads them into the test and
coverage summary. A source file that several test runs cover counts each
line once, covered when any run covered it. A log that a removed target left in bazel-testlogs is no
run of this one, and is not read. A failed case, a command that exits
non-zero, or a run with no JUnit report fails the task; a test rule without
coverage support fails nothing. A coverage.dat that is no LCOV tracefile,
such as the raw LLVM profile a C++ test can leave, is skipped with a warning
in the task's output. The copy of a coverage.dat keeps the records of the
package's own sources: a package it depends on is a project of its own, with
its own coverage.
Coverage is opt-in
bazel test collects no coverage, and bazel coverage can fail where
bazel test passes, as on a C++ test whose coverage output holds a dangling
link. To collect coverage for every package, add to .bazelrc:
build --collect_code_coverageA build line applies to bazel build and bazel test alike. A test line
alone gives the two commands different options, so Bazel discards its
analysis cache each time a run switches between a build and a test.
To collect it for one package, override its test command in its
putnami.json, with the same filter. Its test options then differ from every
other command's, so Bazel analyzes again before and after it:
{
"options": {
"@putnami/bazel": {
"tasks": {
"test": {
"steps": [["bazel", "coverage", "--instrumentation_filter=^//", "--build_event_json_file={output}/build-events.json", "//{component}:all"]]
}
}
}
}
}Bazel keeps its cache
Every task sets cache.enabled to false: Putnami stores no entry and
replays none, and each task result records delegatedTo: bazel. The task
reads Bazel's outputs and never removes one, so a test Bazel has cached
returns as fast as Bazel does.
Impact selection is Putnami's: putnami test --impacted runs Bazel on the
packages whose files changed and on the packages that depend on them, on the
edges the sync wrote. Each command runs a graph step before its task: the
graph step of a package depends on the graph step of each package it
depends on and runs nothing, and the task depends on its own package's graph
step alone. So a change to a package never runs Bazel on the packages it
depends on.
The version check
| Case | Result |
|---|---|
bazel --version prints the version .bazelversion states |
The task runs |
| It prints another one | The task fails with stacks.toolchain_mismatch; set toolchain.check to warn in the package's options to run anyway |
bazel is not on PATH |
The task fails with stacks.toolchain_missing |
The root holds no .bazelversion |
The warning stacks.toolchain_unpinned |
.bazelversion names a Bazelisk alias, such as latest or rolling |
The warning stacks.toolchain_unpinned, and the task runs |
The extension never installs Bazel; Bazelisk on PATH as bazel reads
.bazelversion itself.