doc: how to run example, for n00bs

[coolaj86]

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 <joe@example.com>"]
   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]

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]

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]

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.