Add cross-platform compatible launcher for rust-analyzer (bazelbuild#4118)

For vscode users who commit `.code-workspace` or `settings.json`, this
change introduces a cross-platform compatible entrypoint for
rust-analyzer infrastructure. Note that this doesn't mean the binaries
are magically platform agnostic. It just means the two files mentioned
will be compatible on both Unix and Windows platforms if the vscode
config files are source controlled.

Author: UebelAndre

docs/src/rust_analyzer.md

@@ -23,6 +23,55 @@ Existing user keys in `.vscode/settings.json` are preserved on re-runs.
 Pass `--dry-run` to preview the JSON without writing it; `--replace` to
 overwrite all managed keys (destroys user keys).
 
+#### Committable settings
+
+Managed `rust-analyzer.*` paths use VSCode's `${workspaceFolder}`
+variable and point at small launcher shims under
+`<workspace>/.rules_rust_analyzer/`, e.g.:
+
+```jsonc
+"rust-analyzer.server.path":
+    "${workspaceFolder}/.rules_rust_analyzer/rust_analyzer.exe"
+```
+
+The shims are byte-identical copies of a tiny dispatcher binary;
+they read a sibling `launcher_paths.json` (also in the launcher dir)
+and `exec` the absolute toolchain binary in the Bazel cache. **The
+settings file is safe to commit** — it contains no per-developer or
+per-platform paths. Each developer just runs `setup` once on their
+machine to populate the launcher dir.
+
+Add the launcher dir to `.gitignore`:
+
+```
+.rules_rust_analyzer/
+```
+
+Re-run `setup` after a toolchain bump (rustup update, `MODULE.bazel`
+change, `bazel clean --expunge`) to refresh the launcher dir's
+`launcher_paths.json`. The committed settings file is untouched.
+
+The `.exe` extension on every platform is deliberate: it's the only
+extension Node's `child_process.spawn` handles on Windows without
+`shell: true`, and POSIX kernels ignore file extensions for `execve`
+(a Linux ELF or macOS Mach-O binary named `foo.exe` runs fine).
+That's what lets the same committed path work across Linux, macOS,
+and Windows.
+
+#### `.code-workspace` files
+
+Projects opened via a `.code-workspace` file need the rust-analyzer
+keys inside the workspace file's `settings` object — VSCode answers
+rust-analyzer's window-scoped config requests from there, **not** from
+any folder's `.vscode/settings.json`. `setup vscode` handles this
+automatically: if exactly one `*.code-workspace` exists at the
+workspace root, it targets that file and nests under `settings`. Pass
+`--output <file>.code-workspace` to disambiguate when multiple exist,
+or `--settings-key <key>` to nest under a custom key. With
+`--settings-key`, `--replace` overwrites only that nested object —
+sibling top-level keys (`folders`, `tasks`, `extensions`) survive
+intact.
+
 ### Neovim
 
 ```
@@ -58,18 +107,23 @@ same keys via plugin-specific config files.
 
 ## Flags
 
-Re-runnable at any time. All flags work on any subcommand.
+Re-runnable at any time. Global flags work on any subcommand.
 
 | Flag | Effect |
 |---|---|
+| `--workspace <path>` | Workspace root. Defaults to `$BUILD_WORKSPACE_DIRECTORY` (set by `bazel run`). |
 | `--skip-proc-macro-server` | Don't manage the proc-macro key. |
 | `--skip-rustfmt` | Don't manage the formatter key (use host rustfmt). |
-| `--output-user-root <abs-path>` | `--output_user_root` for flycheck's dedicated Bazel server. Required on Windows for non-trivial workspaces (MAX_PATH). |
-| `--cache-dir <abs-path>` | Where discover writes its merged-JSON cache. |
 | `--per-package-workspaces` | Opt in to per-package workspace splitting (see below). |
 
-VSCode subcommand also accepts `--dry-run` (preview JSON without writing) and
-`--replace` (overwrite all managed keys, destroying user keys).
+The `vscode` subcommand adds:
+
+| Flag | Effect |
+|---|---|
+| `--output <path>` | Settings file to write. Defaults to the unique `*.code-workspace` at the workspace root, falling back to `.vscode/settings.json`. |
+| `--settings-key <key>` | Nest the managed `rust-analyzer.*` keys under this top-level key. Auto-defaults to `settings` for `.code-workspace` outputs. |
+| `--dry-run` | Preview the JSON without writing. |
+| `--replace` | Replace the managed keys instead of merging. With `--settings-key`, only that nested object is replaced — sibling keys (`folders`, `tasks`, `extensions`) survive. |
 
 ## What you get
 
@@ -97,9 +151,6 @@ rm -rf <workspace>/<editor-dir>/.rules_rust_analyzer/cache
 Where `<editor-dir>` is `.vscode` for VSCode, `.helix` for Helix, or
 empty for Neovim / `print` (cache sits at `<workspace>/.rules_rust_analyzer/cache`).
 
-If you passed `--cache-dir` at setup time, the cache is wherever you
-pointed it instead.
-
 The cache survives `bazel clean` by design (it lives in the workspace,
 not the Bazel output base) so a full Bazel rebuild won't invalidate
 stale entries — that's what the manual `rm -rf` is for.
@@ -111,11 +162,12 @@ wrapper appends one line per internal failure.
 
 ### After `bazel clean --expunge` or toolchain changes
 
-Re-run `setup`. The launcher scripts reference the rust-analyzer /
-rustfmt / proc-macro-srv binaries by absolute path baked at install
+Re-run `setup`. The launcher shims dispatch through
+`<launcher_dir>/launcher_paths.json`, which records absolute paths to
+the rust-analyzer / rustfmt / proc-macro-srv binaries at install
 time. Those binaries live in Bazel's output_base; `--expunge` clears
 that, and toolchain changes move them to new paths. Re-running setup
-resolves the new paths and refreshes the launchers.
+re-resolves and rewrites the JSON.
 
 ## Workspace splitting
 

tools/rust_analyzer/BUILD.bazel

@@ -62,12 +62,6 @@ rust_binary(
     ],
 )
 
-# On-save flycheck wrapper. The assembled rust-project.json wires its
-# `flycheck` runnable to `bazel run` this target with `{label}` and
-# `{saved_file}` after rust-analyzer substitutes them. It runs
-# `bazel build` with rustc diagnostics enabled, harvests the resulting
-# `.rustc-output` files via BEP, and streams rustc JSON to stdout for
-# rust-analyzer to render as inline squiggles.
 rust_binary(
     name = "flycheck",
     srcs = ["bin/flycheck.rs"],
@@ -89,11 +83,6 @@ rust_test(
     crate = ":flycheck",
 )
 
-# Opt-mode re-exposures of the two source binaries setup copies into
-# the user's launcher dir. discover/flycheck run on every save /
-# discovery and pay the fastbuild→opt gap repeatedly; forcing `-c opt`
-# here means setup always installs the fastest available build,
-# independent of the parent build's `--compilation_mode`.
 opt_executable(
     name = "discover_bazel_rust_project_opt",
     src = ":discover_bazel_rust_project",
@@ -106,35 +95,40 @@ opt_executable(
     visibility = ["//visibility:private"],
 )
 
-# One-command bootstrap that wires VSCode, Neovim, Helix, or any other
-# rust-analyzer-capable editor at the Bazel rust-analyzer toolchain. Copies
-# the discover/flycheck binaries to editor-appropriate locations and
-# (where the editor's config format is mergeable JSON) writes/merges the
-# relevant settings. Re-runnable; preserves user keys.
-#
-# Invoke with a subcommand per IDE: `vscode`, `neovim`, `helix`, `print`.
+rust_binary(
+    name = "launcher",
+    srcs = ["bin/launcher.rs"],
+    edition = "2021",
+    visibility = ["//visibility:public"],
+    deps = [
+        "//tools/rust_analyzer/3rdparty/crates:serde_json",
+    ],
+)
+
+rust_test(
+    name = "launcher_test",
+    crate = ":launcher",
+)
+
+opt_executable(
+    name = "launcher_opt",
+    src = ":launcher",
+    visibility = ["//visibility:private"],
+)
+
 rust_binary(
     name = "setup",
     srcs = ["bin/setup.rs"],
-    # setup resolves these via runfiles at install time:
-    #   * The three toolchain binaries get baked as absolute
-    #     `output_base/external/...` paths into the editor's
-    #     rust-analyzer settings (they survive `bazel clean`; only
-    #     `--expunge` invalidates them).
-    #   * The two source binaries (discover, flycheck) get copied into
-    #     the launcher dir so the editor's commands stay valid across
-    #     `bazel clean`. The binaries self-locate their config from
-    #     `current_exe()` — no launcher scripts. The toolchain-info
-    #     JSON used to be copied here too; it's now embedded into
-    #     `gen_rust_project_lib` at compile time via `include_str!`.
     data = [
         ":discover_bazel_rust_project_opt",
         ":flycheck_opt",
+        ":launcher_opt",
         "//rust/toolchain:current_rust_analyzer_toolchain",
         "//rust/toolchain:current_rustfmt_toolchain",
     ],
     edition = "2021",
     rustc_env = {
+        "LAUNCHER_RLOCATIONPATH": "$(rlocationpath :launcher_opt)",
         "RUSTFMT_RLOCATIONPATH": "$(RUSTFMT_RLOCATIONPATH)",
         "RUST_ANALYZER_PROC_MACRO_SRV_RLOCATIONPATH": "$(RUST_ANALYZER_PROC_MACRO_SRV_RLOCATIONPATH)",
         "RUST_ANALYZER_RLOCATIONPATH": "$(RUST_ANALYZER_RLOCATIONPATH)",
@@ -145,10 +139,6 @@ rust_binary(
     ],
     visibility = ["//visibility:public"],
     deps = [
-        # Source of truth for the on-disk filenames setup copies into
-        # the launcher dir (`{DISCOVER,FLYCHECK}_BINARY_FILENAME`).
-        # Sharing them keeps the install side and the consumer side
-        # (rust_project.rs's flycheck-runnable path emitter) in sync.
         ":gen_rust_project_lib",
         "//rust/runfiles",
         "//tools/rust_analyzer/3rdparty/crates:anyhow",
@@ -165,15 +155,6 @@ rust_test(
     crate = ":setup",
 )
 
-# Pairs with the `compile_data` entry below: the env_file emits
-# `RUST_ANALYZER_TOOLCHAIN_JSON=<src.path>` through a `map_each`
-# callback so Bazel's path mapping rewrites the path before the action
-# runs. `process_wrapper` reads the env file and sets the env var, then
-# lib.rs's `include_str!(env!("RUST_ANALYZER_TOOLCHAIN_JSON"))` opens
-# the same path-mapped JSON sibling. Going through `rustc_env =`
-# directly would bake the analysis-time path that path mapping never
-# rewrites — the compile-time read then fails to find the file under
-# `--experimental_output_paths=strip`.
 env_file(
     name = "toolchain_info_env",
     src = "//rust/private:rust_analyzer_detect_sysroot",
@@ -186,8 +167,6 @@ rust_library(
         ["**/*.rs"],
         exclude = ["bin"],
     ),
-    # The JSON file itself must be available to rustc — `:toolchain_info_env`
-    # only emits the env-var wrapper pointing at this path.
     compile_data = [
         "//rust/private:rust_analyzer_detect_sysroot",
     ],

tools/rust_analyzer/bin/discover_rust_project.rs

@@ -83,17 +83,10 @@ where
     writeln!(writer, "")
 }
 
-/// Self-locate the editor-specific install dir from `current_exe()`
-/// and publish the two env vars the library reads for per-install
-/// state (`RULES_RUST_RA_LAUNCHER_DIR`, `RULES_RUST_RA_CACHE_DIR`).
-/// `setup` copies this binary into `<launcher_dir>/discover_bazel_rust_project`;
-/// the parent directory of the binary IS the launcher dir.
-///
-/// Already-set env vars are left alone so users / tests can override.
-/// The toolchain-info JSON is NOT plumbed here — its content is baked
-/// into the binary at compile time via `env!()` (see
-/// `gen_rust_project_lib::TOOLCHAIN_INFO_RAW`), so there's nothing to
-/// locate at runtime.
+/// Publish per-install state via env vars the library reads.
+/// `setup` copies this binary into the launcher dir, so
+/// `dirname(current_exe())` IS that dir. Pre-set values win so users
+/// and tests can override.
 fn self_locate_config() -> anyhow::Result<()> {
     let launcher_dir = gen_rust_project_lib::install_dir()?;
     for (name, path) in [

tools/rust_analyzer/bin/flycheck.rs

@@ -75,17 +75,11 @@ fn run() -> Result<u8> {
     let bep_path = temp_dir.join(format!("flycheck_bep_{}.json", std::process::id()));
     let _bep_cleanup = scopeguard(bep_path.clone());
 
-    // flycheck spawns `bazel build` internally. That inner build runs
-    // against a DEDICATED `--output_user_root` so its
-    // `--error_format=json` / `--rustc_output_diagnostics=true` flags
+    // Dedicated `--output_user_root` for the inner `bazel build` so
+    // its `--error_format=json` / `--rustc_output_diagnostics=true`
     // don't thrash the user's primary Bazel server's analysis cache.
-    //
-    // The flycheck binary lives at `<install_dir>/flycheck` (setup
-    // copies it there); the dedicated output_user_root sits alongside
-    // as `<install_dir>/output_user_root`. `install_dir()` resolves
-    // `current_exe`'s parent — see its docstring for why current_exe
-    // over argv[0]. CLI flag override is honored for paths that don't
-    // fit the default (Windows MAX_PATH).
+    // CLI override exists for Windows MAX_PATH cases where the
+    // sibling default is too long.
     let output_user_root = match args.output_user_root.clone() {
         Some(p) => p,
         None => gen_rust_project_lib::install_dir()?.join("output_user_root"),

tools/rust_analyzer/bin/launcher.rs

@@ -0,0 +1,122 @@
+//! Exec-redirect shim that bridges a stable workspace-relative path
+//! in the committed settings file (`${workspaceFolder}/.rules_rust_analyzer/<name>.exe`)
+//! to the user-specific Bazel-cache path of the real toolchain binary.
+//! `setup vscode` copies this binary into the launcher dir once per
+//! logical name and writes the sidecar JSON it dispatches against.
+//!
+//! `.exe` everywhere is required by Node's `child_process.spawn` on
+//! Windows (no `shell: true`, no PATHEXT lookup) and harmless on POSIX
+//! (kernel ignores file extensions for `execve`). See
+//! [`gen_rust_project_lib::DISCOVER_BINARY_FILENAME`] for the same
+//! decision on the discover/flycheck side.
+
+use std::{
+    collections::HashMap,
+    env, fs,
+    path::{Path, PathBuf},
+    process,
+};
+
+const PATHS_FILENAME: &str = "launcher_paths.json";
+
+fn main() {
+    let exe = env::current_exe().unwrap_or_else(|e| die(format!("locating current_exe: {e}")));
+    let logical = logical_name(&exe)
+        .unwrap_or_else(|| die(format!("current_exe has no file stem: {}", exe.display())));
+    let paths_path = exe
+        .parent()
+        .unwrap_or_else(|| die(format!("current_exe has no parent: {}", exe.display())))
+        .join(PATHS_FILENAME);
+    let target = resolve_target(&paths_path, &logical)
+        .unwrap_or_else(|e| die(format!("resolving {logical}: {e}")));
+    exec_replace(&target);
+}
+
+fn logical_name(exe: &Path) -> Option<String> {
+    exe.file_stem().map(|s| s.to_string_lossy().into_owned())
+}
+
+/// Borrows strings out of `raw` to skip per-entry heap allocations on
+/// the LSP-startup hot path.
+fn resolve_target(paths_path: &Path, logical: &str) -> Result<PathBuf, String> {
+    let raw = fs::read_to_string(paths_path)
+        .map_err(|e| format!("reading {}: {e}", paths_path.display()))?;
+    let map: HashMap<&str, &str> =
+        serde_json::from_str(&raw).map_err(|e| format!("parsing {}: {e}", paths_path.display()))?;
+    map.get(logical)
+        .map(PathBuf::from)
+        .ok_or_else(|| format!("no entry for `{logical}` in {}", paths_path.display()))
+}
+
+#[cfg(unix)]
+fn exec_replace(target: &Path) -> ! {
+    use std::os::unix::process::CommandExt;
+    let err = process::Command::new(target)
+        .args(env::args_os().skip(1))
+        .exec();
+    die(format!("exec {}: {err}", target.display()))
+}
+
+#[cfg(not(unix))]
+fn exec_replace(target: &Path) -> ! {
+    let status = process::Command::new(target)
+        .args(env::args_os().skip(1))
+        .status()
+        .unwrap_or_else(|e| die(format!("spawn {}: {e}", target.display())));
+    process::exit(status.code().unwrap_or(1));
+}
+
+fn die(msg: String) -> ! {
+    eprintln!("rules_rust launcher: {msg}");
+    process::exit(127);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn logical_name_strips_exe_suffix() {
+        assert_eq!(
+            logical_name(Path::new("/x/rust_analyzer.exe")).as_deref(),
+            Some("rust_analyzer")
+        );
+    }
+
+    #[test]
+    fn logical_name_passes_through_when_no_suffix() {
+        assert_eq!(
+            logical_name(Path::new("/x/rustfmt")).as_deref(),
+            Some("rustfmt")
+        );
+    }
+
+    #[test]
+    fn resolve_target_returns_mapped_path() {
+        let tmp = std::env::temp_dir().join(format!("launcher_resolve_ok_{}", process::id()));
+        let _ = fs::remove_dir_all(&tmp);
+        fs::create_dir_all(&tmp).unwrap();
+        let paths = tmp.join(PATHS_FILENAME);
+        fs::write(
+            &paths,
+            r#"{"rust_analyzer": "/abs/rust-analyzer", "rustfmt": "/abs/rustfmt"}"#,
+        )
+        .unwrap();
+        let out = resolve_target(&paths, "rust_analyzer").unwrap();
+        assert_eq!(out, PathBuf::from("/abs/rust-analyzer"));
+        let _ = fs::remove_dir_all(&tmp);
+    }
+
+    #[test]
+    fn resolve_target_errors_on_missing_key_with_path_context() {
+        let tmp = std::env::temp_dir().join(format!("launcher_resolve_miss_{}", process::id()));
+        let _ = fs::remove_dir_all(&tmp);
+        fs::create_dir_all(&tmp).unwrap();
+        let paths = tmp.join(PATHS_FILENAME);
+        fs::write(&paths, r#"{"rust_analyzer": "/abs/rust-analyzer"}"#).unwrap();
+        let err = resolve_target(&paths, "rustfmt").unwrap_err();
+        assert!(err.contains("rustfmt"), "{err}");
+        assert!(err.contains(PATHS_FILENAME), "{err}");
+        let _ = fs::remove_dir_all(&tmp);
+    }
+}