# ARM64 Pi Build Troubleshooting Notes

## Current Status (2025-10-22)

**Goal:** Automate ARM64 cross-compilation for Raspberry Pi via SSH using `build-pi.ts`

**Current Issue:** `pkg-config` PATH problem during Cargo build

### Problem Summary

The build script (`build-pi.ts`) successfully:
- ✅ Connects to Pi via SSH (pi4c)
- ✅ Copies source files to `/tmp/msger-native-build`
- ✅ Detects/installs Rust/Cargo
- ✅ Detects `pkg-config` is installed (via `command -v pkg-config`)
- ✅ Verifies GTK dependencies exist (via `pkg-config --exists gtk+-3.0 webkit2gtk-4.0`)
- ✅ Starts cargo build

BUT fails because:
- ❌ Cargo's build scripts cannot find `pkg-config` in PATH
- ❌ Even though `pkg-config` exists in the shell, cargo subprocesses don't inherit the PATH correctly

### Error Details

```
error: failed to run custom build command for `gdk-sys v0.18.2`
Could not run `PKG_CONFIG_PATH=... pkg-config --libs --cflags gdk-3.0 'gdk-3.0 >= 3.22'`
The pkg-config command could not be found.
```

This happens for multiple crates:
- `gdk-sys v0.18.2`
- `glib-sys v0.18.1`
- `gobject-sys v0.18.0`
- `gio-sys v0.18.1`

### Root Cause

When cargo runs build scripts (build.rs files), it spawns subprocesses that don't properly inherit the PATH from the SSH session. The current build command (line 70 in `build-pi.ts`):

```bash
ssh pi4c "cd /tmp/msger-native-build && export PATH=~/.cargo/bin:\$PATH && export PKG_CONFIG_PATH=/usr/lib/aarch64-linux-gnu/pkgconfig:/usr/share/pkgconfig && cargo build --release"
```

The PATH only prepends `~/.cargo/bin` but doesn't include `/usr/bin` where `pkg-config` is actually installed.

### Attempted Solutions

1. ✅ **Fixed dependency order** - Moved `pkg-config` installation check BEFORE GTK dependency check
   - Lines 45-54: Now checks/installs `pkg-config` first
   - Lines 56-65: Then checks/installs GTK dependencies

2. ⏳ **PATH fix needed** - Need to add `/usr/bin` to PATH in cargo build command

### Required Fix

**File:** `build-pi.ts` line 70

**Current:**
```typescript
execSync(`ssh ${PI_HOST} "cd ${PI_BUILD_DIR} && export PATH=~/.cargo/bin:\\$PATH && export PKG_CONFIG_PATH=/usr/lib/aarch64-linux-gnu/pkgconfig:/usr/share/pkgconfig && cargo build --release"`, { stdio: 'inherit' });
```

**Change to:**
```typescript
execSync(`ssh ${PI_HOST} "cd ${PI_BUILD_DIR} && export PATH=/usr/bin:/usr/local/bin:~/.cargo/bin:\\$PATH && export PKG_CONFIG=/usr/bin/pkg-config && export PKG_CONFIG_PATH=/usr/lib/aarch64-linux-gnu/pkgconfig:/usr/share/pkgconfig && cargo build --release"`, { stdio: 'inherit' });
```

**Changes:**
1. Add `/usr/bin:/usr/local/bin:` to the beginning of PATH
2. Add `export PKG_CONFIG=/usr/bin/pkg-config` to explicitly point to pkg-config binary

### Alternative Solutions to Try

If the above doesn't work, consider these alternatives:

1. **Use full path in PKG_CONFIG environment variable:**
   ```bash
   export PKG_CONFIG=$(which pkg-config)
   ```

2. **Install pkg-config to a location cargo can find:**
   ```bash
   # Link pkg-config to /usr/local/bin if it's not there
   sudo ln -s /usr/bin/pkg-config /usr/local/bin/pkg-config
   ```

3. **Use cargo's config.toml to set environment:**
   Create `.cargo/config.toml` on the Pi with:
   ```toml
   [env]
   PKG_CONFIG = "/usr/bin/pkg-config"
   PKG_CONFIG_PATH = "/usr/lib/aarch64-linux-gnu/pkgconfig:/usr/share/pkgconfig"
   ```

4. **SSH with login shell to inherit full PATH:**
   ```bash
   ssh pi4c "bash -l -c 'cd /tmp/msger-native-build && cargo build --release'"
   ```

### Files Modified

- `Y:/dev/utils/msger/msger-native/build-pi.ts` - Main build script
  - Fixed pkg-config dependency order (lines 45-65)
  - Still needs PATH fix at line 70

### Pi Environment Info

- **Host:** pi4c
- **Architecture:** aarch64-unknown-linux-gnu
- **Rust Version:** 1.90.0 (1159e78c4 2025-09-14)
- **Build Directory:** `/tmp/msger-native-build`

### Dependencies Required

- `pkg-config` - ✅ Installed
- `libgtk-3-dev` - ✅ Installed
- `libwebkit2gtk-4.0-dev` - ✅ Installed
- `libsoup2.4-dev` - ✅ Installed
- Rust/Cargo - ✅ Installed

### Next Steps

1. Apply the PATH fix to line 70 of `build-pi.ts`
2. Test the build again
3. If still fails, try alternative solutions listed above
4. Consider creating a setup script on the Pi that persists environment variables
5. Document successful solution in copilot-session-summary.md

### Related Files

- `build-pi.ts` - Main build script
- `copilot-session-summary.md` - Project overview and session history
- `build-arm64.ts` - Alternative ARM64 build approach (cross-compilation)
- `Cargo.toml` - Rust dependencies (includes GTK/WebKit bindings)

### Debug Commands

To debug on the Pi directly:
```bash
# SSH to Pi
ssh pi4c

# Check pkg-config location
which pkg-config
# Should output: /usr/bin/pkg-config

# Check PATH during cargo build
cd /tmp/msger-native-build
export PATH=/usr/bin:/usr/local/bin:~/.cargo/bin:$PATH
export PKG_CONFIG=/usr/bin/pkg-config
export PKG_CONFIG_PATH=/usr/lib/aarch64-linux-gnu/pkgconfig:/usr/share/pkgconfig
cargo build --release --verbose
```

### Notes

- VS Code auto-save was interfering with file edits during troubleshooting
- The `command -v pkg-config` check succeeds, but cargo subprocesses can't find it
- This is a common issue with cargo build scripts and SSH environment inheritance
- The fix is well-documented in Rust community but needs to be applied to this specific setup
