跳至主要内容

安裝

TUT01 · Terminux · 繁體中文影片

影片​

在 YouTube 開啟影片

指南​

Terminux 0.1.0 安裝指南

目錄

適用對象。 第一次在自己的 Linux 帳號安裝 Terminux 0.1.0 可攜式安裝包的工程師,例如 IC 設計或 CAD 工程師。

完成後你會得到。 Terminux 以一般使用者身分安裝在家目錄(不需要 sudo)、與 Qt 的配對通過檢查、Terminux 視窗以英文介面開啟,且內建終端機能執行普通 shell 指令。

本 Guide 不證明的事。 不驗證 EDA 工具、工具 wrapper、DQE 資料、AI/LLM provider 或任何 signoff 流程。S08 的 echo 成功,只代表內建終端機可以使用。

兩種終端機。 系統終端機 是桌面環境原本的終端機程式,執行 Bash;Terminux 內建終端機 是 Terminux 視窗裡的終端機區域。每一步都會註明要在哪一個操作。

平台支援

平台 本版本 狀態
Ubuntu 24.04 x86_64、Bash、X11(Xorg)桌面工作階段 已實測:Ubuntu 24.04.5、glibc 2.39、Xorg/XFCE 桌面
RHEL/Rocky/AlmaLinux 9、CentOS Stream 9(x86_64) 安裝說明列為支援,但 本版本 未實測
其他 Linux 發行版、原生 Wayland、遠端顯示 未驗證
macOS、Windows、非 x86_64 CPU 本安裝包不支援;非 x86_64 系統會被安裝程式擋下

最低 CPU、記憶體與安裝耗時 尚未量測。實錄使用 4 vCPU/8 GiB 的虛擬機,這不是最低需求。

前置條件

基本安裝只需要下表項目。標示「系統管理員」的項目,請洽系統管理員或 CAD/IT 團隊。

條件 說明 通常由誰提供
Ubuntu 24.04 x86_64 glibc 2.34 以上,且系統 libstdc++ 提供 GLIBCXX_3.4.29。安裝程式會檢查兩者,缺一即停止。 系統
一般使用者帳號 可寫的家目錄與足夠空間;安裝與啟動使用同一帳號。不需要也不建議使用 sudo。 你
系統終端機使用 Bash 步驟使用 echo $?、read 等 Bash 語法。 系統
基本工具 tar、gzip、sha256sum、ls、grep、readlink(Ubuntu 桌面預設即有)。 系統
外部 Qt 6.7.3 安裝包不含 Qt。 需要 Qt 6 Desktop gcc 64-bit 安裝,含函式庫、QML 模組,以及 xcb 與 offscreen 平台 plugin。安裝程式原始碼接受 Qt 6.x 且 ≥ 6.7.0,但只實測過 6.7.3。 系統管理員
X11/xcb、OpenGL/EGL 與 GSSAPI 系統函式庫 見下方套件範例。 系統管理員
圖形登入工作階段 在執行 Terminux 的那台主機上,以同一使用者登入的實際桌面工作階段。 你/系統管理員
字型 能顯示所需文字的字型;實錄使用 Noto 字型(含 CJK)。 系統管理員
磁碟空間 安裝程式會自行計算需求;空間不足時停止,並顯示需要與可用的 bytes。 你

已隨包提供,不需另外安裝: Python 3.12(實測安裝包為 3.12.14)與基本 Python 相依套件,安裝時從安裝包離線安裝。不需要 pip、uv、編譯器或 CMake。

基本安裝不需要: EDA 工具、工具 wrapper、tcsh 設定、AI/LLM provider 或 API key、project ID。請見附錄。

X11/xcb、OpenGL/EGL 與 GSSAPI 的 Ubuntu 24.04 套件範例。 來自安裝說明與實錄環境設定,只是範例,不是已證明的最小清單;若有缺漏,安裝程式與 Qt 檢查器會列出確切的函式庫檔名(SONAME)。

用途 Ubuntu 24.04 套件範例
xcb cursor libxcb-cursor0
xcb utility、ICCCM、image、keysyms、render-util libxcb-util1、libxcb-icccm4、libxcb-image0、libxcb-keysyms1、libxcb-render-util0
XKB、X11、xcb libxkbcommon0、libxkbcommon-x11-0、libx11-6、libx11-xcb1、libxcb1
OpenGL/EGL libegl1、libgl1、libglx0、libopengl0
GSSAPI libgssapi-krb5-2

找出你的 Qt root

Terminux 需要你的 Qt root 路徑:直接包含 lib/、qml/、plugins/(以及 lib/cmake/Qt6/)的那個資料夾。

  • 以 Qt SDK 的桌面版安裝而言,通常是版本資料夾底下的編譯器資料夾,例如結尾為 /6.7.3/gcc_64 的路徑(此形式依安裝說明)。
  • 它 不是 裡面的 bin/ 資料夾,也 不是 只含版本或編譯器資料夾的上層資料夾。
  • 系統管理員可能把 Qt 裝在任何位置;不確定時請直接詢問確切路徑。
  • 錄影機器的 Qt root 是 /opt/qt673。這個路徑只屬於那台機器,不是預設值,你的機器上可能不存在。

S02 會示範在安裝前如何記下並檢查你的 Qt root。

快速路徑

已熟悉背景的讀者,可依下列七步完成本課:

  1. S02 — 把 Qt root 存進 QT_ROOT,並檢查結構與版本。
  2. S03 — 驗證安裝包 checksum。沒有可信參考時 STOP。
  3. S04 — 解開安裝包並進入 terminux-0.1.0。
  4. S05 — 以 --qt-dir "$QT_ROOT" --yes 執行安裝程式;echo $? 必須印出 0。
  5. S06 — readlink 印出 0.1.0;Qt 檢查通過;echo $? 印出 0。
  6. S07 — 啟動 ~/.local/bin/terminux。若介面是中文:Language → English,關閉視窗後再啟動一次。
  7. S08 — 在 Terminux 內建終端機執行 echo hello-terminux,看到 hello-terminux 單獨成一行。

搭配影片閱讀

影片與本指南依 S01–S08 分節。安裝前請依 S03 驗證安裝包。

S01-intro — 本課範圍

影片:R1.1 S01-intro 0:00.0–0:12.2

目的

開始前先了解成果與限制:以預編譯安裝包完成使用者層安裝、檢查 Qt、首次啟動,並在 Terminux 內建終端機執行一個普通指令。

開始前確認

先閱讀上方的「平台支援」與「前置條件」。若系統與實測平台不同,步驟或許仍可運作,但未經驗證。

終端機

本節不操作。S02~S06 與 S07 的啟動使用系統終端機;S07 的語言選擇與 S08 使用 Terminux 內建終端機。

工作目錄

不適用。

步驟

執行任何命令前,先把 S02~S08 讀過一遍,並為 S02~S06 準備同一個系統終端機視窗。

當 S08 出現單獨一行 hello-terminux 輸出時,本課即完成。從原始碼建置、EDA 流程與 AI provider 屬於其他主題(見附錄)。

預期結果

成果是可互動的 GUI 終端機;本課未驗證 EDA 或 AI 工作流程。

成功驗證

依 S05~S08 確認安裝、Qt 配對、GUI 與獨立指令輸出。

故障處理

如果你需要原始碼建置、EDA 流程或 AI provider,請先完成這份基本安裝,再參考附錄與對應的產品文件;不要為此修改 S02~S08 的步驟。

S02-prereqs — 備妥執行環境並找出 Qt root

影片:R1.1 S02-prereqs 0:12.2–0:28.1

目的

Terminux 需要安裝包以外的 Qt 與部分系統圖形函式庫。先確認你的 Qt root,避免安裝程式執行到一半才停止。

開始前確認

「前置條件」已備妥,或已由系統管理員確認。

你知道 Qt 6.7.3 安裝在哪裡,或能查得到(見「找出你的 Qt root」)。

終端機

系統終端機(Bash),在你的圖形桌面工作階段中開啟。

工作目錄

任意目錄。

步驟

  1. 把 Qt root 存進 shell 變數 QT_ROOT。出現提示時輸入 絕對路徑(以 / 開頭)後按 Enter;在這個提示中,開頭的 ~ 不會被展開。
read -r -p 'Qt root directory: ' QT_ROOT
  1. 檢查該資料夾具備 Terminux 需要的結構,且是 Qt 6.7 以上版本:
ls -d "$QT_ROOT/lib" "$QT_ROOT/qml" "$QT_ROOT/plugins" "$QT_ROOT/lib/cmake/Qt6"
grep -h 'set(PACKAGE_VERSION "[0-9]' "$QT_ROOT"/lib/cmake/Qt6/Qt6ConfigVersion*.cmake
  1. 不要關閉這個終端機視窗。S05 會用到 $QT_ROOT;如果之後開了新的終端機,請在新視窗重做步驟 1。

成功的樣子。 ls -d 原樣印出四個路徑,沒有任何錯誤;grep 印出一行類似 set(PACKAGE_VERSION "6.7.3") 的內容,其中數字就是你的 Qt 版本。這些輸出來自你自己的機器;撰寫本 Guide 時曾以本機 Qt 6.7.3 SDK 檢查過這些輔助命令,但它們不在錄影中。

Terminux 的所有步驟都不需要 sudo。安裝 Qt 或系統套件是本課開始前另外進行的管理工作;本 Guide 不提供 Qt 下載連結或 Qt 安裝步驟。

參數說明

read -r -p '…' QT_ROOT 顯示提示,並把你的輸入存進目前這個 shell 的 QT_ROOT 變數;-r 讓反斜線保持原樣。

ls -d 列出指定的資料夾本身,而不是資料夾內容。只要出現 No such file or directory,就表示該路徑不是可用的 Qt root。

grep -h 'set(PACKAGE_VERSION "[0-9]' … 讀取的版本檔,與 Terminux Qt 檢查器讀取的是同一組 Qt CMake 檔案。

實測版本是 Qt 6.7.3。安裝程式原始碼接受 Qt 6.x 且 ≥ 6.7.0,但 本版本 沒有測試其他版本。

預期結果

你的 Qt root 含有 lib、qml、plugins 與 lib/cmake/Qt6,版本為 Qt 6 且不低於 6.7.0(實測:6.7.3)。實錄環境為 Ubuntu 24.04 x86_64,Qt 6.7.3 位於 /opt/qt673;此路徑只屬錄影環境。

成功驗證

S05/S06 驗相依閉包,S07 再驗實際顯示;offscreen 自查不能證明桌面可用。

故障處理

ls: cannot access …/lib/cmake/Qt6(或 …/qml):多半是選到上層資料夾(裡面有 6.7.3/ 或 gcc_64/)或 bin/ 資料夾。請改用直接包含 lib/、qml/、plugins/ 的資料夾,再重做步驟 1~2。

路徑以 ~ 開頭:重做步驟 1,輸入完整路徑;echo $HOME 可以看到 ~ 代表的路徑。

grep 沒有輸出,或版本低於 6.7.0(例如 6.2.4):這不是合適的 Qt,請向系統管理員取得 Qt 6.7.3。

缺少的系統函式庫,會在之後由安裝程式或 Qt 檢查器以確切檔名列出;請系統管理員安裝提供該檔案的套件。不要設定 LD_LIBRARY_PATH、QT_PLUGIN_PATH 或 QML2_IMPORT_PATH;Terminux 透過自己安裝後的設定找到 Qt。

S03-identify — 確認安裝包身分

必須從獨立且經驗證的可信來源取得安裝包的 SHA256 參考值。與下載檔一起取得的 checksum 只能證明自身一致。若無獨立可信參考值,請在此 STOP:不要解壓或安裝。

sha256sum terminux-0.1.0-linux-x86_64.tar.gz

只有完整 digest 與獨立可信參考值完全相符,才能繼續 S04;任何不符、讀取錯誤或來源不明都必須 STOP。不要解壓或安裝。

SHA256 output example

S04-extract — 解開安裝包

影片:R1.1 S04-extract 0:52.9–1:03.6

目的

安裝程式在壓縮檔裡。先解開,再進入最上層資料夾。

開始前確認

S03 已通過:出現 OK,結束狀態為 0。

此資料夾有足夠空間。

終端機

系統終端機(Bash),與 S03 同一個視窗。

工作目錄

與 S03 相同的資料夾。

步驟

tar -xzf terminux-0.1.0-linux-x86_64.tar.gz && cd terminux-0.1.0
ls

第一個命令完成後,提示字元會以 terminux-0.1.0 結尾。實錄中 ls 列出:LICENSE、README-INSTALL.md、SHA256SUMS、THIRD_PARTY_NOTICES.md、VERSION、gui、install.sh、portable_installer.py、python、third_party、uninstall.sh、wheelhouse。

參數說明

tar -xzf:-x 解開、-z 處理 gzip、-f 指定壓縮檔名。

&& 只在解壓成功後才執行 cd terminux-0.1.0。

ls 列出資料夾內容,用來確認有 install.sh。

預期結果

工作目錄變為 terminux-0.1.0,ls 可見 install.sh。

成功驗證

確認目錄與實際檔案列表,不混用其他包的 installer。

故障處理

gzip: stdin: not in gzip format 或 Unexpected EOF in archive:下載不完整或檔案不對,請回到 S03。

No space left on device:釋放空間或改用其他資料夾,再重新解壓。

列表中沒有 install.sh:用 pwd 確認你位於 terminux-0.1.0。絕對不要改用其他安裝包或其他版本的安裝程式。

S05-install — 以使用者身分安裝 Terminux

影片:R1.1 S05-install 1:03.6–1:34.5(S05-install 1:03.6–1:17.9;S05-result 1:17.9–1:34.5)

目的

把預編譯 GUI、隨包 Python 執行環境與 Terminux engine 安裝到家目錄,並把 Terminux 連結到你的 Qt。過程不編譯、不使用 sudo。

開始前確認

S02 在這個終端機中完成,因此 $QT_ROOT 已設定。

S04 已完成,你位於 terminux-0.1.0。

你的帳號目前沒有執行中的 Terminux 服務。新帳號不會有;否則請見故障處理。

終端機

系統終端機(Bash),與 S02~S04 同一個視窗。

工作目錄

terminux-0.1.0(解開後的資料夾)。

步驟

./install.sh --qt-dir "${QT_ROOT:?QT_ROOT is empty - repeat the S02 Qt root step}" --yes
echo $?

實錄值。 錄影機器執行的是 ./install.sh --qt-dir /opt/qt673 --yes,因為它的 Qt root 是 /opt/qt673。請如上方命令,透過 $QT_ROOT 使用你自己的 Qt root;只有系統管理員確認 Qt 確實在該處時,才可沿用實錄路徑。

安裝程式會做的事(依 本版本 原始碼;結果已在實錄中觀察到):

  1. 預先檢查:OS、x86_64、glibc、GLIBCXX_3.4.29 與可用空間;若你的帳號仍有執行中的 Terminux 服務,也會停止。
  2. 依安裝包自己的 SHA256SUMS 驗證包內每個檔案。
  3. 建立 ~/.local/opt/terminux/0.1.0.partial,解開隨包 Python,並從 wheelhouse/ 離線安裝 Python 套件。
  4. 建立指向你 Qt root 的 qt 連結,並對這份暫存安裝執行 Qt 檢查。
  5. 全部通過後,才把資料夾改名為 ~/.local/opt/terminux/0.1.0,並把 current 指向 0.1.0。任何一步失敗時,會移除 .partial 資料夾,current 保持不變。
  6. 在 ~/.local/bin/ 建立兩個小型啟動腳本:terminux 與 terminux-qt-check。

安裝程式不會修改 ~/.bashrc、~/.profile 或其他 shell 啟動檔。實錄中安裝約花 12 秒;實際時間可能不同。

本版本的安裝程式訊息為繁體中文。 實錄中的重點行:

實錄訊息 意義
預先檢查通過:Ubuntu 24.04.5 LTS x86_64 glibc=2.39 GLIBCXX_3.4.29 可用;可用空間 … bytes。 預先檢查通過
安裝包 SHA256SUMS 通過。 安裝包內容驗證通過
Successfully installed …(pip 的英文訊息) Python 套件已安裝,但這 不是 最終結果
[通過] …(共九行) Qt 各項檢查通過;失敗 表示未通過
Qt 安裝檢查通過。 Qt 檢查通過
安裝成功:/home/…/.local/opt/terminux/0.1.0 安裝成功
current → 0.1.0 目前使用的版本為 0.1.0

成功行之後,安裝程式還會印出選用提示:Bash 與 tcsh 的 PATH 設定、tcsh hook、啟動命令 ~/.local/bin/terminux、LLM 設定為選用、移除命令,以及多台主機共用安裝時 Qt 與安裝路徑必須相同。請見附錄。

安裝後的配置

路徑 說明
~/.local/opt/terminux/0.1.0/ 版本資料夾:GUI、Python 環境、engine
~/.local/opt/terminux/current 指向 0.1.0 的連結;只在安裝成功後切換
~/.local/opt/terminux/0.1.0/qt 指向你 Qt root 的連結;請勿移動 Qt
~/.local/bin/terminux 啟動 Terminux 的啟動腳本
~/.local/bin/terminux-qt-check S06 使用的 Qt 檢查器啟動腳本
~/.terminux/ 你的執行資料、設定與 log;首次啟動時建立

本版本 實錄:安裝程式輸出結尾的安裝成功行、current → 0.1.0,以及 echo $? 印出 0

參數說明

--qt-dir 是 S02 取得的外部 Qt root。"${QT_ROOT:?…}" 的寫法會在 QT_ROOT 為空時(例如在新的終端機)直接顯示訊息並停止,不會執行安裝程式。

--yes 自動回答安裝程式的確認提問;它 不會 略過平台、ABI、Qt 或執行中服務的檢查。

預設安裝位置是 ~/.local/opt/terminux。原始碼另有 --prefix(改用其他位置)、--no-bin-link(不在 ~/.local/bin 建立啟動腳本)、--reinstall 與 --force;本課沒有使用或測試。--force 只略過「不支援的 OS」檢查,絕不能用來解決 ABI 或 Qt 問題。

預期結果

實際 installer 顯示安裝成功及 current → 0.1.0,結束狀態為 0。

成功驗證

確認可見成功行與立即查得的結束狀態,再完成 S06;只見 pip 成功不足以證明整包安裝成功。

故障處理

bash: QT_ROOT: QT_ROOT is empty - repeat the S02 Qt root step:安裝程式沒有執行。請在這個終端機重做 S02 步驟 1,再重新執行 S05。

Terminux:不支援的平台:…、Terminux:只支援 x86_64。、Terminux:glibc … 低於必要的 2.34。 或 Terminux:系統 libstdc++ 未提供 GLIBCXX_3.4.29;請洽系統管理員。:系統不在支援範圍。請洽系統管理員,不要加 --force。

Terminux:空間不足:需要 … bytes,可用 … bytes。:釋放該檔案系統的空間後,重新執行 S05。

Terminux:daemon 仍在執行(pid=…)… 或 Terminux:owner 位於其他主機 …:請在服務實際執行的主機上,用原本的方式停止它(在原啟動終端機按 Ctrl+C,或使用原服務管理方式)。不要使用 pkill,也不要刪除 lock 檔。

出現 [失敗] …,接著是 已清除 partial:…;current 未變動。:缺少 Qt 元件或函式庫。閱讀 [失敗] 那一行,並參考 S06 的故障處理。

Terminux:同版本已安裝:…;如需重裝,請加 --reinstall。:0.1.0 已經安裝,可以直接進行 S06。只有在明確決定重裝時才使用 --reinstall。

Terminux:partial 已存在,請先人工確認:…:先前的嘗試留下了 partial 資料夾。不要直接刪除;先確認沒有其他安裝正在進行,再聯絡支援窗口。

警告:保留非本安裝建立的檔案 …/.local/bin/terminux。:已存在一個不是本安裝程式建立的檔案,因此 ~/.local/bin/terminux 可能不是 Terminux 的啟動腳本。進行 S07 前,請先確認該檔案是什麼。

echo $? 印出的不是 0:安裝沒有完成。請保留完整輸出以便支援人員查因。

S06-check — 檢查安裝版本與 Qt 配對

影片:R1.1 S06-check 1:34.5–1:52.5

目的

開啟 GUI 前,先確認目前使用的版本,以及安裝後的程式能從你的 Qt 載入所需的一切。

開始前確認

S05 結尾出現 安裝成功,且結束狀態為 0。

S02 的 Qt root 仍在原處且可讀取。

終端機

系統終端機(Bash)。

工作目錄

任意目錄。命令使用完整路徑,不受 PATH 或目前資料夾影響。

步驟

readlink ~/.local/opt/terminux/current
~/.local/bin/terminux-qt-check --qt-dir ~/.local/opt/terminux/current/qt --prefix ~/.local/opt/terminux/current
echo $?

readlink 印出 0.1.0。檢查器的實錄輸出(皆為繁體中文):

實錄訊息 意義
[通過] Qt 6.7.3(需求 Qt 6.x ≥ 6.7.0) Qt 版本符合需求
[通過] Qt 函式庫(31 項) 找到 31 個 Qt 函式庫
[通過] QML import(25 項) 與 [通過] QML plugin(25 項) 找到所需的 QML 模組
[通過] 平台 plugin(2 項) 找到 xcb 與 offscreen 平台 plugin
[通過] xcb plugin 的 ldd 無缺少函式庫 X11(xcb)plugin 沒有缺少系統函式庫
[通過] qt symlink 與 qt.conf 安裝後的 qt 連結與 Qt 設定一致
[通過] terminux --self-check exit=0 GUI 程式能以 offscreen 方式啟動並載入 Qt
[通過] dqe_viewer --self-check exit=0 隨附的 viewer 程式能以 offscreen 方式啟動並載入 Qt
Qt 安裝檢查通過。 整體:Qt 檢查通過

兩項自我檢查都以 offscreen 方式執行:不會開啟視窗,也不能證明你的桌面顯示可用;這要到 S07 才驗證。它們也不是 DQE 資料流程測試。

本版本 實錄:readlink 印出 0.1.0,檢查器各行皆通過,echo $? 印出 0

參數說明

readlink ~/.local/opt/terminux/current 顯示 current 指向哪裡。它只確認連結,不代表完整的程式版本或相容性檢查。

檢查器的 --qt-dir ~/.local/opt/terminux/current/qt 是安裝後指向 Qt 的 連結,而不是直接用 $QT_ROOT,因此連結本身也會被檢查。

檢查器的 --prefix ~/.local/opt/terminux/current 是安裝後的 版本資料夾,與安裝程式的預設位置 ~/.local/opt/terminux 意義不同。

緊接在檢查器之後的 echo $?:0 表示全部檢查通過。

預期結果

readlink 顯示 0.1.0;Qt 6.7.3、庫、imports、plugins、配置與兩個自查皆通過,checker 結束狀態為 0。

成功驗證

確認 checker 所有成功行與立即結束狀態;這不是 production DQE 或真正桌面顯示測試。

故障處理

readlink 沒有輸出或顯示 No such file or directory:S05 沒有完成,請回到 S05。

[失敗] Qt 目錄不存在或 symlink 目標無效:…:Qt root 被移動、改名或未掛載。請把 Qt 恢復到原路徑;Terminux 預期它在那裡。

[失敗] 缺少系統函式庫 libxxx.so.N;EL9:…;Ubuntu 24.04:…:該行會列出對應套件。請系統管理員安裝後,再重新執行 S06。

[失敗] 缺少 QML import:…、缺少 QML plugin:… 或 缺少 Qt 函式庫:Qt 安裝不完整,需由系統管理員補齊同一版本的缺漏元件。

[失敗] qt.conf 配置:… 或某個 self-check 失敗:不要用環境變數繞過;保留完整輸出(含其下方各行)交給支援人員。

S07-launch — 啟動 Terminux 並選擇介面語言

影片:R1.1 S07-launch 1:52.5–2:35.0(S07-start 1:52.5–1:59.9;S07-language-switch 1:59.9–2:27.0;S07-relaunch 2:27.0–2:35.0)

目的

從安裝後的啟動器開啟真正的 Terminux 視窗。新帳號首次開啟時介面可能是繁體中文;本步驟說明實錄中如何切換成英文。

開始前確認

S06 已通過。

你以同一使用者登入這台主機的圖形桌面工作階段(不是沒有顯示的純 SSH 連線)。

Terminux 內建終端機的 Bash 會自動整合,不需修改 ~/.bashrc;也不需要 AI provider、EDA 工具或 project ID。

終端機

從 系統終端機 啟動 Terminux;在 Terminux 內建終端機(Terminux 視窗中顯示 shell 提示字元的區域)選擇語言。

工作目錄

任意目錄。

步驟

  1. 啟動 Terminux:
~/.local/bin/terminux

啟動器幾乎會立刻回到系統終端機的提示字元,這是正常的:它會在需要時啟動 Terminux 背景服務,然後開啟視窗。首次啟動時視窗可能稍慢出現,因為啟動器最多會等待約 30 秒讓服務就緒。

  1. 先確認目前語言:在 Terminux 內建終端機(有提示字元的區域)按右鍵,開啟 Language 子選單。即使語言設定是繁體中文,視窗選單 View 與 Help 仍可能顯示英文,所以它們不能代表目前設定;請看 Language 子選單中哪一項有勾選。若 English 已勾選,直接進行 S08。若勾選的是繁體中文,請選 English。實錄中這兩個選單項目顯示為英文。

  2. 目前開啟的視窗不會有明顯變化,也不會出現重新啟動的對話框;選擇已經儲存。以一般方式關閉 Terminux 視窗(視窗的關閉按鈕,或如錄影中按 Alt+F4)。

  3. 在系統終端機用同一個命令再次啟動 Terminux:

~/.local/bin/terminux

重新啟動後,實錄畫面顯示英文的視窗選單 View 與 Help、視窗底部的狀態文字 Terminux service ready,以及 Terminux 內建終端機中的 shell 提示字元。

Terminux service ready 是短暫的狀態訊息:視窗與提示字元仍在時它可能已經消失,沒看到它不代表失敗。請以視窗已開啟並有 shell 提示字元、Language 子選單中 English 已勾選,以及 S08 的輸出來判斷重啟結果;只有出現實際的錯誤訊息時才停止並保留訊息供支援使用(見故障處理)。

關閉視窗不一定會停止 Terminux 背景服務,這是預期行為;下次啟動會沿用它。語言選擇會存在 Terminux 設定中;請不要手動編輯設定檔來切換語言。

本版本 實錄重新啟動後:英文 View 與 Help 選單、Terminux service ready,以及 Terminux 內建終端機中的 shell 提示字元

參數說明

~/.local/bin/terminux 是 S05 建立的啟動腳本,它會呼叫 ~/.local/opt/terminux/current 底下安裝的啟動器。即使 ~/.local/bin 不在 PATH 中,完整路徑也能使用(見附錄 A)。

不需要任何參數。

預期結果

真正重啟後可見英文介面文字與可輸入的 prompt,且 Language 子選單勾選 English。短暫的狀態訊息 Terminux service ready 可能出現後消失。

成功驗證

launcher 可能在 GUI 關閉前就回到系統 prompt;請確認真正 GUI、Language 子選單中已勾選 English,以及 S08 輸出,不要以是否看見短暫的 Terminux service ready 訊息作判準。關 GUI 不代表 daemon 已停止。

故障處理

bash: …/.local/bin/terminux: No such file or directory:S05 沒有完成,或啟動腳本沒有建立(見 S05 的 警告:保留非本安裝建立的檔案 情況)。

沒有視窗,並出現 TERM_LAUNCH_FAILED … 或 TERM_LAUNCH_GUI_NOT_FOUND 等訊息:重新執行 S06;若通過,確認你是在這台主機的圖形工作階段中操作。請保留完整訊息給支援人員。

TERM_LAUNCH_DAEMON_NOT_READY…:服務在 30 秒內沒有回報就緒,shell 整合可能尚未部署。若視窗已開啟就先關閉,再啟動一次;若訊息重複出現,請保留給支援人員。

TERM_LAUNCH_WRAPPER_SETUP failed 或 disabled:自動 shell 整合沒有部署。訊息會指出要查看的 log 檔。S08 可能仍可通過,但整合功能未經確認(見附錄 B)。

TERM_DAEMON_OWNER_UNAVAILABLE host=… pid=…:你的帳號有另一個 Terminux 服務(可能在共用家目錄的另一台主機上)占用執行環境。在支援窗口確認那個服務確實已不存在之前,不要刪除 lock 檔,也不要執行訊息中提到的 reset。

重新啟動後仍是中文:確認你是在 Terminux 內建終端機的右鍵選單中選了 English、關閉了視窗,並從系統終端機重新啟動。不要用環境變數或修改設定檔強制切換。

S08-verify — 驗證 Terminux 內建終端機

影片:R1.1 S08-verify 2:35.0–3:03.3(S08-verify 2:35.0–2:51.5;S08-recap 2:51.5–3:03.3)

目的

用一個不需要 EDA 工具或 AI provider 的普通指令,確認 Terminux 內建終端機能接受鍵盤輸入、執行命令並顯示輸出。

開始前確認

S07 開啟的 Terminux 視窗仍在,並顯示 shell 提示字元。

終端機

Terminux 內建終端機(Terminux 視窗內),不是系統終端機。

工作目錄

Terminux 提示字元顯示的任何資料夾皆可。

步驟

在 Terminux 內建終端機中點一下,讓它取得鍵盤焦點,輸入下列命令後按 Enter:

echo hello-terminux

如何判讀結果。 你輸入的那一行本身也含有 hello-terminux,那不算證據。成功的標準是:在命令下方出現 獨立的一行輸出,內容只有 hello-terminux,接著出現新的提示字元。

實錄中,命令與輸出之間出現了一行以 [1]+ Done 開頭、以 terminux-notify post_exec … 結尾的訊息。這是自動 shell 整合產生的背景工作通知,既不是錯誤,也不是成功的證據;不必理會。

完成了。 之後要再次啟動 Terminux,請在系統終端機執行 ~/.local/bin/terminux;若已把 ~/.local/bin 加入 PATH,也可以只輸入 terminux(見附錄 A)。

這個結果只證明 Terminux 內建終端機可用,不代表 EDA 工具、wrapper、DQE 流程或 AI provider 已就緒。

本版本 實錄:echo hello-terminux、背景工作 Done 通知,接著是單獨一行的 hello-terminux 與新的提示字元

參數說明

echo 會印出它的參數;hello-terminux 只是一個容易辨識的字,沒有任何 Terminux 專用參數。

預期結果

指令下方有獨立 hello-terminux stdout 行,之前可能有真正的 Done 行,接著回到 prompt。

成功驗證

輸入列本身不算證據;獨立 stdout 只驗證這段終端機互動,不代表 AI/EDA 就緒。

故障處理

輸入時畫面沒有反應:在終端機區域點一下取得焦點,並確認有顯示提示字元。

只有你輸入的那一行,沒有獨立的 hello-terminux 行:在空白行按一次 Enter 後再看。若仍沒有,請截圖保留給支援人員。不要為了讓畫面乾淨而刪除 ~/.terminux、重設設定或停用 shell 整合。

hello-terminux 之前出現 Done 行:屬預期現象,檢查已通過。

故障處理速查

症狀 參考章節
ls: cannot access …/lib/cmake/Qt6 或 Qt 版本不符 S02
FAILED、did NOT match 或沒有 OK S03 — STOP,不要解壓或安裝
gzip: stdin: not in gzip format、找不到 install.sh S04
bash: QT_ROOT: QT_ROOT is empty … S05 — 在同一個終端機重做 S02
Terminux:不支援的平台…、glibc … 低於必要的 2.34、GLIBCXX_3.4.29 S05 — 系統不在支援範圍
Terminux:daemon 仍在執行… 或 owner 位於其他主機… S05 — 仍有 Terminux 服務在執行
[失敗] … S06 — 該行會指出缺少的項目
沒有視窗、出現 TERM_LAUNCH_… 訊息 S07
重新啟動後介面仍是中文 S07
只看到輸入列,沒有獨立的 hello-terminux 行 S08

每一步都適用的原則:保留完整錯誤輸出;不要刪除 ~/.terminux 或 ~/.local/opt/terminux 底下的檔案;不要用 pkill、rm -rf 或 --force 當作修復;不要設定 LD_LIBRARY_PATH、QT_PLUGIN_PATH 或 QML2_IMPORT_PATH。請改為帶著輸出內容聯絡支援窗口。

附錄 A — 選用:較短的啟動命令(PATH)

不是必要步驟;完整路徑 ~/.local/bin/terminux 一定可用。若想只輸入 terminux,可把 ~/.local/bin 加進 PATH,例如在 ~/.bashrc 加入下面這行,再開新的終端機:export PATH="$HOME/.local/bin:$PATH"。可用 type terminux 確認,應顯示位於你家目錄的 .local/bin/terminux。此便利設定 未在 本版本 實錄中測試;實錄只使用完整路徑。

附錄 B — Shell 整合與工具 wrapper

以下功能都不是 S01~S08 的前置條件。

  • Terminux 內建終端機的 Bash 會自動整合。首次啟動時 Terminux 服務會部署 shell hook;內建終端機以自己的啟動檔執行 Bash,先載入你的 ~/.bashrc,再載入 hook。你不需要修改 ~/.bashrc。(;實錄中 shell 啟動檔前後未變,S08 指令正常。本版本 未跑完整 hook 回歸測試。)
  • 外部終端機(你平常的系統終端機)不會自動整合。需要者可自行在 shell 啟動檔中 source ~/.terminux/bash_hooks.sh 以選擇加入。(;本版本 未測試。)
  • 工具 wrapper 位於 ~/.terminux/bin/,由服務的自動設定部署。它們把呼叫轉交給真正的工具,讓 Terminux 能觀察執行;它們本身不是工具,也不會安裝任何 EDA 軟體。這和只負責啟動 Terminux 的 ~/.local/bin/terminux 不同。設定 TERMINUX_AUTO_SETUP_WRAPPERS=0 會停用自動設定。(;本版本 未做端到端驗證。)
  • 若啟動器印出 TERM_LAUNCH_WRAPPER_SETUP failed 或 disabled,hook 可能沒有部署;訊息會指出要查看的 log。視窗能開、echo 能跑,都不代表整合已就緒。

附錄 C — tcsh/csh 使用者

本 Guide 的步驟使用 Bash。tcsh 使用者可參考安裝程式印出的提示(;本版本 未測試,其他版本可能不同):

  • PATH:setenv PATH "$HOME/.local/bin:$PATH"
  • Hook:在 ~/.tcshrc 加入 if ( $?TERMINUX_ACTIVE ) source ~/.terminux/tcsh_hooks.csh;只有沒有 ~/.tcshrc 時才加到 ~/.cshrc。TERMINUX_ACTIVE 只在 Terminux 內建終端機中設定,不影響其他 shell。
  • tcsh 的 $? 意義不同($?NAME 用來測試變數是否存在);查結束狀態請用 echo $status。S02 與 S05 使用的 read 與 ${QT_ROOT:?…} 是 Bash 專用寫法,因此 S02~S06 請在 Bash 中執行。
  • 傳統 csh 沒有 tcsh 的 hook 功能。

附錄 D — EDA 工具、流程與 DQE

不是基本安裝的前置條件,且 本版本 未做端到端驗證。

  • 安裝 Terminux 不會安裝任何 EDA 工具。實際流程需要你自己已安裝並取得授權的工具、工具執行環境、可用的 flow 腳本與輸入資料。
  • wrapper 存在,不代表真正的工具存在或可執行。
  • S06 的 dqe_viewer --self-check 只代表隨附的 viewer 程式能以 offscreen 方式啟動並載入 Qt,不是 DQE 資料流程測試。
  • 若出現選用 STA playbook 無法使用的訊息,屬本版本的已知限制,不影響 S01~S08。

附錄 E — AI/LLM provider

選用功能。未設定 provider 時,Terminux 不會發出 LLM 請求,S01~S08 也不需要 provider。本安裝包只含基本相依;Gemini、Anthropic、local-LLM 與 RAG 的額外套件未包含,需另行準備。provider 設定方式請見產品 README 中 LLM provider 與憑證的段落,本版本 未測試。影片 S02 提到的「核准來源」指 Qt 的提供來源,不是 AI provider。

附錄 F — 移除(僅供參考,本課未執行)

安裝程式會印出此版本的移除命令:~/.local/opt/terminux/0.1.0/uninstall.sh --version 0.1.0。依原始碼,它預設保留 ~/.terminux 中的資料、設定與 log;只有明確加上 --purge-data 才會清除,且需要輸入完整資料路徑確認。它不會修改你的 shell 啟動檔;你自行加入的 hook 行需自行移除。本版本 實錄沒有執行移除。

附錄 G — 平台與操作限制

  • 只實測過 Ubuntu 24.04 x86_64、Qt 6.7.3、Xorg 桌面。其他 Qt 版本、EL9、Wayland、遠端顯示與 GPU 加速皆未驗證。
  • 若多台主機共用同一個家目錄,每台主機都需要相同路徑的 Qt 與相同的安裝路徑(安裝程式訊息);此情境未測試。
  • 最低 CPU、記憶體與安裝耗時尚未量測。

適用版本​

相關文件​