add-tauri-sidecar

Files (1)

• SKILL.md

SKILL.md (first lines)

# Adding a Tauri Sidecar Binary

Sidecars are external executables bundled inside the `.app` and resolved at runtime. The project already uses this for `llama-server` and `fpcalc`. Follow the same pattern for any new binary.

> **Important**: if the binary depends on dynamic libraries (`.dylib`), there are extra macOS-specific steps around rpath patching and code signing. Read the full skill before starting.

---

## 1. Prepare the binary and its dylibs

### Simple binary (no dylib dependencies)

Copy the binary to `src-tauri/binaries/` with the **target-triple** suffix:

```
src-tauri/binaries/my-tool-aarch64-apple-darwin
```

```bash
chmod +x src-tauri/binaries/my-tool-aarch64-apple-darwin
```

### Binary with dylib dependencies (macOS)

If the binary links against `.dylib` files (check with `otool -L my-tool`), you must:

1. Copy the binary **and all its dylibs** into `src-tauri/binaries/`
2. Patch all hardcoded absolute rpath references to use `@rpath` / `@loader_path` instead
3. Add `@loader_path/../Frameworks` to the RPATH of every file so they find each other when Tauri bundles them into `Contents/Frameworks/`
4. Re-sign everything with your Apple Developer ID

**Use the helper script** `tools/bundle-llama-server.sh` as a reference — it does all of this for llama-server. Create a similar script for your binary.

The key `install_name_tool` operations each file needs:
```bash
# Replace Homebrew lib rpath with @loader_path
install_name_tool -rpath "/opt/homebrew/opt/foo/lib" "@loader_path" "$file"

# Add Frameworks rpath so bundled app finds dylibs in Contents/Frameworks/
install_name_tool -add_rpath "@loader_path/../Frameworks" "$file"

# Patch any remaining absolute /opt/homebrew/... install names → @rpath
install_name_tool -change "/opt/homebrew/opt/foo/lib/libfoo.dylib" "@rpath/libfoo.dylib" "$file"

# Re-sign (required after any install_name_tool modification)
codesign --force --options runtime --sign "Developer ID Application: Roberto Lupi (83BHH8484C)" "$file"
```

---

## 2. Declare in `tauri.conf.json`

```json
"bundle": {
  "externalBin": [
    "binaries/my-tool"
  ],
  "macOS": {
    "frameworks": [
      "binaries/libfoo.dylib",
      "binaries/libbar.0.dylib"
    ]
  }
}
```

**Critical**: dylib dependencies go in `bundle.macOS.frameworks`, **not** `bundle.resources`. The `frameworks` key places them in `Contents/Frameworks/` inside the `.app`, which is the path that `@loader_path/../Frameworks` in the rpath resolves to. Using `resources` puts them in the wrong location and causes a crash at runtime.

The path in `externalBin` is **without** the target-triple suffix — Tauri appends it automatically at bundle time.

---

## 3. Resolve the binary path at runtime in Rust

Do **not** use Tauri's `Command::sidecar()` API — this project resolves sidecar paths manually via `AppHandle`. Follow the pattern from `src-tauri/src/llama.rs` and `src-tauri/src/acoustid.rs`:

```rust
use tauri::{AppHandle, Manager};
use std::path::PathBuf;

fn get_my_tool_path(app: &AppHandle) -> Option<PathBuf> {
    #[cfg(target_arch = "aarch64")]
    const TARGET_ARCH: &str = "aarch64";
    #[cfg(target_arch = "x86_64")]
    const TARGET_ARCH: &str = "x86_64";

    #[cfg(target_os = "macos")]
    const TARGET_OS: &str = "apple-darwin";
    #[cfg(target_os = "linux")]
    const TARGET_OS: &str = "unknown-linux-gnu";
    #[cfg(target_os = "windows")]
    const TARGET_OS: &str = "pc-windows-msvc";

    let triple = format!("{}-{}", TARGET_ARCH, TARGET_OS);
    let filename = format!("my-tool-{}", triple);

    // 1. Next to the executable — production .app where Tauri strips the triple suffix
    if let Ok(exe_path) = std::env::current_exe() {
        if let Some(exe_dir) = exe_path.parent() {
            let p = exe_dir.join("my-tool");       // suffix-stripped name
            if p.exists() { return Some(p); }
            let p = exe_dir.join(&filename);        // triple-suffixed name (fallback)
            if p.exists() { return Some(p); }
        }
    }

    // 2. Resource dir — alternate production layout
    if let Ok(res_dir) = app.path().resource_dir() {
        let p = res_dir.join("binaries").join(&filename);
        if p.exists() { return Some(p); }
    }

    // 3. Dev paths relative to repo root (CARGO_MANIFEST_DIR points to src-tauri/)
    let dev_paths = vec![
        std::path::Path::new("src-tauri/binaries").join(&filename),
        std::path::Path::new("binaries").join(&filename),
    ];
    for p in dev_paths {
        if p.exists() { return Some(p); }

From robertolupi/deep-cuts, AGPL-3.0.

More from robertolupi/deep-cuts