cmake_pkg_config

版本 3.31 新增。

處理 pkg-config 格式的套件檔案。

概要

cmake_pkg_config(EXTRACT <package> [<version>] [...])

簡介

此命令會從 pkg-config 格式的套件檔案原生產生 CMake 變數和目標，而無需調用甚至不需要 pkg-config 實作。 <package> 可以是套件檔案的絕對路徑，或是要使用典型的 pkg-config 搜尋模式搜尋的套件名稱。 選用的 <version> 字串具有與 pkg-config 風格的版本規範相同的格式和語意，但例外的是，如果未指定比較運算子，則假定為 =。

此命令有多個簽章，並且某些選項在它們之間是通用的。它們是

EXACT / QUIET / REQUIRED

EXACT 選項要求版本字串完全匹配（包括空字串，如果未提供版本），從而覆蓋典型的 pkg-config 版本比較演算法。 這將忽略附加到版本字串的任何比較運算子。

QUIET 選項會停用資訊性訊息，包括那些指示如果套件不是 REQUIRED 則找不到套件的訊息。 如果找不到套件，REQUIRED 選項會停止處理並顯示錯誤訊息。

STRICTNESS <mode>

指定在解析和分析期間，將如何嚴格驗證套件檔案的內容。 在提供的嚴格模式下，無效的檔案將導致命令失敗。 可能的模式為

• STRICT：密切反映原始 FDO pkg-config 的行為。 變數和關鍵字必須是唯一的。 變數必須在使用前定義。 Name、Description 和 Version 關鍵字必須存在。 檔案的整體結構必須有效且可解析。

• PERMISSIVE：密切反映 pkgconf 實作的行為。 重複的變數會被覆蓋。 重複的關鍵字會被附加。 未定義的變數解析為空字串。 Name、Description 和 Version 關鍵字必須存在。 檔案的整體結構必須有效且可解析。

• BEST_EFFORT：與 PERMISSIVE 在重複或未初始化的變數和關鍵字方面的行為相同，但在任何條件下都不會失敗。 需要 BEST_EFFORT 的套件檔案在所有其他主要實作下都將無法通過驗證，應予以修復。

預設嚴格模式為 PERMISSIVE。

ENV_MODE

指定在執行給定命令時將查詢哪些環境變數。 可能的模式為

• FDO：僅查詢 freedesktop.org pkg-config 實作使用的原始 PKG_CONFIG_* 環境變數集。

• PKGCONF：查詢 pkgconf 實作使用的更廣泛的環境變數集。

• IGNORE：完全忽略環境變數的存在、不存在和值。 在所有情況下，將查詢環境變數，但為了操作目的，環境變數將被視為已定義，但值為空字串。 這不會修改目前的環境。 對於布林環境變數，例如 PKG_CONFIG_ALLOW_*，這表示它們被評估為真值。

  PKG_CONFIG_SYSROOT_PATH 是一個小的例外。 當使用 ENV_MODE IGNORE 時，預設情況下不會發生根路徑前置，並且 pc_sysrootdir 仍預設為 /。

產生目標的子命令始終忽略旗標篩選環境變數。 預設環境模式為 PKGCONF。

PC_LIBDIR <path>...

覆蓋套件檔案的預設搜尋位置；也用於導出 pc_path 套件變數。

當未提供此選項時，預設程式庫目錄是以下值中第一個可用的值

1. CMAKE_PKG_CONFIG_PC_LIB_DIRS

2. PKG_CONFIG_LIBDIR 環境變數

3. pkg-config --variable pc_path pkg-config 的輸出

4. 平台相關的預設值

PC_PATH <path>...

覆蓋將前置於搜尋路徑的補充套件檔案目錄；也用於導出 pc_path 套件變數。

當未提供此選項時，預設路徑是以下值中第一個可用的值

1. CMAKE_PKG_CONFIG_PC_PATH

2. PKG_CONFIG_PATH 環境變數

3. 空清單

DISABLE_UNINSTALLED <bool>

覆蓋對「未安裝」套件檔案的搜尋行為。 這些是帶有「-uninstalled」後綴的套件檔案，它們描述了直接從建置樹整合的套件。

通常，此類套件檔案的優先順序高於「已安裝」套件。 當 DISABLE_UNINSTALLED 為 true 時，將停用搜尋「未安裝」套件。

當未提供此選項時，預設搜尋行為由以下值中第一個可用的值決定

1. CMAKE_PKG_CONFIG_DISABLE_UNINSTALLED

2. 如果定義了 PKG_CONFIG_DISABLE_UNINSTALLED 環境變數，則停用搜尋，否則啟用搜尋。

PC_SYSROOT_DIR <path>

覆蓋將前置於 -I 編譯旗標和 -L 程式庫搜尋位置指定的路徑的根路徑；也用於導出 pc_sysrootdir 套件變數。

當未提供此選項時，預設根路徑由以下值中第一個可用的值提供

1. CMAKE_PKG_CONFIG_SYSROOT_DIR

2. PKG_CONFIG_SYSROOT_DIR 環境變數

3. 如果沒有可用的根路徑，則不會將任何內容前置於包含或程式庫目錄路徑，並且 pc_sysrootdir 將設定為 /

TOP_BUILD_DIR <path>

覆蓋用於導出 pc_top_builddir 套件變數的頂層建置目錄路徑。

當未提供此選項時，預設頂層建置目錄路徑是以下值中第一個可用的值

1. CMAKE_PKG_CONFIG_TOP_BUILD_DIR

2. PKG_CONFIG_TOP_BUILD_DIR 環境變數

3. 如果沒有可用的頂層建置目錄路徑，則不會設定 pc_top_builddir 套件變數

簽章

cmake_pkg_config(EXTRACT <package> [<version>] [...])

將套件的內容提取到變數中。

cmake_pkg_config(EXTRACT <package> [<version>]
                [REQUIRED] [EXACT] [QUIET]
                [STRICTNESS <mode>]
                [ENV_MODE <mode>]
                [PC_LIBDIR <path>...]
                [PC_PATH <path>...]
                [DISABLE_UNINSTALLED <bool>]
                [PC_SYSROOT_DIR <path>]
                [TOP_BUILD_DIR <path>]
                [SYSTEM_INCLUDE_DIRS <path>...]
                [SYSTEM_LIBRARY_DIRS <path>...]
                [ALLOW_SYSTEM_INCLUDES <bool>]
                [ALLOW_SYSTEM_LIBS <bool>])

以下變數將從套件檔案的內容中填入

變數	類型	定義
CMAKE_PKG_CONFIG_NAME	字串	Name 關鍵字的值
CMAKE_PKG_CONFIG_DESCRIPTION	字串	Description 關鍵字的值
CMAKE_PKG_CONFIG_VERSION	字串	Version 關鍵字的值
CMAKE_PKG_CONFIG_PROVIDES	清單	Provides 關鍵字的值
CMAKE_PKG_CONFIG_REQUIRES	清單	Requires 關鍵字的值
CMAKE_PKG_CONFIG_CONFLICTS	清單	Conflicts 關鍵字的值
CMAKE_PKG_CONFIG_CFLAGS	字串	CFlags / Cflags 關鍵字的值
CMAKE_PKG_CONFIG_INCLUDES	清單	來自 CMAKE_PKG_CONFIG_CFLAGS 的所有 -I 前綴旗標
CMAKE_PKG_CONFIG_COMPILE_OPTIONS	清單	來自 CMAKE_PKG_CONFIG_CFLAGS 的所有非 -I 前綴的旗標
CMAKE_PKG_CONFIG_LIBS	字串	Libs 關鍵字的值
CMAKE_PKG_CONFIG_LIBDIRS	清單	來自 CMAKE_PKG_CONFIG_LIBS 的所有 -L 前綴旗標
CMAKE_PKG_CONFIG_LIBNAMES	清單	來自 CMAKE_PKG_CONFIG_LIBS 的所有 -l 前綴旗標
CMAKE_PKG_CONFIG_LINK_OPTIONS	清單	來自 CMAKE_PKG_CONFIG_LIBS 的所有非 -L 或 -l 前綴的旗標
CMAKE_PKG_CONFIG_*_PRIVATE	*	CFLAGS / LIBS / REQUIRES 和衍生的，但在其 .private 後綴形式中

SYSTEM_INCLUDE_DIRS

覆蓋「系統」目錄，用於標記處理 CMAKE_PKG_CONFIG_CFLAGS 和衍生變數中的包含目錄。

當未提供此選項時，預設目錄由以下值中第一個可用的值提供

1. CMAKE_PKG_CONFIG_SYS_INCLUDE_DIRS

2. PKG_CONFIG_SYSTEM_INCLUDE_PATH 環境變數

3. pkgconf --variable pc_system_includedirs pkg-config 的輸出

4. 平台相關的預設值

此外，當 ENV_MODE 為 PKGCONF 時，如果可用，CMAKE_PKG_CONFIG_PKGCONF_INCLUDES 變數將會串連到清單中。 如果它不可用，將查詢以下環境變數並串連

• CPATH

• C_INCLUDE_PATH

• CPLUS_INCLUDE_PATH

• OBJC_INCLUDE_PATH

• INCLUDE（僅限 Windows）

SYSTEM_LIBRARY_DIRS

覆蓋「系統」目錄，用於標記處理 CMAKE_PKG_CONFIG_LIBS 和衍生變數中的程式庫目錄。

當未提供此選項時，預設目錄由以下值中第一個可用的值提供

1. CMAKE_PKG_CONFIG_SYS_LIB_DIRS

2. PKG_CONFIG_SYSTEM_LIBRARY_PATH 環境變數

3. pkgconf --variable pc_system_libdirs pkg-config 的輸出

4. 平台相關的預設值

此外，當 ENV_MODE 為 PKGCONF 時，如果可用，CMAKE_PKG_CONFIG_PKGCONF_LIB_DIRS 變數將會串連到清單中。 如果它不可用，將查詢 LIBRARY_PATH 環境變數並串連。

ALLOW_SYSTEM_INCLUDES

在標記處理 CMAKE_PKG_CONFIG_CFLAGS 和衍生變數中的包含目錄期間，保留「系統」目錄。

當未提供此選項時，預設值由以下值中第一個可用的值決定

1. CMAKE_PKG_CONFIG_ALLOW_SYS_INCLUDES

2. 如果定義了 PKG_CONFIG_ALLOW_SYSTEM_CFLAGS 環境變數，則保留旗標，否則在標記處理期間將對其進行篩選。

ALLOW_SYSTEM_LIBS

在標記處理 CMAKE_PKG_CONFIG_LIBS 和衍生變數中的程式庫目錄期間，保留「系統」目錄。

當未提供此選項時，預設值由以下值中第一個可用的值決定

1. CMAKE_PKG_CONFIG_ALLOW_SYS_LIBS

2. 如果定義了 PKG_CONFIG_ALLOW_SYSTEM_LIBS 環境變數，則保留旗標，否則在標記處理期間將對其進行篩選。