Skip to content

update offload usage after simplified build pipeline #3086

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sgasho wants to merge 2 commits into
base: main
Choose a base branch
from
+7 −12
Open

update offload usage after simplified build pipeline #3086

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1aafc99
offload: simplify build commands by removing --emit=llvm-bc,llvm-ir -…
sgasho Nov 6, 2026
d99a37a
offload: update compile instructions and warning on usage.md
sgasho Nov 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 7 additions & 12 deletions src/offload/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,11 +61,6 @@ fn main() {
```

## Compile instructions
It is important to use a clang compiler build on the same LLVM as rustc.
Just calling clang without the full path will likely use your system clang,
which probably will be incompatible.
So either substitute clang/lld invocations below with absolute path, or set your `PATH` accordingly.

The compilation runs three passes:
1. `HostMetadata`: compile the host code, writing a manifest that lists the kernel
instantiations (including generic ones) required by the host code.
Expand All @@ -75,32 +70,32 @@ The compilation runs three passes:

<div class="warning">

Replace the `target-cpu` (gfx90a) with the right code for your GPU.
These are often referred to as "LLVM target names"[^list].
The commands below target an AMD GPU. For your GPU, change:
- `-Ctarget-cpu=gfx90a` to your GPU's target CPU (e.g. `sm_86` on NVIDIA)[^list]
- on NVIDIA, `amdgcn-amd-amdhsa` to `nvptx64-nvidia-cuda` (in `--target` and in the `-Zoffload=Host` path), and `.elf` to `.ptx`

</div>

First we generate the manifest from the host code:
```
RUSTFLAGS="--emit=llvm-bc,llvm-ir -Csave-temps -Zoffload=HostMetadata=/absolute/path/to/offload.manifest -Zunstable-options" cargo +offload build -r
RUSTFLAGS="-Zoffload=HostMetadata=/absolute/path/to/offload.manifest -Zunstable-options" cargo +offload build -r
```
This pass only writes the manifest.

Now we generate the device (GPU) code, passing the manifest:
```
RUSTFLAGS="-Ctarget-cpu=gfx90a --emit=llvm-bc,llvm-ir -Zoffload=Device=/absolute/path/to/offload.manifest -Csave-temps -Zunstable-options" cargo +offload build -Zunstable-options -r -v --target amdgcn-amd-amdhsa -Zbuild-std=core
RUSTFLAGS="-Ctarget-cpu=gfx90a -Zoffload=Device=/absolute/path/to/offload.manifest -Zunstable-options" cargo +offload build -Zunstable-options -r -v --target amdgcn-amd-amdhsa -Zbuild-std=core
```

Next we generate the host (CPU) code.
```
DEVICE_BC=$(find $PWD/target/amdgcn-amd-amdhsa/release/build -name '<crate_name>.bc')
RUSTFLAGS="-C lto=fat -C embed-bitcode=yes --emit=llvm-bc,llvm-ir -Csave-temps -Zoffload=Host=$DEVICE_BC -Zunstable-options" cargo +offload build -r
RUSTFLAGS="-C lto=fat -C embed-bitcode=yes -Zoffload=Host=$PWD/target/amdgcn-amd-amdhsa/release/<crate_name>.elf -Zunstable-options" cargo +offload build -r
```

In the final step, you can now run your binary

```
./target/x86_64-unknown-linux-gnu/release/binary-name
./target/release/binary-name
all checks passed!
```

Expand Down
Loading