bazel: migrate external mdbook plugins to Bazel#3202
Conversation
mgeisler
changed the title
mdbook plugins to Bazelmdbook plugins to Bazel
mgeisler
force-pushed
the
bazel-all-mdbook-plugins
branch
3 times, most recently
from
9b22ef6 to
7247cc3
Compare
mgeisler
force-pushed
the
bazel-all-mdbook-plugins
branch
from
7247cc3 to
03b642a
Compare
mgeisler
changed the title
mdbook plugins to Bazelmdbook plugins to Bazel
|
Blocked on #3212. |
Configure mdbook-i18n-helpers, mdbook-linkcheck2, mdbook-pandoc, and mdbook-svgbob as Bazel external plugins using `rules_rust`. Update `xtask/src/main.rs` to build all preprocessor tools via Bazel, programmatically resolve their paths, copy them to `~/.cargo/bin`. This is a drop-in replacement for the old Cargo based approach. It will go away as we move the `mdbook build` call itself to Bazel, but it's useful in its own since it establishes that we can build the `mdbook` plugins with Bazel.
mgeisler
force-pushed
the
bazel-all-mdbook-plugins
branch
from
03b642a to
207db0d
Compare
| "2025-09-01/rust-std-nightly-x86_64-unknown-linux-gnu.tar.xz": "b3c2d890d9405285e015ab4ceb78087e3ec55c64b0b3030d79102dfe5e622e09", | ||
| "2025-09-01/rustc-nightly-x86_64-unknown-linux-gnu.tar.xz": "7f5486ae6ece8a734149e5fce6dc8f1bcdcb36b5c5cb53a819569109b445c700", | ||
| }, | ||
| version = "nightly/2025-09-01", |
There was a problem hiding this comment.
That was a few nights ago...
There was a problem hiding this comment.
Yeah, I know 😄 It's what we have hard-coded in main.rs. We should of course update it once in a while.
| crate.from_specs( | ||
| name = "mdbook_plugins", | ||
| generate_binaries = True, | ||
| host_tools = "@rust_host_tools_nightly", |
There was a problem hiding this comment.
Why do we need to build these with the nightly toolchain? (Assuming that that is what this is saying.)
There was a problem hiding this comment.
Yeah, I was asking myself (and Gemini) the same thing! What is happening here is that we want Bazel to run the equivalen to of cargo install.
It turns out that this isn't exposed in a stable way: there is a -Z bindeps flag (reference), but this requires a nightly compiler.
This is what rules_rust uses internally when we specify that we want the binary artifacts.
| artifact = "bin", | ||
| package = "mdbook-pandoc", | ||
| repositories = ["mdbook_plugins"], | ||
| version = "0.11.0", |
There was a problem hiding this comment.
Can we configure Dependabot to update these dependencies too?
There was a problem hiding this comment.
Actually... I don't think it is supported. There is Dependabot support for Bazel modules, but the version number here is from crates.io and Bazel doesn't really know anything about it.
So I think we're in the same boat as before where this was hard-coded in main.rs.
| use_repo(crate, "mdbook_plugins") | ||
|
|
||
| # mdbook-svgbob depends transitively on sauron-core, which has a | ||
| # "=0.3.30" dependency on futures. This conflicts with other plugins. |
There was a problem hiding this comment.
Does Bazel not allow multiple versions of a library crate in the tree? That seems like a big difference from cargo that could relate in other issues in future.
There was a problem hiding this comment.
Yeah, it is different. I've been playing with this for a few weeks now and what I've learnt is that
-
We had the same problem with
cargo install, we just didn't know. When youcargo install foo, a small workspace is created on the fly andfoois compiled in that. Our differentcargo installcalls created different workspaces and could thus depend on whatever incompatible crate versions they like. -
With the declarations here, we create a bigger workspace called
mdbook_pluginsand compile mostmdbookplugins in this workspace. We thus save a little time since transitive dependencies are only compiled once. -
We are creating multiple Bazel "repositories" with
rules_rust: heremdbook_pluginsandsvgbob_plugin. We also have a repository calledcrateswhich is populated with the dependencies from our actual Cargo workspace viacrate.from_cargo( name = "crates", cargo_lockfile = "//:Cargo.lock", manifests = ["//:Cargo.toml"], ) use_repo(crate, "crates")
This uses our
Cargo.lockfile and I believe this means that the same crate can be available in multiple different versions. I'm not 100% sure, though.
I hope this helps clarify things a little?
| ("mdbook-linkcheck2", "0.12.0"), | ||
| ]; | ||
| // Tools not yet migrated to be installed with Bazel. | ||
| let tools = [("mdbook", "0.5.3"), ("i18n-report", "0.2.0")]; |
There was a problem hiding this comment.
Why can't these be moved to Bazel at the same time?
There was a problem hiding this comment.
Actually, they could... I was just starting with the mdbook plugins to round off that part of the build.
I'll migrate everything eventually — and remove cargo xtask install-tools since everything will be installed/compiled on the fly with Bazel.
3 participants
Configure mdbook-i18n-helpers, mdbook-linkcheck2, mdbook-pandoc, and mdbook-svgbob as Bazel external plugins using
rules_rust.Update
xtask/src/main.rsto build all preprocessor tools via Bazel, programmatically resolve their paths, copy them to~/.cargo/bin.This is a drop-in replacement for the old Cargo based approach. It will go away as we move the
mdbook buildcall itself to Bazel, but it's useful in its own since it establishes that we can build themdbookplugins with Bazel.