CMake 配置在 Linux 上無法找到 Qt5

---

簡介

CMake 是一款用於構建、測試和打包軟體的開源跨平臺工具。由於其可移植性和能夠為各種構建系統（如 make、ninja 等）生成構建指令碼的能力，它在業界得到了廣泛應用。Qt 是一款跨平臺應用程式開發框架，廣泛用於建立 GUI 應用程式。在本文中，我們將討論開發人員在 Linux 上配置 CMake 專案時遇到的一個常見問題，即“CMake 配置無法找到 Qt5”。

理解問題

當我們使用 Qt5 配置 CMake 專案時，CMake 需要找到 Qt5 包，其中包括所需的庫、標頭檔案和其他必要檔案。CMake 使用名為“FindQt5.cmake”的模組來搜尋 Qt5 包。此模組會在系統環境變數、CMAKE_PREFIX_PATH 和 QT5DIR 中搜索 Qt5 安裝目錄。

但是，有時即使 Qt5 已安裝在系統上，CMake 也會無法找到 Qt5 包。這可能是由多種原因造成的，例如安裝不正確、缺少環境變數、路徑不正確等。讓我們討論一下 CMake 無法找到 Qt5 的一些常見原因。

CMake 配置失敗的常見原因

• 安裝不正確 - CMake 需要知道 Qt5 安裝目錄的位置才能找到所需檔案。如果 Qt5 未正確安裝，則會導致 CMake 無法找到包。在這種情況下，我們需要確保 Qt5 正確安裝，並且安裝目錄已新增到系統環境變數中。

• 缺少環境變數 - CMake 使用系統環境變數來查詢 Qt5 包。如果缺少環境變數或設定不正確，則會導致 CMake 無法找到包。我們需要確保環境變數（如 CMAKE_PREFIX_PATH 和 QT5DIR）設定正確，並指向正確的 Qt5 安裝目錄。

• 路徑不正確 - 如果 Qt5 安裝目錄的路徑不正確，則 CMake 無法找到包。在這種情況下，我們需要確保將正確的路徑新增到環境變數和 CMake 配置檔案中。

• FindQt5.cmake 模組已過時 - FindQt5.cmake 模組負責查詢 Qt5 包。如果此模組已過時或丟失，則會導致 CMake 無法找到包。在這種情況下，我們需要更新 FindQt5.cmake 模組，或者如果它丟失則安裝它。

• 缺少 Qt5 元件 - Qt5 是一個模組化框架，我們需要為專案安裝所需的元件。如果缺少所需的元件，則 CMake 無法找到包。在這種情況下，我們需要確保已安裝所需的元件。

問題的解決方法

現在我們已經瞭解了 CMake 無法找到 Qt5 的常見原因，讓我們討論一下問題的解決方法。

• 正確的安裝 - 我們需要確保 Qt5 正確安裝，並且安裝目錄已新增到系統環境變數中。要驗證安裝，我們可以在終端中執行命令“qmake -v”。如果 Qt5 正確安裝，我們可以在輸出中看到版本號。

• 設定環境變數 - 我們需要確保環境變數（如 CMAKE_PREFIX_PATH 和 QT5DIR）設定正確，並指向正確的 Qt5 安裝目錄。我們可以在終端中執行以下命令來設定環境變數：

export CMAKE_PREFIX_PATH=/path/to/qt5:$CMAKE_PREFIX_PATH export QT5DIR=/path/to/qt5

我們需要將“/path/to/qt5”替換為 Qt5 安裝目錄的實際路徑。

• 更新路徑 - 如果 Qt5 安裝目錄的路徑不正確，我們需要更新它。我們可以透過將正確的路徑新增到環境變數和 CMake 配置檔案來更新路徑。

要將路徑新增到環境變數，我們可以在終端中執行以下命令：

export PATH=/path/to/qt5/bin:$PATH

要將路徑新增到 CMake 配置檔案，我們可以將以下行新增到 CMakeLists.txt 檔案中：

set(Qt5_DIR "/path/to/qt5/lib/cmake/Qt5")

• 更新 FindQt5.cmake 模組 - 如果 FindQt5.cmake 模組已過時或丟失，我們需要更新它或安裝它。我們可以在終端中執行以下命令來更新模組：

sudo apt-get update sudo apt-get install qtbase5-dev

此命令將更新包管理器並安裝最新版本的 Qt5 開發檔案，其中包括 FindQt5.cmake 模組。

• 安裝所需的 Qt5 元件 - 我們需要確保已安裝專案所需的元件。我們可以在終端中執行以下命令來安裝所需的元件：

sudo apt-get install qtdeclarative5-dev

此命令將安裝開發 Qt5 QML 應用程式所需的 Qt5 元件。

其他提示

以下是一些其他提示，可以幫助您解決“CMake 配置無法找到 Qt5”問題：

• 檢查 CMake 快取 - CMake 為其配置的每個專案建立一個快取檔案。此檔案包含在配置過程中設定的所有 CMake 變數和選項的值。有時，快取檔案包含不正確的值，這會導致 CMake 無法找到 Qt5 包。要解決此問題，您可以刪除 CMake 快取檔案並重新執行 CMake 以重新生成它。您可以在構建目錄中執行以下命令刪除快取檔案：

rm -rf CMakeCache.txt

• 使用 FindPackage 命令 - 您可以使用內建的 CMake 命令 FindPackage 來查詢 Qt5 包，而不是使用 FindQt5.cmake 模組。此命令會自動在標準安裝位置搜尋包並設定必要的 CMake 變數。要使用此命令，請將以下行新增到您的 CMakeLists.txt 檔案中：

find_package(Qt5 COMPONENTS REQUIRED Core Gui Widgets)

此行告訴 CMake 搜尋 Qt5 包和所需的元件。如果找到包，CMake 將設定必要的 CMake 變數，例如 Qt5_FOUND、Qt5_INCLUDE_DIRS、Qt5_LIBRARIES 等。

• 使用 pkg-config - 如果您使用的 Linux 發行版支援 pkg-config 工具，則可以使用它來查詢 Qt5 包。Pkg-config 是一個命令列工具，它提供了一個統一的介面來查詢已安裝的庫及其依賴項。要使用 pkg-config 查詢 Qt5 包，請在終端中執行以下命令：

pkg-config --cflags --libs Qt5Core Qt5Gui Qt5Widgets

此命令將列印使用 Qt5 包所需的必要 C 和 C++ 編譯器標誌和連結器標誌。您可以將這些標誌複製到您的 CMakeLists.txt 檔案中，方法是設定必要的 CMake 變數。

• 使用 CMake 工具鏈檔案 - 如果您要為基於 Linux 的嵌入式系統交叉編譯 CMake 專案，則可以使用 CMake 工具鏈檔案來設定必要的環境變數和工具鏈選項。工具鏈檔案是一個 CMake 指令碼，它定義了交叉編譯環境並設定了必要的 CMake 變數。要使用工具鏈檔案，請使用“-DCMAKE_TOOLCHAIN_FILE”選項和工具鏈檔案的路徑執行 CMake，如下所示：

cmake -DCMAKE_TOOLCHAIN_FILE=/path/to/toolchain/file ...

結論

在本文中，我們討論了開發人員在使用 Qt5 在 Linux 上配置 CMake 專案時遇到的一個常見問題，即“CMake 配置無法找到 Qt5”。我們討論了該問題的常見原因和解決方法，例如更正安裝、設定環境變數、更新路徑和 FindQt5.cmake 模組以及安裝所需的 Qt5 元件。透過遵循本文中討論的解決方法，開發人員可以克服此問題並在 Linux 上使用 Qt5 配置他們的 CMake 專案。