docs: a Bazel concepts page for dx users

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",

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),

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",

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.
 

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: `<name>_upstream`. Private.
-- `typescript_project`: `<name>_typecheck` (private), `<name>_typecheck_test`
-  (public), and `tsconfig_<name>.json` (generated file).
-- TypeScript tests: `<name>_ts`. Private.
-- Kotlin with `kotlinc_opts`: `<name>_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
 

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/<package>/<target>`.
+- Test logs: `bazel-testlogs/<package>/<test>/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: `<name>_upstream`. Private.
+- `typescript_project`: `<name>_typecheck` (private), `<name>_typecheck_test`
+  (public), and `tsconfig_<name>.json` (generated file).
+- TypeScript tests: `<name>_ts`. Private.
+- Kotlin with `kotlinc_opts`: `<name>_kotlinc_opts`. Private.

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)

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"),