Generating a project

Here we’ll describe how you can use our cmdline utility to generate a rust-gpu project from a template. On the next page we’ll inspect its structure, so you can replicate it in any existing project.

First, install our cargo gpu cli, if you haven’t already:

cargo install cargo-gpu

Then generate a rust-gpu project with:

cargo gpu generate

(This subcommand is merely a wrapper around cargo-generate invoked on our rust-gpu-template repository. If you don’t want to run that command, you can also download any expanded template from the generated subdirectory.)

It will ask you a few questions on what kind of project you want:

Which sub-template should be expanded?

• graphics: renders a colorful triangle with vertex and fragment shaders

Feel free to PR new templates!

Project Name:

Type whatever recognizable name you want.

What API?

• wgpu: WebGPU with a nice rusty interface
• ash: lightweight wrapper around Vulkan

If you’re unsure, wgpu is generally easier to use.

How to integrate rust-gpu?

• cargo-gpu (recommended): It’s a rust-gpu installation manager that isolates the specific nightly toolchain that rust-gpu requires, allowing the rest of your project to remain on a stable toolchain (or any other toolchain). Other users don’t need the cli installed, it just offers some extra utilities.
• spirv-builder is the older setup that requires your entire project to be compiled using the specific nightly rust-gpu toolchain.

You should have a new folder named after the project name. Simply cd into it and cargo run should get you a rotating triangle!

It may take a while for mygraphics(build) to finish when you run it for the first time. We have to download the specific rust toolchain we need and build the rust-gpu codegen backend that functions with it. These preparations are cached externally in ~/.cache/rust-gpu/, so even after a cargo clean the build should still be significantly faster.