microsoft/openvmm
Publicmirrored fromhttps://github.com/microsoft/openvmmAvailable
Guide/mdbook-openvmm-shim/README.md
28lines · modecode
| 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 | |