Getting Started

Set up your development environment for contributing to Gõ Nhanh

This guide will help you set up your development environment and get started with contributing to Gõ Nhanh.

Prerequisites

Before you begin, ensure you have the following tools installed:

Tool	Version	Installation
Rust	1.70+	rustup.rs
Xcode	15+	App Store
macOS	13+	System requirement
Git	2.30+	Pre-installed

Gõ Nhanh uses Rust for the core input method engine and Swift/SwiftUI for the macOS interface.

Quick Start

1. Clone the repository

   git clone https://github.com/khaphanspace/gonhanh.org
   cd gonhanh.org
   
2. Run setup script

   The setup script installs Rust targets for cross-compilation:

   make setup
   

   This will:

   • Install aarch64-apple-darwin and x86_64-apple-darwin targets
   • Install swiftformat for code formatting
   • Make build scripts executable
3. Verify your setup

   Run the test suite to ensure everything is configured correctly:

   make test
   

   This runs 160+ integration tests across the Rust core.

4. Build the app

   Build both the Rust core and macOS app:

   make build
   

   The app will automatically open after building.

Project Structure

Understanding the codebase structure will help you navigate and contribute:

gonhanh.org/
├── core/                         # Rust core library (~2068 lines)
│   ├── Cargo.toml               # Rust manifest
│   ├── src/
│   │   ├── lib.rs              # FFI exports (7 functions)
│   │   ├── data/
│   │   │   ├── keys.rs         # Virtual key codes
│   │   │   ├── chars.rs        # Unicode mappings
│   │   │   └── vowel.rs        # Phonology algorithm
│   │   ├── engine/
│   │   │   ├── mod.rs          # Main engine (4-stage pipeline)
│   │   │   └── buffer.rs       # Typing buffer
│   │   └── input/
│   │       ├── telex.rs        # Telex input rules
│   │       └── vni.rs          # VNI input rules
│   └── tests/                  # 160+ integration tests
│
├── platforms/
│   └── macos/                  # macOS SwiftUI app (~765 lines)
│       ├── App.swift           # Entry point
│       ├── MenuBar.swift       # System tray UI
│       ├── SettingsView.swift  # Settings interface
│       ├── RustBridge.swift    # FFI bridge to Rust
│       └── GoNhanh.xcodeproj/  # Xcode project
│
├── scripts/                     # Build automation
│   ├── build/
│   ├── setup/
│   └── test/
│
└── docs/                        # Documentation
    ├── architecture.md
    └── vietnamese-language-system.md

Development Workflow

Making Changes to Rust Core

When working on the input method engine:

# Edit files in core/src/
vim core/src/engine/mod.rs

# Run tests for your changes
cd core && cargo test

# Test specific module
cargo test engine::

# See detailed test output
cargo test -- --nocapture --test-threads=1

Making Changes to macOS UI

When working on the Swift interface:

# Edit Swift files
vim platforms/macos/SettingsView.swift

# Rebuild the app
make macos

# Or open in Xcode for debugging
open platforms/macos/GoNhanh.xcodeproj

Available Make Commands

The project uses a Makefile for common tasks:

Development

make help        # Show all available commands
make test        # Run all tests
make format      # Format code (Rust + Swift)
make lint        # Run linters (clippy + swiftformat)
make build       # Full build and open app
make clean       # Remove build artifacts

Testing

make test        # Standard test suite
make test-dict   # Dictionary validation tests
make test-22k    # Heavy tests with 22k Vietnamese words
make test-100k   # English word tests (100k words)

Debugging

make watch       # Tail debug log in real-time
make perf        # Check RAM usage and memory leaks

Code Quality Standards

Before committing your changes:

1. Format your code

   make format
   

   This runs:

   • cargo fmt for Rust
   • swiftformat for Swift
2. Check for issues

   make lint
   

   This runs:

   • cargo clippy -- -D warnings (no warnings allowed)
   • swiftformat --lint
3. Run tests

   make test
   

   All tests must pass before submitting a PR.

Next Steps

Now that you have your environment set up:

Building

Learn how to build for different platforms

Contributing

Read our contribution guidelines

Code Standards

Follow our coding conventions

Architecture

Understand the system design

If you encounter any issues during setup, check the troubleshooting section or open an issue on GitHub.