C++ 程式庫 - Gradle 建構系統

C++ 程式庫外掛程式提供用於建置 C++ 程式庫的任務、慣例和配置。特別是，C++ 程式庫提供的功能可供消費者使用（即，其他專案使用此外掛程式或C++ 應用程式外掛程式）。

用法

build.gradle.kts

plugins {
    `cpp-library`
}

build.gradle

plugins {
    id 'cpp-library'
}

建置變體

C++ 程式庫外掛程式了解以下維度。閱讀建置變體簡介以取得更多資訊。

建置類型 - 始終設定為debug和release

建置類型控制產生二進制檔的可除錯性以及最佳化。

debug - 產生除錯符號且不最佳化二進制檔
release - 產生除錯符號並最佳化，但從二進制檔中提取除錯符號

連結類型 - 預設為shared

連結類型表示應建立共享程式庫還是靜態程式庫。程式庫可以產生共享程式庫、靜態程式庫或兩者。

連結類型可以按如下方式配置

範例 2. 配置程式庫連結類型

build.gradle.kts

library {
    linkage = listOf(Linkage.STATIC, Linkage.SHARED)
}

build.gradle

library {
    linkage = [Linkage.STATIC, Linkage.SHARED]
}

目標機器 - 預設為建置主機: 目標機器表示應用程式預期在哪些機器上執行。目標機器由其作業系統和架構識別。 Gradle 使用目標機器來決定根據主機上可用的工具鏈選擇哪個工具鏈。

目標機器可以按如下方式配置

範例 3. 配置程式庫目標機器

build.gradle.kts

library {
    targetMachines = listOf(machines.linux.x86_64,
        machines.windows.x86, machines.windows.x86_64,
        machines.macOS.x86_64)
}

build.gradle

library {
    targetMachines = [
        machines.linux.x86_64,
        machines.windows.x86, machines.windows.x86_64,
        machines.macOS.x86_64
    ]
}

任務

下圖顯示了此外掛程式新增的任務之間的關係。

請注意，C++ 程式庫的預設連結類型是共享連結，如圖所示。

圖 1. C++ 程式庫外掛程式預設任務圖

使用靜態連結時，圖表變更為如下所示

圖 2. C++ 程式庫外掛程式僅靜態程式庫任務圖

變體相依任務

C++ 程式庫外掛程式根據程式庫組件的變體建立任務。閱讀建置變體簡介以取得更多資訊。下圖顯示了變體相依任務之間的關係。

圖 3. C++ 程式庫外掛程式變體相依任務圖

取決於連結類型屬性

compileVariantCpp（例如 compileDebugCpp 和 compileReleaseCpp）- CppCompile: 相依於：所有將原始碼檔案貢獻給編譯的任務 :: 使用選定的編譯器編譯 C++ 原始碼檔案。
linkVariant（例如 linkDebug 和 linkRelease）- LinkSharedLibrary（共享連結）: 相依於：所有貢獻於連結程式庫的任務，包括透過專案相依性解析的專案中的 linkVariant 和 createVariant 任務 :: 使用選定的連結器從編譯的物件檔案連結共享程式庫。
createVariant（例如 createDebug 和 createRelease）- CreateStaticLibrary（靜態連結）: 使用選定的封存程式從編譯的物件檔案建立靜態程式庫
assembleVariant（例如 assembleDebug 和 assembleRelease）- 任務（生命週期）: 相依於：linkVariant（共享連結）或 createVariant（靜態連結）:: 彙總組裝此程式庫特定變體的任務。

生命週期任務

C++ 程式庫外掛程式將其某些任務附加到基礎外掛程式章節中記錄的標準生命週期任務 — C++ 程式庫外掛程式會自動套用基礎外掛程式

assemble - 任務（生命週期）: 相依於：當連結類型包含 shared 時為 linkDebug，否則為 createDebug。 :: 彙總任務，組裝專案中目前主機（如果存在）的共享程式庫的除錯變體（如果可用）。此任務由基礎外掛程式新增。
check - 任務（生命週期）: 彙總任務，執行驗證任務，例如執行測試。某些外掛程式會將其自己的驗證任務新增至 check。例如，C++ 單元測試外掛程式會將其測試任務附加到此生命週期任務。此任務由基礎外掛程式新增。
build - 任務（生命週期）: 相依於：check、assemble :: 彙總任務，執行專案的完整建置。此任務由基礎外掛程式新增。
clean - 刪除: 刪除建置目錄及其中的所有內容，即 layout.buildDirectory 專案屬性指定的路徑。此任務由基礎外掛程式新增。

相依性管理

就像 C++ 程式庫外掛程式建立的任務一樣，多個配置是根據程式庫組件的變體建立的。閱讀建置變體簡介以取得更多資訊。下圖描述了 C++ 程式庫外掛程式新增的配置

圖 4. C++ 程式庫外掛程式配置

白色配置是用戶應使用來宣告相依性的配置
粉紅色配置，也稱為可消耗配置 (C)，是在組件編譯、連結或針對程式庫執行時使用的配置
藍色配置，也稱為可解析配置 (R)，是組件內部的，供其自身使用

以下配置用於宣告相依性

api: 用於宣告 API 相依性（請參閱API 與實作章節）。您應該在此處宣告以遞移方式匯出給消費者的相依性，以進行編譯和連結。
implementation 延伸 api: 用於宣告主要組件所有變體的實作相依性（請參閱API 與實作章節）。您應該在此處宣告純粹是內部且不打算暴露給任何變體消費者的相依性。
mainVariantImplementation（例如 mainDebugImplementation 和 mainReleaseImplementation）延伸 implementation: 用於宣告主要組件特定變體的實作相依性（請參閱API 與實作章節）。您應該在此處宣告純粹是內部且不打算暴露給此特定變體消費者的相依性。

以下配置供消費者使用

cppApiElements 延伸 mainVariantImplementation: 用於針對程式庫進行編譯。此配置旨在供消費者使用，以檢索針對程式庫進行編譯所需的所有元素。
variantLinkElements（例如 debugLinkElements 和 releaseLinkElements）延伸 mainVariantImplementation: 用於針對程式庫進行連結。此配置旨在供消費者使用，以檢索針對程式庫進行連結所需的所有元素。
variantRuntimeElements（例如 debugRuntimeElements 和 `releaseRuntimeElements) 延伸 `mainVariantImplementation`: 用於執行程式庫。此配置旨在供消費者使用，以檢索針對程式庫執行所需的所有元素。

以下配置供程式庫本身使用

cppCompileVariant（例如 cppCompileDebug 和 cppCompileRelease）延伸 mainVariantImplementation: 用於編譯程式庫。此配置包含程式庫的編譯包含根目錄，因此在調用 C++ 編譯器來編譯它時使用。
nativeLinkVariant（例如 nativeLinkDebug 和 nativeLinkRelease）延伸 mainVariantImplementation: 僅用於連結程式庫的共享程式庫。此配置包含程式庫的程式庫，因此在調用 C++ 連結器來連結它時使用。
nativeRuntimeVariant（例如 nativeRuntimeDebug 和 nativeRuntimeRelease）延伸 mainVariantImplementation: 用於執行程式庫。此配置包含程式庫的執行階段程式庫。

API 與實作

此外掛程式公開兩個可用於宣告相依性的配置：api 和 implementation。 api 配置應用於宣告由程式庫 API 匯出的相依性，而 implementation 配置應用於宣告組件內部的相依性。

範例 4. 新增相依性

build.gradle.kts

library {
    dependencies {
        api("io.qt:core:5.1")
        implementation("io.qt:network:5.1")
    }
}

build.gradle

library {
    dependencies {
        api "io.qt:core:5.1"
        implementation "io.qt:network:5.1"
    }
}

出現在 api 配置中的相依性將以遞移方式暴露給程式庫的消費者，因此將出現在消費者的編譯包含根目錄和連結程式庫中。另一方面，在 implementation 配置中找到的相依性將不會暴露給消費者，因此不會洩漏到消費者的編譯包含根目錄和連結程式庫中。這帶來了多項好處

相依性不會洩漏到消費者的編譯包含根目錄和連結程式庫中，因此它們永遠不會意外地相依於遞移相依性
由於減少了包含根目錄和連結程式庫，因此編譯速度更快
當實作相依性變更時，重新編譯次數更少，因為消費者不需要重新編譯

慣例

C++ 程式庫外掛程式新增了來源和任務的慣例，如下所示。

專案佈局

C++ 程式庫外掛程式假設專案佈局如下所示。這些目錄都不需要存在或包含任何內容。 C++ 程式庫外掛程式將編譯它找到的任何內容，並忽略任何遺失的內容。

src/main/cpp: C++ 原始碼，副檔名為 .cpp、.C++ 或 .cc
src/main/headers: 私有標頭 - 編譯程式庫所需的標頭，但消費者不需要
src/main/public: 公開標頭 - 編譯程式庫所需的標頭，且消費者需要

您可以透過在 library 腳本區塊中分別配置 source、privateHeaders 和 publicHeaders 來配置專案佈局。

`compileVariantCpp` 任務

C++ 程式庫外掛程式為要建置的程式庫組件的每個變體新增一個 CppCompile 實例（例如 compileDebugCpp 和 compileReleaseCpp）。閱讀建置變體簡介以取得更多資訊。下面顯示了一些最常見的配置選項。

compilerArgs	[]
debuggable	`true`
includes	`configurations.cppCompileVariant` + `library.publicHeaders` + `library.privateHeaders`
macros	[:]
objectFileDir	`layout.buildDirectory.dir("obj/main/$variant")`
optimized	debug 建置類型為 `false`，否則為 `true`
positionIndependentCode	共享連結為 `true`，否則為 `false`
source	`library.cppSource`
systemIncludes	衍生自工具鏈
targetPlatform	衍生自二進制檔的 `TargetMachine`
toolChain	根據目標機器自動選取

`linkVariant` 任務

C++ 程式庫外掛程式為每個包含共享連結作為維度的程式庫變體新增一個 LinkSharedLibrary 實例 - 例如 linkDebug 和 linkRelease。閱讀建置變體簡介以取得更多資訊。下面顯示了一些最常見的配置選項。

debuggable	`true`
libs	`configurations.nativeLinkVariant`
linkedFile	`layout.buildDirectory.dir("lib/main/$variant/libBaseName[.so\|dylib]")` (*nix) 或 `layout.buildDirectory.dir("lib\main\$variant\baseName.dll")` (Windows)
linkerArgs	[]
source	`compileVariantCpp.objects`
targetPlatform	衍生自二進制檔的 `TargetMachine`
toolChain	根據目標機器自動選取

`createVariant` 任務

C++ 程式庫外掛程式為每個包含靜態連結作為維度的程式庫變體新增一個 CreateStaticLibrary 實例 - 例如 createDebug 和 createRelease。閱讀建置變體簡介以取得更多資訊。下面顯示了一些最常見的配置選項。

outputFile	`layout.buildDirectory.dir("lib/main/variant/libBaseName.a")` (*nix) 或 `layout.buildDirectory.dir("lib\main\variant\baseName.lib")` (Windows)
source	`compileVariantCpp.objects`
staticLibArgs	[]
targetPlatform	衍生自二進制檔的 `TargetMachine`
toolChain	根據目標機器自動選取

此頁面是否對您有幫助？