Include full Cargo.toml for examples?

[tyoc213]

I think that examples, should include the Cargo.toml for a more easy "introduction".

[kvark]

Is there another project having a separate Cargo.toml for the examples?

[tyoc213]

I see, the point I'm somewhat new to rust and so to this cargo thing, so seeing on the main page you only need cargo

[dependencies]
gfx = "*"

Didn't understand why doing what is pointed on the main page and trying to do cargo build for the examples didn't work if they don't provide more info for run the examples (directly without take care of more docs than what is on main page and inside the folder example.

I just wanted to run the examples as fast as can without know rust, crates or any "idiosyncrasy"... but now I know. (So I still think that each sample should include the .toml that needs for run without know rust or cargo even for the matter).

as a matter of fact after this

[dependencies]
gfx = "*"
cgmath = "*"
gfx_window_glfw = "*"
glfw = "*"
glutin ="*"

gfx_window_glutin = "*"
env_logger ="*"
time="*"
genmesh="*"
noise="*"
rand="*"

I get

$ cargo run
    Updating registry `https://github.com/rust-lang/crates.io-index`
   Compiling first v0.1.0 (file:///Users/tyoc213/Documents/creations/rustcreations/deferred)
src/main.rs:343:33: 347:30 error: mismatched types:
 expected `glutin::window::Window`,
    found `glutin::window::Window`
(expected struct `glutin::window::Window`,
    found a different struct `glutin::window::Window`) [E0308]
src/main.rs:343         gfx_window_glutin::init(glutin::WindowBuilder::new()
src/main.rs:344             .with_title("Deferred rendering example with gfx-rs".to_string())
src/main.rs:345             .with_dimensions(800, 600)
src/main.rs:346             .with_gl(glutin::GL_CORE)
src/main.rs:347             .build().unwrap()
src/main.rs:343:33: 347:30 help: run `rustc --explain E0308` to see a detailed explanation
src/main.rs:542:9: 560:10 error: type mismatch resolving `<glutin::window::PollEventsIterator<'_> as core::iter::Iterator>::Item == glutin::events::Event`:
 expected enum `glutin::events::Event`,
    found a different enum `glutin::events::Event` [E0271]
src/main.rs:542         for event in output.window.poll_events() {
src/main.rs:543             use glutin::{Event, VirtualKeyCode};
src/main.rs:544             match event {
src/main.rs:545                 Event::Closed => break 'main,
src/main.rs:546                 Event::KeyboardInput(_, _, Some(VirtualKeyCode::Escape)) =>
src/main.rs:547                     break 'main,
                ...
note: in expansion of for loop expansion
src/main.rs:542:9: 560:10 note: expansion site
src/main.rs:542:9: 560:10 help: run `rustc --explain E0271` to see a detailed explanation
error: aborting due to 2 previous errors
Could not compile `deferred`.

So I did an incorrect .toml???

EDIT: I see that glutin ="*" works for deferred, but not for triangle example, it needs 0.2.3 specifically... and so on.

[kvark]

How about adding a section to the README explaining how to run examples? It's somewhat basic knowledge of Cargo, which is an essential part of Rust ecosystem, so a bit of education will not be wasted.

[tyoc213]

Yeah, eventually knowledge will come, but what about a guy/person that say ey that concept sound great I just want to try it out then do it directly (even without knowing what is rust?) what you will love more?? that he continue to see how simple and good this can be like just run it? or that he after see the first error try to figure out what is not there in the example??? so to solve this "little errors" stop a little the flow and learn this extra configuration steps? then continue with the previous flow?

I just think it would be amazing if people could say... ey I just want to try this out and copy file by file each folder and run cargo run and that is all (you will not even need to "clone directly" the repo or run it from there??... how you run this samples then???)

You have seen how easy is to test some js... I think with the correct cargo for each sample, it would be as easy as that without figuring the rest until you will learn it, at the end, the examples are to show off how easy this is.

[kvark]

I do agree with you. Though you are mixing 2 cases together:

1. A newbie just wants to run the examples. Our README would mention to do it via cargo run --example XXX. Problem solved.
2. A newbie wants to start their own code from an example. So they copy Cargo.toml and try to patch it. This may not work right away. We can solve it by having a standalone example (in its own repository) - either by moving an existing one out, or by adding a new one. Then we'd patch README to mention it as well. How does this sound to you?

[tyoc213]

I think if possible use both of them, so the README would say some like

run the examples with cargo run --example XXX and also see our linkto:starter_standalone_template and remember read the link:documentation.

That would be great :+1:

Also don't think it is needed to have an external repo for the stand alone example? but is like you people think it is best.

[ghost]

I think it'd be nice of you to mention how to run examples, either directly giving the command cargo run --example xxx or giving a link to the Rust/cargo doc that teaches how to run examples of any crate.

I'm a newbie and I did not know how to until I stumped upon this issue.

What can also be done on top of that is, just in case a newbie wants to write the example in his own way, simply mention "depends on xxx" in the example readme.

[jacmoe]

What I would like to have is a list of dependencies for each example. I had to add the following to my project cargo toml for the triangle example:

gfx = "*"
gfx_window_glutin = "*"
gfx_device_gl = "*"
glutin = "*"

Luckily, Rust has nice error messages so figuring out the dependencies by trial and error is not difficult..

[kvark]

@Trebgarta @jacmoe the examples code is self-documented with regards to dependencies - just open the source and check extern crate XXX to see what is needed, and the versions/paths can be seen from the root Cargo.toml.

[jacmoe]

I realize that now - my skills are not Rusty enough yet. Yes, indeed, they are actually self-documented. :+1:

[kvark]

@tyoc213 does my comment address your issue enough so that it can be closed?

[tyoc213]

Yes indeed, still think that for newcomers to rust you should not think of them as rustaceans, I mean for starters cargo is not rust... and if an extern person to rust (and its ecosystem) the section on README on how to run examples would be just a NTH. Or at less inside the realm for each example, say some like run me with: cargo run --example name or something like that, just to make it straight forward to people that just only want to see some rust running right away.

[kvark]

@tyoc213 I agree that README could be updated to include that information. PRs are welcome ;)

[kiran-kp]

There's a note on how to run examples in the Getting Started section of the readme. This issue can probably be closed.

[kvark]

@kiran-kp agreed.