Kataglyphis-RustProjectTemplate

Collecting Rust best practices. Part of the Kataglyphis Ecosystem for robust code sharing and rapid development.

For official docs follow this link.

CI lanes are partly opt-in. Linux x86_64 runs on every push. The Windows and Linux ARM lanes only run when the pushed HEAD commit message contains [build-win] / [build-arm] (or you trigger the workflow manually) — otherwise they report skipped, which the badges render just like a pass. See AGENTS.md.

Table of Contents

• About The Project
  • Key Features
  • Dependencies
  • Useful tools
• Getting Started
  • Prerequisites
  • Installation
• Tests
• Run
• Docs
• Updates
• Roadmap
• Contributing
• License
• Contact
• Acknowledgements
• Literature

About The Project

The workspace also contains crates/webgpu_renderer — a WebGPU (wgpu) glTF renderer that runs natively (Vulkan/DX12/Metal) and in the browser (wasm32 + WebGPU): PBR with IBL, cascaded shadow maps, SSAO, bloom, GPU skinning, animations, LOD, hot shader reload, and headless golden tests. See crates/webgpu_renderer/README.md for demos and the SPIR-V/GLSL shader-export pipeline shared with the C++ Vulkan engine.

This template is a foundational part of the Kataglyphis Ecosystem, providing robust Rust best practices. It works synergistically with other projects like Kataglyphis ContainerHub to provide seamless code sharing, rapid development, and consistent identity across our web and systems engineering stack.

Key Features

• Features are to be adjusted to your own project needs.

Category	Feature	Implement Status
Packaging agnostic	Binary only deployment	✔️
	Lore ipsum	✔️
Lore ipsum agnostic
	LORE IPSUM	✔️
	Advanced unit testing	🔶
	Advanced performance testing	🔶
	Advanced fuzz testing	🔶

Legend:

• ✔️ - completed
• 🔶 - in progress
• ❌ - not started

Dependencies

This enumeration also includes submodules.

If you just want the newest versions allowed by your current constraints (updates Cargo.lock only):

Update all:

# update packages
cargo update
# update versions in Cargo.toml
cargo install cargo-edit
cargo upgrade --dry-run --verbose
# --pinned 
cargo upgrade --incompatible

Useful tools

• cargo-outdated

Getting Started

Prerequisites

Installation

1. Clone the repo

   git clone --recurse-submodules git@github.com:Kataglyphis/Kataglyphis-RustProjectTemplate.git

Tests

Run the complete suite (unit + integration + proptest fuzz + doc tests) at the debug profile:

cargo test --workspace --locked

CI additionally gates on formatting and lints, both as hard failures. Run them before pushing:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --locked -- -D warnings

The crates/webgpu_renderer headless golden tests need a GPU adapter and silently skip without one. Set KATAGLYPHIS_REQUIRE_GPU=1 to turn a missing adapter into a failure, so a green run actually means they rendered:

KATAGLYPHIS_REQUIRE_GPU=1 cargo test --workspace --locked

The suites live in:

• Unit tests inside the workspace crates (currently kataglyphis_telemetry).
• Integration tests: tests/integration.rs.
• Fuzz (property-based) tests: tests/fuzz_test.rs via proptest (256 random inputs per case by default). There is no separate cargo-fuzz/libFuzzer setup.

Latest verified run (2026-08-07, Stevedore Windows container): the 8 tests that predate crates/webgpu_renderer pass — 3 integration, 1 proptest fuzz case, 4 telemetry unit.

kataglyphis_webgpu_renderer is now excluded from the container run on purpose. Any of its test binaries links wgpu, and wgpu's gles backend makes the executable import opengl32.dll at load time; Windows Server Core does not ship that DLL, so the process dies with 0xc0000135 (STATUS_DLL_NOT_FOUND) before main. The loader resolves that import, so no runtime flag avoids it — and letting it run turned the entire cargo test --workspace into a crash with no results. The gles feature is kept deliberately: it is the OpenGL fallback for machines without Vulkan/DX12. Run those tests on a desktop Windows host, where the DLL exists:

cargo test -p kataglyphis_webgpu_renderer --locked

Not a regression either way — the old "8 passed" figure was recorded a day before that crate existed. See AGENTS.md for the full analysis.

Run

cargo run -- read --path ../README.md

Windows: GStreamer + ONNX Overlay (WGPU)

Build + Run (CPU via tract):

cargo run --bin kataglyphis_cli --features gui_windows,onnx_tract -- gui --backend dx12

Build + Run (ONNX Runtime + DirectML):

cargo run --bin kataglyphis_cli --features gui_windows,onnxruntime_directml -- gui --backend dx12

Build + Run (ONNX Runtime + CUDA, NVIDIA):

# PowerShell
$env:KATAGLYPHIS_ORT_DEVICE="cuda"
cargo run --bin kataglyphis_cli --features gui_windows,onnxruntime_cuda -- gui --backend dx12

# CMD
set KATAGLYPHIS_ORT_DEVICE=cuda
cargo run --bin kataglyphis_cli --features gui_windows,onnxruntime_cuda -- gui --backend dx12

Optional environment variables:

• KATAGLYPHIS_ONNX_MODEL – Pfad zum ONNX-Modell (Default: models/yolov10m.onnx)
• KATAGLYPHIS_ONNX_BACKEND – tract oder ort (Default: automatisch)
• KATAGLYPHIS_ORT_DEVICE – cpu | auto | cuda (Default: cpu)
• KATAGLYPHIS_PREPROCESS – letterbox | stretch (Default: stretch)
• KATAGLYPHIS_SWAP_XY – setze 1, falls die Modell-Ausgabe X/Y vertauscht (Default: 0)
• KATAGLYPHIS_SCORE_THRESHOLD – Score-Schwelle für Erkennung (Default: 0.5)
• KATAGLYPHIS_INFER_EVERY_MS – Inferenz-Intervall in ms (Default: 100, 0 = jedes Frame)

CUDA Hinweise:

• Benötigt NVIDIA-Treiber + CUDA/cuDNN Runtime auf dem System.
• Wenn CUDA-Init fehlschlägt, kann KATAGLYPHIS_ORT_DEVICE=auto genutzt werden (fällt auf CPU zurück).

Overlay:

• Zeigt FPS, Inferenz-Latenz, CPU/RSS und eine CPU-Historie.
• Inferenz kann im Overlay ein-/ausgeschaltet werden.

Analysis

cargo +nightly check --manifest-path Cargo.toml --target wasm32-unknown-unknown -Z build-std=std,panic_abort

Resource usage logging (CPU/GPU/RAM)

cargo run --features gui_windows,onnxruntime_directml -- --resource-log --resource-log-interval-ms 1000 --resource-log-gpu=true gui

Optional: zusätzlich in Datei schreiben

cargo run --features gui_windows,onnxruntime_directml -- --resource-log --resource-log-file .\resource.log gui

Burn / PyTorch-Replacement Demos

Diese Demos sind als separates Binary integriert und per Feature gated.

cargo run --features burn_demos --bin burn-demos -- --help

Beispiele:

cargo run --features burn_demos --bin burn-demos -- tensor-demo

cargo run --features burn_demos --bin burn-demos -- linear-regression --epochs 50 --steps-per-epoch 50 --lr 0.02 --batch-size 256

cargo run --features burn_demos --bin burn-demos -- xor --epochs 2000 --lr 0.05

cargo run --features burn_demos --bin burn-demos -- two-moons --epochs 200 --steps-per-epoch 50 --lr 0.01 --batch-size 256

# ONNX Runtime YOLOv10m Demo (Default model: models/yolov10m.onnx)
cargo run --features burn_demos --bin burn-demos -- onnx-yolov10 --runs 1 --print-topk 3

Windows

cargo run --features gui_windows -- gui --backend dx12

# Vulkan backend
cargo run --features gui_windows -- gui --backend vulkan

# Auto-select (wgpu PRIMARY)
cargo run --features gui_windows -- gui --backend primary

Windows: build & test in the Stevedore container

The workspace builds and tests inside the Kataglyphis ContainerHub Windows developer image (ghcr.io/kataglyphis/kataglyphis_beschleuniger:winamd64) using Stevedore's docker.exe.

ContainerHub is the ground truth for container and PowerShell functionality. The scripts here are thin drivers: docker.exe discovery, isolation flags, container teardown, SDK-tool lookup, MSIX manifest expansion, config access and build-step logging all come from its modules under windows/scripts/modules/. Before adding a helper to scripts/windows/, check whether ContainerHub already has it — several that were written locally turned out to exist there in a better form. Everything is pwsh (PowerShell 7+); nothing here runs under Windows PowerShell 5.1.

The driver bind-mounts this repository directly into the container (as C:\ws-mnt) — no copy, so artifacts land straight in your tree and ExternalLib/ is available inside. It builds all three profiles (dev/debug, profile = release + debuginfo, release = fat LTO) and optionally the full debug test suite:

# build debug + profile + release in the container
pwsh -ExecutionPolicy Bypass -File .\scripts\windows\Container\Invoke-StevedoreBuild.ps1

# build AND run cargo test --workspace (unit + integration + proptest fuzz + doc)
pwsh -ExecutionPolicy Bypass -File .\scripts\windows\Container\Invoke-StevedoreBuild.ps1 -Test

# only if your host refuses the mount (see below)
pwsh -ExecutionPolicy Bypass -File .\scripts\windows\Container\Invoke-StevedoreBuild.ps1 -StageSources

Dev Drive (ReFS) is not a blocker — reading through a bind mount works. What does not work is create-then-rename through it (bindFlt rejects copySync/renameSync with errno 3), which is precisely what cargo does. The driver keeps every build write container-local (CARGO_TARGET_DIR=C:\ct, CARGO_HOME=C:\ch), so only a plain artifact copy crosses the mount. If a host really does refuse it, docker run fails at once with "Der Dateisystem-Minifilter kann nicht an das Entwicklervolume angefügt werden"; fix it permanently with one elevated fsutil devdrv setfiltersallowed bindFlt, wcifs and a remount, or use -StageSources meanwhile. fsutil devdrv query needs elevation itself, so a failing query tells you nothing — just try the mount.

Artifacts land in target\container\{debug,profile,release} and are mirrored to the (gitignored) repo-root debug\, profile\, release\ folders; each contains the CLI exe, cdylib (.dll + import lib), staticlib (.lib) and pdb. Latest verified run (2026-08-07, rustc 1.97.1): all three profiles built (debug 1m35s, profile 1m32s, release 1m12s), written straight into the repo through the mount, and the binaries run on the host, e.g.:

.\release\kataglyphis_cli.exe stats --path .\README.md

Host caveats the driver handles automatically. ContainerHub is the authority on all of this — these are pointers, not a second copy:

• --isolation process for the full host CPU count (Hyper-V isolation caps at 2), via Get-ContainerIsolationArgs.
• All cargo writes stay container-local (CARGO_TARGET_DIR=C:\ct, CARGO_HOME=C:\ch); only a plain artifact copy crosses the mount, because bindFlt rejects create-then-rename.
• A dropped docker CLI pipe does not mean the build died — the driver waits on the actual container state, and tears containers down with Remove-BuildContainerSafe.

Topic	Read
Setting up a Windows host for Stevedore (services, docker-users, CNI nat conf)	docs/windows-host-setup.md
Windows container internals: wcifs/bindFlt, process isolation, layer-commit bug	docs/windows-builds.md
Running Linux containers on Windows (Rancher Desktop)	docs/rancher-desktop-linux-containers.md
Wiring a new project to all of it	docs/adopting-in-a-new-project.md

Linux containers locally (Rancher Desktop)

The Linux image is always ghcr.io/kataglyphis/kataglyphis_beschleuniger:latest-cross, in CI and locally. Rancher Desktop defaults to the containerd engine, so use nerdctl, not docker — and from Git Bash disable path mangling or the mount argument is destroyed. Full instructions: docs/rancher-desktop-linux-containers.md.

$env:MSYS_NO_PATHCONV=1; $env:MSYS2_ARG_CONV_EXCL='*'
rdctl shell nerdctl --namespace default run --rm --user root `
  -v kata-cargo-cache:/cargo-cache `
  -v /mnt/d/path/to/repo:/workspace -w /workspace `
  ghcr.io/kataglyphis/kataglyphis_beschleuniger:latest-cross `
  bash -lc 'export CARGO_HOME=/cargo-cache; bash ExternalLib/Kataglyphis-ContainerHub/linux/scripts/02-toolchain/rust/cargo_release.sh'

Two things that will bite on a Windows checkout, both verified 2026-08-07:

• Shell scripts must be LF. .gitattributes enforces it, but a checkout older than that rule keeps CRLF and bash dies on set: pipefail\r: invalid option name. One-time fix: git ls-files -z '*.sh' | xargs -0 rm -f && git checkout -- .
• CARGO_HOME in the image is root-owned, so point it at a writable path (a named volume keeps the registry across runs).

Windows MSIX packaging

Voraussetzungen:

• Windows SDK (inkl. makeappx und signtool) — der Pfad wird über ContainerHubs Resolve-WindowsSdkToolPath gefunden (respektiert WindowsSdkVerBinPath/WindowsSDKVersion aus VsDevCmd)
• PowerShell 7+ (pwsh) — 5.1 reicht nicht; alle Skripte tragen #requires -Version 7.0

MSIX bauen (inkl. Release-Build):

pwsh -ExecutionPolicy Bypass -File .\ExternalLib\Kataglyphis-ContainerHub\windows\scripts\rust\New-MsixPackage.ps1

MSIX bauen und mit einer vorhandenen PFX signieren:

pwsh -ExecutionPolicy Bypass -File .\scripts\windows\New-MsixPackage.ps1 `
  -CertificatePath .\certs\my-signing-cert.pfx `
  -CertificatePassword "<PASSWORD>"

MSIX bauen und Testzertifikat automatisch erzeugen:

pwsh -ExecutionPolicy Bypass -File .\scripts\windows\New-MsixPackage.ps1 `
  -CreateTestCertificate `
  -CertificatePassword "<TEST_CERT_PASSWORD>"

Output:

• Paket: dist\msix\Kataglyphis.RustProjectTemplate_<VERSION>_x64.msix
• Staging-Inhalt: dist\msix\staging\

Wichtige Parameter:

• -Binary (Default: kataglyphis_cli)
• -Features (Default: gui_windows,onnxruntime_directml)
• -Version (Format: Major.Minor.Build[.Revision])
• -Publisher (muss zum Signaturzertifikat passen, z. B. CN=Kataglyphis)
• -SkipBuild (packt vorhandenen Release-Build erneut)

MSIX installieren (mit Testzertifikat):

1. PowerShell als Administrator öffnen.
2. Zertifikat in vertrauenswürdige Stores importieren.
3. Paket installieren.

$certPath = "C:\\GitHub\\Kataglyphis-Inference-Engine\\ExternalLib\\Kataglyphis-RustProjectTemplate\\dist\\msix\\Kataglyphis.RustProjectTemplate.testcert.pfx"
$msixPath = "C:\\GitHub\\Kataglyphis-Inference-Engine\\ExternalLib\\Kataglyphis-RustProjectTemplate\\dist\\msix\\Kataglyphis.RustProjectTemplate_0.1.0.0_x64.msix"
$pwd = ConvertTo-SecureString "<TEST_CERT_PASSWORD>" -AsPlainText -Force

Import-PfxCertificate -FilePath $certPath -Password $pwd -CertStoreLocation "Cert:\\LocalMachine\\Root"
Import-PfxCertificate -FilePath $certPath -Password $pwd -CertStoreLocation "Cert:\\LocalMachine\\TrustedPeople"

Add-AppxPackage -Path $msixPath

Windows MSI packaging

Läuft als Schritt von Build-Windows.ps1 (abschaltbar mit -SkipMsi, oder Msi.Enabled = $false in scripts/windows/Build-Windows.config.psd1).

Output: dist\msi\kataglyphis_cli-<VERSION>-x64.msi

Gebaut wird mit WiX Toolset v4 (wix.exe build), nicht mit cargo-wix: cargo-wix steuert auch in seiner neuesten Version (0.3.9) nur WiX v3 über candle.exe/light.exe, während das Container-Image WiX 4.0.6 als einzelnes wix.exe mitbringt. wix/main.wxs liegt entsprechend im v4-Schema vor und bekommt Version, Binary- und Lizenzpfad als Präprozessor-Variablen übergeben. Der Dialog-Satz WixUI_FeatureTree stammt aus WixToolset.UI.wixext, das im Image bereits installiert ist.

Installationsprüfung:

Get-AppxPackage -Name "Kataglyphis.RustProjectTemplate" | Select-Object Name, PackageFullName, Status

Troubleshooting:

• 0x800B0109: Zertifikatskette ist nicht vertrauenswürdig. Zertifikat wie oben in LocalMachine\\Root und LocalMachine\\TrustedPeople importieren (Admin erforderlich).
• Import-PfxCertificate: Zugriff verweigert: PowerShell nicht als Administrator gestartet.
• Details zum letzten Deploy-Fehler anzeigen:

Get-AppxLog -ActivityID <ACTIVITY_ID>

App nach Installation starten:

• Über das Startmenü nach Kataglyphis RustProjectTemplate suchen und starten.
• Oder per PowerShell:

$pkg = Get-AppxPackage -Name "Kataglyphis.RustProjectTemplate"
Start-Process "shell:AppsFolder\$($pkg.PackageFamilyName)!App"

MSIX Update / Reinstall:

• Neue Version mit höherer -Version bauen und signieren.
• Dann erneut installieren:

Add-AppxPackage -Path "C:\\GitHub\\Kataglyphis-Inference-Engine\\ExternalLib\\Kataglyphis-RustProjectTemplate\\dist\\msix\\Kataglyphis.RustProjectTemplate_<NEW_VERSION>_x64.msix"

MSIX deinstallieren:

Get-AppxPackage -Name "Kataglyphis.RustProjectTemplate" | Remove-AppxPackage

Linux

# WGPU (recommended)
cargo run --features gui_wgpu -- gui --backend vulkan

# GTK demo
cargo run --features gui_unix -- gui

Docs

cargo doc --open

Updates

How to update all installed packages:

1. Install updater:

cargo install cargo-update

2. Now update all packages:

cargo install-update -a

Cameras

sudo v4l2-ctl --list-formats-ext -d /dev/video0
gst-launch-1.0 v4l2src device=/dev/video0 ! videoconvert ! autovideosink
gst-launch-1.0 videotestsrc ! video/x-raw,width=640,height=480,framerate=30/1 ! autovideosink

Roadmap

Upcoming :)

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Contact

Jonas Heinle - @Cataglyphis_ - jonasheinle@googlemail.com

Project Link: https://github.com/Kataglyphis/...

Acknowledgements

Literature

Some very helpful literature, tutorials, etc.