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 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
Clone the repository
git clone https://github.com/khaphanspace/gonhanh.org cd gonhanh.org
Run setup script
The setup script installs Rust targets for cross-compilation: This will:
Install aarch64-apple-darwin and x86_64-apple-darwin targets
Install swiftformat for code formatting
Make build scripts executable
Verify your setup
Run the test suite to ensure everything is configured correctly: This runs 160+ integration tests across the Rust core.
Build the app
Build both the Rust core and macOS app: 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:
Format your code
This runs:
cargo fmt for Rustswiftformat for Swift
Check for issues
This runs:
cargo clippy -- -D warnings (no warnings allowed)swiftformat --lint
Run tests
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
