docs: add RISC-V build support (#11933)

Co-authored-by: Jack Amadeo <jackamadeo@squareup.com>
This commit is contained in:
Faried Nawaz T
2026-09-09 19:37:11 +00:00
committed by GitHub
parent b0b35a2990
commit 675edfc3c6
3 changed files with 541 additions and 1 deletions
+285
View File
@@ -0,0 +1,285 @@
# Building goose for RISC-V (riscv64gc-unknown-linux-gnu)
This document describes how to build goose-cli for RISC-V 64-bit systems with full V8/code-mode support.
> [!WARNING]
> This is an experimental, community-contributed build process. RISC-V is not
> officially supported by the goose project.
## Prerequisites
- Rust 1.96.1+ (no toolchain upgrade needed)
- RISC-V cross-compilation toolchain: `gcc-riscv64-linux-gnu`
- Target: `rustup target add riscv64gc-unknown-linux-gnu`
### Linker Configuration
Building **on** RISC-V hardware needs nothing extra - the native linker is
used automatically.
**Cross-compiling** (e.g. from x86_64) needs the cross linker, otherwise
rustc invokes the host `cc` and linking fails. Either export:
```bash
export CARGO_TARGET_RISCV64GC_UNKNOWN_LINUX_GNU_LINKER=riscv64-linux-gnu-gcc
```
or add to `.cargo/config.toml` (or `~/.cargo/config.toml`):
```toml
[target.riscv64gc-unknown-linux-gnu]
linker = "riscv64-linux-gnu-gcc"
```
Adjust the binary name if your distribution ships the cross gcc under a
different name.
## Overview
V8 152.2.0 is the first version with pre-built RISC-V binaries. However:
- Current goose uses v8 145.0.0 via deno_core 0.381.1 (no RISC-V support)
- Upgrading requires patching deno_core and serde_v8 for V8 152 API changes
- These patches are intrusive and affect all platforms if applied via Cargo.toml patches
## Setup Steps
### 1. Clone rusty_v8 v152.2.0
Run from the repository root:
```bash
git init vendor/rusty_v8
git -C vendor/rusty_v8 remote add origin https://github.com/denoland/rusty_v8.git
git -C vendor/rusty_v8 fetch --depth 1 origin 2768994f664e8a6e3aba27503606c58339136e2a
git -C vendor/rusty_v8 checkout --detach FETCH_HEAD
rm -rf vendor/rusty_v8/.git
```
This provides v8 152.2.0 with RISC-V support. Cargo will download pre-built binaries automatically.
### 2. Vendor deno_core 0.381.1
Run from the repository root:
```bash
wget -P vendor https://static.crates.io/crates/deno_core/deno_core-0.381.1.crate
echo "77660b04f5368bcd69a42e0fdd6343e325eb781ec7d79bbf49ff2548ae4f17b6 vendor/deno_core-0.381.1.crate" | sha256sum --check
tar -C vendor -xzf vendor/deno_core-0.381.1.crate
mv vendor/deno_core-0.381.1 vendor/deno_core
rm vendor/deno_core-0.381.1.crate
```
### 3. Vendor serde_v8 0.290.0
Run from the repository root:
```bash
wget -P vendor https://static.crates.io/crates/serde_v8/serde_v8-0.290.0.crate
echo "21a52aca5a5661aea9c2ccf8c2f985f2381266d7aab03a0d02beadb4ae1190ea vendor/serde_v8-0.290.0.crate" | sha256sum --check
tar -C vendor -xzf vendor/serde_v8-0.290.0.crate
mv vendor/serde_v8-0.290.0 vendor/serde_v8
rm vendor/serde_v8-0.290.0.crate
```
### 4. Apply Patches
#### vendor/v8 — drop it from the workspace
The cloned `vendor/rusty_v8` is itself the `v8` crate at `152.2.0`, so the
root `[patch.crates-io]` entry points straight at it (see step 6). The
committed `vendor/v8` shim is not edited, but it must leave the workspace:
it pulls in `v8-goose`, which declares `links = "rusty_v8"`, and once the
patch resolves denoland's `v8` 152 (also `links = "rusty_v8"`) a workspace
containing both fails with "more than one crate with links=rusty_v8". Remove
`vendor/v8` from `members` and add it to `exclude` (see step 6).
#### vendor/deno_core/Cargo.toml
Update the v8 and ICU-data dependencies:
```toml
[dependencies.v8]
version = "152.2.0" # was 145.0.0
default-features = false
[dependencies.deno_core_icudata]
version = "0.78.0" # was 0.77.0; V8 152 needs the ICU 78 data blob
optional = true
```
#### vendor/serde_v8/Cargo.toml
Update v8 dependency:
```toml
[dependencies.v8]
version = "152.2.0" # was 145.0.0
default-features = false
```
### 5. Source Patches to vendor/deno_core
These patches adapt deno_core 0.381.1 to V8 152 API changes.
#### Wrap `v8::Global::open()` calls in `unsafe {}`
V8 152 marked `Global::open()` as unsafe. Affected files:
- `error.rs` (2 locations)
- `modules/map.rs` (9 locations)
- `runtime/jsrealm.rs` (1 location)
- `runtime/jsruntime.rs` (3 locations)
- `ops_builtin_v8.rs` (1 location)
Example:
```rust
// Before:
let cb = callback.open(scope);
// After:
let cb = unsafe { callback.open(scope) };
```
#### Disable fast-call path in `runtime/bindings.rs`
Fast-call API causes SIGILL on RISC-V during snapshot creation:
```rust
// Replace lines ~600-605:
let template = builder.build(scope);
// (Remove the if/else with fast_function)
```
#### Update `WasmStreaming` in `ops_builtin.rs`
```rust
// Before:
pub struct WasmStreamingResource(pub(crate) RefCell<v8::WasmStreaming>);
// After:
pub struct WasmStreamingResource(pub(crate) RefCell<v8::WasmStreaming<false>>);
```
#### Update ICU data in `runtime/setup.rs`
The initializer name and the data blob must match (see the
`deno_core_icudata` bump above) — `set_common_data_78` rejects the ICU 77
blob and V8 initialization fails.
```rust
// Line ~19:
v8::icu::set_common_data_78(deno_core_icudata::ICU_DATA).unwrap();
// was: set_common_data_77
// Line ~24 - remove this line:
" --no-validate-asm", // Remove - V8 13+ doesn't support this flag
```
### 6. Update Root Cargo.toml
Add workspace exclusion and patches:
```toml
[workspace]
members = ["crates/*"] # drop "vendor/v8" (see step 4)
exclude = ["vendor/v8", "vendor/rusty_v8"]
resolver = "2"
# Relax ICU pins (temporal 0.2.6 handles this):
icu_calendar = { version = ">=2.1", default-features = false }
icu_locale = { version = ">=2.1", default-features = false }
[patch.crates-io]
deno_core = { path = "vendor/deno_core" }
serde_v8 = { path = "vendor/serde_v8" }
v8 = { path = "vendor/rusty_v8" } # was vendor/v8; rusty_v8 is the v8 crate
# ... existing patches
```
### 7. Update crates/goose/Cargo.toml
Relax ICU pins:
```toml
icu_calendar = { version = ">=2.1", default-features = false }
icu_locale = { version = ">=2.1", default-features = false }
```
### 8. RISC-V Update Command Handling (already in repo)
`crates/goose-cli/src/commands/update.rs` already handles RISC-V:
- `asset_name()` includes the riscv64gc-gnu asset name so the function
compiles on RISC-V (otherwise every branch is cfg-disabled and the body
would evaluate to `()` instead of `&'static str`).
- `update()` bails early on riscv64 with a clear error, because release
artifacts are not published for this platform yet:
```rust
#[cfg(all(target_arch = "riscv64", not(feature = "disable-update")))]
{
bail!("Self-update is not supported on riscv64: no release artifacts are published for this platform.");
}
```
Once RISC-V assets are added to the release pipeline, remove that bail
block and drop `not(target_arch = "riscv64")` from the main branch.
Because the bail makes the rest of the module cfg-disabled on riscv64,
the file also carries a module-level allow so `clippy -D warnings` stays
clean for RISC-V builds (inert on other targets):
```rust
#![cfg_attr(target_arch = "riscv64", allow(dead_code, unused_imports, unused_variables))]
```
### 9. Update Dependencies
Update only the dependencies this setup changes, not the whole lockfile:
```bash
cargo update deno_core_icudata icu_calendar icu_locale temporal_rs
```
Expected changes:
- v8: 145.0.0 → 152.2.0 (local, via the patch)
- deno_core_icudata: 0.77.0 → 0.78.0
- temporal_rs: 0.1.2 → 0.2.6
- icu_calendar: 2.1.1 → 2.3.0
### 10. Build
```bash
cargo build --release --target riscv64gc-unknown-linux-gnu -p goose-cli --bin goose
```
Output: `target/riscv64gc-unknown-linux-gnu/release/goose`
## Complete Patch Script
See `scripts/setup-riscv.sh` for automated setup.
## Known Issues
- Fast-call optimization disabled (SIGILL on RISC-V snapshot creation)
- Patches affect all platforms when using vendored deno_core
- Adds ~2.6MB vendor dependencies to repository
## Alternative: Conditional Compilation
For production PR, consider:
1. Keep deno_core/serde_v8 patches in separate git branch
2. Document manual setup steps
3. Only commit minimal changes (update.rs, CI workflow)
4. Let users apply patches locally for RISC-V builds
## Verification
```bash
# Check architecture
file target/riscv64gc-unknown-linux-gnu/release/goose
# Output: ELF 64-bit LSB pie executable, UCB RISC-V
# Test execution (on RISC-V hardware)
./target/riscv64gc-unknown-linux-gnu/release/goose --version
./target/riscv64gc-unknown-linux-gnu/release/goose doctor
```
+22 -1
View File
@@ -1,3 +1,11 @@
// On riscv64, update() bails early because no release artifacts are published,
// so the implementation below (and most of this module) is cfg-disabled and
// would otherwise trigger dead_code/unused warnings that fail clippy.
#![cfg_attr(
target_arch = "riscv64",
allow(dead_code, unused_imports, unused_variables)
)]
use anyhow::{bail, Context, Result};
use reqwest::{
header::{HeaderValue, AUTHORIZATION},
@@ -38,6 +46,12 @@ fn asset_name() -> &'static str {
{
"goose-aarch64-unknown-linux-musl.tar.bz2"
}
// RISC-V builds compile with this asset name, but update() rejects the
// platform until release artifacts are published. See update() below.
#[cfg(all(target_os = "linux", target_arch = "riscv64", target_env = "gnu"))]
{
"goose-riscv64gc-unknown-linux-gnu.tar.bz2"
}
#[cfg(all(target_os = "windows", target_arch = "x86_64", feature = "cuda"))]
{
"goose-x86_64-pc-windows-msvc-cuda.zip"
@@ -297,7 +311,14 @@ pub async fn update(canary: bool, reconfigure: bool) -> Result<()> {
bail!("Update is disabled in this build.");
}
#[cfg(not(feature = "disable-update"))]
// RISC-V release artifacts are not published yet, so reject self-update
// rather than downloading a nonexistent asset.
#[cfg(all(target_arch = "riscv64", not(feature = "disable-update")))]
{
bail!("Self-update is not supported on riscv64: no release artifacts are published for this platform.");
}
#[cfg(all(not(target_arch = "riscv64"), not(feature = "disable-update")))]
{
let tag = if canary { "canary" } else { "stable" };
let asset = asset_name();
+234
View File
@@ -0,0 +1,234 @@
#!/usr/bin/env bash
# Experimental, community-contributed RISC-V setup. This configuration is not
# officially supported by the goose project.
# This script vendors dependencies and applies necessary patches for V8 152.2.0.
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
VENDOR_DIR="$REPO_ROOT/vendor"
RUSTY_V8_COMMIT="2768994f664e8a6e3aba27503606c58339136e2a"
DENO_CORE_SHA256="77660b04f5368bcd69a42e0fdd6343e325eb781ec7d79bbf49ff2548ae4f17b6"
SERDE_V8_SHA256="21a52aca5a5661aea9c2ccf8c2f985f2381266d7aab03a0d02beadb4ae1190ea"
verify_sha256() {
local file="$1"
local expected="$2"
local actual
if command -v sha256sum > /dev/null 2>&1; then
actual="$(sha256sum "$file" | awk '{print $1}')"
elif command -v shasum > /dev/null 2>&1; then
actual="$(shasum -a 256 "$file" | awk '{print $1}')"
else
echo "Error: sha256sum or shasum is required to verify downloads" >&2
return 1
fi
if [ "$actual" != "$expected" ]; then
echo "Error: SHA-256 mismatch for $file" >&2
echo "Expected: $expected" >&2
echo "Actual: $actual" >&2
return 1
fi
}
echo "=== Setting up goose for RISC-V build ==="
echo "Repository: $REPO_ROOT"
echo ""
# 1. Clone rusty_v8
echo "1. Cloning rusty_v8 commit $RUSTY_V8_COMMIT (v152.2.0)..."
if [ -d "$VENDOR_DIR/rusty_v8" ]; then
echo " Already exists, skipping..."
else
git -C "$VENDOR_DIR" init rusty_v8
git -C "$VENDOR_DIR/rusty_v8" remote add origin https://github.com/denoland/rusty_v8.git
git -C "$VENDOR_DIR/rusty_v8" fetch --depth 1 origin "$RUSTY_V8_COMMIT"
git -C "$VENDOR_DIR/rusty_v8" checkout --detach FETCH_HEAD
rm -rf "$VENDOR_DIR/rusty_v8/.git"
echo " ✓ Done"
fi
# 2. Vendor deno_core
echo "2. Vendoring deno_core 0.381.1..."
if [ -d "$VENDOR_DIR/deno_core" ]; then
echo " Already exists, skipping..."
else
cd "$VENDOR_DIR"
wget -q https://static.crates.io/crates/deno_core/deno_core-0.381.1.crate
verify_sha256 deno_core-0.381.1.crate "$DENO_CORE_SHA256"
tar xzf deno_core-0.381.1.crate
mv deno_core-0.381.1 deno_core
rm deno_core-0.381.1.crate
echo " ✓ Done"
fi
# 3. Vendor serde_v8
echo "3. Vendoring serde_v8 0.290.0..."
if [ -d "$VENDOR_DIR/serde_v8" ]; then
echo " Already exists, skipping..."
else
cd "$VENDOR_DIR"
wget -q https://static.crates.io/crates/serde_v8/serde_v8-0.290.0.crate
verify_sha256 serde_v8-0.290.0.crate "$SERDE_V8_SHA256"
tar xzf serde_v8-0.290.0.crate
mv serde_v8-0.290.0 serde_v8
rm serde_v8-0.290.0.crate
echo " ✓ Done"
fi
# 4. vendor/v8
# Nothing to patch: the cloned vendor/rusty_v8 IS the `v8` crate at 152.2.0,
# so step 8 points `[patch.crates-io] v8` straight at it. The committed
# vendor/v8 shim is left alone (it stays a workspace member for cargo-machete
# but nothing depends on it once the patch is redirected).
echo "4. vendor/v8: using cloned rusty_v8 directly, nothing to patch"
# 5. Update deno_core v8 dependency
echo "5. Updating deno_core v8 dependency to 152.2.0..."
sed -i 's/version = "145\.0\.0"/version = "152.2.0"/' "$VENDOR_DIR/deno_core/Cargo.toml"
echo " ✓ Done"
# 6. Update serde_v8 v8 dependency
echo "6. Updating serde_v8 v8 dependency to 152.2.0..."
sed -i 's/version = "145\.0\.0"/version = "152.2.0"/' "$VENDOR_DIR/serde_v8/Cargo.toml"
echo " ✓ Done"
# 7. Apply deno_core source patches
echo "7. Applying deno_core source patches for V8 152 API..."
# Wrap .open() calls in unsafe
sed -i 's/let format_exception_cb = format_exception_cb\.open(scope);/let format_exception_cb = unsafe { format_exception_cb.open(scope) };/' "$VENDOR_DIR/deno_core/error.rs"
sed -i 's/let cb = cb\.open(tc_scope);/let cb = unsafe { cb.open(tc_scope) };/' "$VENDOR_DIR/deno_core/error.rs"
sed -i 's/let resolver = resolver_handle\.open(scope);/let resolver = unsafe { resolver_handle.open(scope) };/g' "$VENDOR_DIR/deno_core/modules/map.rs"
sed -i 's/let module = module_handle\.open(scope);/let module = unsafe { module_handle.open(scope) };/g' "$VENDOR_DIR/deno_core/modules/map.rs"
sed -i 's/let promise = pending_dyn_evaluate\.promise\.open(scope);/let promise = unsafe { pending_dyn_evaluate.promise.open(scope) };/g' "$VENDOR_DIR/deno_core/modules/map.rs"
sed -i 's/let _module = pending_dyn_evaluate\.module\.open(scope);/let _module = unsafe { pending_dyn_evaluate.module.open(scope) };/g' "$VENDOR_DIR/deno_core/modules/map.rs"
sed -i 's/let resolver = state\.resolver\.open(scope);/let resolver = unsafe { state.resolver.open(scope) };/g' "$VENDOR_DIR/deno_core/modules/map.rs"
sed -i 's/let ctx = self\.context()\.open(scope);/let ctx = unsafe { self.context().open(scope) };/g' "$VENDOR_DIR/deno_core/runtime/jsrealm.rs"
sed -i 's/let cb = function\.open(scope);/let cb = unsafe { function.open(scope) };/g' "$VENDOR_DIR/deno_core/runtime/jsruntime.rs"
sed -i 's/run_immediate_callbacks_cb\.as_ref()\.unwrap()\.open(tc_scope);/unsafe { run_immediate_callbacks_cb.as_ref().unwrap().open(tc_scope) };/g' "$VENDOR_DIR/deno_core/runtime/jsruntime.rs"
sed -i 's/let function = handler\.open(scope);/let function = unsafe { handler.open(scope) };/g' "$VENDOR_DIR/deno_core/runtime/jsruntime.rs"
sed -i 's/js_event_loop_tick_cb\.as_ref()\.unwrap()\.open(tc_scope);/unsafe { js_event_loop_tick_cb.as_ref().unwrap().open(tc_scope) };/g' "$VENDOR_DIR/deno_core/runtime/jsruntime.rs"
# Fix ops_builtin_v8.rs - multiline sed
sed -i '/cb_handle$/{ N; s/cb_handle\n \.open(scope)/unsafe { cb_handle.open(scope) }/; }' "$VENDOR_DIR/deno_core/ops_builtin_v8.rs"
# Disable fast-call path in bindings.rs: replace the whole if/else block
# with the fallback assignment (c on an address range replaces all of it)
sed -i '/let template = if let Some(fast_function)/,/};/c\
// Disable fast path for v8 152 - causes SIGILL on RISC-V snapshot creation\
let template = builder.build(scope);' "$VENDOR_DIR/deno_core/runtime/bindings.rs"
# With the fast path disabled, the fast_fn binding above is unused; silence
# the resulting warning so clippy -D warnings stays clean.
sed -i 's/^ let (slow_fn, fast_fn) = / let (slow_fn, _fast_fn) = /' "$VENDOR_DIR/deno_core/runtime/bindings.rs"
# Update WasmStreaming generic
sed -i 's/pub struct WasmStreamingResource(pub(crate) RefCell<v8::WasmStreaming>);/pub struct WasmStreamingResource(pub(crate) RefCell<v8::WasmStreaming<false>>);/' "$VENDOR_DIR/deno_core/ops_builtin.rs"
# ICU 77 -> 78: V8 152 bundles ICU 78, so the initializer name AND the data
# blob must both move. deno_core_icudata 0.78.0 ships the matching ICU 78 data;
# passing the 0.77.0 blob to set_common_data_78 fails V8 initialization.
sed -i 's/set_common_data_77/set_common_data_78/' "$VENDOR_DIR/deno_core/runtime/setup.rs"
sed -i 's/^version = "0\.77\.0"$/version = "0.78.0"/' "$VENDOR_DIR/deno_core/Cargo.toml"
# Remove --no-validate-asm flag
sed -i 's/" --no-validate-asm",//' "$VENDOR_DIR/deno_core/runtime/setup.rs"
echo " ✓ Done"
# 8. Update root Cargo.toml
echo "8. Updating root Cargo.toml..."
cd "$REPO_ROOT"
# Drop the vendor/v8 shim from the workspace and exclude it plus rusty_v8.
# The shim pulls in `v8-goose`, which declares `links = "rusty_v8"`; once the
# patch below resolves denoland's `v8` 152 (also `links = "rusty_v8"`), a
# workspace containing both fails with "more than one crate with
# links=rusty_v8". Use awk for portability (GNU/BSD sed multi-line differs).
if ! grep -q '^exclude = \[' Cargo.toml; then
awk '
/^members = \[/ { in_members = 1 }
in_members && /cargo-machete/ { next }
in_members && /"vendor\/v8"/ { next }
in_members && /^\]$/ {
print
print "exclude = [\"vendor/v8\", \"vendor/rusty_v8\"]"
in_members = 0
next
}
{ print }
' Cargo.toml > Cargo.toml.new
mv Cargo.toml.new Cargo.toml
fi
# Relax ICU pins
sed -i 's/icu_calendar = { version = "=2\.1\.1"/icu_calendar = { version = ">=2.1"/' Cargo.toml
sed -i 's/icu_locale = { version = "=2\.1\.1"/icu_locale = { version = ">=2.1"/' Cargo.toml
# Add deno_core/serde_v8 patches and repoint the existing `v8` patch at the
# cloned rusty_v8 (same crate name, version 152.2.0). Multi-line sed `a\` is
# fragile across sed implementations, so use awk.
if ! grep -q 'vendor/deno_core' Cargo.toml; then
awk '
/^\[patch\.crates-io\]$/ {
print
print "deno_core = { path = \"vendor/deno_core\" }"
print "serde_v8 = { path = \"vendor/serde_v8\" }"
next
}
/^v8 = \{ path = "vendor\/v8" \}$/ {
print "v8 = { path = \"vendor/rusty_v8\" }"
next
}
{ print }
' Cargo.toml > Cargo.toml.new
mv Cargo.toml.new Cargo.toml
fi
echo " ✓ Done"
# 9. Update crates/goose/Cargo.toml
echo "9. Updating crates/goose/Cargo.toml..."
sed -i 's/icu_calendar = { version = "=2\.1\.1"/icu_calendar = { version = ">=2.1"/' "$REPO_ROOT/crates/goose/Cargo.toml"
sed -i 's/icu_locale = { version = "=2\.1\.1"/icu_locale = { version = ">=2.1"/' "$REPO_ROOT/crates/goose/Cargo.toml"
echo " ✓ Done"
# Note: update.rs already handles RISC-V (asset name + self-update bail) in
# the repo, so no patching is needed here.
# 10. Update dependencies
# Re-resolve only what this setup changes: the ICU-78 data blob and the
# ICU/temporal crates freed by the relaxed pins. The patched path crates
# (v8, deno_core, serde_v8) are picked up by the build itself. A bare
# `cargo update` would drift every eligible dependency.
echo "10. Updating Cargo dependencies..."
cd "$REPO_ROOT"
cargo update --quiet deno_core_icudata icu_calendar icu_locale temporal_rs
echo " ✓ Done"
# 11. Verify toolchain is available.
echo "11. Checking RISC-V toolchain..."
if [ "$(uname -m)" = "riscv64" ]; then
echo " ✓ native RISC-V build - no cross toolchain needed"
elif command -v riscv64-linux-gnu-gcc > /dev/null 2>&1; then
echo " ✓ riscv64-linux-gnu-gcc found"
echo " For cross-compiling, export before building:"
echo " export CARGO_TARGET_RISCV64GC_UNKNOWN_LINUX_GNU_LINKER=riscv64-linux-gnu-gcc"
else
echo " ⚠ riscv64-linux-gnu-gcc not found"
echo " Install it (e.g. 'sudo apt install gcc-riscv64-linux-gnu') and set:"
echo " export CARGO_TARGET_RISCV64GC_UNKNOWN_LINUX_GNU_LINKER=riscv64-linux-gnu-gcc"
fi
echo ""
echo "=== Setup complete! ==="
echo ""
echo "To build for RISC-V:"
echo " cargo build --release --target riscv64gc-unknown-linux-gnu -p goose-cli --bin goose"
echo ""
echo "Output binary:"
echo " target/riscv64gc-unknown-linux-gnu/release/goose"