Problem
manual/book.toml declares the [preprocessor.environment] preprocessor (the
mdbook-environment crate) to
interpolate {{DOCS_URL}} (and other env vars) into the manual's markdown.
mdbook-environment 0.0.4 (latest, built against mdbook ^0.4) cannot parse
mdbook 0.5's preprocessor input, so with mdbook 0.5.x the manual build fails:
INFO Book building has started
Unable to parse the input
ERROR The "environment" preprocessor exited unsuccessfully with exit status: 1
Because xtask's Manual::install_deps installs mdbook unpinned
(cargo install mdbook), a fresh machine now gets mdbook 0.5.x (latest 0.5.4)
and the manual cannot build. Downstream, the renderling.xyz site pipeline then
fails with a confusing manual/book canonicalize panic.
Workaround currently in place: the deploy machine is pinned to
mdbook 0.4.52 (cargo install mdbook --version 0.4.52 --force). The wgsl-rs
book (which uses no external preprocessors) builds fine on both 0.4 and 0.5.
Ask
- Bump to mdbook 0.5.x and replace the env-var interpolation with something
that works there. Ideas: vendor/patch mdbook-environment against 0.5 (or
upstream a fix), generate the docs URL into an {{#include}}d file at
build time from xtask (which already receives --docs-url), or
preprocess the sources before invoking mdbook.
- Pin the mdbook version in
Manual::install_deps either way, so a fresh
machine cannot silently drift onto an incompatible version.
Related
deps.rs has_binary probes for binaries by shelling out to hash, a shell
builtin — a fragile check.
- When the manual build fails,
xtask logs could not build the manual but
exits 0, so callers believe the build succeeded and fail later with an
unrelated-looking panic. The build failure should exit non-zero.
Found while deploying the wgsl-rs operator's manual through the renderling.xyz
pipeline (wgsl-rs#29).
Problem
manual/book.tomldeclares the[preprocessor.environment]preprocessor (themdbook-environmentcrate) tointerpolate
{{DOCS_URL}}(and other env vars) into the manual's markdown.mdbook-environment0.0.4 (latest, built against mdbook ^0.4) cannot parsemdbook 0.5's preprocessor input, so with mdbook 0.5.x the manual build fails:
Because
xtask'sManual::install_depsinstallsmdbookunpinned(
cargo install mdbook), a fresh machine now gets mdbook 0.5.x (latest 0.5.4)and the manual cannot build. Downstream, the renderling.xyz site pipeline then
fails with a confusing
manual/bookcanonicalize panic.Workaround currently in place: the deploy machine is pinned to
mdbook 0.4.52(cargo install mdbook --version 0.4.52 --force). The wgsl-rsbook (which uses no external preprocessors) builds fine on both 0.4 and 0.5.
Ask
that works there. Ideas: vendor/patch
mdbook-environmentagainst 0.5 (orupstream a fix), generate the docs URL into an
{{#include}}d file atbuild time from
xtask(which already receives--docs-url), orpreprocess the sources before invoking mdbook.
Manual::install_depseither way, so a freshmachine cannot silently drift onto an incompatible version.
Related
deps.rs has_binaryprobes for binaries by shelling out tohash, a shellbuiltin — a fragile check.
xtasklogscould not build the manualbutexits 0, so callers believe the build succeeded and fail later with an
unrelated-looking panic. The build failure should exit non-zero.
Found while deploying the wgsl-rs operator's manual through the renderling.xyz
pipeline (wgsl-rs#29).