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	清單	所有未加上 -L 或 -l 前綴的 CMAKE_PKG_CONFIG_LIBS 旗標
CMAKE_PKG_CONFIG_*_PRIVATE	*	CFLAGS / LIBS / REQUIRES 及其衍生變數，但使用 .private 後綴形式

SYSTEM_INCLUDE_DIRS

覆寫「系統」目錄，用於在 CMAKE_PKG_CONFIG_CFLAGS 和衍生變數中處理 include 目錄的旗標。

如果未提供此選項，則預設目錄由以下值中第一個可用的值提供：

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 和衍生變數中處理 include 目錄的旗標時，保留「系統」目錄。

如果未提供此選項，則預設值由以下值中第一個可用的值決定：

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 環境變數，則保留旗標，否則在處理旗標期間會被過濾掉。