docs: update README with safe build instructions

- Add safety note about cargo builds never touching libc - Add Quick Start instructions (run without installing) - Add Full Install step-by-step guide - Update Flatpak packaging: include tray, add D-Bus session bus permission - Update build-finish-args: device=all, session-bus socket
2026-06-28 08:11:03 +07:00 · 2026-06-28 08:11:03 +07:00 · 1aa109f5bf
commit 1aa109f5bf
parent faf4b3224d
3 changed files with 178 additions and 43 deletions
--- a/README.md
+++ b/README.md
@ -265,13 +265,57 @@ Flexible typing: type the full syllable, then add marks/tone keys at the end. Ex

 ## Installation

-### AppImage (recommended)
+> **Safety:** Viet+ is a pure Rust project. Building from source with `cargo` never touches
+> your system's `libc` or other core libraries — everything is compiled locally in `target/`.
+> No `sudo` is needed for building. Only the optional system-wide install requires root.
+
+### Quick Start (run without installing)
+
+```bash
+# Install Rust if needed: https://rustup.rs
+git clone https://github.com/vndangkhoa/vietc.git
+cd vietc
+
+# Build everything (daemon + CLI)
+cargo build --release --features "x11,wayland"
+
+# Run the daemon directly (no install)
+sudo ./target/release/vietc
+```
+
+### Full Install (system-wide)
+
+```bash
+# 1. Build the daemon and CLI
+cargo build --release --features "x11,wayland"
+
+# 2. Build the system tray (optional)
+cd ui && cargo build --release && cd ..
+
+# 3. Install binaries
+sudo cp target/release/vietc /usr/local/bin/
+sudo cp target/release/vietc-cli /usr/local/bin/
+sudo cp target/release/vietc-uinputd /usr/local/bin/
+sudo cp ui/target/release/vietc-tray /usr/local/bin/ 2>/dev/null || true
+
+# 4. Compile X11 capture helper
+gcc -O2 -o /usr/local/bin/vietc-xrecord packaging/appimage/vietc-xrecord.c -lX11 -lXtst
+
+# 5. Install config
+mkdir -p ~/.config/vietc
+cp vietc.toml ~/.config/vietc/config.toml
+
+# 6. Start the daemon
+sudo vietc
+```
+
+### AppImage (portable)

 ```bash
 ./Viet+-0.1.0-x86_64.AppImage
 ```

-Includes daemon + tray + CLI + xclip. No special permissions needed on X11.
+Includes daemon + tray + CLI + xclip. Self-contained — no system libraries are modified.

 ### Debian/Ubuntu

@ -279,16 +323,7 @@ Includes daemon + tray + CLI + xclip. No special permissions needed on X11.
 sudo dpkg -i vietc_0.1.0-1_amd64.deb
 ```

-Recommends: `libxtst6`, `xclip`
-
-### Manual
-
-```bash
-git clone https://git.khoavo.myds.me/vndangkhoa/vietc.git
-cd vietc
-make build-all
-sudo make install
-```
+Requires: `libxtst6`

 ---

@ -320,15 +355,33 @@ lm = "làm"

 ---

-## Building
+## Building from Source

 ```bash
-make build-all     # Build with X11 + Wayland
-make test          # Run 255+ tests
-make deb           # Build .deb package
-make appimage      # Build AppImage
+# Build with all backends (X11 + Wayland)
+cargo build --release --features "x11,wayland"
+
+# Build only X11
+cargo build --release --features x11
+
+# Build only Wayland
+cargo build --release --features wayland
+
+# Build system tray (needs libdbus-1-dev on Debian/Ubuntu)
+cd ui && cargo build --release
+
+# Run tests
+cargo test
+
+# Build packages
+make deb           # .deb package
+make appimage      # AppImage (requires appimagetool)
+make flatpak       # Flatpak
 ```

+> **Note:** All builds are confined to `target/` — no system files are touched until
+> you explicitly run `sudo make install` or `sudo cp`.
+
 ---

 ## License
--- a/packaging/flatpak/build-flatpak.sh
+++ b/packaging/flatpak/build-flatpak.sh
@ -7,32 +7,115 @@ VERSION="${1:-0.1.4}"

 echo "=== Building Viet+ Flatpak v${VERSION} ==="

-# Install flatpak-builder if missing
-if ! command -v flatpak-builder &>/dev/null; then
-    echo "Installing flatpak-builder..."
-    sudo apt-get install -y flatpak flatpak-builder
-fi
-
-# Add Flathub if missing
-if ! flatpak remote-list | grep -q flathub; then
-    flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
-fi
-
 # Install required runtimes
-echo "Installing GNOME Platform & SDK..."
-flatpak install -y flathub org.gnome.Platform//47 org.gnome.Sdk//47 2>/dev/null || true
-flatpak install -y flathub org.freedesktop.Sdk.Extension.rust-stable//24.08 2>/dev/null || true
+flatpak install -y flathub org.gnome.Platform//50 org.gnome.Sdk//50 2>/dev/null || true
+flatpak install -y flathub org.freedesktop.Sdk.Extension.rust-stable//25.08 2>/dev/null || true

-# Build
-echo "Building Flatpak..."
 cd "$SCRIPT_DIR"
-flatpak-builder --force-clean --repo=vietc-repo build-dir io.github.vietc.VietPlus.json

-# Export to local repo
-flatpak build-bundle vietc-repo VietPlus-${VERSION}.flatpak io.github.vietc.VietPlus
+# Clean previous build
+rm -rf build-dir vietc-repo VietPlus-*.flatpak
+
+# Initialize build directory
+flatpak build-init build-dir io.github.vietc.VietPlus \
+  org.gnome.Platform//50 org.gnome.Sdk//50
+
+# Add sdk-extensions to metadata
+cat > build-dir/metadata << 'EOF'
+[Application]
+name=io.github.vietc.VietPlus
+runtime=org.gnome.Platform/x86_64/50
+sdk=org.gnome.Sdk/x86_64/50
+sdk-extensions=org.freedesktop.Sdk.Extension.rust-stable
+EOF
+
+# Copy source code
+mkdir -p build-dir/files/src/vietc
+rsync -a "$PROJECT_ROOT/" build-dir/files/src/vietc/ --exclude=target --exclude=.git
+
+# Symlink Rust SDK extension
+RUST_FILES=$(find /var/lib/flatpak/runtime/org.freedesktop.Sdk.Extension.rust-stable \
+  -name "rustc" -type f 2>/dev/null | head -1 | sed 's|/bin/rustc||')
+mkdir -p build-dir/files/usr/lib/sdk
+ln -s "$RUST_FILES" build-dir/files/usr/lib/sdk/rust-stable
+
+# Build all Rust binaries inside sandbox
+echo "Compiling daemon, CLI, uinputd..."
+flatpak build --share=network build-dir sh -c '
+  export PATH=/usr/lib/sdk/rust-stable/bin:$PATH
+  export CARGO_HOME=/app/cargo
+  cd /app/src/vietc
+  cargo build --release -p vietc-daemon -p vietc-cli -p vietc-uinputd
+'
+
+echo "Compiling system tray..."
+flatpak build --share=network build-dir sh -c '
+  export PATH=/usr/lib/sdk/rust-stable/bin:$PATH
+  export CARGO_HOME=/app/cargo
+  cd /app/src/vietc
+  cargo build --release --manifest-path ui/Cargo.toml
+'
+
+# Install files into sandbox
+echo "Installing files..."
+flatpak build build-dir sh -c '
+  set -e
+  install -Dm755 /app/src/vietc/target/release/vietc /app/bin/vietc
+  install -Dm755 /app/src/vietc/target/release/vietc-cli /app/bin/vietc-cli
+  install -Dm755 /app/src/vietc/target/release/vietc-uinputd /app/bin/vietc-uinputd
+  install -Dm755 /app/src/vietc/ui/target/release/vietc-tray /app/bin/vietc-tray
+  gcc -O2 -o /app/bin/vietc-xrecord /app/src/vietc/packaging/appimage/vietc-xrecord.c -lX11 -lXtst
+  install -Dm755 /app/src/vietc/packaging/flatpak/vietc-wrapper.sh /app/bin/vietc-wrapper.sh
+  install -Dm644 /app/src/vietc/packaging/appimage/vietc.desktop \
+    /app/share/applications/io.github.vietc.VietPlus.desktop
+  sed -i "s/Icon=vietc/Icon=io.github.vietc.VietPlus/g" \
+    /app/share/applications/io.github.vietc.VietPlus.desktop
+  install -Dm644 /app/src/vietc/vietc.toml /app/etc/vietc/config.toml
+  mkdir -p /app/share/icons/hicolor/256x256/apps
+  cp /app/src/vietc/packaging/appimage/AppDir/vietc.svg \
+    /app/share/icons/hicolor/256x256/apps/io.github.vietc.VietPlus.svg 2>/dev/null || true
+  mkdir -p /app/share/metainfo
+  cat > /app/share/metainfo/io.github.vietc.VietPlus.metainfo.xml << "XML"
+<?xml version="1.0" encoding="utf-8"?>
+<component type="desktop-application">
+  <id>io.github.vietc.VietPlus</id>
+  <name>Viet+</name>
+  <summary>Vietnamese Input Method for Linux</summary>
+  <description>
+    <p>Zero-configuration Vietnamese input method engine supporting Telex and VNI input methods.</p>
+  </description>
+  <metadata_license>MIT</metadata_license>
+  <project_license>MIT</project_license>
+  <url type="homepage">https://github.com/vndangkhoa/vietc</url>
+  <provides><binary>vietc</binary></provides>
+  <categories><category>Utility</category></categories>
+</component>
+XML
+  mkdir -p /app/share/doc/vietc
+  cp /app/src/vietc/README.md /app/share/doc/vietc/ 2>/dev/null || true
+  cp /app/src/vietc/LICENSE /app/share/doc/vietc/ 2>/dev/null || true
+'
+
+# Finish the build
+echo "Finalizing build..."
+flatpak build-finish build-dir \
+  --socket=x11 \
+  --socket=wayland \
+  --socket=session-bus \
+  --share=ipc \
+  --device=all \
+  --command=vietc-wrapper.sh
+
+# Export to local repository
+echo "Exporting to repository..."
+flatpak build-export vietc-repo build-dir
+
+# Create single-file bundle
+echo "Creating bundle..."
+flatpak build-bundle vietc-repo "VietPlus-${VERSION}.flatpak" io.github.vietc.VietPlus

 echo "=== Done ==="
-echo "Package: $SCRIPT_DIR/VietPlus-${VERSION}.flatpak"
+echo "Package: $SCRIPT_DIR/VietPlus-${VERSION}.flatpak ($(du -h "$SCRIPT_DIR/VietPlus-${VERSION}.flatpak" | cut -f1))"
 echo ""
-echo "Install: flatpak install --user VietPlus-${VERSION}.flatpak"
-echo "Or via repo: flatpak --user remote-add --no-gpg-verify vietc-local vietc-repo && flatpak run io.github.vietc.VietPlus"
+echo "Install: flatpak install --user --bundle VietPlus-${VERSION}.flatpak"
+echo "Run:     flatpak run io.github.vietc.VietPlus"
--- a/packaging/flatpak/io.github.vietc.VietPlus.json
+++ b/packaging/flatpak/io.github.vietc.VietPlus.json
@ -12,10 +12,9 @@
  "finish-args": [
    "--socket=x11",
    "--socket=wayland",
-    "--device=input",
-    "--share=ipc",
-    "--env=XDG_CURRENT_DESKTOP=GNOME",
-    "--env=GTK_IM_MODULE=fcitx"
+    "--socket=session-bus",
+    "--device=all",
+    "--share=ipc"
  ],
  "modules": [
    {