Cài đặt

Cài bằng một dòng lệnh

Lệnh này làm lần lượt các việc sau:

1. Nhận ra distro của máy và chọn đúng gói trong bản release mới nhất trên GitHub.
2. In ra gói sẽ cài và hỏi lại. Trả lời c thì mới đi tiếp; bấm Enter là dừng.
3. Tải gói về và so hash SHA-256 với file SHA256SUMS. Không khớp thì không cài.
4. Cài bằng trình quản lý gói của máy (dnf, apt, pacman hoặc zypper); lúc này máy hỏi mật khẩu sudo.
5. Trên GNOME, KDE Plasma (Wayland) và các desktop X11 chọn bộ gõ bằng im-config, như Xfce, Cinnamon, MATE (MX Linux, Linux Mint): đặt fcitx5 làm bộ gõ cho tài khoản, thêm Ngó Sen vào danh sách bộ gõ và đặt phím bật tiếng Việt là Ctrl+Shift, trừ khi đã tự chọn phím khác cho fcitx5. Trên KDE Plasma, lệnh cài chọn fcitx5 làm bàn phím ảo của KDE (System Settings, mục Virtual Keyboard), để app Qt như Kate, Dolphin cũng gõ được.

Trên GNOME, lệnh cài còn ẩn các icon fcitx5 thừa trong danh sách app và bật extension sửa lỗi gõ trên GNOME 50.0 đến 50.3. GNOME không có khay hệ thống, như Fedora, thì lệnh cài thêm extension Input Method Panel để icon và menu bộ gõ hiện trên thanh trên cùng. Trên Debian và Ubuntu, lệnh cài luôn cài kèm im-config và các gói giúp app GTK, Qt gõ được qua fcitx5.

Các bước cấu hình chỉ áp dụng cho tài khoản đang chạy lệnh. Tài khoản khác trên cùng máy thì đăng nhập vào đó rồi chạy lại lệnh cài. Muốn tự làm các bước đó thì thêm --no-setup, lệnh chỉ cài gói:

curl -fsSL https://raw.githubusercontent.com/ngosen/ngosen/main/install.sh | bash -s -- --no-setup

Cập nhật từ bản cũ thì cấu hình giữ nguyên. Script làm gì thì đọc được trong install.sh.

Các gói không có chữ ký số. File tải về chỉ được so hash SHA-256, lấy qua HTTPS từ GitHub.

Distro nào có gói

“Chỉ build” nghĩa là gói build được và qua test lúc build, chưa ai gõ thử trên distro đó. Chép theo ghi chú của bản 1.4.1-1, ngày 14/10/2026. Mức đã test lấy từ lần test bản 0.5. Các bản sửa bảng tính trong 1.0 được test trên máy ảo CachyOS (KDE Wayland), với LibreOffice Calc, WPS Office và Google Sheets trong Firefox. Bản 1.1 đổi tên các file cài vào máy. Lần cập nhật từ 1.0.0-1 được test trên máy ảo Linux Mint 22 (Cinnamon X11): cấu hình cũ được chép sang, bộ gõ vẫn nằm trong danh sách và gõ ra đúng chữ. Bản 1.2 thay cửa sổ cài đặt. Lưu và Hoàn tác qua fcitx5 thật được test trên máy ảo Linux Mint 22 (Cinnamon X11), CachyOS (KDE Wayland) và Ubuntu 26.04 (GNOME Wayland). Trên máy ảo CachyOS (KDE Wayland), bản 1.2 gõ ra đúng chữ trong GNOME Text Editor. Bản sửa lỗi đảo chữ trong gnome-terminal được test bằng client D-Bus giả lập và gõ tay trong gnome-terminal: không còn đảo chữ. Bản 1.2.1 chỉ bỏ trang Ứng dụng khỏi cửa sổ cài đặt, bộ gõ không đổi. Cửa sổ 4 trang được mở trên máy ảo CachyOS (KDE Wayland), cả giao diện sáng và tối. Bản 1.2.2 sửa nhãn cạnh con trỏ và lỗi mất dấu trên thanh địa chỉ Edge. Lỗi Edge được tái hiện bằng một test viết lại từ log gõ phím trên Fedora 44 (KDE Wayland), rồi gõ tay lại trên Edge sau khi sửa: ra đúng “ngó”, cạnh con trỏ hiện “vi”. Bản 1.3.0 thêm tuỳ chọn Backspace xoá dấu thanh, được gõ tay trên Fedora 44 (KDE Wayland) với bản build từ nhánh next. Icon khay mới được xem trên máy ảo Linux Mint 22.3 (Cinnamon) và MX Linux 25.3 (Xfce). Gói Debian 13 được cài trên máy ảo MX Linux 25.3: Telex “vieejt” ra “việt” trong terminal GTK. Lần cập nhật từ 1.0.0-1 rồi chạy fcitx5 -rd cũng được test trên máy ảo MX Linux 25.3: Ngó Sen vẫn nằm trong danh sách bộ gõ. Bản 1.4.0 chủ yếu đổi lệnh cài một dòng. Lệnh cài được chạy trên máy ảo Ubuntu 26.04 (GNOME Wayland), CachyOS (GNOME 51), Linux Mint (Cinnamon X11) và MX Linux 25 (Xfce X11) với bản build từ nhánh next: sau khi đăng nhập lại, Ctrl+Shift rồi Telex “tieengs vieetj” ra “tiếng việt” trong ô chữ GTK3, 3/3 lần trên mỗi máy. Lệnh gỡ được test trên Ubuntu 26.04 (IBus chạy lại) và MX Linux 25. Bản 1.4.1 chỉ đổi lệnh cài, bộ gõ giữ nguyên như 1.4.0. Lệnh cài trên KDE được chạy trên máy ảo CachyOS (Plasma 6.7 Wayland) với tài khoản chưa cấu hình bộ gõ: sau khi đăng nhập lại, Ctrl+Shift rồi Telex “tieengs vieetj” ra “tiếng việt” 3/3 lần trong ô chữ Qt6 và 3/3 lần trong ô chữ GTK3; trước khi sửa, ô chữ Qt6 ra chữ thô. Với gói 1.4.0, Chrome 155, VS Code, Discord, Firefox và GNOME Text Editor (Flatpak) gõ đúng trên máy ảo Ubuntu 26.04 (GNOME Wayland); Chrome ép chạy qua XWayland sai 5/30 lần.

Lõi ghép dấu: Rust hay Go

Lõi ghép dấu là phần biến tieengs thành tiếng. Gói cho Fedora 44, Arch, CachyOS, Ubuntu 26.04, Ubuntu 24.04, Fedora 43, openSUSE Tumbleweed dùng bản viết bằng Rust. Gói cho Debian 13, Ubuntu 22.04, Debian 12 vẫn dùng bản Go, vì bản Rust trong kho gói của các distro đó quá cũ. Hai bản gõ ra chữ như nhau.

Cài xong

Cài bằng lệnh một dòng trên GNOME, KDE Plasma (Wayland) hoặc Xfce, Cinnamon, MATE thì đăng xuất rồi đăng nhập lại, sau đó bấm Ctrl+Shift để bật tiếng Việt.

Trên desktop khác, hoặc khi cài gói bằng tay, còn ba việc:

1. Khởi động lại fcitx5:

   fcitx5 -rd

   Trên KDE Wayland: đăng xuất rồi đăng nhập lại, vì KDE tự mở fcitx5 và lệnh trên không thay được.
2. Mở “Fcitx5 Configuration” và thêm bộ gõ Ngó Sen.
3. Trên KDE Wayland: vào System Settings, mục Virtual Keyboard, chọn “Fcitx 5”. Từ bản 1.4.1, lệnh cài một dòng tự chọn mục này, chỉ khi cài gói bằng tay mới phải làm.

Trong cửa sổ cài đặt Ngó Sen, trang Gõ chữ, click nút Gõ Sen ở hàng Chế độ gõ. Chế độ này dùng được cho hầu hết app: gõ nhanh không mất chữ, gõ đúng trong trình duyệt, thanh địa chỉ, Facebook, app Electron như Zalo và terminal. Chế độ Gạch chân (Preedit) hiện chữ gạch chân trong lúc gõ, dành cho app không hợp với Gõ Sen.

Kiểu gõ được dùng và test hằng ngày là Telex. VNI và các kiểu khác dùng được nhưng chưa test kỹ.

Ubuntu 26.04: extension sửa lỗi gõ

GNOME trên Ubuntu 26.04 làm mất phím Backspace mà bộ gõ gửi, nên Chrome, Edge và app Electron gõ ra tieêngếng. Gói Ngó Sen kèm một extension sửa lỗi này. Lệnh cài một dòng tự bật extension trên GNOME 50.0 đến 50.3. Nếu cài gói bằng tay, đăng xuất rồi đăng nhập lại, sau đó chạy một lần:

gnome-extensions enable forward-keys@ngosen.github.io

Khi Ubuntu đưa bản sửa của GNOME vào (báo lỗi trên Launchpad) thì tắt extension:

gnome-extensions disable forward-keys@ngosen.github.io

Ubuntu: VS Code

Cài VS Code bằng gói .deb từ trang của Microsoft hoặc bằng Flatpak từ Flathub thì gõ được tiếng Việt ngay. Bản snap (cài từ App Center) gõ ra Telex thô như tieengs. Cách chữa tạm là cho nó gõ qua XIM, theo mục “Ubuntu: VS Code” trong README; khi đó khoảng một câu trong mười có một chữ sai dấu.

Không muốn chạy script tải từ mạng

Tải gói ở trang Releases, chọn file theo bảng trên, rồi so hash:

sha256sum -c SHA256SUMS --ignore-missing

Cài gói bằng trình quản lý gói của máy, rồi khởi động lại fcitx5:

fcitx5 -rd

Cập nhật

Chạy lại đúng lệnh cài, rồi khởi động lại fcitx5 bằng fcitx5 -rd; trên KDE Wayland thì đăng xuất rồi đăng nhập lại. Không có cơ chế tự cập nhật.

Bản thử

Muốn test tính năng chưa phát hành thì cài bản thử, build tự động mỗi khi nhánh next thay đổi:

curl -fsSL https://raw.githubusercontent.com/ngosen/ngosen/next/install.sh | NGOSEN_RELEASE_URL=https://github.com/ngosen/ngosen/releases/download/next-build bash

Số phiên bản của bản thử có thêm ngày giờ và mã commit, nên cài đè lên bản chính thức được, và bản chính thức sau đó vẫn tự nâng lên.

Từ bản 0.5.0, Ngó Sen đánh số riêng, không theo số 3.5.10 cũ nữa. Trình quản lý gói vẫn coi các bản này mới hơn 3.5.10-4, nên cập nhật như thường.

Bản 0.5.0 cũng bỏ uinput server, service chạy nền từng bấm phím Backspace thay bộ gõ. Cập nhật từ bản cũ thì gói tự tắt service đó và xoá tài khoản uinput_proxy của nó, không phải làm gì thêm.

Tự build từ source

Dành cho distro chưa có gói hoặc khi muốn tự build. Lệnh đầy đủ nằm trong TU-DUNG.md, viết cho Arch và CachyOS; distro khác cài các gói tương ứng, các bước còn lại giống hệt. NixOS có cách riêng, xem mục NixOS.

1. Máy từng tự build Ngó Sen 1.0.0 trở về trước thì xoá các file cũ mà bản đó cài, theo bước 1 trong TU-DUNG.md, vì cmake --install chỉ thêm file chứ không xoá.
2. Cài công cụ build: cmake, gcc, go, git, python, fcitx5 và vài gói khác, liệt kê trong TU-DUNG.md.
3. Tải source và build. Phải cài vào /usr, vì fcitx5 tìm bộ gõ ở đó, và nhớ --recurse-submodules, vì lõi ghép dấu nằm ở repo con bamboo-core.

git clone --recurse-submodules -b main https://github.com/ngosen/ngosen.git
cd ngosen
cmake -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_INSTALL_LIBDIR=/usr/lib
cmake --build build -j8
sudo cmake --install build

Trên Fedora và openSUSE dùng -DCMAKE_INSTALL_LIBDIR=lib64 thay cho /usr/lib.

4. Máy từng chạy uinput server của Ngó Sen bản cũ thì tắt nó và xoá các file nó để lại, theo bước 4 trong TU-DUNG.md, vì cmake --install chỉ thêm file chứ không xoá.
5. Làm ba việc ở mục Cài xong: khởi động lại fcitx5, thêm Ngó Sen, rồi trên KDE Wayland chọn “Fcitx 5”.

Cập nhật về sau: trong thư mục ngosen, chạy git pull --recurse-submodules, lặp lại bước 3, rồi fcitx5 -rd.

Chạy test: build thêm một lần với -DBUILD_TESTING=ON rồi chạy unshare -Urn ctest; lệnh đầy đủ ở mục “Chạy bộ kiểm” trong TU-DUNG.md.

Gỡ cài đặt

Một dòng lệnh, hỏi lại rồi mới gỡ:

curl -fsSL https://raw.githubusercontent.com/ngosen/ngosen/main/install.sh | bash -s -- --uninstall

Trên GNOME, lệnh này còn trả lại những gì lệnh cài đã đổi cho tài khoản đang chạy: fcitx5 thôi tự chạy khi đăng nhập, app dùng lại IBus, tắt extension sửa lỗi gõ và gỡ Input Method Panel nếu lệnh cài đã thêm. Đăng xuất rồi đăng nhập lại là GNOME dùng IBus như cũ. File nào đã tự sửa thì để nguyên. fcitx5 vẫn còn trên máy; muốn gỡ luôn thì chạy sudo apt autoremove (Ubuntu, Debian) sau đó.

Trên Xfce, Cinnamon, MATE, lệnh gỡ trả bộ gõ về mặc định của máy. fcitx5 vẫn còn cài nên có thể vẫn tự chạy, chỉ gõ được tiếng Anh. Muốn gỡ hẳn thì chạy sudo apt remove fcitx5.

Trên KDE, lệnh gỡ để fcitx5 làm bàn phím ảo như cũ, vì fcitx5 có thể đang dùng cho bộ gõ khác. Muốn bỏ thì chọn None ở System Settings, mục Virtual Keyboard.

Gỡ bằng tay:

1. Mở “Fcitx5 Configuration” và bỏ Ngó Sen khỏi danh sách bộ gõ.
2. Gỡ gói rồi khởi động lại fcitx5:

   sudo dnf remove fcitx5-ngosen       # Fedora
   sudo apt remove fcitx5-ngosen       # Ubuntu, Debian
   sudo pacman -R fcitx5-ngosen        # Arch, CachyOS
   sudo zypper remove fcitx5-ngosen    # openSUSE
   fcitx5 -rd

Các file cấu hình ngosen*.conf trong ~/.config/fcitx5/conf/, và lotus*.conf nếu từng dùng bản trước 1.1.0, vẫn ở lại máy để lần cài sau dùng tiếp. Muốn xoá sạch thì xoá các file đó.

NixOS

Lệnh cài không dùng cho NixOS. Trên NixOS, thêm flake của repo Ngó Sen vào cấu hình rồi đưa gói vào addon của fcitx5. Gói được build từ source trong repo, kèm lõi Rust.

# flake.nix
inputs.ngosen.url = "github:ngosen/ngosen";

# configuration.nix, với inputs truyền qua specialArgs
i18n.inputMethod = {
  enable = true;
  type = "fcitx5";
  fcitx5.addons = [ inputs.ngosen.packages.${pkgs.stdenv.hostPlatform.system}.default ];
};

Áp cấu hình xong thì khởi động lại fcitx5 bằng fcitx5 -rd.

Mức đã test: CI build gói, chạy test và nạp addon vào fcitx5 trên màn hình X ảo (Xvfb). Chưa ai test trên máy NixOS thật; Wayland, GNOME và máy aarch64 cũng chưa test. Gặp lỗi xin mở issue.

NixOS: tự build từ bản clone

git clone -b main https://github.com/ngosen/ngosen.git
cd ngosen
nix build          # build gói và chạy test, kết quả ở ./result
nix flake check    # thêm bước nạp addon vào fcitx5 trên màn hình X ảo

Muốn dùng bản vừa build thì trỏ input của cấu hình vào thư mục clone, phần còn lại giữ như trên, rồi chạy sudo nixos-rebuild switch:

inputs.ngosen.url = "git+file:///home/ten-ban/ngosen";

Flake chỉ thấy các file git đang theo dõi, nên file mới phải git add trước khi build. Đang sửa code thì nix develop mở một shell có đủ công cụ build; build và chạy test như trong TU-DUNG.md, thêm -DNGOSEN_RUST_CORE=ON vì gói Nix dùng lõi Rust.