feat(khal-builder): add support for building a crate dependency instead of a local dir

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 _Disclaimer: this changelog is updated using generative AI, but is still verified manually._
 
+## v0.1.1
+
+### Added
+- `KhalBuilder::from_dependency` (in `khal-builder`): locates the shader crate via cargo's `links` metadata mechanism instead of a hard-coded relative path. This lets a published host crate rebuild its shaders on the consumer's machine using a registry-fetched copy of the shader crate, without needing to bundle the shader sources in the host's published artifact.
+
+### Changed
+- The `khal-example` tutorial crate now uses `KhalBuilder::from_dependency` instead of a hard-coded `"../khal-example-shaders"` path, and `khal-example-shaders` declares `links = "khal-example-shaders"` plus a small `build.rs` that re-exports its `CARGO_MANIFEST_DIR` to dependents. This is the recommended pattern for downstream crates that publish to crates.io.
+
 ## v0.1.0
 
 This shows the changes between the time of open-sourcing the crate and its first release to crates.io:

Cargo.toml

@@ -9,6 +9,9 @@ members = [
 ]
 resolver = "2"
 
+[workspace.package]
+version = "0.1.1"
+
 [workspace.dependencies]
 bytemuck = { version = "1", features = ["derive", "extern_crate_std"] }
 anyhow = "1"

crates/khal-builder/Cargo.toml

@@ -3,7 +3,7 @@ name = "khal-builder"
 authors = ["Sébastien Crozet <sebcrozet@dimforge.com>"]
 description = "Build-time utilities for compiling khal shader crates to SPIR-V and CUDA PTX."
 repository = "https://github.com/dimforge/khal"
-version = "0.1.0"
+version = { workspace = true }
 edition = "2024"
 license = "MIT OR Apache-2.0"
 

crates/khal-builder/src/lib.rs

@@ -41,6 +41,31 @@ impl KhalBuilder {
         builder
     }
 
+    /// Creates a new builder by locating the shader crate via cargo's `links`
+    /// metadata mechanism.
+    ///
+    /// `links_name` must match the `links` value declared in the shader
+    /// crate's `Cargo.toml`. The shader crate's `build.rs` must emit
+    /// `cargo::metadata=manifest_dir=$CARGO_MANIFEST_DIR`, and the host crate
+    /// must depend on the shader crate as a `[build-dependencies]` entry.
+    /// Cargo then exposes `DEP_<LINKS>_MANIFEST_DIR` to this build script,
+    /// which works identically for in-workspace path dependencies and for
+    /// versions fetched from a registry.
+    pub fn from_dependency(links_name: &str, enable_builtin_features: bool) -> Self {
+        let env_key = format!(
+            "DEP_{}_MANIFEST_DIR",
+            links_name.to_ascii_uppercase().replace('-', "_")
+        );
+        let manifest_dir = std::env::var(&env_key).unwrap_or_else(|_| {
+            panic!(
+                "environment variable `{env_key}` is not set; ensure `{links_name}` is declared \
+                 as a `[build-dependencies]` entry of the host crate and that its `build.rs` emits \
+                 `cargo::metadata=manifest_dir=$CARGO_MANIFEST_DIR`"
+            )
+        });
+        Self::new(manifest_dir, enable_builtin_features)
+    }
+
     /// Sets the `RUST_MIN_STACK` environment variable for the shader compilation processes.
     pub fn rust_min_stack(mut self, stack: u32) -> Self {
         self.rust_min_stack = stack;

crates/khal-derive/Cargo.toml

@@ -3,7 +3,7 @@ name = "khal-derive"
 authors = ["Sébastien Crozet <sebcrozet@dimforge.com>"]
 description = "Proc-macro for Slang shaders."
 repository = "https://github.com/dimforge/khal"
-version = "0.1.0"
+version = { workspace = true }
 edition = "2024"
 license = "MIT OR Apache-2.0"
 

crates/khal-example-shaders/Cargo.toml

@@ -3,6 +3,14 @@ name = "khal-example-shaders"
 version = "0.1.0"
 edition = "2024"
 publish = false
+# `links` declares a unique shader-crate identity so cargo will pass any
+# metadata emitted by this crate's `build.rs` to dependents (host crates) as
+# `DEP_KHAL_EXAMPLE_SHADERS_<KEY>` env vars. This is what lets the host crate's
+# `build.rs` locate the shader sources, whether they come from a workspace
+# path during development or from `~/.cargo/registry/src/...` once this crate
+# is published and pulled from crates.io.
+links = "khal-example-shaders"
+build = "build.rs"
 
 [features]
 cpu = ["khal-std/cpu"]

crates/khal-example-shaders/build.rs

@@ -0,0 +1,15 @@
+// Re-exports this crate's source location to host crates that build the
+// shaders. Combined with `links = "khal-example-shaders"` in Cargo.toml, the
+// `cargo::metadata=manifest_dir=...` line below is delivered to any direct
+// `[build-dependencies]` consumer as `DEP_KHAL_EXAMPLE_SHADERS_MANIFEST_DIR`.
+// The host crate's `build.rs` reads that variable (via
+// `KhalBuilder::from_dependency`) to find the shader sources, which works
+// identically for in-workspace path deps and for crates fetched from
+// crates.io — so a published host crate can rebuild its shaders on the
+// consumer's machine without bundling this crate's source itself.
+fn main() {
+    let manifest_dir =
+        std::env::var("CARGO_MANIFEST_DIR").expect("CARGO_MANIFEST_DIR not set by cargo");
+    println!("cargo::metadata=manifest_dir={manifest_dir}");
+    println!("cargo:rerun-if-changed=build.rs");
+}

crates/khal-example/Cargo.toml

@@ -18,4 +18,10 @@ async-std = { version = "1", features = ["attributes"] }
 khal-example-shaders = { path = "../khal-example-shaders" }
 
 [build-dependencies]
-khal-builder = { version = "0.1.0", path = "../khal-builder" }
+khal-builder = { version = "0.1.0", path = "../khal-builder" }
+# Listed as a build-dep (in addition to the regular `[dependencies]` entry
+# above) so cargo runs the shader crate's `build.rs` before ours and
+# forwards its `DEP_KHAL_EXAMPLE_SHADERS_MANIFEST_DIR` env var to our
+# `build.rs`. Without this line our `build.rs` would have no way to locate
+# the shader sources when this crate is consumed from crates.io.
+khal-example-shaders = { path = "../khal-example-shaders" }

crates/khal-example/build.rs

@@ -1,8 +1,14 @@
 use khal_builder::KhalBuilder;
 
 fn main() {
-    let shader_crate = "../khal-example-shaders";
     let output_dir = "shaders-spirv";
 
-    KhalBuilder::new(shader_crate, true).build(output_dir);
+    // `from_dependency` resolves the shader crate's source directory by reading
+    // the `DEP_KHAL_EXAMPLE_SHADERS_MANIFEST_DIR` env var that cargo
+    // populates from the shader crate's `links` metadata (see its
+    // `build.rs`). Prefer this over a hard-coded `"../khal-example-shaders"`
+    // path: the relative path only resolves inside the workspace and
+    // disappears from the published artifact, whereas the env var is set
+    // for both workspace and registry-fetched copies of the shader crate.
+    KhalBuilder::from_dependency("khal-example-shaders", true).build(output_dir);
 }

crates/khal-std/Cargo.toml

@@ -3,7 +3,7 @@ name = "khal-std"
 authors = ["Sébastien Crozet <sebcrozet@dimforge.com>"]
 description = "GPU standard library for khal compute shaders, with cross-platform primitives compiling to SPIR-V, CUDA PTX, and CPU targets."
 repository = "https://github.com/dimforge/khal"
-version = "0.1.0"
+version = { workspace = true }
 edition = "2024"
 license = "MIT OR Apache-2.0"
 

crates/khal/Cargo.toml

@@ -3,7 +3,7 @@ name = "khal"
 authors = ["Sébastien Crozet <sebcrozet@dimforge.com>"]
 description = "Abstractions for running compute shaders with Rust."
 repository = "https://github.com/dimforge/khal"
-version = "0.1.0"
+version = { workspace = true }
 edition = "2024"
 license = "MIT OR Apache-2.0"