Wgpu-rs: [Documentation] Took me 30 min to get started

[eliemichel]

It is way too much. Sorry if this sounds abrupt. ^^ Running the examples was fairly straightforward, but the usage section of the readme is only talking about the examples, and going from there to a simple standalone project relying on wgpu took me like 30 min.

I am not very fluent in Rust yet, so maybe there is a magic "convert example to standalone project" command available in cargo, idk. The thing is I come from the graphics community so I feel pretty much like the intended target of such a library, I must not be the only person coming with experience of graphics libraries but less experience of Rust so it might be worth recalling the basics, if "converting an example into a project" is a basic.

I want to quickly start a new project, so I copy one of the example folders, rename it src and create a Cargo.toml next to it. I started over with hello-triangle because the one I had choosed first was relying on some additional framework.rs that I could not locate. After a lot of trial error I figured out I need this in the Cargo.toml dependency section:

[dependencies]
wgpu = { git = "https://github.com/gfx-rs/wgpu-rs" }
winit = "0.24.0"
wgpu-subscriber = "0.1.0"
pollster = "0.2.1"

(Using last wgpu crate wasn't compatible with the hello-triangle example from the repository.) This is nothing obvious, it would have saved me much time to have this available already somewhere. And I am not even sure it is the most idiomatic solution (hence I am not doing a pull request cause documentation written by beginner is sometimes worst than no documentation... I don't feel legit.)

[DKolter]

I can recommend you Sotrh as a place to start learning wgpu, it also contains the Cargo.toml file needed to get started. Maybe, there will be a revival of this Tutorial which is currently deprecated, as wgpu had changes since then. You might also want to look into this.

[kvark]

@eliemichel thank you for feedback! It's easy to just walk away, or to write an angry reddit post, but you did the right thing getting back to us, highly appreciated!
This is a real problem that you faced, many people stumbled upon it in gfx, wgpu, and other projects. I think it's basic Rust knowledge that's required here, there is nothing specific about wgpu-rs in how examples can be run. Perhaps, linking to the tutorial mentioned by @DKolter from the readme is the best we can do?

[eliemichel]

Hello yes linking Sotrh tutorial in the readme would have helped me, it is the kind of thing I was looking for when first going through the repo! Thanks for the other resources @DKolter (and thx for the welcome @kvark :) )

[fintelia]

I do think it could be made easier for users wanting to convert the examples into stand alone binaries. For instance, the #[path="../framework.rs"] mod framework; construction isn't widely know about in Rust and so beginners like OP might not discover that the relevant file is located at examples/framework.rs.

It is also probably more non-obvious than necessary exactly which crates should be included in your Cargo.toml

[kvark]

@fintelia what do you have in mind? I don't think removing the framework is on the radar any time soon - it works exceptionally well for our needs. Besides, there are "hello-*" examples that don't use the framework. Having the dependencies spelled out would be nice, but the tutorial covers that better, anyway.

[fintelia]

I don't have anything definite in mind. Perhaps just add a 'getting started' section to the README which gives a sample Cargo.toml and says to use the code from hello-triangle?

[francesco-cattoglio]

my very personal 2 cents:
wgpu can have a very steep learning curve, even for people that have a discrete OpenGL background. For this reason, even having a very simple template project would not help that much. What I would suggest is adding a link to Sotrh "learn-wgpu" to the README (or any other tutorial that is currently around). Sotrh's tutorial is how I started with wgpu and worked very well for me.