docs: add resolve-cflags script and update extending-runtime docs

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

Author: simongdavies

docs/extending-runtime.md

@@ -74,15 +74,24 @@ libc stubs) — no copying files or build scripts needed.
 
 ### 3. Build and embed in hyperlight-js
 
-Build your custom runtime for the Hyperlight target and embed it:
+Build your custom runtime for the Hyperlight target.
+
+The hyperlight target has no libc, so QuickJS needs Hyperlight target stub headers
+and `-D__wasi__=1` to disable pthreads. Set `HYPERLIGHT_CFLAGS` before
+building — the helper script resolves the include path automatically
+from your Cargo dependency tree:
 
 ```bash
-# Build for the hyperlight target
+# Resolve CFLAGS (finds hyperlight-js-runtime's include/ directory)
+export HYPERLIGHT_CFLAGS=$(node scripts/resolve-cflags.js \
+  --manifest-path=my-custom-runtime/Cargo.toml)
+
+# Build the custom runtime for the hyperlight target
 cargo hyperlight build --manifest-path my-custom-runtime/Cargo.toml
 
-# Build hyperlight-js with your custom runtime embedded
-HYPERLIGHT_JS_RUNTIME_PATH=/path/to/my-custom-runtime \
-    cargo build -p hyperlight-js
+# Build hyperlight-js with the custom runtime embedded
+export HYPERLIGHT_JS_RUNTIME_PATH=my-custom-runtime/target/x86_64-hyperlight-none/release/my-custom-runtime
+cargo build -p hyperlight-js
 ```
 
 ### 4. Use from the host

src/hyperlight-js-runtime/scripts/resolve-cflags.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/**
+ * Resolves HYPERLIGHT_CFLAGS for crates that extend hyperlight-js-runtime.
+ *
+ * The hyperlight target (x86_64-hyperlight-none) has no libc. QuickJS
+ * (compiled by rquickjs-sys) needs Hyperlight target stub headers for stdio.h,
+ * time.h, and unistd.h, plus -D__wasi__=1 to disable pthreads.
+ * These stubs live in hyperlight-js-runtime/include/.
+ *
+ * This script uses cargo metadata to find that include directory
+ * regardless of whether the crate is a path, git, or registry dep.
+ *
+ * Usage:
+ *   export HYPERLIGHT_CFLAGS=$(node resolve-cflags.js --manifest-path=path/to/Cargo.toml)
+ *   cargo hyperlight build --manifest-path path/to/Cargo.toml
+ *
+ * Requires: Node.js, cargo
+ * Output:   -I/absolute/path/to/include -D__wasi__=1
+ */
+
+const { execSync } = require("child_process");
+const path = require("path");
+
+const args = process.argv.slice(2);
+const manifestArg = args.find((a) => a.startsWith("--manifest-path="));
+const manifestPath = manifestArg ? manifestArg.split("=")[1] : "Cargo.toml";
+
+try {
+  const meta = JSON.parse(
+    execSync(
+      `cargo metadata --format-version 1 --manifest-path ${manifestPath}`,
+      { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }
+    )
+  );
+
+  const pkg = meta.packages.find((p) => p.name === "hyperlight-js-runtime");
+  if (!pkg) {
+    process.stderr.write(
+      "Error: hyperlight-js-runtime not found in the dependency tree.\n" +
+        "Make sure your Cargo.toml depends on hyperlight-js-runtime.\n"
+    );
+    process.exit(1);
+  }
+
+  const includeDir = path.join(path.dirname(pkg.manifest_path), "include");
+  console.log(`-I${includeDir} -D__wasi__=1`);
+} catch (err) {
+  process.stderr.write(`Failed to resolve CFLAGS: ${err.message}\n`);
+  process.exit(1);
+}