Cài đặt¶

Có 7 cách cài. Nếu bạn dùng Ubuntu/Debian, dùng cách đầu tiên.

Cách	Phù hợp khi	Tự cập nhật
APT repo	Ubuntu/Debian — khuyên dùng	✅
COSMIC Store / GNOME Software	Pop!_OS, Ubuntu — thích bấm chuột hơn gõ lệnh	✅
Nhờ AI agent	Không chắc distro của mình; đã dùng Claude Code / Codex / Gemini	tuỳ cách agent chọn
Gói `.deb`	Ubuntu/Debian, tải tay	❌
Gói `.rpm`	Fedora/CentOS	❌
CMake thủ công	Distro khác, hoặc muốn sửa code	❌
`install.sh`	Build nhanh từ source	❌

Cách 1 — APT repo (Ubuntu/Debian)¶

Thêm repo một lần, sau đó apt upgrade như mọi gói khác.

# 1. Thêm khoá ký của repo
curl -fsSL https://sonnam0904.github.io/telebit/pubkey.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/telebit-archive-keyring.gpg

# 2. Thêm repo (jammy = Ubuntu 22.04, noble = 24.04, resolute = 26.04,
#    bookworm = Debian 12, trixie = Debian 13)
echo "deb [signed-by=/usr/share/keyrings/telebit-archive-keyring.gpg] https://sonnam0904.github.io/telebit $(lsb_release -cs) main" \
  | sudo tee /etc/apt/sources.list.d/telebit.list

# 3. Cài
sudo apt update
sudo apt install telebit

telebit là metapackage, chỉ phụ thuộc gói thật telebit-fcitx5 — nên sudo apt install telebit-fcitx5 cũng cho kết quả y hệt.

Repo hỗ trợ jammy, noble, resolute, bookworm và trixie

Suite	Bản phân phối
`jammy`	Ubuntu 22.04 LTS
`noble`	Ubuntu 24.04 LTS
`resolute`	Ubuntu 26.04 LTS
`bookworm`	Debian 12
`trixie`	Debian 13

Nếu lsb_release -cs trả về codename khác (ví dụ một bản Ubuntu non-LTS, hoặc Linux Mint), repo sẽ không có suite tương ứng. Khi đó dùng .deb tải tay hoặc CMake.

Xong thì sang Dùng lần đầu.

Cách 2 — COSMIC Store / GNOME Software¶

Sau khi đã thêm APT repo ở Cách 1, Telebit hiện ra trong trình quản lý ứng dụng đồ hoạ như một app bình thường: mở store, tìm "Telebit", bấm Install. Cài xong thì mở Telebit từ menu ứng dụng để bật bộ gõ và kiểm tra trạng thái.

Cần gói appstream, nếu không store sẽ không thấy Telebit

Store không đọc gói — nó đọc catalog mà apt tải về. Việc tải catalog do gói appstream cấu hình, và Pop!_OS/Ubuntu bản desktop đã có sẵn. Nếu thiếu, store sẽ không hiện Telebit dù apt install telebit vẫn chạy bình thường:

sudo apt install appstream
sudo apt update

Nếu vừa thêm repo mà store chưa thấy, ép nó đọc lại catalog:

sudo appstreamcli refresh --force

Trên KDE, Discover hiển thị Telebit ở dạng add-on của Fcitx 5 thay vì một app riêng.

Cách 3 — Gói `.deb` tải tay¶

File .deb không nằm trong repo source; mỗi bản được build trên GitHub Actions.

1. Tải

Nguồn	Cách lấy
Releases	Trang Releases — mỗi tag có năm `.deb`, hậu tố `+jammy` (Ubuntu 22.04), `+noble` (24.04), `+resolute` (26.04), `+bookworm` (Debian 12) hoặc `+trixie` (Debian 13)
Artifacts	Actions → Release → run mới nhất → Artifacts → `telebit-fcitx5-deb-jammy` / `-noble` / `-resolute` / `-bookworm` / `-trixie`

Chọn đúng hậu tố cho bản phân phối của bạn (lsb_release -cs để kiểm tra) — mỗi bản được build trên chính release đó nên liên kết với đúng libstdc++/libc tương ứng.

2. Cài

cd ~/Downloads
sudo apt update
sudo apt install -y ./telebit-fcitx5_*_amd64.deb

Bắt buộc có ./

Không có ./ (hoặc đường dẫn tuyệt đối), apt sẽ hiểu đó là tên gói trên mirror và báo không tìm thấy.

Nếu dùng dpkg và thiếu dependency:

sudo dpkg -i ./telebit-fcitx5_*_amd64.deb
sudo apt-get install -f -y

3. Khởi động lại fcitx5

fcitx5 -r

Cách 4 — Gói `.rpm` (Fedora/CentOS)¶

Gói yêu cầu fcitx5 đã có sẵn (nằm trong repo mặc định của Fedora).

Mỗi bản release có hai .rpm — một cho Fedora 43 (~fedora43) và một cho Fedora 44 (~fedora44) — vì mỗi bản được build trên chính Fedora đó để khớp libstdc++/fcitx5. Tải bản đúng với rpm -E %fedora của bạn từ Releases hoặc Actions → Artifacts (telebit-fcitx5-rpm-fedora43 / -fedora44), rồi:

cd ~/Downloads
sudo dnf install -y ./telebit-fcitx5*.rpm
fcitx5 -r

Cách 5 — CMake thủ công¶

Cài dependency trước:

Ubuntu/DebianFedoraArch

sudo apt update
sudo apt install -y \
  fcitx5 fcitx5-configtool fcitx5-config-qt fcitx5-module-lua \
  libfcitx5core-dev libfcitx5utils-dev libcurl4-openssl-dev \
  libgtk-4-dev extra-cmake-modules cmake build-essential

sudo dnf install -y fcitx5 fcitx5-configtool fcitx5-devel libcurl-devel \
  gtk4-devel gcc-c++ cmake make extra-cmake-modules

sudo pacman -S --needed base-devel cmake fcitx5 fcitx5-configtool curl \
  gtk4 extra-cmake-modules

Build và cài:

Toàn hệ thống (khuyên dùng)Chỉ cho user hiện tại

cd telebit-fcitx5
cmake -B build -DCMAKE_INSTALL_PREFIX=/usr .
cmake --build build
sudo cmake --install build
fcitx5 -r

cd telebit-fcitx5
cmake -B build -DCMAKE_INSTALL_PREFIX="$HOME/.local" .
cmake --build build
cmake --install build
fcitx5 -r

Đừng chọn --user nếu fcitx5 cài qua APT

fcitx5 chỉ nạp addon .so từ thư mục lib addon của chính bản build nó — thường là /usr/lib/<arch>/fcitx5. Nó không tự dò $HOME/.local/lib/fcitx5.

Nếu fcitx5 của bạn đến từ APT/.deb/.rpm (trường hợp phổ biến nhất), phải cài toàn hệ thống, nếu không addon sẽ không bao giờ xuất hiện. Chỉ dùng user-local khi bạn tự build và chạy fcitx5 từ $HOME/.local.

Cách 6 — Script `install.sh`¶

Ở thư mục gốc repository:

./install.sh            # mặc định = --system (PREFIX=/usr, cần sudo)
./install.sh --system
./install.sh --user     # PREFIX=$HOME/.local

Script sẽ: build core C++ → chạy bộ test → build addon → cmake --install theo PREFIX. Test fail là script dừng, không cài gì cả.

Sau khi cài¶

Chưa xong đâu — cần bật fcitx5 và thêm input method vào danh sách: Dùng lần đầu.

Cách nhanh nhất là mở Telebit từ menu ứng dụng (hoặc chạy telebit-setup): tab Cài đặt có nút bật Telebit trong fcitx5 và các tuỳ chọn kiểu gõ, tab Trạng thái cho biết bộ gõ có thật sự tới được từng ứng dụng hay chưa.

Chưa thấy telebit-fcitx5 trong danh sách?

Lần cài đầu tiên thường cần logout/login hoặc reboot, vì fcitx5 quét danh sách addon khi khởi động session. Nếu vẫn không thấy, xem Xử lý sự cố.