Building from Source
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Building opcode from source allows developers to create custom binaries for various platforms, including Windows, macOS, and Linux. The project utilizes a cross-language architecture combining a React/TypeScript frontend with a Rust backend via the Tauri 2 framework. This process ensures that all security features, such as process isolation and local storage management, are correctly compiled into the final executable.
Sources: README.md:144-148, web_server.design.md:12-20
Prerequisites
Before initiating the build, several system-level tools and environment configurations must be present.
System Requirements
| Component | Requirement |
|---|---|
| Operating System | Windows 10/11, macOS 11+, or Linux (Ubuntu 20.04+) |
| RAM | Minimum 4GB (8GB recommended) |
| Storage | At least 1GB free space |
Sources: README.md:188-192
Required Toolchain
- Rust: Version 1.70.0 or later is required to compile the backend logic and Tauri commands.
- Bun: The latest version is used as the primary package manager and runtime for frontend tasks.
- Claude Code CLI: Must be installed and available in the system
PATHas the application acts as a GUI wrapper for this tool. - Git: Used for repository cloning and version control.
Sources: README.md:194-211, package.json:11-16
Platform-Specific Dependencies
Different operating systems require specific libraries to support the Tauri webview and system integration:
- Linux (Ubuntu/Debian): Requires
libwebkit2gtk-4.1-dev,libgtk-3-dev, andbuild-essential. - macOS: Requires Xcode Command Line Tools and optionally
pkg-config. - Windows: Requires Microsoft C++ Build Tools and WebView2 runtime.
Sources: README.md:215-241, src-tauri/tauri.conf.json:84-86
Build Architecture
The build process synchronizes the compilation of the frontend assets into a distribution directory which is then embedded into the Rust-based system binary.
The diagram above illustrates the multi-stage pipeline where frontend assets are bundled by Vite before being consumed by the Cargo build process.
Sources: README.md:244-266, src-tauri/tauri.conf.json:7-11
Execution Steps
1. Preparation
Clone the repository and install the Node.js dependencies specified in package.json.
git clone https://github.com/getAsterisk/opcode.git
cd opcode
bun install
Sources: README.md:244-253
2. Development Build
To run the application with hot-reloading for both frontend and backend code:
bun run tauri dev
Sources: README.md:257-259, package.json:10
3. Production Compilation
Generating the optimized release binary involves running the Tauri build command. This command triggers the beforeBuildCommand (bun run build) which runs tsc and vite build.
bun run tauri build
Sources: README.md:262-264, src-tauri/tauri.conf.json:9
4. Specialized Build Options
The project supports various build targets and modes:
- Debug Production:
bun run tauri build --debug(larger binary, faster compilation). - Universal macOS:
bun run tauri build --target universal-apple-darwin. - Web Server Mode:
just web(builds the Axum-based Rust server for browser access).
Sources: README.md:271-278, web_server.design.md:88-91
Build Artifacts
Upon successful completion, artifacts are located in src-tauri/target/release/.
| Platform | Executable | Installer(s) |
|---|---|---|
| Linux | opcode | .deb, .AppImage, .rpm |
| macOS | opcode.app | .dmg |
| Windows | opcode.exe | .msi, .exe |
Sources: README.md:301-314, src-tauri/tauri.conf.json:57-63
Troubleshooting Common Build Failures
Developers may encounter issues related to missing environment variables or toolchain mismatches.
| Error | Resolution |
|---|---|
"cargo not found" | Ensure ~/.cargo/bin is in PATH; run source ~/.cargo/env. |
"webkit2gtk not found" | Install libwebkit2gtk-4.1-dev (Linux only). |
"claude command not found" | Install Claude Code CLI and verify with claude --version. |
| Out of Memory | Reduce parallel jobs using cargo build -j 2. |
Sources: README.md:282-300
Conclusion
Building opcode from source is a streamlined process managed by Bun and Cargo. By adhering to the platform-specific dependency requirements and using the Tauri CLI, developers can produce high-performance, secure desktop applications or web-accessible servers tailored to their specific environment.
Sources: README.md:320-330, CONTRIBUTING.md:46-53