Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: how to run example, for n00bs #476

Open
coolaj86 opened this issue Jun 10, 2022 · 3 comments
Open

doc: how to run example, for n00bs #476

coolaj86 opened this issue Jun 10, 2022 · 3 comments

Comments

@coolaj86
Copy link

coolaj86 commented Jun 10, 2022

Re: #475

  1. Make sure your rustc version is 1.61.0 or greater
    rustup update
    rustup override unset
    rustup default stable
    rustc --version
  2. Create a new project
    mkdir -p ./my-print-rcdom/
    pushd ./my-print-rcdom/
    cargo init
  3. Update Cargo.toml to include the dependencies (also, 2018 appears to be the required edition)
    [package]
    name = "example01"
    version = "0.1.0"
    authors = ["Joe Doe <[email protected]>"]
    edition = "2018"
    
    # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
    
    [dependencies]
    html5ever = "0.25.2"
    markup5ever_rcdom = "0.1.0"
  4. Replace src/main.rs with the contents of, for example, ./rcdom/examples/print-rcdom.rs
    rm ./src/main.rs
    curl -L -o ./src/main.rs https://raw.githubusercontent.com/servo/html5ever/1b34cf17c/rcdom/examples/print-rcdom.rs
  5. Install, build, run (with input):
    cargo build
    curl https://example.com | cargo run

Troubleshooting

Weird bug:

warning: unused import: `html5ever::tendril::TendrilSink`
  --> src/main.rs:20:5
   |
20 | use html5ever::tendril::TendrilSink;
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: `#[warn(unused_imports)]` on by default

Some errors have detailed explanations: E0277, E0599.
For more information about an error, try `rustc --explain E0277`.

Changing the name field in Cargo.toml (to anything at all), saving, and running cargo install again.

A room full of rust developers, including one of the most popular teachers on udemy in the room here with us, cannot figure this out.

@jeffyromney
Copy link

I would change:
"Make sure your rustc version is 1.61.0 or greater"
To something like:
"Update rust to a compatible version if needed. This was tested on 1.61.0"

@spencer1573
Copy link

spencer1573 commented Jun 10, 2022

Changing the name field in Cargo.toml will cause the Cargo.lock to be regenerated, and then it works.
-- @coolaj86

now the question is why?

@parkero
Copy link

parkero commented Jun 10, 2022

TL;DR: Wildcards in your dependencies can be dangerous and make Cargo do it's best to guess what you really want. A lone "*" means "every version ever" and is especially dangerous because it encompasses breaking changes across versions. Standard practice is to use version numbers (you can check crates.io), as those are the published versions.

I believe the issue stems from using a wildcard field ("*") for a dependency in the Cargo.toml.

On first run (i.e. absence of a Cargo.lock) Cargo adds all the dependencies you asked for in the Cargo.toml to the resolution list. In this particular case It looks like this:

html5ever = "*" // ANY version will do, newest is 0.26 on crates.io, add it and use it for our own code
markdown5ever_rcdom = "*" // ANY version will do, newest is 0.1, add it and use it for our own code

We then resolve the dependencies of our dependencies (turtles all the way down): markdown5ever_rcdom depends on html5ever^0.25: meaning any semver compatible version with 0.25. We have 0.26 already but that is not semver compatible right? So we add 0.25 (or rather 0.25.2 because semver) to the list as well.

Now the rub: we have two things with the same names with breaking changes between their versions. Our own code will resolve to what we asked for in the toml, which at the time resolved to 0.26. After that the breaking changes between 0.25<->0.26, well, break, and we get the error.

Now why does changing the name of the project work?

This seemed crazy at first but here is what I believe is happening:
On name change, the resolution targets are rebuilt from the Cargo.lock first, then checked against our current dependencies.

html5ever = "*" // ANY version will do, including 0.25.2 which we already know we need, just use it

With no mention, specifically, of needing 0.26 (only a "*"), all our requirements have been filled. 0.25.2 is used for our own code and 0.26 is removed from the list.

As an aside, the readme.md in rcdom seems to be trying to ward off people from using it at all. One might stray away from leveraging it early (or ever?) in a rust learning journey.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

4 participants