microsoft/openvmm

Public

2edf894c3b8d71dbbe99482fa5c2690433302883

Find a branch or tag

HTTPS

Guide/mdbook-openvmm-shim/README.md

28lines · modecode

unknown

1	`# mdbook-openvmm-shim`
2
3	`This is a small standalone Rust binary which implements a mdbook preprocessor`
4	"shim", used to give OpenVMM additional control over how `mdbook` finds and
5	`interacts with external preprocessors.`
6
7	`Notably: it allows us to work around the following outstanding mdbook issue:`
8	`Preprocessor cannot add folders/files directly to book directory`
9	`[#1222](https://github.com/rust-lang/mdBook/issues/1222). Instead, this shim`
10	will dynamically invoke each preprocessor's `install` subcommand on-demand,
11	`avoiding the need to check-in the somewhat large third-party css/js/html blobs`
12	`that these plugins depend on.`
13
14	In addition, this shim has the benefit of keeping the `mdbook` end-user
15	`experience as vanilla as possible, without requiring a project-specific wrapper`
16	script (e.g: `cargo xtask mdbook`).
17
18	`## Why is this its own workspace?`
19
20	Since `book.toml` uses `cargo run` to invoke this script, having this crate live
21	`in the main OpenVMM Rust workspace would result in delays of ~0.5s on each`
22	command invocation (due to `cargo run` needing to scan the whole workspace on
23	each invocation). Having it in its own workspace results in a `cargo run`
24	overhead of roughly `0.01` seconds (on average), which is far more tolerable.
25
26	In the future, when `cargo-script` finally lands (see
27	`<https://github.com/rust-lang/cargo/issues/12207>), this shim should simply be a`
28	standalone file in the `Guide/` directory.
29