From beb320be9f56cbfd927a542e8d798379e83c6147 Mon Sep 17 00:00:00 2001 From: pcodedynamics Date: Sun, 6 Sep 2026 11:50:41 +0700 Subject: [PATCH] docs(linux): lead with Fcitx5, and get the session variables right MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit install.sh now installs Fcitx5 on every desktop, so `funput` leads every table and command block, with `funput-ibus` documented in full right below it for anyone already on IBus who would rather not rewire their session. The environment-variable section was the weak part and is now rebuilt against upstream (Using_Fcitx_5_on_Wayland, Setup_Fcitx_5). It gave only the X11 trio — correct for X11, but the page never said a Wayland session needs something different, and that is the session most readers are in: GTK 3/4 speak text-input-v3 on their own there, and the trio set globally makes KWin blink the candidate window. The section now branches on `$XDG_SESSION_TYPE` first and the desktop second, names the tool that owns this per distro (`im-config` on Debian/Ubuntu, `fcitx5-autostart` on Fedora, by hand on Arch and openSUSE), warns that im-config sets nothing in a Wayland session because that hook ships disabled, carries the Qt 6.8.2+ `QT_IM_MODULES` form, and lists where the variables can live — environment.d is read by GDM and Plasma 5.22+ only, so ~/.bash_profile is offered for everyone else, with the reboot upstream asks for. Two more corrections from the same pass. `fcitx5 -r` is wrong on KDE, where KWin hands the daemon a socket a replacement cannot inherit, so both places that suggested restarting now say to log out instead. And the page promised a .sha256 file with every release and a `sha256sum -c` line for it, but no Linux release has ever carried one — the installer verifies the release API's digest itself. Also: --user sat under Arch despite working on every distro and said nothing about the re-login Fcitx5 needs; Troubleshooting had no Fcitx5 branch; and the warning against installing both packages contradicted the packaging, which lets them coexist — enabling both in one session is the actual problem. Both locales. Co-Authored-By: Claude Opus 5 --- docs/install/linux.mdx | 256 +++++++++++++----- .../current/install/linux.mdx | 256 +++++++++++++----- 2 files changed, 384 insertions(+), 128 deletions(-) diff --git a/docs/install/linux.mdx b/docs/install/linux.mdx index 16f38bb..715b562 100644 --- a/docs/install/linux.mdx +++ b/docs/install/linux.mdx @@ -5,28 +5,37 @@ sidebar_position: 4 # Cài đặt trên Linux -Funput trên Linux chạy qua **IBus** hoặc **Fcitx5** — đây là input method engine thật sự (preedit/commit), tích hợp với desktop environment, không phải ứng dụng portable. +Funput trên Linux chạy qua **Fcitx5** hoặc **IBus** — đây là input method engine thật sự (preedit/commit), tích hợp với desktop environment, không phải ứng dụng portable. Hai gói riêng biệt: | Gói | Framework | Dùng khi | | --- | --------- | -------- | -| `funput-ibus` | **IBus** | GNOME, Ubuntu mặc định | -| `funput` | **Fcitx5** | KDE Plasma, hoặc cần per-app auto-switch | +| `funput` | **Fcitx5** — khuyến nghị | Mặc định cho mọi desktop | +| `funput-ibus` | **IBus** | Bạn đang dùng IBus sẵn (GNOME/Ubuntu) và không muốn đổi session | -:::caution -Không cài cả hai gói cho cùng một desktop session — hãy chọn đúng framework mà session đang dùng. +Cả hai đều kéo theo `funput-settings` — ứng dụng Cài đặt dùng chung — đúng cùng phiên bản. + +:::info +Hai gói **cài chung được** (chúng không giành file của nhau). Nhưng mỗi phiên đăng nhập chỉ nên **bật một framework**: bật cả hai thì hai bộ gõ cùng nhận phím. ::: ## Chọn framework -| Môi trường | Framework | Gói cài | -| ---------- | --------- | ------- | -| GNOME / Ubuntu mặc định | IBus | `funput-ibus` | -| KDE Plasma / cần đầy đủ tính năng | Fcitx5 | `funput` | +| Môi trường | Framework khuyến nghị | Gói cài | +| ---------- | --------------------- | ------- | +| KDE Plasma | Fcitx5 | `funput` | +| GNOME / Ubuntu / khác | Fcitx5 | `funput` | +| Đã quen IBus, không muốn đổi session | IBus | `funput-ibus` | + +**Vì sao Fcitx5 là mặc định:** đây là bản đầy đủ hơn — nó vẽ được preedit trên panel cho những ứng dụng tự giấu preedit (WPS Office), điều mà phía IBus không có kênh nào làm được — và hỗ trợ tự chuyển bộ gõ theo từng ứng dụng. + +:::caution +Trên **GNOME/Ubuntu**, session mặc định nối vào IBus. Chọn Fcitx5 ở đó nghĩa là phải [nối session vào Fcitx5](#noi-session) rồi **đăng xuất và đăng nhập lại** — cài xong chưa gõ được ngay. Muốn tránh bước đó thì dùng `funput-ibus`. +::: :::tip -Script `install.sh` tự chọn framework: KDE Plasma → Fcitx5, còn lại → IBus. Ép tay bằng `--ibus` hoặc `--fcitx5`. +Script `install.sh` mặc định cài **Fcitx5** trên mọi desktop. Ép sang IBus bằng `--ibus`. ::: ## Cách 1: Kho Funput `repo.funput.app` (khuyến nghị) @@ -58,11 +67,11 @@ sudo apt update **Bước 2 — Cài đặt:** ```bash -# IBus (GNOME / Ubuntu mặc định) -sudo apt install funput-ibus - -# Fcitx5 (KDE / đầy đủ tính năng) +# Fcitx5 (khuyến nghị) sudo apt install funput + +# IBus +sudo apt install funput-ibus ``` ### Fedora (.rpm) @@ -80,11 +89,11 @@ Thả thẳng file `.repo` thay vì `dnf config-manager --add-repo ` — dn **Bước 2 — Cài đặt:** ```bash +# Fcitx5 (khuyến nghị) +sudo dnf install funput + # IBus sudo dnf install funput-ibus - -# Fcitx5 -sudo dnf install funput ``` ### openSUSE (.rpm) @@ -100,57 +109,57 @@ sudo zypper refresh **Bước 2 — Cài đặt:** ```bash +# Fcitx5 (khuyến nghị) +sudo zypper install funput + # IBus sudo zypper install funput-ibus - -# Fcitx5 -sudo zypper install funput ``` :::info Kho chỉ phục vụ **bản mới nhất**. Nếu cần cài phiên bản cũ, dùng [GitHub Releases](https://github.com/Funput/Funput/releases). ::: -Sau khi cài xong, chuyển sang mục [Bật bộ gõ](#bật-bộ-gõ) bên dưới. +Sau khi cài xong, chuyển sang mục [Bật bộ gõ](#bat-bo-go) bên dưới. ## Cách 2: GitHub Releases (tải thủ công) Tải gói phù hợp từ [GitHub Releases](https://github.com/Funput/Funput/releases): -| Định dạng | IBus | Fcitx5 | -| --------- | ---- | ------ | -| `.deb` (Debian/Ubuntu) | `funput-ibus_*_.deb` | `funput_*_.deb` | -| `.rpm` (Fedora/openSUSE) | `funput-ibus-*..rpm` | `funput-*..rpm` | +| Định dạng | Fcitx5 | IBus | +| --------- | ------ | ---- | +| `.deb` (Debian/Ubuntu) | `funput_*_.deb` | `funput-ibus_*_.deb` | +| `.rpm` (Fedora/openSUSE) | `funput-*..rpm` | `funput-ibus-*..rpm` | Kiến trúc: `.deb` dùng `amd64` / `arm64`; `.rpm` dùng `x86_64` / `aarch64`. +Nhớ tải kèm gói `funput-settings` cùng phiên bản — cả hai bản đều phụ thuộc vào nó. + **Cài gói đã tải:** ```bash # Debian / Ubuntu -sudo apt install ./funput-ibus_*_.deb -# hoặc sudo apt install ./funput_*_.deb +# hoặc +sudo apt install ./funput-ibus_*_.deb # Fedora -sudo dnf install ./funput-ibus-*..rpm -# hoặc sudo dnf install ./funput-*..rpm +# hoặc +sudo dnf install ./funput-ibus-*..rpm # openSUSE -sudo zypper install ./funput-ibus-*..rpm +sudo zypper install --allow-unsigned-rpm ./funput-*..rpm # hoặc -sudo zypper install ./funput-*..rpm +sudo zypper install --allow-unsigned-rpm ./funput-ibus-*..rpm ``` -Mỗi bản phát hành kèm file **SHA-256** (`.sha256`) để kiểm tra tính toàn vẹn: - -```bash -sha256sum -c funput-ibus_*.deb.sha256 -``` +:::info +Gói rời trên GitHub Releases **không được ký** — chữ ký GPG chỉ có ở kho `repo.funput.app`. `apt` và `dnf` chấp nhận file cục bộ, riêng `zypper` sẽ dừng lại hỏi, nên cần `--allow-unsigned-rpm`. +::: :::caution -Nếu `apt`/`dpkg` báo lỗi đọc file (`could not locate member control.tar`, `unexpected end of file`) — file `.deb` tải về bị **hỏng/cắt cụt**. Tải lại và đối chiếu SHA-256. +Nếu `apt`/`dpkg` báo lỗi đọc file (`could not locate member control.tar`, `unexpected end of file`) — file `.deb` tải về bị **hỏng/cắt cụt**. Tải lại từ đầu. ::: ## Cách 3: Script cài nhanh (`install.sh`) @@ -161,6 +170,8 @@ Một lệnh tự nhận distro + kiến trúc, **thêm kho `repo.funput.app`** curl -fsSL https://raw.githubusercontent.com/Funput/Funput/main/platforms/linux/install.sh | bash ``` +Không có cờ nào thì script cài bản **Fcitx5**. + Tùy chọn: ```bash @@ -168,23 +179,55 @@ Tùy chọn: curl -fsSL .../install.sh | bash -s -- --ibus curl -fsSL .../install.sh | bash -s -- --fcitx5 +# Cài vào ~/.local, không cần sudo (xem mục bên dưới) +curl -fsSL .../install.sh | bash -s -- --user + # Bỏ qua kho, tải gói rời từ GitHub Releases (không tự cập nhật) curl -fsSL .../install.sh | bash -s -- --no-repo # Ghim phiên bản (tự hàm ý --no-repo, vì kho chỉ giữ bản mới nhất) curl -fsSL .../install.sh | bash -s -- --version v1.2026.28 + +# Xem script sẽ chạy những lệnh gì mà không thay đổi gì cả +curl -fsSL .../install.sh | bash -s -- --dry-run ``` +Script in ra kế hoạch (distro, framework, gói, nguồn cài) trước khi động vào máy, và `--dry-run` in **đúng từng lệnh** sẽ chạy mà không thực thi lệnh nào — hữu ích khi bạn muốn xem trước những gì sẽ chạy bằng `sudo`. `--help` liệt kê đầy đủ tùy chọn. + +:::info +Với `--no-repo`, `--version` và `--user`, script tải gói từ GitHub Releases rồi **đối chiếu SHA-256** với digest mà GitHub công bố cho chính file đó; lệch một byte là dừng, không cài. Đường mặc định (qua kho) không cần bước này — apt/dnf/zypper/pacman đã kiểm chữ ký GPG. +::: + :::info Chỉ `--no-repo` và `--version` mới tải gói rời từ **GitHub Releases**; hai đường đó **không có cập nhật tự động** — chạy lại script để cập nhật. Trên **Arch** không dùng được hai cờ này (không có gói rời cho Arch) — dùng kho, hoặc `--user`. ::: +## Cài không cần sudo (`--user`) {#khong-sudo} + +Đường này cài vào `~/.local` — không cần quyền root, không đụng package manager. Chạy trên **mọi distro và mọi kiến trúc**, kể cả Arch Linux ARM. Điều kiện: máy **đã có sẵn** daemon Fcitx5 hoặc IBus (bản thân daemon vẫn phải cài bằng package manager). + +```bash +# Fcitx5 (mặc định) +curl -fsSL https://raw.githubusercontent.com/Funput/Funput/main/platforms/linux/install.sh | bash -s -- --user + +# IBus +curl -fsSL https://raw.githubusercontent.com/Funput/Funput/main/platforms/linux/install.sh | bash -s -- --user --ibus +``` + +:::caution +Với **Fcitx5**, script phải ghi thêm `FCITX_ADDON_DIRS` vào `~/.config/environment.d/funput.conf` — Fcitx5 chỉ quét thư mục addon hệ thống, không quét `~/.local`. Biến đó chỉ có hiệu lực sau khi **đăng xuất và đăng nhập lại**. Muốn thử ngay trong phiên hiện tại, chạy lại daemon với đúng dòng lệnh mà script in ra. + +Với **IBus** thì không cần: `ibus-daemon` tự quét `~/.local/share/ibus/component`, chỉ cần `ibus restart`. +::: + +Cập nhật: chạy lại đúng lệnh đó — nó luôn lấy bản mới nhất và ghi đè. + ## Arch Linux Arch không có gói trên GitHub Releases. Kho `repo.funput.app` phục vụ Arch bằng **kho pacman** riêng, cùng khoá GPG với kho apt/dnf. :::caution -Gói dựng sẵn cho **x86_64**. Arch Linux ARM là distro riêng, không dùng được kho này — trên máy ARM hãy dùng [đường `--user`](#không-sudo-trên-arch). +Gói dựng sẵn cho **x86_64**. Arch Linux ARM là distro riêng, không dùng được kho này — trên máy ARM hãy dùng [đường `--user`](#khong-sudo). ::: **Bước 1 — Nhập khoá (làm một lần):** @@ -210,11 +253,11 @@ sudo pacman -Sy **Bước 3 — Cài đặt:** ```bash -# IBus (GNOME) -sudo pacman -S funput-ibus - -# Fcitx5 (KDE / đầy đủ tính năng) +# Fcitx5 (khuyến nghị) sudo pacman -S funput + +# IBus +sudo pacman -S funput-ibus ``` Cả hai đều kéo theo `funput-settings` (app cài đặt) đúng cùng phiên bản. Cập nhật bằng `sudo pacman -Syu` như mọi gói khác. @@ -223,29 +266,103 @@ Cả hai đều kéo theo `funput-settings` (app cài đặt) đúng cùng phiê Đây là gói **binary**, link vào thư viện Arch tại thời điểm dựng. Arch cập nhật liên tục, nên sau một đợt bump soname (fcitx5, ibus, gtk4) gói có thể tạm không nạp được. Kho **tự dựng lại hai tuần một lần** trên Arch mới nhất, nên tình trạng đó được vá trong khoảng hai tuần mà không cần đợi Funput ra bản mới — `pacman -Syu` sẽ nhận bản dựng lại đó. ::: -### Không sudo trên Arch +## Bật bộ gõ {#bat-bo-go} + +### Fcitx5 (khuyến nghị) + +1. **Đảm bảo Fcitx5 chạy cùng session:** + - KDE Plasma: **System Settings → Virtual keyboard → Fcitx 5**. Đây là cách bắt buộc để dùng được `text-input` với ứng dụng Wayland thuần. + - GNOME và các desktop khác: bật mục autostart của Fcitx 5, hoặc chép thủ công: + + ```bash + mkdir -p ~/.config/autostart && cp /usr/share/applications/org.fcitx.Fcitx5.desktop ~/.config/autostart + ``` + + Trên GNOME, Fcitx5 khi khởi động sẽ **thay thế `ibus-daemon`** đang chạy và phục vụ luôn giao thức ibus mà GNOME dùng — nên phần lớn ứng dụng chạy được ngay. +2. **[Nối session vào Fcitx5](#noi-session)** (biến môi trường), rồi **đăng xuất và đăng nhập lại**. +3. Mở `fcitx5-configtool` → **+** → thêm **Funput** (nhóm Vietnamese). +4. Bật/tắt tiếng Việt: **`Ctrl + ` ` `** hoặc icon Fcitx5 ở khay hệ thống. + +### Nối session vào Fcitx5 {#noi-session} -Đường cài vào `~/.local` chạy được trên mọi kiến trúc, chỉ cần đã có sẵn daemon IBus hoặc Fcitx5: +Funput là engine *bên trong* Fcitx5 — ứng dụng chỉ gõ được nếu session đã trỏ về Fcitx5. Đặt biến nào thì phụ thuộc **loại session trước, desktop sau**. Xem bạn đang ở loại nào: ```bash -curl -fsSL https://raw.githubusercontent.com/Funput/Funput/main/platforms/linux/install.sh | bash -s -- --user +echo $XDG_SESSION_TYPE +``` + +Nguồn: [Using Fcitx 5 on Wayland](https://fcitx-im.org/wiki/Using_Fcitx_5_on_Wayland) và [Setup Fcitx 5](https://fcitx-im.org/wiki/Setup_Fcitx_5). + +#### Session `x11` + +Bộ ba kinh điển, dùng chung cho mọi desktop: + +``` +XMODIFIERS=@im=fcitx +GTK_IM_MODULE=fcitx +QT_IM_MODULE=fcitx +``` + +Đừng viết tay nếu distro của bạn có sẵn công cụ: + +| Distro | Công cụ | +| ------ | ------- | +| Debian / Ubuntu (và Mint, Pop!_OS…) | `im-config -n fcitx5` — ghi đúng bộ trên **và** khởi động daemon. Chạy `im-config` không tham số để có wizard. | +| Fedora | `sudo dnf install fcitx5-autostart` — gói này đặt sẵn `/etc/profile.d` và autostart. `im-chooser` (gói `imsettings`) là bản đồ hoạ tương đương. | +| Arch, openSUSE, còn lại | Không có công cụ riêng — đặt tay theo mục [Đặt ở đâu](#dat-o-dau) bên dưới. | + +#### Session `wayland` + +Bộ ba ở trên **không đúng** cho Wayland: GTK 3/4 tự nói chuyện với compositor qua `text-input-v3`, và đặt cả bộ ở mức global trên KWin làm nhấp nháy candidate window. + +**GNOME — và sway, các compositor wlroots khác:** + +```bash +mkdir -p ~/.config/environment.d +cat > ~/.config/environment.d/fcitx5.conf <<'EOF' +XMODIFIERS=@im=fcitx +QT_IM_MODULE=fcitx +EOF +``` + +- Để trống `GTK_IM_MODULE` — GTK 3/4 đã dùng `text-input-v3` sẵn. +- `QT_IM_MODULE=fcitx` là cho **Qt 5 và Qt cũ hơn 6.8.2** (chúng chạy qua XWayland). Nếu distro của bạn đã có **Qt 6.8.2 trở lên**, dùng `QT_IM_MODULES=wayland;fcitx` thay cho dòng đó. + +**KDE Plasma (5.27 trở lên):** + +```bash +mkdir -p ~/.config/environment.d +cat > ~/.config/environment.d/fcitx5.conf <<'EOF' +XMODIFIERS=@im=fcitx +EOF ``` -## Bật bộ gõ +- **Không** đặt `GTK_IM_MODULE` / `QT_IM_MODULE` / `SDL_IM_MODULE` ở mức global — candidate window sẽ nhấp nháy trên KWin. Nếu một ứng dụng riêng lẻ (loại chỉ chạy được X11) cần, hãy đặt cho riêng nó: `env QT_IM_MODULE=fcitx wps`. +- Nếu trước đây bạn đã chạy `im-config` và nó đặt cả bộ, chạy lại `im-config` rồi chọn mục *"do not set any IM … use desktop default"*. + +:::info Debian/Ubuntu trên Wayland +`im-config` **không đặt biến nào** cho phiên Wayland — hook `/etc/profile.d/im-config_wayland.sh` được ship ở trạng thái vô hiệu hoá. Nên trên Ubuntu/Wayland bạn vẫn phải tự đặt theo hai khối trên; `im-config -n fcitx5` chỉ có tác dụng cho phiên X11. +::: + +#### Đặt ở đâu {#dat-o-dau} + +| Nơi đặt | Được đọc bởi | +| ------- | ------------ | +| `~/.config/environment.d/fcitx5.conf` | GDM, và Plasma 5.22+ (bất kể dùng DM nào) | +| `~/.bash_profile` (nhớ `export`) | GDM / SDDM / LightDM, và cả đăng nhập từ TTY | +| `/etc/profile` (cần root) | Mọi distro, áp cho mọi người dùng | + +:::caution +Biến môi trường chỉ được nạp khi **bắt đầu một session mới** — mở terminal mới là không đủ. Riêng với `environment.d`, tài liệu Fcitx5 lưu ý systemd user manager có thể sống sót qua lần đăng xuất, nên **khởi động lại máy** là cách chắc chắn nhất. +::: -### IBus (GNOME / Ubuntu) +### IBus 1. Nạp lại engine: `ibus restart` (hoặc đăng nhập lại). 2. **Settings → Keyboard → Input Sources → +** → **Vietnamese** → **Funput**. 3. Chuyển nguồn nhập: **`Super + Space`**. 4. Bật/tắt tiếng Việt khi đang ở Funput: **`Ctrl + ` ` `**. -### Fcitx5 (KDE) - -1. Mở `fcitx5-configtool` → **+** → thêm **Funput** (nhóm Vietnamese). -2. Nếu Fcitx5 chưa chạy: đăng nhập lại, hoặc kiểm tra biến môi trường IM (X11: `GTK_IM_MODULE=fcitx`, `QT_IM_MODULE=fcitx`, `XMODIFIERS=@im=fcitx`). -3. Bật/tắt tiếng Việt: **`Ctrl + ` ` `** hoặc icon Fcitx5 ở khay hệ thống. - ## Cấu hình sau cài - Mở app **Funput** trong menu ứng dụng để chọn **Telex** hoặc **VNI**, smart/eager restore và các tùy chọn khác. @@ -257,7 +374,7 @@ curl -fsSL https://raw.githubusercontent.com/Funput/Funput/main/platforms/linux/ | ---- | ------------- | | **[repo.funput.app](https://repo.funput.app)** | Qua package manager — **cập nhật tự động** | | `install.sh` (mặc định) | Đã thêm kho, nên cũng **cập nhật tự động** | -| `install.sh --no-repo` / `--version` | Chạy lại script | +| `install.sh --no-repo` / `--version` / `--user` | Chạy lại script | | GitHub Releases | Tải gói mới, cài đè thủ công | Cập nhật tự động qua apt/dnf/zypper/pacman cần đã thêm kho **repo.funput.app** — bằng tay theo Cách 1 (hoặc mục Arch Linux), hoặc để `install.sh` tự làm. @@ -265,40 +382,51 @@ Cập nhật tự động qua apt/dnf/zypper/pacman cần đã thêm kho **repo. ### Cập nhật qua kho Funput ```bash -# Debian / Ubuntu (IBus) -sudo apt update && sudo apt upgrade funput-ibus - # Debian / Ubuntu (Fcitx5) sudo apt update && sudo apt upgrade funput -# Fedora (IBus) -sudo dnf upgrade funput-ibus +# Debian / Ubuntu (IBus) +sudo apt update && sudo apt upgrade funput-ibus # Fedora (Fcitx5) sudo dnf upgrade funput -# openSUSE (IBus) -sudo zypper update funput-ibus +# Fedora (IBus) +sudo dnf upgrade funput-ibus # openSUSE (Fcitx5) sudo zypper update funput +# openSUSE (IBus) +sudo zypper update funput-ibus + # Arch sudo pacman -Syu ``` :::tip -Sau khi cập nhật, nếu bộ gõ không hoạt động bình thường: chạy `ibus restart` (IBus) hoặc đăng nhập lại. +Sau khi cập nhật, nếu bộ gõ không hoạt động bình thường: chạy `fcitx5 -r -d` (Fcitx5 — **trừ KDE**, xem cảnh báo ở phần Xử lý sự cố) hoặc `ibus restart` (IBus). Đăng nhập lại luôn là cách an toàn cho mọi desktop. ::: ## Xử lý sự cố -### Funput không xuất hiện trong Input Sources +### Funput không xuất hiện trong danh sách bộ gõ + +- **Fcitx5:** chạy `fcitx5-diagnose` trước tiên — nó soát cả biến môi trường session lẫn addon đã nạp, và chỉ thẳng ra chỗ thiếu. Sau đó khởi động lại daemon bằng `fcitx5 -r -d` rồi mở lại `fcitx5-configtool`. + :::caution Trên KDE thì đừng restart + Khi Fcitx5 được khởi động từ **Virtual keyboard**, KWin trao cho nó một socket mà tiến trình mới không kế thừa được. `fcitx5 -r` (hoặc "Restart" trong tray) sẽ làm ứng dụng Wayland mất bộ gõ cho tới lần đăng nhập sau — hãy đăng xuất/đăng nhập lại thay vì restart. + ::: - **IBus:** chạy `ibus restart` hoặc đăng nhập lại. -- Kiểm tra bạn đã cài đúng gói cho framework đang dùng (`funput-ibus` cho IBus, `funput` cho Fcitx5). +- Kiểm tra bạn đã cài đúng gói cho framework đang dùng (`funput` cho Fcitx5, `funput-ibus` cho IBus). - Mở app **Funput** từ menu ứng dụng — onboarding có thể hướng dẫn bước còn thiếu. +### Đã thêm Funput trong Fcitx5 nhưng gõ vào ứng dụng không ăn + +Gần như luôn là biến môi trường của session — xem [Nối session vào Fcitx5](#noi-session). `fcitx5-diagnose` liệt kê từng biến kèm giá trị đang có. Nhớ rằng chúng chỉ có hiệu lực sau khi đăng xuất/đăng nhập lại. + +Nếu chỉ **một vài ứng dụng** không ăn (thường là app Qt hoặc XWayland như WPS): đó là `QT_IM_MODULE`, xem khối GNOME ở trên. + ### `apt` báo dependency not installable Thường do **sai kiến trúc** — ví dụ tải gói `amd64` trên máy `arm64` (hoặc ngược lại). Tải đúng gói cho kiến trúc máy bạn. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/install/linux.mdx b/i18n/en/docusaurus-plugin-content-docs/current/install/linux.mdx index 303c05e..1aed617 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/install/linux.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/install/linux.mdx @@ -5,28 +5,37 @@ sidebar_position: 4 # Install on Linux -On Linux, Funput runs through **IBus** or **Fcitx5** — a real input method engine (preedit/commit) integrated with your desktop environment, not a portable app. +On Linux, Funput runs through **Fcitx5** or **IBus** — a real input method engine (preedit/commit) integrated with your desktop environment, not a portable app. Two separate packages: | Package | Framework | Use when | | ------- | --------- | -------- | -| `funput-ibus` | **IBus** | GNOME, default Ubuntu | -| `funput` | **Fcitx5** | KDE Plasma, or you need per-app auto-switch | +| `funput` | **Fcitx5** — recommended | The default for every desktop | +| `funput-ibus` | **IBus** | You already run IBus (GNOME/Ubuntu) and would rather not change your session | -:::caution -Do not install both packages for the same desktop session — choose the framework your session actually uses. +Both pull in `funput-settings` — the shared Settings app — at exactly the same version. + +:::info +The two packages **can be installed side by side** (they do not share files). But enable only **one framework per login session**: with both enabled, two input methods receive the same keys. ::: ## Choose a framework -| Environment | Framework | Package | -| ----------- | --------- | ------- | -| GNOME / default Ubuntu | IBus | `funput-ibus` | -| KDE Plasma / full feature set | Fcitx5 | `funput` | +| Environment | Recommended framework | Package | +| ----------- | --------------------- | ------- | +| KDE Plasma | Fcitx5 | `funput` | +| GNOME / Ubuntu / other | Fcitx5 | `funput` | +| Already on IBus, not changing your session | IBus | `funput-ibus` | + +**Why Fcitx5 is the default:** it is the fuller shell — it can draw a panel preedit for applications that hide the client preedit (WPS Office), which the IBus side has no channel for, and it supports per-app input-method switching. + +:::caution +On **GNOME/Ubuntu**, the session is wired to IBus out of the box. Choosing Fcitx5 there means you must [connect your session to Fcitx5](#noi-session) and then **log out and back in** — it will not type right after installation. To avoid that step, use `funput-ibus`. +::: :::tip -The `install.sh` script auto-selects a framework: KDE Plasma → Fcitx5, otherwise → IBus. Override with `--ibus` or `--fcitx5`. +The `install.sh` script installs **Fcitx5** by default on every desktop. Force IBus with `--ibus`. ::: ## Option 1: Funput repository `repo.funput.app` (recommended) @@ -58,11 +67,11 @@ This is the **deb822** (`.sources`) format. The older one-line `.list` form stil **Step 2 — Install:** ```bash -# IBus (GNOME / default Ubuntu) -sudo apt install funput-ibus - -# Fcitx5 (KDE / full features) +# Fcitx5 (recommended) sudo apt install funput + +# IBus +sudo apt install funput-ibus ``` ### Fedora (.rpm) @@ -80,11 +89,11 @@ The `.repo` file is dropped in directly rather than through `dnf config-manager **Step 2 — Install:** ```bash +# Fcitx5 (recommended) +sudo dnf install funput + # IBus sudo dnf install funput-ibus - -# Fcitx5 -sudo dnf install funput ``` ### openSUSE (.rpm) @@ -100,57 +109,57 @@ sudo zypper refresh **Step 2 — Install:** ```bash +# Fcitx5 (recommended) +sudo zypper install funput + # IBus sudo zypper install funput-ibus - -# Fcitx5 -sudo zypper install funput ``` :::info The repository only serves the **latest version**. To install an older release, use [GitHub Releases](https://github.com/Funput/Funput/releases). ::: -When installation finishes, continue to [Enable the input method](#enable-the-input-method) below. +When installation finishes, continue to [Enable the input method](#bat-bo-go) below. ## Option 2: GitHub Releases (manual download) Download the matching package from [GitHub Releases](https://github.com/Funput/Funput/releases): -| Format | IBus | Fcitx5 | -| ------ | ---- | ------ | -| `.deb` (Debian/Ubuntu) | `funput-ibus_*_.deb` | `funput_*_.deb` | -| `.rpm` (Fedora/openSUSE) | `funput-ibus-*..rpm` | `funput-*..rpm` | +| Format | Fcitx5 | IBus | +| ------ | ------ | ---- | +| `.deb` (Debian/Ubuntu) | `funput_*_.deb` | `funput-ibus_*_.deb` | +| `.rpm` (Fedora/openSUSE) | `funput-*..rpm` | `funput-ibus-*..rpm` | Architectures: `.deb` uses `amd64` / `arm64`; `.rpm` uses `x86_64` / `aarch64`. +Download the matching `funput-settings` package too — both shells depend on it. + **Install the downloaded package:** ```bash # Debian / Ubuntu -sudo apt install ./funput-ibus_*_.deb -# or sudo apt install ./funput_*_.deb +# or +sudo apt install ./funput-ibus_*_.deb # Fedora -sudo dnf install ./funput-ibus-*..rpm -# or sudo dnf install ./funput-*..rpm +# or +sudo dnf install ./funput-ibus-*..rpm # openSUSE -sudo zypper install ./funput-ibus-*..rpm +sudo zypper install --allow-unsigned-rpm ./funput-*..rpm # or -sudo zypper install ./funput-*..rpm +sudo zypper install --allow-unsigned-rpm ./funput-ibus-*..rpm ``` -Each release includes a **SHA-256** checksum file (`.sha256`): - -```bash -sha256sum -c funput-ibus_*.deb.sha256 -``` +:::info +Standalone packages on GitHub Releases are **not signed** — GPG signatures exist only in the `repo.funput.app` repository. `apt` and `dnf` accept a local file as is; `zypper` stops to ask, hence `--allow-unsigned-rpm`. +::: :::caution -If `apt`/`dpkg` reports read errors (`could not locate member control.tar`, `unexpected end of file`) — the `.deb` download is **corrupt or truncated**. Re-download and verify SHA-256. +If `apt`/`dpkg` reports read errors (`could not locate member control.tar`, `unexpected end of file`) — the `.deb` download is **corrupt or truncated**. Download it again. ::: ## Option 3: Quick install script (`install.sh`) @@ -161,6 +170,8 @@ One command detects your distro and architecture, **adds the `repo.funput.app` r curl -fsSL https://raw.githubusercontent.com/Funput/Funput/main/platforms/linux/install.sh | bash ``` +With no flags, the script installs the **Fcitx5** build. + Options: ```bash @@ -168,23 +179,55 @@ Options: curl -fsSL .../install.sh | bash -s -- --ibus curl -fsSL .../install.sh | bash -s -- --fcitx5 +# Install into ~/.local, no sudo (see the section below) +curl -fsSL .../install.sh | bash -s -- --user + # Skip the repository, fetch a standalone package from GitHub Releases curl -fsSL .../install.sh | bash -s -- --no-repo # Pin a version (implies --no-repo, since the repository only carries the latest) curl -fsSL .../install.sh | bash -s -- --version v1.2026.28 + +# Print every command the script would run, and run none of them +curl -fsSL .../install.sh | bash -s -- --dry-run ``` +The script prints its plan (distro, framework, package, source) before touching anything, and `--dry-run` prints **the exact commands** it would run without executing any of them — useful for reviewing what will run under `sudo`. `--help` lists every option. + +:::info +On the `--no-repo`, `--version` and `--user` paths the script downloads from GitHub Releases and **verifies SHA-256** against the digest GitHub publishes for that asset; a single wrong byte aborts the install. The default path does not need this — apt/dnf/zypper/pacman already check the GPG signature. +::: + :::info Only `--no-repo` and `--version` download from **GitHub Releases**; those two paths have **no automatic update** — run the script again to upgrade. Neither flag works on **Arch**, which has no release asset — use the repository, or `--user`. ::: +## Install without sudo (`--user`) {#khong-sudo} + +This path installs into `~/.local` — no root, no package manager. It works on **every distro and architecture**, Arch Linux ARM included. It requires an **already-installed** Fcitx5 or IBus daemon (the daemon itself still comes from your package manager). + +```bash +# Fcitx5 (default) +curl -fsSL https://raw.githubusercontent.com/Funput/Funput/main/platforms/linux/install.sh | bash -s -- --user + +# IBus +curl -fsSL https://raw.githubusercontent.com/Funput/Funput/main/platforms/linux/install.sh | bash -s -- --user --ibus +``` + +:::caution +For **Fcitx5**, the script also writes `FCITX_ADDON_DIRS` into `~/.config/environment.d/funput.conf` — Fcitx5 scans only the system addon directories, never `~/.local`. That variable takes effect after you **log out and back in**. To test it in the current session, re-run the daemon with the exact command the script prints. + +**IBus** needs none of that: `ibus-daemon` scans `~/.local/share/ibus/component` itself, so `ibus restart` is enough. +::: + +To update: run the same command again — it always fetches the latest release and overwrites in place. + ## Arch Linux Arch has no package on GitHub Releases. `repo.funput.app` serves it as a **pacman repository** instead, under the same GPG key as the apt and dnf ones. :::caution -The packages are built for **x86_64**. Arch Linux ARM is a separate distribution and cannot use this repository — on ARM, use [the `--user` install](#no-sudo-on-arch). +The packages are built for **x86_64**. Arch Linux ARM is a separate distribution and cannot use this repository — on ARM, use [the `--user` install](#khong-sudo). ::: **Step 1 — Import the key (one time):** @@ -210,11 +253,11 @@ sudo pacman -Sy **Step 3 — Install:** ```bash -# IBus (GNOME) -sudo pacman -S funput-ibus - -# Fcitx5 (KDE / full features) +# Fcitx5 (recommended) sudo pacman -S funput + +# IBus +sudo pacman -S funput-ibus ``` Both pull in `funput-settings` (the Settings app) at exactly the same version. Update with `sudo pacman -Syu` like any other package. @@ -223,29 +266,103 @@ Both pull in `funput-settings` (the Settings app) at exactly the same version. U These are **binary** packages, linked against the Arch libraries of the build day. Arch moves continuously, so after a soname bump (fcitx5, ibus, gtk4) they may briefly fail to load. The repository **rebuilds itself fortnightly** against current Arch, so that is repaired within about two weeks without waiting for a new Funput release — `pacman -Syu` picks the rebuild up. ::: -### No sudo on Arch +## Enable the input method {#bat-bo-go} + +### Fcitx5 (recommended) + +1. **Make sure Fcitx5 runs in your session:** + - KDE Plasma: **System Settings → Virtual keyboard → Fcitx 5**. This is required for `text-input` to work with native Wayland applications. + - GNOME and other desktops: enable the Fcitx 5 autostart entry, or copy it by hand: + + ```bash + mkdir -p ~/.config/autostart && cp /usr/share/applications/org.fcitx.Fcitx5.desktop ~/.config/autostart + ``` + + On GNOME, Fcitx5 **replaces the running `ibus-daemon`** at startup and serves the ibus protocol GNOME uses, so most applications work straight away. +2. **[Connect your session to Fcitx5](#noi-session)** (environment variables), then **log out and back in**. +3. Open `fcitx5-configtool` → **+** → add **Funput** (Vietnamese group). +4. Toggle Vietnamese: **`Ctrl + ` ` `** or the Fcitx5 tray icon. + +### Connect your session to Fcitx5 {#noi-session} -The `~/.local` install works on any architecture — it only needs an IBus or Fcitx5 daemon already present: +Funput is an engine *inside* Fcitx5 — applications only reach it if the session itself talks to Fcitx5. What to set depends on **the session type first, the desktop second**. Check which one you are on: ```bash -curl -fsSL https://raw.githubusercontent.com/Funput/Funput/main/platforms/linux/install.sh | bash -s -- --user +echo $XDG_SESSION_TYPE +``` + +Sources: [Using Fcitx 5 on Wayland](https://fcitx-im.org/wiki/Using_Fcitx_5_on_Wayland) and [Setup Fcitx 5](https://fcitx-im.org/wiki/Setup_Fcitx_5). + +#### An `x11` session + +The classic three, the same on every desktop: + +``` +XMODIFIERS=@im=fcitx +GTK_IM_MODULE=fcitx +QT_IM_MODULE=fcitx +``` + +Do not write them by hand if your distro ships a tool for it: + +| Distro | Tool | +| ------ | ---- | +| Debian / Ubuntu (and Mint, Pop!_OS…) | `im-config -n fcitx5` — writes exactly the above **and** starts the daemon. Run `im-config` with no arguments for the wizard. | +| Fedora | `sudo dnf install fcitx5-autostart` — the package ships an `/etc/profile.d` script and an autostart entry. `im-chooser` (from `imsettings`) is the graphical equivalent. | +| Arch, openSUSE, others | No distro tool — set them by hand, see [Where to put them](#dat-o-dau) below. | + +#### A `wayland` session + +The three above are **not** right for Wayland: GTK 3/4 reach the compositor through `text-input-v3` on their own, and setting the trio globally under KWin makes the candidate window blink. + +**GNOME — and sway, other wlroots compositors:** + +```bash +mkdir -p ~/.config/environment.d +cat > ~/.config/environment.d/fcitx5.conf <<'EOF' +XMODIFIERS=@im=fcitx +QT_IM_MODULE=fcitx +EOF +``` + +- Leave `GTK_IM_MODULE` unset — GTK 3/4 already use `text-input-v3`. +- `QT_IM_MODULE=fcitx` is for **Qt 5 and Qt older than 6.8.2**, which run through XWayland. If your distro ships **Qt 6.8.2 or newer**, use `QT_IM_MODULES=wayland;fcitx` instead of that line. + +**KDE Plasma (5.27 or later):** + +```bash +mkdir -p ~/.config/environment.d +cat > ~/.config/environment.d/fcitx5.conf <<'EOF' +XMODIFIERS=@im=fcitx +EOF ``` -## Enable the input method +- Do **not** set `GTK_IM_MODULE` / `QT_IM_MODULE` / `SDL_IM_MODULE` globally — the candidate window blinks under KWin. If one specific application needs it (the kind that only runs under X11), set it for that app alone: `env QT_IM_MODULE=fcitx wps`. +- If you previously ran `im-config` and it set the whole trio, run `im-config` again and pick *"do not set any IM … use desktop default"*. + +:::info Debian/Ubuntu on Wayland +`im-config` **sets no variables at all** in a Wayland session — the `/etc/profile.d/im-config_wayland.sh` hook ships disabled. So on Ubuntu under Wayland you still set them yourself with the blocks above; `im-config -n fcitx5` only takes effect in an X11 session. +::: + +#### Where to put them {#dat-o-dau} + +| Location | Read by | +| -------- | ------- | +| `~/.config/environment.d/fcitx5.conf` | GDM, and Plasma 5.22+ (whichever display manager) | +| `~/.bash_profile` (with `export`) | GDM / SDDM / LightDM, and a TTY login | +| `/etc/profile` (needs root) | Every distro, for every user | + +:::caution +Environment variables are only picked up when a **new session starts** — opening a new terminal is not enough. For `environment.d` specifically, the Fcitx5 documentation notes the systemd user manager can survive a logout, so **rebooting** is the reliable way to apply a change. +::: -### IBus (GNOME / Ubuntu) +### IBus 1. Reload engines: `ibus restart` (or log out and back in). 2. **Settings → Keyboard → Input Sources → +** → **Vietnamese** → **Funput**. 3. Switch input sources: **`Super + Space`**. 4. Toggle Vietnamese on/off while Funput is active: **`Ctrl + ` ` `**. -### Fcitx5 (KDE) - -1. Open `fcitx5-configtool` → **+** → add **Funput** (Vietnamese group). -2. If Fcitx5 is not running: log out and back in, or check IM environment variables (X11: `GTK_IM_MODULE=fcitx`, `QT_IM_MODULE=fcitx`, `XMODIFIERS=@im=fcitx`). -3. Toggle Vietnamese: **`Ctrl + ` ` `** or the Fcitx5 tray icon. - ## After installation - Open the **Funput** app from the application menu to choose **Telex** or **VNI**, smart/eager restore, and other options. @@ -257,7 +374,7 @@ curl -fsSL https://raw.githubusercontent.com/Funput/Funput/main/platforms/linux/ | ------- | ------------- | | **[repo.funput.app](https://repo.funput.app)** | Via package manager — **automatic updates** | | `install.sh` (default) | Adds the repository, so also **automatic updates** | -| `install.sh --no-repo` / `--version` | Run the script again | +| `install.sh --no-repo` / `--version` / `--user` | Run the script again | | GitHub Releases | Download new package, install over existing | Automatic updates through apt/dnf/zypper/pacman require the **repo.funput.app** repository — added by hand as in Option 1 (or under Arch Linux), or by `install.sh` for you. @@ -265,40 +382,51 @@ Automatic updates through apt/dnf/zypper/pacman require the **repo.funput.app** ### Update via the Funput repository ```bash -# Debian / Ubuntu (IBus) -sudo apt update && sudo apt upgrade funput-ibus - # Debian / Ubuntu (Fcitx5) sudo apt update && sudo apt upgrade funput -# Fedora (IBus) -sudo dnf upgrade funput-ibus +# Debian / Ubuntu (IBus) +sudo apt update && sudo apt upgrade funput-ibus # Fedora (Fcitx5) sudo dnf upgrade funput -# openSUSE (IBus) -sudo zypper update funput-ibus +# Fedora (IBus) +sudo dnf upgrade funput-ibus # openSUSE (Fcitx5) sudo zypper update funput +# openSUSE (IBus) +sudo zypper update funput-ibus + # Arch sudo pacman -Syu ``` :::tip -After updating, if the input method misbehaves: run `ibus restart` (IBus) or log out and back in. +After updating, if the input method misbehaves: run `fcitx5 -r -d` (Fcitx5 — **except on KDE**, see the warning under Troubleshooting) or `ibus restart` (IBus). Logging out and back in is the safe answer on every desktop. ::: ## Troubleshooting -### Funput does not appear in Input Sources +### Funput does not appear in the input-method list + +- **Fcitx5:** run `fcitx5-diagnose` first — it checks both the session environment variables and the loaded addons, and points straight at what is missing. Then restart the daemon with `fcitx5 -r -d` and reopen `fcitx5-configtool`. + :::caution Do not restart on KDE + When Fcitx5 is started from **Virtual keyboard**, KWin hands it a socket a replacement process cannot inherit. `fcitx5 -r` (or "Restart" in the tray menu) leaves Wayland applications with no input method until the next login — log out and back in instead. + ::: - **IBus:** run `ibus restart` or log out and back in. -- Confirm you installed the correct package for your framework (`funput-ibus` for IBus, `funput` for Fcitx5). +- Confirm you installed the correct package for your framework (`funput` for Fcitx5, `funput-ibus` for IBus). - Open the **Funput** app from the application menu — onboarding may guide you through any missing step. +### Funput is added in Fcitx5 but typing does nothing + +Almost always the session environment variables — see [Connect your session to Fcitx5](#noi-session). `fcitx5-diagnose` lists each variable with its current value. Remember they only take effect after a log out and back in. + +If only **some applications** are affected (typically Qt or XWayland apps such as WPS), that is `QT_IM_MODULE` — see the GNOME block above. + ### `apt` reports dependency not installable Usually a **wrong architecture** — e.g. an `amd64` package on an `arm64` machine (or vice versa). Download the package matching your system.