Contributing

Contributing

Building for Development

git clone https://github.com/mmaher88/laren.git
cd laren
cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j$(nproc)
cd build && ctest --output-on-failure

Project Structure

laren/
├── src/
│   ├── util/          # Unicode, memory mapping (no deps)
│   ├── dict/          # Trie + dictionary loader
│   ├── core/          # Transliteration pipeline
│   │   ├── rule_engine.cpp   # ⭐ Arabizi → Arabic mappings
│   │   ├── transliterator.cpp # Pipeline orchestration
│   │   └── ranker.cpp        # Frequency-based ranking
│   └── engine/        # Fcitx5 integration
│       ├── laren_engine.cpp  # Addon lifecycle
│       └── laren_state.cpp   # Key handling, candidates, UI
├── data/
│   └── dictionary.tsv  # 375k Arabic words
├── tests/              # GoogleTest unit tests
├── resources/          # Fcitx5 config files
└── pkg/                # Packaging (Arch, Fedora, Debian)

Development Workflow

flowchart LR
    A["Edit code"] --> B["Build"]
    B --> C["Run tests"]
    C --> D["Install .so"]
    D --> E["Restart fcitx5"]
    E --> F["Test live"]

    style A fill:#e1f5fe
    style F fill:#c8e6c9

Loading

Quick iteration loop

# Build and install
cmake --build build -j$(nproc) && sudo cp build/src/laren.so /usr/lib/fcitx5/laren.so

# Restart fcitx5 (KDE Wayland)
killall fcitx5; sleep 1
qdbus6 org.kde.KWin /VirtualKeyboard org.kde.kwin.VirtualKeyboard.enabled false
sleep 1
qdbus6 org.kde.KWin /VirtualKeyboard org.kde.kwin.VirtualKeyboard.enabled true

Adding New Arabizi Mappings

Edit src/core/rule_engine.cpp. Mappings are defined in the RuleEngine() constructor:

// Single letter: first option is tried first
{"k", {ar::QAF, ar::KAF}},

// Digraph: consumed before single letters
{"sh", {ar::SHEEN}},

// Number mapping
{"7", {ar::HAA}},

After adding mappings, run tests to verify:

cmake --build build && cd build && ctest --output-on-failure

Adding Dictionary Words

Edit data/dictionary.tsv (tab-separated: arabic_word\tfrequency):

كويس	5000
يلا	4500

Higher frequency = ranked higher in suggestions.

Cross-Distro Testing

Use distrobox to test on multiple distros without VMs:

# Fedora
distrobox create --name test-fedora --image fedora:41
distrobox enter test-fedora
sudo dnf install cmake gcc-c++ fcitx5-devel
cmake -B /tmp/build -DCMAKE_INSTALL_PREFIX=/usr -DBUILD_TESTS=OFF
cmake --build /tmp/build

# Ubuntu
distrobox create --name test-ubuntu --image ubuntu:24.04
distrobox enter test-ubuntu
sudo apt install cmake g++ fcitx5-modules-dev libfcitx5core-dev
cmake -B /tmp/build -DCMAKE_INSTALL_PREFIX=/usr -DBUILD_TESTS=OFF
cmake --build /tmp/build

Packaging

Packaging files live in pkg/:

File	Target
pkg/arch/PKGBUILD	AUR (Arch, CachyOS, Manjaro)
pkg/fedora/fcitx5-laren.spec	Fedora COPR
pkg/debian/control	Ubuntu PPA / Debian