C++ 函式庫 - Gradle 繁體中文

C++ 函式庫外掛程式與組態快取不相容。

C++ 函式庫外掛程式提供用於組建 C++ 函式庫的工作、慣例和約定。特別是，C++ 函式庫提供使用者（例如，使用此外掛程式或C++ 應用程式外掛程式的其他專案）可使用的功能。

使用方式

build.gradle.kts

plugins {
    `cpp-library`
}

build.gradle

plugins {
    id 'cpp-library'
}

組建變異

C++ 函式庫外掛程式了解下列面向。請閱讀組建變異簡介以取得更多資訊。

組建類型 - 永遠設定為偵錯和發行

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

debug - 產生偵錯符號，且不最佳化二進位檔
release - 產生偵錯符號並最佳化，但從二進位檔中萃取偵錯符號

連結 - 預設為共用

連結表示應建立共用函式庫或靜態函式庫。函式庫可以產生共用函式庫、靜態函式庫或兩者。

連結可以設定如下

範例 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 - 任務（生命週期）: 依賴於：linkDebug（當連結包含 shared）或 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: 副檔名為 .cpp、.C++ 或 .cc 的 C++ 來源
src/main/headers: 私人標頭 - 編譯函式庫所需的標頭，但使用者不需要
src/main/public: 公開標頭 - 編譯函式庫和使用者所需的標頭

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

`compileVariantCpp` 任務

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

編譯器參數	[]
可除錯	`true`
包含	`configurations.cppCompileVariant` + `library.publicHeaders` + `library.privateHeaders`
巨集	[:]
物件檔案目錄	`layout.buildDirectory.dir("obj/main/$variant")`
最佳化	除錯建置類型為 `false`，否則為 `true`
位置獨立程式碼	共用連結為 `true`，否則為 `false`
來源	`library.cppSource`
系統包含	從工具鏈衍生
目標平台	從二進位檔的 `TargetMachine` 衍生
工具鏈	根據目標機器自動選取

`linkVariant` 任務

C++ 函式庫外掛會新增 LinkSharedLibrary 執行個體，針對每個函式庫變異，其中包含共用連結作為一個維度 - 例如 linkDebug 和 linkRelease。請參閱建置變異簡介以取得更多資訊。以下是部分最常見的組態選項。

可除錯	`true`
函式庫	`configurations.nativeLinkVariant`
連結檔案	`layout.buildDirectory.dir("lib/main/$variant/libBaseName[.so\|dylib]")` (*nix) 或 `layout.buildDirectory.dir("lib\main\$variant\baseName.dll")` (Windows)
連結器參數	[]
來源	`compileVariantCpp.objects`
目標平台	從二進位檔的 `TargetMachine` 衍生
工具鏈	根據目標機器自動選取

`createVariant` 任務

C++ 函式庫外掛會新增 CreateStaticLibrary 執行個體，針對每個函式庫變異，其中包含靜態連結作為一個維度 - 例如 createDebug 和 createRelease。請參閱建置變異簡介以取得更多資訊。以下是部分最常見的組態選項。

輸出檔案	`layout.buildDirectory.dir("lib/main/variant/libBaseName.a")` (*nix) 或 `layout.buildDirectory.dir("lib\main\variant\baseName.lib")` (Windows)
來源	`compileVariantCpp.objects`
靜態函式庫參數	[]
目標平台	從二進位檔的 `TargetMachine` 衍生
工具鏈	根據目標機器自動選取

此頁面有幫助嗎？