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	string	建置為最上層時要使用的版本釘選
default-features	No	Feature 物件[]	需要預設列出的功能
相依性	No	Dependency[]	建置及使用此專案所需的相依性清單
description	程式庫	string 或 string[]	專案描述
文件	No	string	上游項目檔的 URI
features	No	{string： Feature}	項目使用者可用的選用功能
首頁	No	string	上游專案首頁的 URI
許可證	No	string 或 null	SPDX 授權表達式
維護	No	string 或 string[]	套件檔案的維護者
name	程式庫	string	專案名稱
重寫	No	Override[]	建置為最上層時要使用的版本釘選
port-version	No	整數	埠檔案修訂
支援	No	平台表達式	支援的平臺和組建組態
版本 version-semver version-date version-string	程式庫	string	上游版本資訊

"builtin-baseline"

指定預設登錄中版本解析的快捷方式 "baseline" 。 字串。 選擇性，僅供最上層專案使用。

此欄位表示認可 https://github.com/microsoft/vcpkg ，其會為您的指令清單提供全域最低版本資訊。 最上層指令清單檔案需要使用版本設定，而不需指定 "default-registry"。 其語意與定義預設登入相同：

{
  "default-registry": {
    "kind": "builtin",
    "baseline": "<value>"
  }
}

如需更多語意詳細數據，請參閱 版本設定 和使用 登錄 。

"default-features"

合理行為所需的一組功能，不需要額外的自定義。

如果下列任一項，系統會自動選取預設功能：

1. 埠對埠相依性具有 "default-features": true -- 預設值。
2. 最上層指令清單與的埠 "default-features": false沒有相依性。

默認功能會處理為最上層專案可能不知道的可轉移相依性提供「預設」設定的特定案例。 其他人所使用的埠應該幾乎一律 "default-features": false 用於其相依性。

您可以使用 Feature 物件來定義平臺特定的預設功能：

{
  "name": "my-port",
  "default-features": [
    "png",
    {
      "name": "winssl",
      "platform": "windows"
    }
  ]
}

如需功能的詳細資訊，請參閱 "features" 。

"description"

埠的描述。 字串或字串串數位。 連結庫的必要專案，最上層專案的選擇性專案。

這可用來協助使用者探索連結庫做為 或 find 命令的一search部分，並了解連結庫的功能。

"dependencies"

專案所需的相依性清單。 Dependency 物件的陣列。 選擇性。

此欄位會列出建置和使用連結庫或應用程式所需的所有相依性。

範例埠相依性

"dependencies": [
  {
    "name": "arrow",
    "default-features": false,
    "features": [
      "json",
      {
        "name": "mimalloc",
        "platform": "windows"
      }
    ]
  },
  "boost-asio",
  "openssl",
  {
    "name": "picosha2",
    "platform": "!windows"
  }
]

"documentation"

上游項目檔的 URI。 字串。 選擇性。

"features"

項目使用者可用的功能。 名稱對應至 Feature物件。 選擇性。

功能是布爾值旗標，會將其他行為和相依性新增至組建。 如需功能的詳細資訊，請參閱指令清單概念檔。

"homepage"

專案首頁的 URI。 字串。 選擇性。

"license"

專案的SPDX簡短授權表達式。 字串或 Null。 選擇性。

"license"應該是SPDX 3.19授權表達式，或應該null指出用戶必須讀取已部署的/share/<port>/copyright檔案。 不支援 DocumentRefs。

範例授權字串

• MIT
• LGPL-2.1-only AND BSD-2-Clause
• GPL-2.0-or-later WITH Bison-exception-2.2

EBNF

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 ;

"maintainers"

套件維護人員的清單。 字串或字串串數位。 選擇性。

我們建議使用“GivennameSurname<email>” 格式。

"name"

專案的名稱。 字串。 連結庫的必要專案，最上層專案的選擇性專案。

名稱必須是小寫 ASCII 字母、數位或連字元 （-）。 它不得以連字元開頭或結尾。 建議連結庫將其組織或架構名稱納入為前置詞，例如 msft- 或 boost- ，以協助用戶尋找和描述相關聯的連結庫。

例如，具有正式名稱 Boost.Asio 的連結庫可能會指定名稱 boost-asio。

"overrides"

要用於特定相依性的確切版本釘選。 Override 對象的陣列。 選擇性。

"overrides" 會忽略從可轉移的指令清單（亦即相依性）。 只會使用最上層項目定義的覆寫。

名稱	必要	類型​	Description
NAME	Yes	string	埠名稱
version	Yes	string	要釘選的上游版本資訊。
version-semver version-date version-string	Yes	string	命名特定配置已被取代的替代方案 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"
    }
  ]

"port-version"

版本後綴，區分封裝檔案的修訂。 整數。 預設為 0。

"port-version"每當發行不會變更上游來源版本的新版本時，應該遞增 。 當上游來源版本變更時， 版本字段 應該變更，且 "port-version" 應該重設為 0 （或移除）。

如需詳細資訊，請參閱 版本控制 。

"supports"

支援的平臺和組建組態。 平台表達式。 選擇性。

此欄位記載項目不應該在特定平台組態上成功建置或執行。

例如，如果您的連結庫不支援建置 Linux，您可以使用 "supports": "!linux"。

"vcpkg-configuration"

允許在 vcpkg.json 檔案中內嵌 vcpkg 組態屬性。 屬性內 vcpkg-configuration 的所有專案都會被視為在檔案中 vcpkg-configuration.json 定義。 如需詳細資訊，請參閱 vcpkg-configuration.json 檔。

vcpkg-configuration在 中vcpkg.json定義 ，同時不允許檔案，vcpkg-configuration.json並會導致 vcpkg 命令終止並出現錯誤訊息。

內嵌範例 vcpkg-configuration

{
  "name": "test",
  "version": "1.0.0",
  "dependencies": [ "beison", "zlib" ],
  "vcpkg-configuration": {
    "registries": [
      {
        "kind": "git",
        "baseline": "dacf4de488094a384ca2c202b923ccc097956e0c",
        "repository": "https://github.com/northwindtraders/vcpkg-registry",
        "packages": [ "beicode", "beison" ]
      }
    ],
    "overlay-ports": [ "./my-ports/fmt", 
                       "./team-ports"
    ]
  }

"version"、 、 "version-semver"、 "version-date""version-string"

上游專案的版本。 字串。 連結庫的必要專案，最上層專案的選擇性專案。

指令清單最多必須包含一個版本欄位。 每個版本欄位都會對應至不同的版本設定 設定：

• "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	string	相依性的名稱
平台	No	平台表達式	使用相依性之平臺的限定符
version>=	No	string	最低必要版本。 埠版本會 #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	string	功能的描述
相依性	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。 選擇性。 如果未提供，授權會與最上層 授權 欄位中指定的相同。

平台表達式

平台表達式是 JSON 字串，描述何時需要相依性，或預期要建置連結庫或功能。

運算式是從基本標識碼、邏輯運算元和群組建置：

• !<expr>、 not <expr> - 否定
• <expr>|<expr>、 - <expr>||<expr><expr>,<expr> 邏輯 OR （關鍵詞or已保留，但在平台表示式中無效）
• <expr>&<expr><expr> and <expr> 、 <expr>&&<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"
wasm32	VCPKG_TARGET_ARCHITECTURE == "wasm32"
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"
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)"
}