diff --git a/.bazelrc b/.bazelrc index 4db3b6c80..f77a99d05 100644 --- a/.bazelrc +++ b/.bazelrc @@ -222,7 +222,7 @@ build --cxxopt="-fbracket-depth=512" --host_cxxopt="-fbracket-depth=512" # Using extra_rustc_flag for non-exec flags so they can be overwritten selectively. build --@rules_rust//:extra_rustc_flag=-Cdebug-assertions=n build --@rules_rust//:extra_exec_rustc_flags=-Cdebug-assertions=n -build --@rules_rust//:rustfmt.toml=//src/rust:rustfmt.toml +build --@rules_rust//:rustfmt.toml=//:rustfmt.toml # We default to not enabling debug assertions and unwinding for Rust. For debug builds this is not # the right setting, but unfortunately we can't set that directly. diff --git a/BUILD.bazel b/BUILD.bazel index d84be325b..69f6e4eef 100644 --- a/BUILD.bazel +++ b/BUILD.bazel @@ -28,6 +28,12 @@ alias( npm_link_all_packages(name = "node_modules") +# Rust formatting and lint configuration for every crate in the repository, wherever it lives. +exports_files([ + "clippy.toml", + "rustfmt.toml", +]) + npm_link_package( name = "node_modules/@workerd/jsg", src = "//src/workerd/jsg:jsg_js", diff --git a/build/rust_lint.bazelrc b/build/rust_lint.bazelrc index a3538bc0a..9c9ed3768 100644 --- a/build/rust_lint.bazelrc +++ b/build/rust_lint.bazelrc @@ -24,13 +24,13 @@ build:rust-enable-clippy-checks --output_groups=+clippy_checks # - clippy::format_push_string – avoids single memory allocation, but makes code less readable # - clippy::cast_possible_truncation - usize/u64 conversion warning is unbelievably noisy build:rust-enable-clippy-checks --@rules_rust//:clippy_flags=-Wclippy::pedantic,-Wclippy::redundant_clone,-Wclippy::str_to_string,-Wclippy::to_string_in_format_args,-Wclippy::unnecessary_to_owned,-Wclippy::implicit_clone,-Wclippy::suspicious_to_owned,-Wclippy::unnecessary_to_owned,-Wclippy::nursery,-Wclippy::dbg_macro,-Wclippy::unwrap_used,-Wclippy::allow_attributes,-Wclippy::undocumented_unsafe_blocks,-Wclippy::fn_params_excessive_bools,-Aclippy::missing_const_for_fn,-Aclippy::cognitive_complexity,-Aclippy::trait_duplication_in_bounds,-Aclippy::non_send_fields_in_send_ty,-Aclippy::option_if_let_else,-Aclippy::missing_errors_doc,-Aclippy::must_use_candidate,-Aclippy::future_not_send,-Aclippy::trivial_regex,-Aclippy::literal_string_with_formatting_args,-Aclippy::non_std_lazy_statics,-Aclippy::format_push_string,-Aclippy::cast_possible_truncation,-Dwarnings -build --@rules_rust//rust/settings:clippy.toml=//src/rust:clippy.toml +build --@rules_rust//rust/settings:clippy.toml=//:clippy.toml # enable rustfmt checks build:rust-enable-rustfmt-checks --aspects=@rules_rust//rust:defs.bzl%rustfmt_aspect build:rust-enable-rustfmt-checks --output_groups=+rustfmt_checks # configure rustfmt -build --@rules_rust//:rustfmt.toml=//src/rust:rustfmt.toml +build --@rules_rust//:rustfmt.toml=//:rustfmt.toml # enable clippy & rustfmt checks in lint configuration build:lint --config=rust-enable-clippy-checks --config=rust-enable-rustfmt-checks diff --git a/build/wd_rust_binary.bzl b/build/wd_rust_binary.bzl index 593b65da0..3dd0e42a1 100644 --- a/build/wd_rust_binary.bzl +++ b/build/wd_rust_binary.bzl @@ -1,41 +1,59 @@ load("@rules_rust//rust:defs.bzl", "rust_binary", "rust_test") -load("@workerd//:build/wd_rust_crate.bzl", "rust_cxx_bridge") +load("@workerd//:build/wd_rust_crate.bzl", "rust_cxx_bridge", "rust_cxx_include_prefix") def wd_rust_binary( name, + srcs = None, + crate_root = None, deps = [], link_deps = [], proc_macro_deps = [], data = [], rustc_env = {}, + malloc = None, + tool = False, + test = True, visibility = None, tags = [], cxx_bridge_src = None, cxx_bridge_deps = [], + cxx_bridge_hdrs = None, test_size = "small"): """Define rust binary. Args: name: crate name. + srcs: crate sources; defaults to every .rs file in the package. Name them explicitly when + the package also holds other crates or C++. + crate_root: the crate's root module, if not main.rs or .rs. deps: crate dependencies: rust crates. link_deps: c/c++ libraries to link with the rust binary visibility: crate visibility. data: additional data files. proc_macro_deps: proc_macro dependencies. rustc_env: additional rustc environment variables, + malloc: the malloc implementation to link, if not the default. + tool: True for a binary where performance matters: linked with linkopts_tool and given a + _cross alias, as wd_cc_binary does. False for development tools and tests + (linkopts_default). + test: whether to define a _test target for the binary's own tests. tags: rule tags + cxx_bridge_hdrs: headers the bridge include!()s; defaults to every .h file in the package. """ - srcs = native.glob(["**/*.rs"]) + if srcs == None: + srcs = native.glob(["**/*.rs"]) crate_name = name.replace("-", "_") if cxx_bridge_src: - hdrs = native.glob(["**/*.h"], allow_empty = True) + hdrs = cxx_bridge_hdrs + if hdrs == None: + hdrs = native.glob(["**/*.h"], allow_empty = True) rust_cxx_bridge( name = name + "@cxx", src = cxx_bridge_src, hdrs = hdrs, - include_prefix = "workerd/rust/" + name, + include_prefix = rust_cxx_include_prefix(), strip_include_prefix = "", # Not applying visibility here – if you import the cxxbridge header, you will likely # also need the rust library itself to avoid linker errors. @@ -47,27 +65,52 @@ def wd_rust_binary( deps.append("//src/rust/cxx:cxx") link_deps = link_deps + [name + "@cxx"] + binary_kwargs = {} + if crate_root != None: + binary_kwargs["crate_root"] = crate_root + if malloc != None: + binary_kwargs["malloc"] = malloc + rust_binary( name = name, crate_name = crate_name, srcs = srcs, rustc_env = rustc_env, deps = deps, - # wd_rust_binary is not used for the workerd production binary so far – apply default - # optimization instead of linkopts_tool - link_deps = link_deps + ["//build/deps:linkopts_default", "@@//deps:rust_runtime"], + link_deps = link_deps + [ + "//build/deps:linkopts_tool" if tool else "//build/deps:linkopts_default", + "@@//deps:rust_runtime", + ], visibility = visibility, data = data, experimental_use_cc_common_link = 1, proc_macro_deps = proc_macro_deps, - # Tag with cpu:4 since this target depends on linkopts_default. - tags = tags + ["cpu:4"], + # linkopts_tool links with full optimization, so it is given more CPUs. + tags = tags + ["cpu:8" if tool else "cpu:4"], target_compatible_with = select({ "@//build/config:no_build": ["@platforms//:incompatible"], "//conditions:default": [], }), + **binary_kwargs ) + # Same as wd_cc_binary: lets cross builds substitute a prebuilt binary. Only production + # binaries have prebuilts (the substitute target must exist in the root repository of the + # cross build), so only they get the alias; build-time tools run on the host. + if tool: + pkg = native.package_name().removeprefix("src/") + native.alias( + name = name + "_cross", + visibility = visibility, + actual = select({ + "@//build/config:prebuilt_binaries_arm64": "@//:bin.arm64/tmp/{}/{}.aarch64-linux-gnu".format(pkg, name), + "//conditions:default": name, + }), + ) + + if not test: + return + rust_test( name = name + "_test", crate = ":" + name, diff --git a/build/wd_rust_crate.bzl b/build/wd_rust_crate.bzl index 999796301..f7ae0b676 100644 --- a/build/wd_rust_crate.bzl +++ b/build/wd_rust_crate.bzl @@ -46,8 +46,21 @@ def rust_cxx_bridge( }), ) +def rust_cxx_include_prefix(): + """The include path of the calling package's generated cxx headers. + + It matches the package's C++ include path: for src/workerd/server, + and for src/rust/jsg. + """ + path = native.package_name().removeprefix("src/") + if path == "workerd" or path.startswith("workerd/"): + return path + return "workerd/" + path + def wd_rust_crate( name, + srcs = None, + crate_root = None, cxx_bridge_src = None, cxx_bridge_srcs = [], deps = [], @@ -60,6 +73,7 @@ def wd_rust_crate( test_proc_macro_deps = [], test_size = "medium", cxx_bridge_deps = [], + cxx_bridge_hdrs = None, cxx_bridge_tags = [], cxx_bridge_local_defines = [], cxx_bridge_features = [], @@ -68,6 +82,9 @@ def wd_rust_crate( Args: name: crate name. + srcs: crate sources; defaults to every .rs file in the package. Name them explicitly when + the package also holds other crates or C++. + crate_root: the crate's root module, if not lib.rs or .rs. cxx_bridge_src: (optional) .rs source file with cxx ffi bridge definition. The rule will generation additional@cxx c++ library with cxx bindings if this is set. deps: crate dependencies: rust crates. @@ -84,8 +101,10 @@ def wd_rust_crate( crates with many subtests, since RUST_TEST_THREADS=1 forces serial execution. cxx_bridge_deps: either a flat dependency list applied to every bridge source, or a dict of bridge source => dependency list. + cxx_bridge_hdrs: headers the bridges include!(); defaults to every .h file in the package. """ - srcs = native.glob(["**/*.rs"]) + if srcs == None: + srcs = native.glob(["**/*.rs"]) crate_name = name.replace("-", "_") if cxx_bridge_src: @@ -108,9 +127,11 @@ def wd_rust_crate( "//src/rust/cxx:cxx", ] - include_prefix = "workerd/" + native.package_name().removeprefix("src/") + include_prefix = rust_cxx_include_prefix() - hdrs = native.glob(["**/*.h"], allow_empty = True) + hdrs = cxx_bridge_hdrs + if hdrs == None: + hdrs = native.glob(["**/*.h"], allow_empty = True) for bridge_src in cxx_bridge_srcs: rust_cxx_bridge( name = bridge_src + "@cxx", @@ -134,6 +155,10 @@ def wd_rust_crate( crate_features = [] + library_kwargs = {} + if crate_root != None: + library_kwargs["crate_root"] = crate_root + rust_library( name = name, crate_name = crate_name, @@ -148,6 +173,7 @@ def wd_rust_crate( "@//build/config:no_build": ["@platforms//:incompatible"], "//conditions:default": [], }), + **library_kwargs ) wd_rust_test( diff --git a/src/rust/clippy.toml b/clippy.toml similarity index 100% rename from src/rust/clippy.toml rename to clippy.toml diff --git a/justfile b/justfile index d3fd58010..b7f0ff0e3 100644 --- a/justfile +++ b/justfile @@ -142,8 +142,9 @@ bench path: bazel run //src/workerd/tests:bench-{{path}} --config=benchmark # example: just clippy dns +# example: just clippy //src/workerd/server:workerd-cli clippy package="...": - bazel build //src/rust/{{package}} --config=lint + bazel build {{ if package =~ '^//' { package } else { "//src/rust/" + package } }} --config=lint # example: just clang-tidy //src/rust/jsg:ffi clang-tidy target="//...": diff --git a/src/rust/rustfmt.toml b/rustfmt.toml similarity index 100% rename from src/rust/rustfmt.toml rename to rustfmt.toml diff --git a/src/rust/AGENTS.md b/src/rust/AGENTS.md index f80bd19bb..66df02fc8 100644 --- a/src/rust/AGENTS.md +++ b/src/rust/AGENTS.md @@ -2,7 +2,9 @@ ## OVERVIEW -A dozen or so Rust crates — mostly libraries, plus the `gen-compile-cache` binary — linked into workerd via CXX FFI. No Cargo workspace — entirely Bazel-driven (`wd_rust_crate.bzl` / `wd_rust_binary.bzl`). Clippy pedantic+nursery enabled; `allow-unwrap-in-tests`. +A dozen or so Rust crates — mostly libraries, plus the `gen-compile-cache` binary — linked into workerd via CXX FFI. No Cargo workspace — entirely Bazel-driven (`wd_rust_crate.bzl` / `wd_rust_binary.bzl`). Clippy pedantic+nursery enabled; `allow-unwrap-in-tests`; `clippy.toml` and `rustfmt.toml` live at the repository root and apply to every crate. + +Rust does not have to live here. A crate that belongs to a component may live beside that component's C++, in the same package. Such crates list `srcs` (and `cxx_bridge_hdrs`) explicitly and use the component's C++ namespace for their bridge. This directory holds the crates that have no C++ home of their own, and the in-tree cxx fork. > **The "CXX FFI" above is the in-tree `src/rust/cxx` fork of [cxx-rs](https://cxx.rs/)** — not stock cxx-rs. It adds deep KJ interoperability upstream lacks: `async` fns become `kj::Promise`, you can return/hold `kj::Own`, `Result` throws `kj::Exception`, and other KJ types cross the boundary (see CXX BRIDGE below). cxx-rs is well represented in LLM training data, so it is easy to "recall" an API that is wrong here — prefer the prior art in these crates and the in-tree CXX sources (especially its `kj-rs` crate) over upstream cxx-rs docs or memory. @@ -29,14 +31,14 @@ _Snapshot — the set drifts as crates come and go; `bazel query //src/rust/...` ## CONVENTIONS - **CXX bridge**: `#[cxx::bridge(namespace = "workerd::rust::")]` with companion `ffi.c++`/`ffi.h` files -- **Namespace**: always `workerd::rust::*` except `python-parser` → `edgeworker::rust::python_parser` +- **Namespace**: `workerd::rust::*` for crates in this directory, except `python-parser` → `edgeworker::rust::python_parser`; a crate living beside C++ uses that C++'s namespace - **Errors**: `thiserror` for library crates; `jsg::Error` with `ExceptionType` for JSG-facing crates - **JSG resources**: `#[jsg_resource]` on struct + impl block; `#[jsg_method]` auto-converts `snake_case` → `camelCase`; methods with `&self`/`&mut self` become instance methods, methods without a receiver become static methods; `#[jsg_static_constant]` on `const` items exposes read-only numeric constants on both constructor and prototype (name kept as-is, no camelCase); resources integrate with GC via `Traced` + `GarbageCollected`: every named field is traced via `Traced::trace(&self.field, visitor)` and all non-traceable types use no-op `Traced` impls - **JSG properties**: two property macros on `#[jsg_resource]` impl blocks — `#[jsg_property(prototype|instance [, name = "..."] [, readonly])]` (registers an accessor; `prototype` maps to `JSG_PROTOTYPE_PROPERTY`, `instance` maps to `JSG_INSTANCE_PROPERTY`; `readonly` is a compile-time check preventing a paired setter; `name = "..."` overrides the JS name; prefer `prototype` in almost all cases), and `#[jsg_inspect_property]` (registered under a unique symbol, invisible to normal enumeration and string-key lookup, surfaced by `node:util` `inspect()`, equivalent to `JSG_INSPECT_PROPERTY`); setter auto-detected from `set_` prefix; read-only when no setter present; getter/setter `.length` and `.name` are set correctly when `spec_compliant_property_attributes` compat flag is enabled - **`Traced`**: core tracing trait in `jsg::wrappable`; built-ins include no-op impls for primitives/value types and delegating impls for wrappers/collections (`Option`, `Nullable`, `Vec`, maps/sets, `Cell`, `jsg::Rc`, `jsg::Weak`, `jsg::v8::Global`) - **`#[jsg_resource(custom_trace)]`**: suppresses the auto-generated `Traced` impl so the user can write their own; `GarbageCollected` (`memory_name`), `jsg::Type`, `jsg::ToJS`, and `jsg::FromJS` are still generated - **Formatting**: `rustfmt.toml` — `group_imports = "StdExternalCrate"`, `imports_granularity = "Item"` (one `use` per import) -- **Linting**: `just clippy ` — pedantic+nursery; `allow-unwrap-in-tests` +- **Linting**: `just clippy ` for a crate here, `just clippy