From b1c930857f13eba026c1f50614c206b88dcbadab Mon Sep 17 00:00:00 2001 From: Martin Kuntz Jacobsen Date: Wed, 4 Nov 2026 20:43:49 +0100 Subject: [PATCH] docs: add a Bazel concepts page for dx users (closes #6184) Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_011u9TXHDZrfmzFQ2WT8QAKK --- BUILD.bazel | 1 + README.md | 1 + docs/BUILD.bazel | 1 + docs/README.md | 1 + docs/adopting-existing-bazel.md | 10 +-- docs/bazel-for-dx-users.md | 104 ++++++++++++++++++++++++++++++++ docs/tutorial.md | 1 + tools/docs/site/user/book.bzl | 1 + 8 files changed, 112 insertions(+), 8 deletions(-) create mode 100644 docs/bazel-for-dx-users.md diff --git a/BUILD.bazel b/BUILD.bazel index a75834e574..ef7935c820 100644 --- a/BUILD.bazel +++ b/BUILD.bazel @@ -351,6 +351,7 @@ real_source_target( "//docs:README.md", "//docs:adopting-existing-bazel.md", "//docs:adopting-without-bazel.md", + "//docs:bazel-for-dx-users.md", "//docs:cli/commands/README.md", "//docs:github-ci.md", "//docs:support-matrix.md", diff --git a/README.md b/README.md index 9a963350c6..184a4fb1aa 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,7 @@ and C toolchains. Only the root module's tags count. [patches/README.md](patches/README.md). Next: [tutorial](docs/tutorial.md), [docs index](docs/README.md), +[Bazel for dx users](docs/bazel-for-dx-users.md), [adopting rules_dx in an existing Bazel repo](docs/adopting-existing-bazel.md), [adopting rules_dx without Bazel experience](docs/adopting-without-bazel.md), [command reference](docs/cli/commands/README.md), diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel index c5142d8108..5ff8f192c4 100644 --- a/docs/BUILD.bazel +++ b/docs/BUILD.bazel @@ -34,6 +34,7 @@ real_source_target( "README.md", "adopting-existing-bazel.md", "adopting-without-bazel.md", + "bazel-for-dx-users.md", "cli/commands/README.md", "cli/commands/audit-update.md", "cli/commands/build-test-coverage.md", diff --git a/docs/README.md b/docs/README.md index 808810720e..72dcbf52b7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,6 +4,7 @@ Start here to use `dx`. `dx` runs through Bazel. Install Bazel via Bazelisk (see `.bazelversion`), then follow the command and CI guides below. - [Tutorial](tutorial.md): from an empty directory to a passing `dx test`. +- [Bazel for dx users](bazel-for-dx-users.md): sandbox, runfiles, caching, logs, visibility. - [Adopting rules_dx in an existing Bazel repo](adopting-existing-bazel.md): move from upstream rules one package at a time. - [Adopting rules_dx without Bazel experience](adopting-without-bazel.md): use `dx` in a Cargo, Python or JavaScript repo. diff --git a/docs/adopting-existing-bazel.md b/docs/adopting-existing-bazel.md index 322151ca2d..3ba15510da 100644 --- a/docs/adopting-existing-bazel.md +++ b/docs/adopting-existing-bazel.md @@ -102,14 +102,8 @@ are in the [Rule names](cli/commands/README.md#rule-names) table of ## Generated target names -A dx macro adds targets next to yours. They show up in `bazel query`, error -messages, and `--test_filter`. Do not reuse these names in the same package. - -- Every dx wrapper: `_upstream`. Private. -- `typescript_project`: `_typecheck` (private), `_typecheck_test` - (public), and `tsconfig_.json` (generated file). -- TypeScript tests: `_ts`. Private. -- Kotlin with `kotlinc_opts`: `_kotlinc_opts`. Private. +A dx macro adds targets next to yours. See +[Generated targets dx adds](bazel-for-dx-users.md#generated-targets-dx-adds). ## Roll back diff --git a/docs/bazel-for-dx-users.md b/docs/bazel-for-dx-users.md new file mode 100644 index 0000000000..f5e2315a6b --- /dev/null +++ b/docs/bazel-for-dx-users.md @@ -0,0 +1,104 @@ +# Bazel for dx users + +The Bazel terms and behaviours you meet in your first hour with `dx`. Each +section says what you will see and what to do. + +## Workspace, module, package, target, label + +- **Module**: the repository root, marked by `MODULE.bazel`. +- **Package**: a directory that contains a `BUILD.bazel` file. +- **Target**: a named thing in a package, such as a library or a test. +- **Label**: the full name of a target: `//cli/worktree:worktree_test`. + `//` is the module root, the part before `:` is the package, the part after + is the target name. Inside a package, `:name` is enough. +- `//cli/worktree/...` means every target in that package and below. + `//...` means every target in the repo. Prefer a narrow pattern, since + `//...` builds and tests everything. + +## BUILD files are generated + +Run `dx generate --apply` after you add, move, or delete source files or +change imports. It writes the `BUILD.bazel` files. See +[generate](cli/commands/generate.md). + +- Safe to hand-edit: attributes dx does not own, such as `data`, `env`, + `tags`, `size`, and `visibility`. Keep them next to the target; generate + keeps them. +- Do not hand-edit: source lists and dependency lists that generate writes. + The next `dx generate --apply` overwrites your change. + +## Visibility + +Targets are private to their package unless `visibility` says otherwise. +The error looks like `target '//a:lib' is not visible from target '//b:app'`. +Fix it on the target being used: + +```starlark +visibility = ["//b:__pkg__"], # one package +visibility = ["//b:__subpackages__"], # a package and everything below +visibility = ["//visibility:public"], # everyone +``` + +## Tests run in a sandbox + +A test sees only what it declares, in a directory of its own. + +- Files: list them in `data`. They appear under the test's runfiles + directory. Read them through the runfiles library or a path relative to the + test's working directory. +- `../fixtures/x.json` fails because the sandbox does not contain your + source tree. Put `x.json` in `data` (or in a target listed in `data`) and + open it by its path inside the runfiles. +- Environment variables are not passed through. Set fixed ones with `env` + on the target, or pass one for a single run with + `--test_env=NAME` (value from your shell) or `--test_env=NAME=value`. +- There is no network by default. A test that needs it must say so, for + example with the `requires-network` tag. + +## Test caching + +`(cached) PASSED` means the inputs of the test did not change since the last +pass, so Bazel did not run it again. This is correct and not a stale result. + +To force a rerun, use `--nocache_test_results`, or `--runs_per_test=1`. To +rerun after changing only an env var, pass it with `--test_env`. Changing a +file listed in `data` reruns the test by itself. + +## dx run and bazel run + +`dx run` and `bazel run` start the program from its runfiles directory, not +from your current directory. Relative paths you pass in the program resolve +there. To find where you started, read `BUILD_WORKING_DIRECTORY`: + +```sh +cd "$BUILD_WORKING_DIRECTORY" +``` + +## Outputs and logs + +- Build outputs: `bazel-bin//`. +- Test logs: `bazel-testlogs///test.log`. Failures print the + path at the end of the run. +- The `bazel-*` entries in the repo root are symlinks. Add them to + `.gitignore`; do not edit them. + +## The Bazel server and disk use + +Bazel keeps one background server per repo. A second Bazel command in the +same repo waits with `Another command is running`; wait for it or stop the +first. The server holds memory between commands. It exits after idle time, or +stop it with `bazel shutdown`. + +Build outputs and caches grow over time. `dx clean` frees disk; see +[check, fix, clean](cli/commands/check-fix-clean.md). + +## Generated targets dx adds + +A dx macro adds targets next to yours. They show up in `bazel query`, error +messages, and `--test_filter`. Do not reuse these names in the same package. + +- Every dx wrapper: `_upstream`. Private. +- `typescript_project`: `_typecheck` (private), `_typecheck_test` + (public), and `tsconfig_.json` (generated file). +- TypeScript tests: `_ts`. Private. +- Kotlin with `kotlinc_opts`: `_kotlinc_opts`. Private. diff --git a/docs/tutorial.md b/docs/tutorial.md index 4841044ccf..3808b27671 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -153,6 +153,7 @@ Run the same checks on every pull request. See [GitHub CI](github-ci.md). ## Next +- [Bazel for dx users](bazel-for-dx-users.md) - [Command reference](cli/commands/README.md) - [Adopting rules_dx in an existing Bazel repo](adopting-existing-bazel.md) - [Examples](../examples/README.md) diff --git a/tools/docs/site/user/book.bzl b/tools/docs/site/user/book.bzl index e13aa57e55..36f2c7f956 100644 --- a/tools/docs/site/user/book.bzl +++ b/tools/docs/site/user/book.bzl @@ -31,6 +31,7 @@ USER_BOOK = [ "//docs:adopting-without-bazel.md", ), mdbook_page("Tutorial", "docs/tutorial.md", "//docs:tutorial.md"), + mdbook_page("Bazel For dx Users", "docs/bazel-for-dx-users.md", "//docs:bazel-for-dx-users.md"), mdbook_page("Proxy And CA Certificates", "docs/proxy-and-ca.md", "//docs:proxy-and-ca.md"), mdbook_page("Use A Remote Cache", "docs/remote-cache.md", "//docs:remote-cache.md"), mdbook_page("Use JetBrains IDEs And Other Editors", "docs/editors.md", "//docs:editors.md"),