# How to Build CodeWhale from Source for Unsupported Platforms: A Complete Guide

> Build CodeWhale from source for unsupported platforms. Install Rust, add your target triple, and compile with Cargo or use cross for automated cross-compilation. Complete guide available.

- Repository: [Hunter Bown/CodeWhale](https://github.com/Hmbown/CodeWhale)
- Tags: how-to-guide
- Published: 2026-06-02

---

**To build CodeWhale for any Rust-supported architecture, install the Rust toolchain, add your target triple with `rustup target add <target>`, and run `cargo build --release --target <target>` or use Docker-based `cross` for automated cross-compilation.**

CodeWhale is primarily distributed as pre-built binaries for Linux x86_64, macOS x86_64/arm64, and Windows x86_64. When targeting unsupported platforms—such as ARM64 Linux, RISC-V, s390x, or musl-based embedded systems—you must compile the Rust codebase yourself. Because CodeWhale is a pure-Rust project maintained in **Hmbown/CodeWhale** and defined in the root **[`Cargo.toml`](https://github.com/Hmbown/CodeWhale/blob/main/Cargo.toml)**, you can use standard Rust cross-compilation tooling to generate binaries for virtually any target the Rust compiler supports.

## Prerequisites

Before building, ensure you have the required tooling installed on your host machine.

- **Rust Toolchain:** Install `rustup`, `rustc`, and `cargo` via the official rustup script. This provides the compiler for both the host and target architectures.
- **Target Definition:** Add your specific target triple using `rustup target add <target>` (e.g., `aarch64-unknown-linux-gnu`).
- **Cross-Compiler/Linker:** For non-native builds, install the appropriate GCC cross-compiler (e.g., `gcc-aarch64-linux-gnu`) or the `musl` toolchain for static linking.
- **Cross (Optional):** Install `cross` via `cargo install cross` to automate Docker-based cross-compilation without manually configuring system libraries.
- **Docker:** Required only if using `cross` or the repository's **`Dockerfile.toolbox`** for containerized builds.

> **Tip:** If you use Nix, run `nix develop` in the repository root to enter a reproducible environment with the exact compiler and linker pinned in **`flake.nix`**, bypassing manual tool installation.

## Choosing Your Target Platform

Identify the correct Rust target triple for your unsupported platform. Common examples include:

| Platform | Rust Target Triple |
|----------|-------------------|
| Linux ARM64 | `aarch64-unknown-linux-gnu` |
| Linux musl (static) | `x86_64-unknown-linux-musl` |
| Linux RISC-V 64 | `riscv64gc-unknown-linux-gnu` |
| macOS ARM64 | `aarch64-apple-darwin` |
| Windows ARM64 | `aarch64-pc-windows-msvc` |

Add your chosen target to the Rust toolchain:

```bash
rustup target add aarch64-unknown-linux-gnu  # Replace with your target

```

## Building from Source

### Native Cross-Compilation

For targets where you have installed the appropriate linker (e.g., `gcc-aarch64-linux-gnu`), build directly with Cargo:

```bash
cargo build --release --target aarch64-unknown-linux-gnu \
    --features "default"

```

The compiled binary appears at `target/aarch64-unknown-linux-gnu/release/codewhale`. Adjust the `--features` flag based on platform capabilities, as defined in **[`Cargo.toml`](https://github.com/Hmbown/CodeWhale/blob/main/Cargo.toml)**.

### Using Cross (Docker-Based)

If you lack the native toolchain or sysroot, use **`cross`** to automate the process. The tool pulls pre-configured Docker images containing the correct libraries:

```bash

# Install cross once

cargo install cross

# Build without host dependencies

cross build --release --target aarch64-unknown-linux-gnu \
    --features "default"

```

`cross` mounts the source directory and produces output in `target/<triple>/release/` identical to native compilation.

### Static Linking for Maximum Portability

To create a standalone binary with no dynamic dependencies (ideal for container images or embedded systems), target **musl** instead of glibc:

```bash
rustup target add x86_64-unknown-linux-musl
cross build --release --target x86_64-unknown-linux-musl

```

Verify the result with `ldd`—it should report "not a dynamic executable," confirming static linking.

## Reproducible Builds with Nix

The **Hmbown/CodeWhale** repository includes a **`flake.nix`** that pins the exact Rust compiler version and cross-compilation toolchains. This eliminates "works on my machine" issues when building for unsupported platforms.

Enable flakes and enter the development shell:

```bash
mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf

nix develop .#aarch64-linux  # Attribute matches the target

cargo build --release --target aarch64-unknown-linux-gnu

```

The flake also provides pre-built cross-compilation environments (e.g., `#cross-aarch64-linux`) that work without Docker.

## Verifying and Packaging

### Verify Binary Architecture

Confirm the binary targets your intended architecture:

```bash
file target/aarch64-unknown-linux-gnu/release/codewhale

# Output: ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV), statically linked

```

Test execution via QEMU if the target differs from your host:

```bash
apt-get install qemu-user-static
qemu-aarch64-static target/aarch64-unknown-linux-gnu/release/codewhale --version

```

### Container Packaging

For distribution, package a musl static binary in a minimal container. Reference **`Dockerfile.toolbox`** or create a scratch-based image:

```dockerfile
FROM scratch
COPY --chmod=755 target/x86_64-unknown-linux-musl/release/codewhale /usr/local/bin/codewhale
ENTRYPOINT ["/usr/local/bin/codewhale"]

```

## Troubleshooting Common Issues

| Symptom | Cause | Solution |
|---------|-------|----------|
| **Linker errors** (e.g., "cannot find -lssl") | Missing OpenSSL development libraries in the target sysroot. | Switch to a musl static build, or install `libssl-dev:<arch>` for the target architecture. |
| **"linking with `cc` failed"** | Missing cross-compiler in `PATH`. | Install the matching `gcc-<arch>-linux-gnu` package, or use `cross` which bundles its own toolchain. |
| **Runtime "No such file or directory"** | Dynamic glibc mismatch between build host and target. | Rebuild using a musl target for static linking, or bundle required libraries in your deployment image. |
| **Feature compilation errors** | Enabled a platform-specific feature (e.g., Windows APIs) on an incompatible target. | Disable default features and selectively enable compatible ones: `cargo build --no-default-features --features "core"`. |

The **[`scripts/release/install.sh`](https://github.com/Hmbown/CodeWhale/blob/main/scripts/release/install.sh)** script and **[`.github/workflows/ci.yml`](https://github.com/Hmbown/CodeWhale/blob/main/.github/workflows/ci.yml)** provide working examples of environment setup and build commands used for officially supported platforms.

## Summary

- **CodeWhale** is a pure-Rust project that can compile for any architecture supported by the Rust compiler.
- Install the **Rust toolchain**, add your **target triple**, and ensure a matching **cross-compiler** is available.
- Use **`cargo build --release --target <triple>`** for native cross-compilation or **`cross build`** for Docker-based automation.
- Target **musl** targets (e.g., `x86_64-unknown-linux-musl`) for fully static binaries with zero dynamic dependencies.
- Leverage the **`flake.nix`** in the repository for reproducible build environments without manual dependency management.
- Verify binaries with `file` and `ldd` before deployment to ensure they match your target platform.

## Frequently Asked Questions

### Can I build CodeWhale for 32-bit ARM or PowerPC?

Yes. CodeWhale can target any architecture supported by Rust, including `armv7-unknown-linux-gnueabihf` or `powerpc64-unknown-linux-gnu`. Add the target with `rustup target add` and ensure you have the corresponding cross-compiler installed (e.g., `gcc-arm-linux-gnueabihf`), then run `cargo build --release --target <triple>`.

### Why does my binary fail to run with "No such file or directory" when the file exists?

This error typically indicates a dynamic linker mismatch. If you built against glibc on a system with a newer version than your target runtime, the required shared libraries are missing. Rebuild using a **musl** target (e.g., `x86_64-unknown-linux-musl`) to create a statically linked binary that has no external dependencies.

### Do I need to install OpenSSL separately on the target system?

Only if you build dynamically against glibc. The **[`Cargo.toml`](https://github.com/Hmbown/CodeWhale/blob/main/Cargo.toml)** configures OpenSSL linking based on features and target. For maximum portability, use the musl target which statically links OpenSSL via the `openssl` crate, eliminating the need for system SSL libraries on the target.

### What is the difference between using `cross` and the Nix flake?

**`cross`** uses Docker containers to provide isolated build environments with pre-configured sysroots, requiring Docker installation but no manual dependency management. The **`flake.nix`** provides a reproducible development shell that pins the exact compiler and linker versions directly on your host system without containers, offering faster iteration for Nix users.