https://github.com/enzymead/rustbook
https://github.com/enzymead/rustbook
autodiff rust
Last synced: about 1 year ago
JSON representation
- Host: GitHub
- URL: https://github.com/enzymead/rustbook
- Owner: EnzymeAD
- Created: 2023-12-18T03:20:25.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-18T04:28:37.000Z (about 1 year ago)
- Last Synced: 2025-04-18T09:04:08.547Z (about 1 year ago)
- Topics: autodiff, rust
- Language: Rust
- Homepage: https://enzyme.mit.edu/rust/
- Size: 1.25 MB
- Stars: 11
- Watchers: 4
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Enzyme-Rust Book
This book is build using [mdBook](https://rust-lang.github.io/mdBook/index.html)
It requires a working rustup installation.
Install mdBook with
```console
$ cargo install mdbook
```
Build and run this book afterwards locally with
```console
$ mdbook serve --open
```
## Running tests
This book contains many code fragments that are important to test.
### Rust-Enzyme toolchain
We assume that you have a rustup toolchain called `enzyme`. This would have been created in your rust build directory by running something like:
```console
$ rustup toolchain link enzyme $(pwd)/build/host/stage1
```
The above only needs to be run once. The `enzyme` toolchain will also need `rustdoc` support. Again, from the Rust build directory, you'll need to have run something like
```console
$ x build --stage 1 library tools/rustdoc
```
This will need to be re-run each time you `git pull`.
### Configuring an override
It's unlikely that you want `enzyme` as your default toolchain for all your rust activities. Instead, you probably use `cargo +enzyme build` when working with Rust-Enyzme. You can specify a [directory override](https://rust-lang.github.io/rustup/overrides.html#directory-overrides) by running the following (once) in the Enzyme-rustbook directory:
```console
$ rustup override set enzyme
```
### Testing with Cargo
Code samples worth testing are being migrated to the `samples` crate. You can run all samples with a simple
``` console
$ cargo test
```
or, using [cargo-nextest](https://nexte.st/),
``` console
$ cargo nextest run
```
### Testing with mdBook (deprecated)
Finally, you can run tests for all chapters using
```console
$ mdbook test
```
or a specific chapter using that chapter's name, such as
```console
$ mdbook test -c Usage
```
This testing mode is being phased out as we move testable code into the `samples` crate. When using this mode, you will need the following workaround:
#### mdBook and `lto=fat` (temporary workaround)
Rust's Enzyme support currently requires `lto=fat`, which is not part of the default profile for `rustdoc` (which is invoked by `mdbook test`). My temporary hack has been to patch `mdbook` by applying the following.
``` diff
diff --git i/src/book/mod.rs w/src/book/mod.rs
index c0ab8a5..409482f 100644
--- i/src/book/mod.rs
+++ w/src/book/mod.rs
@@ -319,7 +319,11 @@ impl MDBook {
tmpf.write_all(ch.content.as_bytes())?;
let mut cmd = Command::new("rustdoc");
- cmd.arg(&path).arg("--test").args(&library_args);
+ cmd.arg(&path)
+ .arg("--test")
+ .args(&library_args)
+ .arg("-C")
+ .arg("lto=fat");
if let Some(edition) = self.config.rust.edition {
match edition {
```
I'll find a better solution and make a pull request.