Add binary build system for cross-platform distribution
- Add scripts/build.ts: Bun-based build script for generating binaries
- Support macOS (x64, ARM64, Universal), Windows (x64, ARM64), Linux (x64, ARM64)
- Add build:* npm scripts for each platform (build:mac, build:win, build:linux, etc)
- Configure electron-builder with platform-specific settings:
* macOS: DMG + ZIP, Universal binaries, proper icon paths
* Windows: NSIS installer + ZIP, configurable install directory
* Linux: AppImage + DEB + tar.gz packages
- Add BUILD.md: Comprehensive build documentation with examples
- Update README.md: Add build instructions and reference BUILD.md
- Artifacts named: OpenCode Client-{version}-{os}-{arch}.{ext}
- Output directory: release/
Usage:
bun run build:mac # macOS Universal (Intel + Apple Silicon)
bun run build:win # Windows x64
bun run build:linux # Linux x64
bun run build:all # All platforms
This commit is contained in:
Shantur Rathore
247
BUILD.md
Normal file
247
BUILD.md
Normal file
@@ -0,0 +1,247 @@
|
||||
# Building OpenCode Client Binaries
|
||||
|
||||
This guide explains how to build distributable binaries for OpenCode Client.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Bun** - Package manager and runtime
|
||||
- **Node.js** - For electron-builder
|
||||
- **Electron Builder** - Installed via devDependencies
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Build for Current Platform (macOS default)
|
||||
|
||||
```bash
|
||||
bun run build:binaries
|
||||
```
|
||||
|
||||
This builds for macOS (Universal - Intel + Apple Silicon) by default.
|
||||
|
||||
## Platform-Specific Builds
|
||||
|
||||
### macOS
|
||||
|
||||
```bash
|
||||
# Universal (Intel + Apple Silicon) - Recommended
|
||||
bun run build:mac
|
||||
|
||||
# Intel only (x64)
|
||||
bun run build:mac-x64
|
||||
|
||||
# Apple Silicon only (ARM64)
|
||||
bun run build:mac-arm64
|
||||
```
|
||||
|
||||
**Output formats:** `.dmg`, `.zip`
|
||||
|
||||
### Windows
|
||||
|
||||
```bash
|
||||
# x64 (64-bit Intel/AMD)
|
||||
bun run build:win
|
||||
|
||||
# ARM64 (Windows on ARM)
|
||||
bun run build:win-arm64
|
||||
```
|
||||
|
||||
**Output formats:** `.exe` (NSIS installer), `.zip`
|
||||
|
||||
### Linux
|
||||
|
||||
```bash
|
||||
# x64 (64-bit)
|
||||
bun run build:linux
|
||||
|
||||
# ARM64
|
||||
bun run build:linux-arm64
|
||||
```
|
||||
|
||||
**Output formats:** `.AppImage`, `.deb`, `.tar.gz`
|
||||
|
||||
### Build All Platforms
|
||||
|
||||
```bash
|
||||
bun run build:all
|
||||
```
|
||||
|
||||
⚠️ **Note:** Cross-platform builds may have limitations. Build on the target platform for best results.
|
||||
|
||||
## Build Process
|
||||
|
||||
The build script performs these steps:
|
||||
|
||||
1. **Compile TypeScript** → Electron app (main, preload, renderer)
|
||||
2. **Bundle with Vite** → Optimized production build
|
||||
3. **Package with electron-builder** → Platform-specific binaries
|
||||
|
||||
## Output
|
||||
|
||||
Binaries are generated in the `release/` directory:
|
||||
|
||||
```
|
||||
release/
|
||||
├── OpenCode Client-0.1.0-mac-universal.dmg
|
||||
├── OpenCode Client-0.1.0-mac-universal.zip
|
||||
├── OpenCode Client-0.1.0-win-x64.exe
|
||||
├── OpenCode Client-0.1.0-linux-x64.AppImage
|
||||
└── ...
|
||||
```
|
||||
|
||||
## File Naming Convention
|
||||
|
||||
```
|
||||
OpenCode Client-{version}-{os}-{arch}.{ext}
|
||||
```
|
||||
|
||||
- **version**: From package.json (e.g., `0.1.0`)
|
||||
- **os**: `mac`, `win`, `linux`
|
||||
- **arch**: `x64`, `arm64`, `universal`
|
||||
- **ext**: `dmg`, `zip`, `exe`, `AppImage`, `deb`, `tar.gz`
|
||||
|
||||
## Platform Requirements
|
||||
|
||||
### macOS
|
||||
|
||||
- **Build on:** macOS 10.13+
|
||||
- **Run on:** macOS 10.13+
|
||||
- **Code signing:** Optional (recommended for distribution)
|
||||
|
||||
### Windows
|
||||
|
||||
- **Build on:** Windows 10+, macOS, or Linux
|
||||
- **Run on:** Windows 10+
|
||||
- **Code signing:** Optional (recommended for distribution)
|
||||
|
||||
### Linux
|
||||
|
||||
- **Build on:** Any platform
|
||||
- **Run on:** Ubuntu 18.04+, Debian 10+, Fedora 32+, Arch
|
||||
- **Dependencies:** Varies by distro
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Build fails on macOS
|
||||
|
||||
```bash
|
||||
# Install Xcode Command Line Tools
|
||||
xcode-select --install
|
||||
```
|
||||
|
||||
### Build fails on Linux
|
||||
|
||||
```bash
|
||||
# Install dependencies (Debian/Ubuntu)
|
||||
sudo apt-get install -y rpm
|
||||
|
||||
# Install dependencies (Fedora)
|
||||
sudo dnf install -y rpm-build
|
||||
```
|
||||
|
||||
### "electron-builder not found"
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
bun install
|
||||
```
|
||||
|
||||
### Build is slow
|
||||
|
||||
- Use platform-specific builds instead of `build:all`
|
||||
- Close other applications to free up resources
|
||||
- Use SSD for faster I/O
|
||||
|
||||
## Development vs Production
|
||||
|
||||
**Development:**
|
||||
|
||||
```bash
|
||||
bun run dev # Hot reload, no packaging
|
||||
```
|
||||
|
||||
**Production:**
|
||||
|
||||
```bash
|
||||
bun run build:binaries # Full build + packaging
|
||||
```
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
Example GitHub Actions workflow:
|
||||
|
||||
```yaml
|
||||
name: Build Binaries
|
||||
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- "v*"
|
||||
|
||||
jobs:
|
||||
build-mac:
|
||||
runs-on: macos-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: oven-sh/setup-bun@v1
|
||||
- run: bun install
|
||||
- run: bun run build:mac
|
||||
|
||||
build-win:
|
||||
runs-on: windows-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: oven-sh/setup-bun@v1
|
||||
- run: bun install
|
||||
- run: bun run build:win
|
||||
|
||||
build-linux:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: oven-sh/setup-bun@v1
|
||||
- run: bun install
|
||||
- run: bun run build:linux
|
||||
```
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
Edit `package.json` → `build` section to customize:
|
||||
|
||||
- App icon
|
||||
- Code signing
|
||||
- Installer options
|
||||
- File associations
|
||||
- Auto-update settings
|
||||
|
||||
See [electron-builder docs](https://www.electron.build/) for details.
|
||||
|
||||
## Clean Build
|
||||
|
||||
Remove previous builds:
|
||||
|
||||
```bash
|
||||
rm -rf release/ dist/
|
||||
bun run build:binaries
|
||||
```
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q: Can I build for Windows on macOS?**
|
||||
A: Yes, but native binaries (e.g., DMG) require the target OS.
|
||||
|
||||
**Q: How large are the binaries?**
|
||||
A: Approximately 100-150 MB (includes Electron runtime).
|
||||
|
||||
**Q: Do I need code signing?**
|
||||
A: Not required, but recommended for public distribution to avoid security warnings.
|
||||
|
||||
**Q: How do I update the version?**
|
||||
A: Update `version` in `package.json`, then rebuild.
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
|
||||
- Check [electron-builder documentation](https://www.electron.build/)
|
||||
- Open an issue in the repository
|
||||
- Review existing build logs in `release/`
|
||||
Reference in New Issue
Block a user