add cargo-gpu new

[Firestar99]

• cargo-gpu new effectively aliases cargo generate with the rust-gpu-template repo
• This makes cargo-gpu depend on cargo-generate, which significantly increases the amount of dependencies cargo-gpu has. I expect most users to migrate to cargo-gpu-install for their build script needs.
  • if you really need cargo-gpu as a dep, I've made cargo-generate a default feature you can disable
• cargo generate also depends on quite a few outdated packages, including vulnerabilities, making our cargo deny complain. I've made it pass by ignoring them all, as I don't think there's a huge concern for a dev cmdline tool.

close #576

[LegNeato]

Wait, we have cargo-gpu, spirvbuilder, and cargo-gpu-install?!?! That seems really bad and confusing.

Can't we just put this behind an off-by-default flag (looks like it is on?) that is turned on for the binary? That way people using cargo-gpu in teh build script don't get changes in behavior and we still get this feature.

So I guess I don't see why cargo-gpu-install even exists?

[Firestar99]

Can't we just put this behind an off-by-default flag (looks like it is on?) that is turned on for the binary?

No we can't, cause if you cargo install, it'll always build the binary with the default feature set. So if we were to hide binary-only features behind a feature flag, noone would use them, cause noone will pass extra --features when installing a binary. Especially something like cargo new, which is primarily for newer users to give them a preconfigured rust-gpu workspace. We also didn't find a way to configure cargo install to pass additional features when building a crate.

So our only option was to split the crate in two, a library crate for build scripts (cargo-gpu-install) and a binary crate for cli usage (cargo-gpu). And since we wanted cargo install cargo-gpu to work, the cli crate has to be named cargo-gpu, so we named the library cargo-gpu-install since it'll only contain the Install action. It's only purpose is to install the rustup toolchain, build the codegen backend, and return you an InstalledBackend, from which you can create a SpirvBuilder (see cargo-gpu-install's readme). This split has also cuts out many cli-related dependencies like clap, crossterm and mio (async file io).

For additional background:

• The original PR: Split install action into the new crate cargo-gpu-install cargo-gpu#132
• much of the crate splitting discussion is in: Divide project into library and binary parts cargo-gpu#112

[LegNeato]

Ahhh, I see. Thanks for explaining.

[LegNeato]

We should support --lib and --bin like cargo, right now it assumes a certain opinionated shape. How do we specify shader types to include or not include? I glanced over the template and it seems to assume graphics. Should we default to compute (less boilerplate / host code needed) and be able to specify which shader stages to generate? Should we even have a default?

[Firestar99]

Adding a compute example should be quite straight forward to do, preferably I'll make that before rustweek.

The bigger problem is that these templates are not single crates, but an entire workspace with a shader crate, a binary crate with a build script and all the setup that's required to get rust-gpu up and running (with cargo-gpu or directly via spirv-builder). So the --lib vs --bin question doesn't really make sense in that context.

I could see a need for a cargo cmd that adds a shader crate to an existing workspace, but that wouldn't just be simple template expansion. It would be scripts that actively modify the workspace to add a shader crate (which could be a template) and the build script so some other crate with all required dependencies. I could see an argument that this should be cargo gpu new and we should move the whole-workspace template expansion to a different subcommand? Or keep this PR as cargo gpu new and later on offer a completely custom template selection, so that graphics becomes the graphics-workspace and adding a shader crate to an existing workspace is graphics-crate? I don't think we'll make that anytime soon, but still think having a discussion about subcommand naming now is a good idea.

[LegNeato]

You could have multiple types of libs...a lib that runs on the gpu for others to use (you can scaffold tests using host code), a lib that is host+device that others can call into (for example, you could have a sort() on the host that does the work on the GPU), etc.

So I guess we could punt and put the current one behind --bin, as it is conceptually maps to cargo's --bin if you squint.

But I also agree, maybe we punt and we rename it cargo gpu example or something?

When shadowing cargo want to tie it conceptually as close as possible to cargo's behavior so it just works and is intuitive for people coming from CPU. It also informs us the shape for future upstreaming. So if we can't get there or don't have time to do design work, perhaps it is better to just make it different so there isn't an impedance mismatch.