search

cognitive-engineering-lab / rust-book

The Rust Programming Language: Experimental Edition
https://rust-book.cs.brown.edu
Other
504 stars 82 forks source link

Instructions on how build the project listed in README is incomplete #122

Closed atsuzaki closed 5 months ago

atsuzaki commented 10 months ago

The only step mentioned in README is to installing mdbook at the rust-lang/rust version as advised, but running mdbook build shows up missing aquascope and quiz commands (and ultimately failed for I'm not sure if related reasons?).

2023-08-24 10:23:08 [INFO] (mdbook::book): Book building has started
2023-08-24 10:23:08 [WARN] (mdbook::preprocess::cmd): The command wasn't found, is the "aquascope" preprocessor installed?
2023-08-24 10:23:08 [WARN] (mdbook::preprocess::cmd):   Command: mdbook-aquascope
2023-08-24 10:23:08 [WARN] (mdbook::preprocess::cmd): The command wasn't found, is the "quiz" preprocessor installed?
2023-08-24 10:23:08 [WARN] (mdbook::preprocess::cmd):   Command: mdbook-quiz
2023-08-24 10:23:08 [INFO] (mdbook::book): Running the html backend
2023-08-24 10:23:08 [ERROR] (mdbook::utils): Error: Rendering failed
2023-08-24 10:23:08 [ERROR] (mdbook::utils):    Caused By: Unable to copy across additional CSS and JS
2023-08-24 10:23:08 [ERROR] (mdbook::utils):    Caused By: Unable to copy /Users/atsuzaki/projects/rust-book/js-extensions/packages/consent-form/dist/index.css to /Users/atsuzaki/projects/rust-book/book/js-extensions/packages/consent-form/dist/index.css
2023-08-24 10:23:08 [ERROR] (mdbook::utils):    Caused By: No such file or directory (os error 2)

I tried to cargo install mdbook-aquascope and cargo install mdbook-quiz, then proceeded to run into trouble where the aquascope is built with a diff version, and subsequently dies.

2023-08-24 10:21:21 [INFO] (mdbook::book): Book building has started
Warning: The aquascope plugin was built against version 0.4.34 of mdbook, but we're being called from version 0.4.28
Command failed
2023-08-24 10:21:21 [ERROR] (mdbook::utils): Error: The "aquascope" preprocessor exited unsuccessfully with exit status: 1 status

I reckon the correct thing to do is to not use the crates.io ver, but directly from the aquascope repo?

But alas, would really appreciate if we could have clearer build instructions for this project. (I want to help fix your bugs, if only I could build this darn thing 😭)

willcrichton commented 10 months ago

Ah yes I haven't updated the build instructions, sorry. The best reference for this is our CI: https://github.com/cognitive-engineering-lab/rust-book/blob/main/.github/workflows/main.yml

In particular, you will need pnpm:

https://github.com/cognitive-engineering-lab/rust-book/blob/c11cef1e1deacea7ff2fa946d976fe37b062eb9b/.github/workflows/main.yml#L24-L26

And Depot:

https://github.com/cognitive-engineering-lab/rust-book/blob/c11cef1e1deacea7ff2fa946d976fe37b062eb9b/.github/workflows/main.yml#L34-L35

And Aquascope:

https://github.com/cognitive-engineering-lab/rust-book/blob/c11cef1e1deacea7ff2fa946d976fe37b062eb9b/.github/workflows/main.yml#L59-L63

And mdbook-quiz:

https://github.com/cognitive-engineering-lab/rust-book/blob/c11cef1e1deacea7ff2fa946d976fe37b062eb9b/.github/workflows/main.yml#L65-L66

Then running cargo make watch should build the JS dependencies and start the notebook.

willcrichton commented 10 months ago

And any contributions would be much appreciated!

KineticAeon commented 10 months ago

I'm trying to update the readme so that it has proper install instructions, but I've had a nightmare and a half attempting to install Aquascope. If this doesn't belong in this repo, please tell me and I'll put it in the Aquascope one instead. This is part of the output of cargo make install mdbook:

error[E0658]: use of unstable library feature 'is_terminal'
  --> /Users/aeon/.cargo/registry/src/index.crates.io-6f17d22bba15001f/anstream-0.5.0/src/is_terminal.rs:68:9
   |
68 |         std::io::IsTerminal::is_terminal(self)
   |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: see issue #98070 <https://github.com/rust-lang/rust/issues/98070> for more information
   = help: add `#![feature(is_terminal)]` to the crate attributes to enable

   Compiling proc-macro-error v1.0.4
   Compiling pest v2.7.2
For more information about this error, try `rustc --explain E0658`.
error: could not compile `anstream` (lib) due to 5 previous errors
warning: build failed, waiting for other jobs to finish...
[cargo-make] ERROR - Error while executing command, exit code: 101
[cargo-make] WARN - Build Failed.

Any ideas on what to do here?

willcrichton commented 10 months ago

@KineticAeon sorry for the troubles. Clap updated recently, and that broke the build. I just fixed that issue, so you should be able to install Aquascope.

KineticAeon commented 10 months ago

Alright, thanks a ton. I'll get to work finishing it up tomorrow when I've got the time and submit a PR. It could end up a bit rough style-wise, but it'll work.

KineticAeon commented 10 months ago

I've run into another error, this time involving the spellcheck module. It gives a ton of these errors:

Error: Cannot find module 'spellchecker'
Require stack:
- /tmp/.tmpCpFP9H.cjs
    at Module._resolveFilename (node:internal/modules/cjs/loader:1048:15)
    at Module._load (node:internal/modules/cjs/loader:901:27)
    at Module.require (node:internal/modules/cjs/loader:1115:19)
    at require (node:internal/modules/helpers:119:18)
    at Module.<anonymous> (/tmp/.tmpCpFP9H.cjs:5:22)
    at Module._compile (node:internal/modules/cjs/loader:1233:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1287:10)
    at Module.load (node:internal/modules/cjs/loader:1091:32)
    at Module._load (node:internal/modules/cjs/loader:938:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:83:12) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [ '/tmp/.tmpCpFP9H.cjs' ]
}

Node.js v20.4.0
Validation failed for quiz: /home/aeon/rust-book/src/../quizzes/ch17-01-what-is-oo.toml
2023-08-28 01:26:25 [ERROR] (mdbook::utils): Error: The "quiz" preprocessor exited unsuccessfully with exit status: 1 status

I thought the spellcheck was a separate script, is there something I'm missing here?

KineticAeon commented 10 months ago

Nevermind, seems like there’s a duplicate of this issue I didn’t think to check for. I’ll do its fix and hopefully have the draft instructions tested by tomorrow.

KineticAeon commented 10 months ago

Even after installing spellchecker I get the same error. I'm starting to think this might be a bit too broken for me to try and get right, so I don't think I'll end up fixing the requirements. They're just too messed up right now.

willcrichton commented 10 months ago

@KineticAeon thanks for the attempt. I will put it on my todo list to writeup easily-replicable installation instructions.

willcrichton commented 9 months ago

Btw @KineticAeon @atsuzaki -- I recently updated mdbook-quiz to eliminate some of the annoying dependencies. I also updated the requirements for rust-book to link to the relevant install instructions: https://github.com/cognitive-engineering-lab/rust-book#requirements

hamirmahal commented 6 months ago

I'd also like to contribute, but I get an error.

rust-book (main)$ mdbook build
2023-12-07 00:41:31 [INFO] (mdbook::book): Book building has started
Aquascope failed for program:
struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}
fn main() {
    let user1 = User {
        email: String::from("someone@example.com"),
        username: String::from("someusername123"),
        active: true,
        sign_in_count: 1,
    };
}
with error:
error: no such command: `aquascope`

        View all installed commands with `cargo --list`

2023-12-07 00:41:49 [ERROR] (mdbook::utils): Error: The "aquascope" preprocessor exited unsuccessfully with exit status: 1 status
willcrichton commented 6 months ago

@hamirmahal did you follow the linked instructions in the README to install mdbook-aquascope?

hamirmahal commented 6 months ago

@willcrichton I did

cargo install mdbook-aquascope --locked --version 0.3.0
rustup toolchain install nightly-2023-08-25 -c rust-src rustc-dev llvm-tools-preview miri
cargo +nightly-2023-08-25 install aquascope_front --git https://github.com/cognitive-engineering-lab/aquascope --tag v0.3.0 --locked
cargo +nightly-2023-08-25 miri setup

as mentioned at https://github.com/cognitive-engineering-lab/aquascope#installation

and ended up with

...
   Compiling aquascope v0.1.0 (/home/hamir/.cargo/git/checkouts/aquascope-b3a33f8c343833b5/b5781b3/crates/aquascope)
   Compiling aquascope_front v0.1.0 (/home/hamir/.cargo/git/checkouts/aquascope-b3a33f8c343833b5/b5781b3/crates/aquascope_front)
    Finished release [optimized] target(s) in 1m 08s
  Installing /home/hamir/.cargo/bin/aquascope-driver
  Installing /home/hamir/.cargo/bin/cargo-aquascope
   Installed package `aquascope_front v0.1.0 (https://github.com/cognitive-engineering-lab/aquascope?tag=v0.3.0#b5781b39)` (executables `aquascope-driver`, `cargo-aquascope`)
hamir@hamir-desktop:~/rust-book (main)$ mdbook build
2023-12-07 16:57:19 [INFO] (mdbook::book): Book building has started
2023-12-07 16:57:29 [INFO] (mdbook::book): Running the html backend
2023-12-07 16:57:29 [ERROR] (mdbook::utils): Error: Rendering failed
2023-12-07 16:57:29 [ERROR] (mdbook::utils):    Caused By: Unable to copy across additional CSS and JS
2023-12-07 16:57:29 [ERROR] (mdbook::utils):    Caused By: Unable to copy /home/hamir/rust-book/js-extensions/packages/consent-form/dist/index.css to /home/hamir/rust-book/book/js-extensions/packages/consent-form/dist/index.css
2023-12-07 16:57:29 [ERROR] (mdbook::utils):    Caused By: No such file or directory (os error 2)
willcrichton commented 6 months ago

@hamirmahal ah I left out some instructions. You also need to install pnpm and run:

cd js-extensions
pnpm init-repo

Then run mdbook build. (I added this to the README.)