vcpkg.json參考
如需搭配 vcpkg 使用指令清單的概觀,請參閱 指令清單模式。
指令清單是嚴格的 JSON 檔。 它們不能包含C++樣式的批注 (//
) 或尾端逗號。 不過,您可以使用開頭 $
的功能變數名稱,在具有定義完善的索引鍵集的任何物件中撰寫批注。 任何允許使用者定義索引鍵的物件中都不允許這些批註字位(例如 "features"
)。
最新的 JSON 架構可在取得 https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json。 具有 JSON 架構支援的 IDE,例如 Visual Studio 和 Visual Studio Code,可以使用此檔案來提供自動完成和語法檢查。 對於大部分的 IDE,您應該將 中的 vcpkg.json
設定"$schema"
為此 URL。
{
"$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json",
"dependencies": [
"boost-system",
{
"name": "cpprestsdk",
"default-features": false
},
"libxml2",
"yajl"
]
}
此範例示範使用 boost-system
、 cpprestsdk
、 libxml2
和 yajl
的應用程式指令清單。 此範例也包含參考 $schema
,以啟用更佳的 IDE 驗證和自動完成。
名稱 | 必要 | 類型 | 描述 |
---|---|---|---|
builtin-baseline | No | 字串 | 建置為最上層時要使用的版本釘選 |
default-features | No | Feature 物件[] | 需要預設列出的功能 |
相依性 | No | Dependency[] | 建置及使用此專案所需的相依性清單 |
description | 程式庫 | string 或 string[] | 專案描述 |
文件 | No | 字串 | 上游項目檔的 URI |
features | No | {string: Feature} | 項目使用者可用的選用功能 |
首頁 | No | 字串 | 上游專案首頁的 URI |
許可證 | No | string 或 null | SPDX 授權表達式 |
維護 | No | string 或 string[] | 套件檔案的維護者 |
name | 程式庫 | 字串 | 專案名稱 |
覆寫 | No | Override[] | 建置為最上層時要使用的版本釘選 |
port-version | No | 整數 | 埠檔案修訂 |
支援 | No | 平台表達式 | 支援的平臺和組建組態 |
版本 version-semver version-date version-string |
程式庫 | 字串 | 上游版本資訊 |
指定預設登錄中版本解析的快捷方式 "baseline"
。 字串。 選擇性,僅供最上層專案使用。
此欄位表示認可 https://github.com/microsoft/vcpkg ,其會為您的指令清單提供全域最低版本資訊。 最上層指令清單檔案需要使用版本設定,而不需指定 "default-registry"
。 其語意與定義預設登入相同:
{
"default-registry": {
"kind": "builtin",
"baseline": "<value>"
}
}
合理行為所需的一組功能,不需要額外的自定義。
如果下列任一項,系統會自動選取預設功能:
- 埠對埠相依性具有
"default-features": true
-- 預設值。 - 最上層指令清單與的埠
"default-features": false
沒有相依性。
默認功能會處理為最上層專案可能不知道的可轉移相依性提供「預設」設定的特定案例。 其他人所使用的埠應該幾乎一律 "default-features": false
用於其相依性。
您可以使用 Feature 物件來定義平臺特定的預設功能:
{
"name": "my-port",
"default-features": [
"png",
{
"name": "winssl",
"platform": "windows"
}
]
}
如需功能的詳細資訊,請參閱 "features"
。
埠的描述。 字串或字串串數位。 連結庫的必要專案,最上層專案的選擇性專案。
這可用來協助使用者探索連結庫做為 或 find
命令的一search
部分,並了解連結庫的功能。
專案所需的相依性清單。 Dependency 物件的陣列。 選擇性。
此欄位會列出建置和使用連結庫或應用程式所需的所有相依性。
"dependencies": [
{
"name": "arrow",
"default-features": false,
"features": [
"json",
{
"name": "mimalloc",
"platform": "windows"
}
]
},
"boost-asio",
"openssl",
{
"name": "picosha2",
"platform": "!windows"
}
]
上游項目檔的 URI。 字串。 選擇性。
項目使用者可用的功能。 名稱對應至 Feature物件。 選擇性。
功能是布爾值旗標,會將其他行為和相依性新增至組建。 如需功能的詳細資訊,請參閱指令清單概念檔。
專案首頁的 URI。 字串。 選擇性。
專案的SPDX簡短授權表達式。 字串或 Null。 選擇性。
"license"
應該是SPDX 3.19授權表達式,或應該null
指出用戶必須讀取已部署的/share/<port>/copyright
檔案。 不支援 DocumentRefs。
注意
vcpkg 登錄中每個套件提供的授權資訊代表Microsoft對授權需求的最佳瞭解。 不過,這項資訊可能不是明確的。 建議使用者確認他們打算使用的每個套件的確切授權需求,因為最終要確保符合適用的授權是其責任。
MIT
LGPL-2.1-only AND BSD-2-Clause
GPL-2.0-or-later WITH Bison-exception-2.2
vcpkg 會使用下列 EBNF 來剖析授權欄位:
idchar = ? regex /[-.a-zA-Z0-9]/ ?
idstring = ( idchar ), { idchar } ;
(* note that unrecognized license and license exception IDs will be warned against *)
license-id = idstring ;
license-exception-id = idstring ;
(* note that DocumentRefs are unsupported by this implementation *)
license-ref = "LicenseRef-", idstring ;
with = [ whitespace ], "WITH", [ whitespace ] ;
and = [ whitespace ], "AND", [ whitespace ] ;
or = [ whitespace ], "OR", [ whitespace ] ;
simple-expression = [ whitespace ], (
| license-id
| license-id, "+"
| license-ref
), [ whitespace ] ;
(* the following are split up from compound-expression to make precedence obvious *)
parenthesized-expression =
| simple-expression
| [ whitespace ], "(", or-expression, ")", [ whitespace ] ;
with-expression =
| parenthesized-expression
| simple-expression, with, license-exception-id, [ whitespace ] ;
(* note: "a AND b OR c" gets parsed as "(a AND b) OR c" *)
and-expression = with-expression, { and, with-expression } ;
or-expression = and-expression, { or, and-exression } ;
license-expression = or-expression ;
套件維護人員的清單。 字串或字串串數位。 選擇性。
我們建議使用“Givenname Surname<email>” 格式。
專案的名稱。 字串。 連結庫的必要專案,最上層專案的選擇性專案。
名稱必須是小寫 ASCII 字母、數位或連字元 (-
)。 它不得以連字元開頭或結尾。 建議連結庫將其組織或架構名稱納入為前置詞,例如 msft-
或 boost-
,以協助用戶尋找和描述相關聯的連結庫。
例如,具有正式名稱 Boost.Asio
的連結庫可能會指定名稱 boost-asio
。
要用於特定相依性的確切版本釘選。 Override 對象的陣列。 選擇性。
"overrides"
會忽略從可轉移的指令清單(亦即相依性)。 只會使用最上層項目定義的覆寫。
名稱 | 必要 | 類型 | Description |
---|---|---|---|
NAME | Yes | 字串 | 埠名稱 |
version | Yes | 字串 | 要釘選的上游版本資訊。 |
version-semver version-date version-string |
Yes | 字串 | 命名特定配置已被取代的替代方案 version 。 |
port-version | No | 整數 | 要釘選的埠檔案修訂。 已被取代,以利放入版本本身。 |
"port-version"
應該在 中"version"
指定為#N
後綴。 例如, "version": "1.2.3#7"
名稱 1.2.3 版,埠-7 版。
如需更多語意詳細數據,另 請參閱版本控制 。
"overrides": [
{
"name": "arrow", "version": "1.2.3#7"
},
{
"name": "openssl", "version": "1.1.1h#3"
}
]
版本後綴,區分封裝檔案的修訂。 整數。 預設為 0
。
"port-version"
每當發行不會變更上游來源版本的新版本時,應該遞增 。 當上游來源版本變更時, 版本字段 應該變更,且 "port-version"
應該重設為 0
(或移除)。
如需詳細資訊,請參閱 版本控制 。
支援的平臺和組建組態。 平台表達式。 選擇性。
此欄位記載項目不應該在特定平台組態上成功建置或執行。
例如,如果您的連結庫不支援建置 Linux,您可以使用 "supports": "!linux"
。
允許在 vcpkg.json
檔案中內嵌 vcpkg 組態屬性。 屬性內 vcpkg-configuration
的所有專案都會被視為在檔案中 vcpkg-configuration.json
定義。 如需詳細資訊,請參閱 vcpkg-configuration.json
檔。
vcpkg-configuration
在 中vcpkg.json
定義 ,同時不允許檔案,vcpkg-configuration.json
並會導致 vcpkg 命令終止並出現錯誤訊息。
{
"name": "test",
"version": "1.0.0",
"dependencies": [ "beison", "zlib" ],
"vcpkg-configuration": {
"registries": [
{
"kind": "git",
"baseline": "768f6a3ad9f9b6c4c2ff390137690cf26e3c3453",
"repository": "https://github.com/microsoft/vcpkg-docs",
"reference": "vcpkg-registry",
"packages": [ "beicode", "beison" ]
}
],
"overlay-ports": [ "./my-ports/fmt",
"./team-ports"
]
}
上游專案的版本。 字串。 連結庫的必要專案,最上層專案的選擇性專案。
指令清單最多必須包含一個版本欄位。 每個版本欄位都會對應至不同的版本設定 設定:
"version"
- 寬鬆 語意 2.0.0 版,允許或少於 3 個主要數位。 範例:1.2.3.4.10-alpha1
"version-semver"
- 嚴格 語意版本 2.0.0。 範例:2.0.1-rc5
"version-date"
- 格式化為YYYY-MM-DD
的日期,其為選擇性結尾的點分隔數值序列。 用於沒有數值版本的套件(例如 Live-at-HEAD)。 範例:2022-12-09.314562
"version-string"
- 任意字串。 用於沒有可排序版本的套件。 這應該很少使用,不過在引進其他版本字段之前建立的所有埠都會使用此配置。
如需詳細資訊,請參閱 版本控制 。
每個相依性都是字串或具有下列欄位的物件:
名稱 | 必要 | 類型 | 描述 |
---|---|---|---|
default-features | No | bool | 需要預設列出的功能 |
features | No | Feature 物件[] | 需要的其他功能清單 |
host | No | bool | 需要主計算機的相依性,而不是目標 |
name | Yes | 字串 | 相依性的名稱 |
平台 | No | 平台表達式 | 使用相依性之平臺的限定符 |
version>= | No | 字串 | 最低必要版本。 埠版本會 #N 以後綴來識別,例如 1.2.3#7 ,將 port-version 7 命名為 。 |
字串會解譯為定義為字串值名稱的物件。
相依性: "default-features"
布爾值,表示專案相依於相依性之「依預設」功能。 預設為 true
。
在大部分情況下,這應該定義為 false
,而且應該明確相依於任何必要的功能。
相依性: "features"
需要的其他功能清單。 Feature 對象的陣列。 選擇性。
Feature Object 是具有下列欄位的物件:
name
- 功能的名稱。 字串。 必要。platform
- 平台運算式,可限制需要此功能的平臺。 選擇性。
簡單字串也是有效的 Feature Object
對等專案 { "name": "<feature-name>" }
。
例如,
{
"name": "ffmpeg",
"default-features": false,
"features": [
"mp3lame",
{
"name": "avisynthplus",
"platform": "windows"
}
]
}
使用 ffmpeg
具有 mp3 編碼支援的連結庫。 僅在 Windows 上, avisynthplus
也已啟用支援。
相依性: "host"
布爾值,表示必須針對 主機三重 專案建置相依性,而不是目前的埠三重。 預設為 false
。
提供建置期間應「執行」之工具或文稿的任何相依性(例如組建系統、程式代碼產生器或協助程式)都應該標示為 "host": true
。 這可在目標不是可執行文件的情況下啟用正確的交叉編譯,例如針對 進行編譯 arm64-android
時。
如需詳細資訊,請參閱 主機相依性 。
相依性: "name"
相依性的名稱。 字串。 必要。
這會遵循與 "name"
項目屬性相同的限制。
相依性: "platform"
表達式,限制需要相依性的平臺。 平台表達式。 選擇性。
如果表達式不符合目前的組態,則不會使用相依性。 例如,如果相依性具有 "platform": "!windows"
,則只有在以非 Windows 系統為目標時,才需要它。
相依性: "version>="
相依性的最低版本條件約束。
此欄位會指定相依性的最低版本,選擇性地使用 #N
後綴,視需要指定最小埠版本。
如需版本設定語意的詳細資訊,請參閱 版本控制。
每項功能都是具有下列欄位的物件:
名稱 | 必要 | 類型 | 描述 |
---|---|---|---|
description | Yes | 字串 | 功能的描述 |
相依性 | No | Dependency[] | 相依性清單 |
支援 | No | 平台表達式 | 功能支援的平台和設定限定符 |
許可證 | No | string 或 null | SPDX 授權表達式 |
如需 功能的概念性概觀,請參閱指令清單模式 檔。
{
"features": {
"cbor": {
"description": "The CBOR backend",
"dependencies": [
{
"$explanation": [
"This is how you tell vcpkg that the cbor feature depends on the json feature of this package"
],
"name": "libdb",
"default-features": false,
"features": [ "json" ]
}
]
},
"csv": {
"description": "The CSV backend",
"dependencies": [
"fast-cpp-csv-parser"
]
},
"json": {
"description": "The JSON backend",
"dependencies": [
"jsoncons"
]
}
}
}
功能: "dependencies"
功能所需的相依性清單。 Dependency 物件的陣列。 選擇性。
此欄位會列出建置和使用此功能所需的任何其他相依性。
功能: "description"
功能的描述。 字串或字串串數位。 必要。
這可用來協助使用者探索功能做為 或 find
命令的一search
部分,並瞭解此功能的功能。
功能: "supports"
此欄位會記錄功能將成功建置和執行的平臺組態。
功能: "license"
功能的SPDX簡短授權表達式。 字串或 Null。 選擇性。 如果未提供,授權會與最上層 授權 欄位中指定的相同。
注意
vcpkg 登錄中每個套件提供的授權資訊代表Microsoft對授權需求的最佳瞭解。 不過,這項資訊可能不是明確的。 建議使用者確認他們打算使用的每個套件的確切授權需求,因為最終要確保符合適用的授權是其責任。
平台表達式是 JSON 字串,描述何時需要相依性,或預期要建置連結庫或功能。
運算式是從基本標識碼、邏輯運算元和群組建置:
!<expr>
、not <expr>
- 否定<expr>|<expr>
,<expr>,<expr>
- 邏輯 OR (關鍵詞or
已保留,但在平台運算式中無效)<expr>&<expr>
,<expr> and <expr>
- 邏輯 AND(<expr>)
- 群組/優先順序
下列識別碼是根據三重設定和組建組態來定義:
識別碼 | 三重條件 |
---|---|
x64 |
VCPKG_TARGET_ARCHITECTURE == "x64" |
x86 |
VCPKG_TARGET_ARCHITECTURE == "x86" |
arm |
VCPKG_TARGET_ARCHITECTURE == "arm" 或VCPKG_TARGET_ARCHITECTURE == "arm64" |
arm32 |
VCPKG_TARGET_ARCHITECTURE == "arm" |
arm64 |
VCPKG_TARGET_ARCHITECTURE == "arm64" |
arm64ec |
VCPKG_TARGET_ARCHITECTURE == "arm64ec" |
wasm32 |
VCPKG_TARGET_ARCHITECTURE == "wasm32" |
mips64 |
VCPKG_TARGET_ARCHITECTURE == "mips64" |
windows |
VCPKG_CMAKE_SYSTEM_NAME == "" 或VCPKG_CMAKE_SYSTEM_NAME == "WindowsStore" 或 VCPKG_CMAKE_SYSTEM_NAME == "MinGW" |
mingw |
VCPKG_CMAKE_SYSTEM_NAME == "MinGW" |
uwp |
VCPKG_CMAKE_SYSTEM_NAME == "WindowsStore" |
xbox |
VCPKG_CMAKE_SYSTEM_NAME == "" 和XBOX_CONSOLE_TARGET 已定義。 |
linux |
VCPKG_CMAKE_SYSTEM_NAME == "Linux" |
osx |
VCPKG_CMAKE_SYSTEM_NAME == "Darwin" |
ios |
VCPKG_CMAKE_SYSTEM_NAME == "iOS" |
freebsd |
VCPKG_CMAKE_SYSTEM_NAME == "FreeBSD" |
openbsd |
VCPKG_CMAKE_SYSTEM_NAME == "OpenBSD" |
android |
VCPKG_CMAKE_SYSTEM_NAME == "Android" |
emscripten |
VCPKG_CMAKE_SYSTEM_NAME == "Emscripten" |
qnx |
VCPKG_CMAKE_SYSTEM_NAME == "QNX" |
vxworks |
VCPKG_CMAKE_SYSTEM_NAME == "VxWorks" |
static |
VCPKG_LIBRARY_LINKAGE == "static" |
staticcrt |
VCPKG_CRT_LINKAGE == "static" |
native |
TARGET_TRIPLET == HOST_TRIPLET |
- 非 Windows 上的 sha256 需求
picosha2
,但從 Windows 上的 OS 取得它 (BCrypt)
{
"name": "picosha2",
"platform": "!windows"
}
- 需要 arm64 Windows 和 amd64 Linux 上的 zlib
{
"name": "zlib",
"platform": "(windows & arm64) | (linux & x64)"
}