From 31f5f9ce7697a2ace774b86b73eabf1bbe7dce51 Mon Sep 17 00:00:00 2001 From: jasonwitty Date: Fri, 29 Aug 2025 11:23:41 -0700 Subject: [PATCH] re: Accessibility: Cross-compile guide --- README.md | 6 ++ docs/cross-compiling.md | 204 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 210 insertions(+) create mode 100644 docs/cross-compiling.md diff --git a/README.md b/README.md index fbfc897..ea5d2bc 100644 --- a/README.md +++ b/README.md @@ -94,6 +94,12 @@ cargo build --release ./target/release/socktop ws://REMOTE_HOST:3000/ws ``` +### Cross-compiling for Raspberry Pi + +For Raspberry Pi and other ARM devices, you can cross-compile the agent from a more powerful machine: + +- [Cross-compilation guide](./docs/cross-compiling.md) - Instructions for cross-compiling from Linux, macOS, or Windows hosts + ### Quick demo (no agent setup) Spin up a temporary local agent on port 3231 and connect automatically: diff --git a/docs/cross-compiling.md b/docs/cross-compiling.md new file mode 100644 index 0000000..d0ce42d --- /dev/null +++ b/docs/cross-compiling.md @@ -0,0 +1,204 @@ +# Cross-Compiling socktop_agent for Raspberry Pi + +This guide explains how to cross-compile the socktop_agent on various host systems and deploy it to a Raspberry Pi. Cross-compiling is particularly useful for older or resource-constrained Pi models where native compilation might be slow. + +## Cross-Compilation Host Setup + +Choose your host operating system: + +- [Debian/Ubuntu](#debianubuntu-based-systems) +- [Arch Linux](#arch-linux-based-systems) +- [macOS](#macos) +- [Windows](#windows) + +## Debian/Ubuntu Based Systems + +### Prerequisites + +Install the cross-compilation toolchain for your target Raspberry Pi architecture: + +```bash +# For 64-bit Raspberry Pi (aarch64) +sudo apt update +sudo apt install gcc-aarch64-linux-gnu libc6-dev-arm64-cross libdrm-dev:arm64 + +# For 32-bit Raspberry Pi (armv7) +sudo apt update +sudo apt install gcc-arm-linux-gnueabihf libc6-dev-armhf-cross libdrm-dev:armhf +``` + +### Setup Rust Cross-Compilation Targets + +```bash +# For 64-bit Raspberry Pi +rustup target add aarch64-unknown-linux-gnu + +# For 32-bit Raspberry Pi +rustup target add armv7-unknown-linux-gnueabihf +``` + +### Configure Cargo for Cross-Compilation + +Create or edit `~/.cargo/config.toml`: + +```toml +[target.aarch64-unknown-linux-gnu] +linker = "aarch64-linux-gnu-gcc" + +[target.armv7-unknown-linux-gnueabihf] +linker = "arm-linux-gnueabihf-gcc" +``` + +## Arch Linux Based Systems + +### Prerequisites + +Install the cross-compilation toolchain using pacman and AUR: + +```bash +# Install base dependencies +sudo pacman -S base-devel + +# For 64-bit Raspberry Pi (aarch64) +sudo pacman -S aarch64-linux-gnu-gcc +# Install libdrm for aarch64 using an AUR helper (e.g., yay, paru) +yay -S aarch64-linux-gnu-libdrm + +# For 32-bit Raspberry Pi (armv7) +sudo pacman -S arm-linux-gnueabihf-gcc +# Install libdrm for armv7 using an AUR helper +yay -S arm-linux-gnueabihf-libdrm +``` + +### Setup Rust Cross-Compilation Targets + +```bash +# For 64-bit Raspberry Pi +rustup target add aarch64-unknown-linux-gnu + +# For 32-bit Raspberry Pi +rustup target add armv7-unknown-linux-gnueabihf +``` + +### Configure Cargo for Cross-Compilation + +Create or edit `~/.cargo/config.toml`: + +```toml +[target.aarch64-unknown-linux-gnu] +linker = "aarch64-linux-gnu-gcc" + +[target.armv7-unknown-linux-gnueabihf] +linker = "arm-linux-gnueabihf-gcc" +``` + +## macOS + +The recommended approach for cross-compiling from macOS is to use Docker: + +```bash +# Install Docker +brew install --cask docker + +# Pull a cross-compilation Docker image +docker pull messense/rust-musl-cross:armv7-musleabihf # For 32-bit Pi +docker pull messense/rust-musl-cross:aarch64-musl # For 64-bit Pi +``` + +### Using Docker for Cross-Compilation + +```bash +# Navigate to your socktop project directory +cd path/to/socktop + +# For 64-bit Raspberry Pi +docker run --rm -it -v "$(pwd)":/home/rust/src messense/rust-musl-cross:aarch64-musl cargo build --release --target aarch64-unknown-linux-musl -p socktop_agent + +# For 32-bit Raspberry Pi +docker run --rm -it -v "$(pwd)":/home/rust/src messense/rust-musl-cross:armv7-musleabihf cargo build --release --target armv7-unknown-linux-musleabihf -p socktop_agent +``` + +The compiled binaries will be available in your local target directory. + +## Windows + +The recommended approach for Windows is to use Windows Subsystem for Linux (WSL2): + +1. Install WSL2 with a Debian/Ubuntu distribution by following the [official Microsoft documentation](https://docs.microsoft.com/en-us/windows/wsl/install). + +2. Once WSL2 is set up with a Debian/Ubuntu distribution, open your WSL terminal and follow the [Debian/Ubuntu instructions](#debianubuntu-based-systems) above. + +## Cross-Compile the Agent + +After setting up your environment, build the socktop_agent for your target Raspberry Pi: + +```bash +# For 64-bit Raspberry Pi +cargo build --release --target aarch64-unknown-linux-gnu -p socktop_agent + +# For 32-bit Raspberry Pi +cargo build --release --target armv7-unknown-linux-gnueabihf -p socktop_agent +``` + +## Transfer the Binary to Your Raspberry Pi + +Use SCP to transfer the compiled binary to your Raspberry Pi: + +```bash +# For 64-bit Raspberry Pi +scp target/aarch64-unknown-linux-gnu/release/socktop_agent pi@raspberry-pi-ip:~/ + +# For 32-bit Raspberry Pi +scp target/armv7-unknown-linux-gnueabihf/release/socktop_agent pi@raspberry-pi-ip:~/ +``` + +Replace `raspberry-pi-ip` with your Raspberry Pi's IP address and `pi` with your username. + +## Install Dependencies on the Raspberry Pi + +SSH into your Raspberry Pi and install the required dependencies: + +```bash +ssh pi@raspberry-pi-ip + +# For Raspberry Pi OS (Debian-based) +sudo apt update +sudo apt install libdrm-dev libdrm-amdgpu1 + +# For Arch Linux ARM +sudo pacman -Syu +sudo pacman -S libdrm +``` + +## Make the Binary Executable and Install + +```bash +chmod +x ~/socktop_agent + +# Optional: Install system-wide +sudo install -o root -g root -m 0755 ~/socktop_agent /usr/local/bin/socktop_agent + +# Optional: Set up as a systemd service +sudo install -o root -g root -m 0644 ~/socktop-agent.service /etc/systemd/system/socktop-agent.service +sudo systemctl daemon-reload +sudo systemctl enable --now socktop-agent +``` + +## Troubleshooting + +If you encounter issues with the cross-compiled binary: + +1. **Incorrect Architecture**: Ensure you've chosen the correct target for your Raspberry Pi model: + - For Raspberry Pi 2: use `armv7-unknown-linux-gnueabihf` + - For Raspberry Pi 3/4/5 in 64-bit mode: use `aarch64-unknown-linux-gnu` + - For Raspberry Pi 3/4/5 in 32-bit mode: use `armv7-unknown-linux-gnueabihf` + +2. **Dependency Issues**: Check for missing libraries: + ```bash + ldd ~/socktop_agent + ``` + +3. **Run with Backtrace**: Get detailed error information: + ```bash + RUST_BACKTRACE=1 ~/socktop_agent + ```