Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/khaphanspace/gonhanh.org/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers building Gõ Nhanh from source for different platforms and configurations.

​
Quick Build

For most development work, use the standard build command: 
make build
This runs the complete build pipeline:
  1. Formats code
  2. Builds Rust core as universal binary (arm64 + x86_64)
  3. Builds macOS app with Xcode
  4. Auto-opens the app

​
Building Components

​
Rust Core Library

The core input method engine is built as a static library that can be linked from any platform.
1

Build for macOS (universal binary)

make core
This creates a universal binary supporting both architectures:
  • aarch64-apple-darwin (Apple Silicon)
  • x86_64-apple-darwin (Intel)
Output: platforms/macos/libgonhanh_core.a
2

Verify the binary

lipo -info platforms/macos/libgonhanh_core.a
Expected output:
Architectures in the fat file are: x86_64 arm64
3

Check library size

du -sh platforms/macos/libgonhanh_core.a
Typically ~2-3 MB for the optimized release build.
The core library has zero external dependencies in production. This keeps the binary small and self-contained.

​
macOS Application

The macOS app is built using Xcode with SwiftUI: 
make macos
The core library must be built first. Run make core if you get a “library not found” error.

​
Build Output

The built application is located at: 
platforms/macos/build/Release/GoNhanh.app

​
Xcode Configuration

The build uses these Xcode settings:
  • Configuration: Release
  • Architectures: arm64, x86_64 (universal)
  • Deployment Target: macOS 13.0+
  • Signing: Ad-hoc for development

​
Linux Build

Linux support is currently in beta.
make build-linux
This builds the Fcitx5 input method plugin.

​
Build Configurations

​
Development Build

Standard build with ad-hoc signing: 
./scripts/build/macos.sh
Features:
  • Ad-hoc code signing (runs on your machine only)
  • Debug symbols included
  • Fast iteration

​
Release Build with Signing

For distribution with Developer ID: 
./scripts/build/macos.sh --sign
Requirements:
  • Developer ID Application certificate in Keychain
  • Or set APPLE_SIGNING_IDENTITY environment variable
./scripts/build/macos.sh --sign

​
Notarized Build

For public distribution on macOS: 
./scripts/build/macos.sh --notarize
Required environment variables: 
export APPLE_ID="your@email.com"
export APPLE_APP_PASSWORD="xxxx-xxxx-xxxx-xxxx"
export APPLE_TEAM_ID="XXXXXXXXXX"
1

Get an App-Specific Password

  1. Go to appleid.apple.com
  2. Sign in with your Apple ID
  3. Generate an app-specific password
2

Find your Team ID

Check your Apple Developer account or run:
xcrun altool --list-providers -u "your@email.com" -p "your-app-password"
3

Run notarization

./scripts/build/macos.sh --notarize
This process takes 5-15 minutes.

​
Custom Version Build

Build with a specific version number: 
./scripts/build/macos.sh --version 1.2.3
Useful for:
  • Testing update mechanisms
  • Pre-release builds
  • Custom distributions

​
Build Scripts

Understanding the build scripts:

​
Core Build Script

Location: scripts/build/core.sh 
#!/bin/bash
set -e

echo "🦀 Building Rust core..."

cd core

# Build for Apple Silicon
cargo build --release --target aarch64-apple-darwin

# Build for Intel
cargo build --release --target x86_64-apple-darwin

# Create universal binary
lipo -create \
    target/aarch64-apple-darwin/release/libgonhanh_core.a \
    target/x86_64-apple-darwin/release/libgonhanh_core.a \
    -output ../platforms/macos/libgonhanh_core.a
The universal binary ensures the app runs natively on both architectures.

​
macOS Build Script

Location: scripts/build/macos.sh Key features:
  • Version management (git tags or custom)
  • Code signing (ad-hoc, Developer ID, or notarized)
  • Xcode integration
  • Automatic permission handling

​
Cargo Configuration

The Rust core uses optimized release settings: 
[profile.release]
opt-level = "z"          # Optimize for size
lto = true               # Link-time optimization
codegen-units = 1        # Better optimization
strip = true             # Strip symbols
panic = "abort"          # Smaller binary
This produces a minimal binary size (~2-3 MB) while maintaining performance.

​
Installation

​
Install to /Applications

After building, install the app: 
make install
This:
  1. Removes old login items pointing to build directory
  2. Kills any running instances
  3. Copies the app to /Applications/
  4. Launches the installed app

​
Create DMG Installer

Create a distributable DMG: 
make dmg
The DMG includes:
  • GoNhanh.app
  • Custom background
  • Shortcut to Applications folder
  • License information

​
Troubleshooting

​
Common Build Issues

The Rust core hasn’t been built yet.Solution:
make core
Xcode Command Line Tools aren’t installed.Solution:
xcode-select --install
Required compilation targets aren’t installed.Solution:
make setup
Build scripts aren’t executable.Solution:
chmod +x scripts/**/*.sh
Rust version mismatch.Solution: Check your Rust version:
rustc --version
Update if needed:
rustup update

​
Runtime Issues

Missing Accessibility permission.Solution:
  1. Go to System Settings → Privacy & Security → Accessibility
  2. Add GoNhanh to the list
  3. Enable the toggle
Outdated Xcode tools.Solution:
xcode-select --install
Preferences file corruption.Solution:
defaults delete org.gonhanh.GoNhanh
Then restart the app.

​
Clean Build

Start fresh by removing all build artifacts: 
make clean
This removes:
  • Rust target directory (core/target/)
  • macOS build directory (platforms/macos/build/)
  • Linux build directory (platforms/linux/build/)
  • App preferences
  • Login items pointing to build directory

​
Advanced: Manual Xcode Build

For debugging or custom configurations:
1

Open the project

open platforms/macos/GoNhanh.xcodeproj
2

Configure build scheme

  1. Product → Scheme → Edit Scheme
  2. Select Release configuration
  3. Set architectures to arm64 + x86_64
3

Build and run

Press Cmd+R or Product → Run

​
Next Steps

Contributing

Learn about the contribution process

Code Standards

Follow our coding conventions and best practices

Build docs developers (and LLMs) love

Get started for freeTalk to us