Add ability to reference 3rd-party crates

[alexreg]

It would be nice to have the ability to reference 3rd-party (e.g. crates.io) crates, for the sake of things like mdbook test, which currently fail when doing something like extern crate foo;.

[dhardy]

There appears to be a -L option to help here, but it leaves a lot to be desired. E.g.:

git clone ../rand rand
cd rand
cargo build
cd ..
mdbook test -L rand/target/debug/deps

fails with:

error[E0464]: multiple matching crates for `rand`
 --> /tmp/mdbook-4MUEU6/overview.md:8:1
  |
2 | extern crate rand;
  | ^^^^^^^^^^^^^^^^^^
  |
  = note: candidates:
          crate `rand`: /home/dhardy/projects/rand/book/rand/target/debug/deps/librand-eab6e1d50c8bd424.rlib
          crate `rand`: /home/dhardy/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/lib/librand-710e56bbaacb064e.rlib
          crate `rand`: /home/dhardy/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/lib/librand-3f50c2bb97d1d7f5.rlib

Whoops, even with a fresh build I still have three versions of rand to choose from!

---

Perhaps the book.toml should contain a dependencies section (or dev-dependencies) like Cargo.toml does?

[alexreg]

@dhardy Yeah, I like the suggestion about book.toml (shouldn't we name it MdBook.toml or something for consistency?)

[dhardy]

I'm making a suggestion in passing, nothing more.

[alexreg]

I know, but it's worth pursuing probably.

[dhardy]

Too right, and it makes it impossible to test my book properly: rust-random/book#1

Apparently another copy of rand is already provided by rustup — but it's not the version I want to test against.

[Michael-F-Bryan]

I've been thinking about rewriting mdbook test for a while now but haven't really had the time or known if the demand is there. At the moment we just shell out to rustdoc and effectively run rustdoc --test path/to/chapter.md for each chapter in the book, passing the -L argument straight through. It's clunky because we're directly calling rustdoc when cargo would normally set up all the dependency stuff for you.

If someone wants to champion this feature, mdbook already has pretty decent plugin support and lets you provide your own program for consuming a book and doing something with it. As an example of a backend which processes a book instead of rendering it, mdbook-linkcheck will validate all links in a book. So It's possible to create a backend which will:

1. Create an empty crate under the output directory
2. Dump the contents of each chapter into individual files in this crate
3. Add the necessary dependencies to Cargo.toml
4. Use rust-skeptic to generate the corresponding test code

Starting off as a plugin would let us iterate quickly outside the mdbook repository, possibly merging it into mdbook as a built-in renderer if that makes sense. I'd be happy to help out with reviewing and mentoring if needed 🙂

[GuillaumeGomez]

Just a tiny note: currently when I need to test code examples from the book part, I use doc-comment. With the add of cfg(doctest), it only runs on test so it can be a dev-dependency and has the advantage to not force you to rebuild everytime (which is a down side of rust-skeptic).