Skip to content
This repository was archived by the owner on Apr 15, 2026. It is now read-only.

Commit 43fd7df

Browse files
Firestar99Firestar99
authored
readme: repository has merged into rust-gpu
1 parent e837b29 commit 43fd7df

File tree

1 file changed

+2
-350
lines changed

1 file changed

+2
-350
lines changed

‎README.md‎

Lines changed: 2 additions & 350 deletions
Original file line numberDiff line numberDiff line change
@@ -1,351 +1,3 @@
1-
# cargo-gpu
1+
# cargo-gpu has moved
22

3-
`cargo-gpu` is an installation manager and command line tool for [rust-gpu](https://github.com/Rust-GPU/rust-gpu/). `cargo-gpu` is not an essential requirement, it should just make working with `rust-gpu` easier.
4-
5-
There are 2 ways to use it:
6-
1. Through a CLI, ie `cargo gpu ...`
7-
2. As a crate included in your build scripts or executables
8-
9-
## 1. CLI Quickstart
10-
11-
To install the command line tool, ensure you are using `rustup`. Then run:
12-
13-
```
14-
cargo install --git https://github.com/rust-gpu/cargo-gpu cargo-gpu
15-
```
16-
17-
You can then use `cargo gpu` to compile your shader crates or use any of the other commands you're used to:
18-
19-
```
20-
cargo gpu build
21-
cargo gpu check
22-
cargo gpu clippy
23-
```
24-
25-
### Example project
26-
27-
To create an example project from our [templates](https://github.com/Rust-GPU/rust-gpu-template), use the command below:
28-
```
29-
cargo install cargo-generate
30-
cargo generate --git https://github.com/Rust-GPU/rust-gpu-template
31-
# choose any template you want, then select cargo-gpu cmdline integration
32-
# you may have to adjust the crate name
33-
cargo gpu build -p mygraphics-shaders
34-
```
35-
36-
This plain invocation will compile the crate in the current directory and place the compiled shaders in the current directory.
37-
38-
Use `cargo gpu help` to see more options :)
39-
40-
## 2. Crate Quickstart
41-
42-
Add `cargo-gpu-install` as a regular or build dependency to your project, and use it like this:
43-
44-
```rust,no_run
45-
let shader_crate = PathBuf::from("./shaders");
46-
let backend = cargo_gpu_install::Install::from_shader_crate(shader_crate.clone()).run()?;
47-
let mut builder = backend.to_spirv_builder(shader_crate, "spirv-unknown-vulkan1.2");
48-
// configure the builder...
49-
let spv_result = builder.build()?;
50-
```
51-
52-
For more detail, see the [readme of `cargo-gpu-install`](crates/cargo-gpu-install/README.md) or use any of our [templates](https://github.com/Rust-GPU/rust-gpu-template) as reference and choosing the `cargo-gpu` integration.
53-
54-
## How it works
55-
56-
Behind the scenes `cargo gpu` compiles a custom [codegen backend](https://doc.rust-lang.org/beta/unstable-book/compiler-flags/codegen-backend.html)
57-
for `rustc` that allows emitting [SPIR-V](https://www.khronos.org/spir/) assembly, instead of the conventional LLVM assembly. SPIR-V is a dedicated
58-
graphics language that is aimed to be open and portable so that it works with as many drivers and devices as possible.
59-
60-
With the custom codegen backend (`rustc_codegen_spirv`) `cargo gpu` then compiles the shader it is pointed to. However, because custom codegen backends
61-
are currently [an unstable feature](https://github.com/rust-lang/rust/issues/77933), `cargo gpu` also needs to install a "nightly" version of Rust. In
62-
the usage instructions the backend and nightly Rust version are referred to as "artefacts" and can be explicitly managed with the arguments to the
63-
`install` subcommand.
64-
65-
> [!TIP]
66-
> Whilst `cargo gpu` attempts to isolate shader compilation as much possible, if the shader crate is contained in a workspace then it's possible that
67-
> the nightly version required by the shader is, ironically, older than the Rust/Cargo versions required by the workspace. Say for instance the
68-
> workspace might use a newer `Cargo.lock` layout not supported by the pinned version of the shader crate's custom codegen backend. The solution to
69-
> this is to either exclude the shader from the workspace, or upgrade the shader's `spirv-std` dependency to the latest.
70-
71-
## CLI Usage
72-
73-
All the following arguments for the `build` and `install` commands can also be set in the shader crate's `Cargo.toml`
74-
file. In general usage that would be the recommended way to set config. See `crates/shader-crate-template/Cargo.toml`
75-
for an example.
76-
77-
````
78-
Commands:
79-
install Install rust-gpu compiler artifacts
80-
build Compile a shader crate to SPIR-V
81-
show Show some useful values
82-
help Print this message or the help of the given subcommand(s)
83-
84-
Options:
85-
-h, --help
86-
Print help
87-
88-
-V, --version
89-
Print version
90-
91-
92-
* Install
93-
Install rust-gpu compiler artifacts
94-
95-
Usage: cargo-gpu install [OPTIONS]
96-
97-
Options:
98-
--shader-crate <SHADER_CRATE>
99-
Directory containing the shader crate to compile
100-
101-
[default: ./]
102-
103-
--spirv-builder-source <SPIRV_BUILDER_SOURCE>
104-
Source of `spirv-builder` dependency Eg: "https://github.com/Rust-GPU/rust-gpu"
105-
106-
--spirv-builder-version <SPIRV_BUILDER_VERSION>
107-
Version of `spirv-builder` dependency.
108-
* If `--spirv-builder-source` is not set, then this is assumed to be a crates.io semantic
109-
version such as "0.9.0".
110-
* If `--spirv-builder-source` is set, then this is assumed to be a Git "commitsh", such
111-
as a Git commit hash or a Git tag, therefore anything that `git checkout` can resolve.
112-
113-
--rebuild-codegen
114-
Force `rustc_codegen_spirv` to be rebuilt
115-
116-
--auto-install-rust-toolchain
117-
Assume "yes" to "Install Rust toolchain: [y/n]" prompt
118-
119-
--no-clear-target
120-
Clear target dir of `rustc_codegen_spirv` build after a successful build, saves about 200MiB of disk space
121-
122-
--force-overwrite-lockfiles-v4-to-v3
123-
There is a tricky situation where a shader crate that depends on workspace config can have
124-
a different `Cargo.lock` lockfile version from the the workspace's `Cargo.lock`. This can
125-
prevent builds when an old Rust toolchain doesn't recognise the newer lockfile version.
126-
127-
The ideal way to resolve this would be to match the shader crate's toolchain with the
128-
workspace's toolchain. However, that is not always possible. Another solution is to
129-
`exclude = [...]` the problematic shader crate from the workspace. This also may not be a
130-
suitable solution if there are a number of shader crates all sharing similar config and
131-
you don't want to have to copy/paste and maintain that config across all the shaders.
132-
133-
So a somewhat hacky workaround is to have `cargo gpu` overwrite lockfile versions. Enabling
134-
this flag will only come into effect if there are a mix of v3/v4 lockfiles. It will also
135-
only overwrite versions for the duration of a build. It will attempt to return the versions
136-
to their original values once the build is finished. However, of course, unexpected errors
137-
can occur and the overwritten values can remain. Hence why this behaviour is not enabled by
138-
default.
139-
140-
This hack is possible because the change from v3 to v4 only involves a minor change to the
141-
way source URLs are encoded. See these PRs for more details:
142-
* <https://github.com/rust-lang/cargo/pull/12280>
143-
* <https://github.com/rust-lang/cargo/pull/14595>
144-
145-
-h, --help
146-
Print help (see a summary with '-h')
147-
148-
149-
* Build
150-
Compile a shader crate to SPIR-V
151-
152-
Usage: cargo-gpu build [OPTIONS]
153-
154-
Options:
155-
--shader-crate <SHADER_CRATE>
156-
Directory containing the shader crate to compile
157-
158-
[default: ./]
159-
160-
--spirv-builder-source <SPIRV_BUILDER_SOURCE>
161-
Source of `spirv-builder` dependency Eg: "https://github.com/Rust-GPU/rust-gpu"
162-
163-
--spirv-builder-version <SPIRV_BUILDER_VERSION>
164-
Version of `spirv-builder` dependency.
165-
* If `--spirv-builder-source` is not set, then this is assumed to be a crates.io semantic
166-
version such as "0.9.0".
167-
* If `--spirv-builder-source` is set, then this is assumed to be a Git "commitsh", such
168-
as a Git commit hash or a Git tag, therefore anything that `git checkout` can resolve.
169-
170-
--rebuild-codegen
171-
Force `rustc_codegen_spirv` to be rebuilt
172-
173-
--auto-install-rust-toolchain
174-
Assume "yes" to "Install Rust toolchain: [y/n]" prompt
175-
176-
--no-clear-target
177-
Clear target dir of `rustc_codegen_spirv` build after a successful build, saves about 200MiB of disk space
178-
179-
--force-overwrite-lockfiles-v4-to-v3
180-
There is a tricky situation where a shader crate that depends on workspace config can have
181-
a different `Cargo.lock` lockfile version from the the workspace's `Cargo.lock`. This can
182-
prevent builds when an old Rust toolchain doesn't recognise the newer lockfile version.
183-
184-
The ideal way to resolve this would be to match the shader crate's toolchain with the
185-
workspace's toolchain. However, that is not always possible. Another solution is to
186-
`exclude = [...]` the problematic shader crate from the workspace. This also may not be a
187-
suitable solution if there are a number of shader crates all sharing similar config and
188-
you don't want to have to copy/paste and maintain that config across all the shaders.
189-
190-
So a somewhat hacky workaround is to have `cargo gpu` overwrite lockfile versions. Enabling
191-
this flag will only come into effect if there are a mix of v3/v4 lockfiles. It will also
192-
only overwrite versions for the duration of a build. It will attempt to return the versions
193-
to their original values once the build is finished. However, of course, unexpected errors
194-
can occur and the overwritten values can remain. Hence why this behaviour is not enabled by
195-
default.
196-
197-
This hack is possible because the change from v3 to v4 only involves a minor change to the
198-
way source URLs are encoded. See these PRs for more details:
199-
* <https://github.com/rust-lang/cargo/pull/12280>
200-
* <https://github.com/rust-lang/cargo/pull/14595>
201-
202-
-o, --output-dir <OUTPUT_DIR>
203-
Path to the output directory for the compiled shaders
204-
205-
[default: ./]
206-
207-
-w, --watch
208-
Watch the shader crate directory and automatically recompile on changes
209-
210-
--debug
211-
Build in release. Defaults to true
212-
213-
--target <TARGET>
214-
The target triple, eg. `spirv-unknown-vulkan1.2`
215-
216-
[default: spirv-unknown-vulkan1.2]
217-
218-
--no-default-features
219-
Set --default-features for the target shader crate
220-
221-
--features <FEATURES>
222-
Set --features for the target shader crate
223-
224-
--deny-warnings
225-
Deny any warnings, as they may never be printed when building within a build script. Defaults to false
226-
227-
--multimodule
228-
Splits the resulting SPIR-V file into one module per entry point. This is useful in cases where ecosystem tooling has bugs around multiple entry points per module - having all entry points bundled into a single file is the preferred system
229-
230-
--spirv-metadata <SPIRV_METADATA>
231-
Sets the level of metadata (primarily `OpName` and `OpLine`) included in the SPIR-V binary. Including metadata significantly increases binary size
232-
233-
[default: none]
234-
235-
Possible values:
236-
- none: Strip all names and other debug information from SPIR-V output
237-
- name-variables: Only include `OpName`s for public interface variables (uniforms and the like), to allow shader reflection
238-
- full: Include all `OpName`s for everything, and `OpLine`s. Significantly increases binary size
239-
240-
--capabilities <CAPABILITIES>
241-
Adds a capability to the SPIR-V module. Checking if a capability is enabled in code can be done via `#[cfg(target_feature = "TheCapability")]`
242-
243-
--extensions <EXTENSIONS>
244-
Adds an extension to the SPIR-V module. Checking if an extension is enabled in code can be done via `#[cfg(target_feature = "ext:the_extension")]`
245-
246-
--relax-struct-store
247-
Record whether or not the validator should relax the rules on types for stores to structs. When relaxed, it will allow a type mismatch as long as the types are structs with the same layout. Two structs have the same layout if
248-
249-
1) the members of the structs are either the same type or are structs with same layout, and
250-
251-
2) the decorations that affect the memory layout are identical for both types. Other decorations are not relevant.
252-
253-
--relax-logical-pointer
254-
Records whether or not the validator should relax the rules on pointer usage in logical addressing mode.
255-
256-
When relaxed, it will allow the following usage cases of pointers: 1) `OpVariable` allocating an object whose type is a pointer type 2) `OpReturnValue` returning a pointer value
257-
258-
--relax-block-layout <RELAX_BLOCK_LAYOUT>
259-
Records whether the validator should use "relaxed" block layout rules. Relaxed layout rules are described by Vulkan extension `VK_KHR_relaxed_block_layout`, and they affect uniform blocks, storage blocks, and push constants.
260-
261-
This is enabled by default when targeting Vulkan 1.1 or later. Relaxed layout is more permissive than the default rules in Vulkan 1.0.
262-
263-
[default: false]
264-
[possible values: true, false]
265-
266-
--uniform-buffer-standard-layout
267-
Records whether the validator should use standard block layout rules for uniform blocks
268-
269-
--scalar-block-layout
270-
Records whether the validator should use "scalar" block layout rules. Scalar layout rules are more permissive than relaxed block layout.
271-
272-
See Vulkan extnesion `VK_EXT_scalar_block_layout`. The scalar alignment is defined as follows: - scalar alignment of a scalar is the scalar size - scalar alignment of a vector is the scalar alignment of its component - scalar alignment of a matrix is the scalar alignment of its component - scalar alignment of an array is the scalar alignment of its element - scalar alignment of a struct is the max scalar alignment among its members
273-
274-
For a struct in Uniform, `StorageClass`, or `PushConstant`: - a member Offset must be a multiple of the member's scalar alignment - `ArrayStride` or `MatrixStride` must be a multiple of the array or matrix scalar alignment
275-
276-
--skip-block-layout
277-
Records whether or not the validator should skip validating standard uniform/storage block layout
278-
279-
--preserve-bindings
280-
Records whether all bindings within the module should be preserved
281-
282-
-m, --manifest-file <MANIFEST_FILE>
283-
Renames the manifest.json file to the given name
284-
285-
[default: manifest.json]
286-
287-
-h, --help
288-
Print help (see a summary with '-h')
289-
290-
291-
* Show
292-
Show some useful values
293-
294-
Usage: cargo-gpu show <COMMAND>
295-
296-
Commands:
297-
cache-directory Displays the location of the cache directory
298-
spirv-source The source location of spirv-std
299-
commitsh The git commitsh of this cli tool
300-
capabilities All the available SPIR-V capabilities that can be set with `--capabilities`
301-
help Print this message or the help of the given subcommand(s)
302-
303-
Options:
304-
-h, --help
305-
Print help
306-
307-
308-
* Cache-directory
309-
Displays the location of the cache directory
310-
311-
Usage: cargo-gpu show cache-directory
312-
313-
Options:
314-
-h, --help
315-
Print help
316-
317-
318-
* Spirv-source
319-
The source location of spirv-std
320-
321-
Usage: cargo-gpu show spirv-source [OPTIONS]
322-
323-
Options:
324-
--shader-crate <SHADER_CRATE>
325-
The location of the shader-crate to inspect to determine its spirv-std dependency
326-
327-
[default: ./]
328-
329-
-h, --help
330-
Print help
331-
332-
333-
* Commitsh
334-
The git commitsh of this cli tool
335-
336-
Usage: cargo-gpu show commitsh
337-
338-
Options:
339-
-h, --help
340-
Print help
341-
342-
343-
* Capabilities
344-
All the available SPIR-V capabilities that can be set with `--capabilities`
345-
346-
Usage: cargo-gpu show capabilities
347-
348-
Options:
349-
-h, --help
350-
Print help
351-
````
3+
cargo-gpu has been merged into the [rust-gpu](https://github.com/Rust-GPU/rust-gpu/) repository at [`/crates/cargo-gpu`](https://github.com/Rust-GPU/rust-gpu/tree/main/crates/cargo-gpu)

0 commit comments

Comments
 (0)