vcpkg.json リファレンス

vcpkg でマニフェストを使用する方法の概要については、 Manifest モードを参照してください。

マニフェストは厳密な JSON ドキュメントです。 C++スタイルのコメント (//) や末尾のコンマを含めることはできません。 ただし、 $ で始まるフィールド名を使用して、明確に定義されたキーのセットを持つ任意のオブジェクトにコメントを書き込むことができます。 これらのコメント フィールドは、ユーザー定義キー ( "features" など) を許可するオブジェクトでは使用できません。

最新の JSON スキーマは、 https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.jsonで使用できます。 Visual Studio や Visual Studio Code などの JSON スキーマがサポートされている IDE では、このファイルを使用してオートコンプリートと構文チェックを提供できます。 ほとんどの 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を使用するアプリケーションのマニフェストを示します。 この例には、IDE の検証とオートコンプリートの向上を可能にする $schema 参照も含まれています。

最上位フィールド

"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"

ポートの説明。 文字列または文字列の配列。 ライブラリの場合は必須。トップレベル プロジェクトの場合は省略可能です。

これは、ユーザーが search または find コマンドの一部としてライブラリを検出し、ライブラリの機能を学習するのに役立ちます。

"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 オブジェクトへの名前のマップ。 省略可能。

機能は、ビルドに動作と依存関係を追加するブール型フラグです。 機能の詳細については、 Manifest の概念に関するドキュメント を参照してください。

"homepage"

プロジェクトのホームページへの URI。 文字列。 省略可能。

"license"

プロジェクトの SPDX の短いライセンス式。 文字列または null。 省略可能。

"license"は、SPDX 3.19 ライセンス式であるかユーザーが展開された/share/<port>/copyright ファイルを読み取る必要があることを示すためにnullする必要があります。 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"

パッケージメンテナーの一覧。 文字列または文字列の配列。 省略可能。

"Givenname Surname<email>" という形式を使用することをお勧めします。

"name"

プロジェクトの名前です。 文字列。 ライブラリの場合は必須。トップレベル プロジェクトの場合は省略可能です。

名前は、小文字の ASCII 文字、数字、またはハイフン (-) である必要があります。 先頭と末尾をハイフンにすることはできません。 ライブラリは、ユーザーが関連するライブラリを見つけて説明するのに役立つ msft- や boost- など、組織名またはフレームワーク名をプレフィックスとして含めるのが推奨されます。

たとえば、 Boost.Asio の正式な名前を持つライブラリには、 boost-asioという名前を付ける場合があります。

"overrides"

特定の依存関係に使用する正確なバージョン ピン。 Override オブジェクトの配列。 省略可能。

"overrides" 推移的なマニフェスト (つまり依存関係から) は無視されます。 最上位レベルのプロジェクトによって定義されたオーバーライドのみが使用されます。

"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" をインクリメントする必要があります。 アップストリーム ソース バージョンが変更されると、 version フィールド が変更され、 "port-version" が 0 (または削除) にリセットされます。

詳細については、 バージョン管理 を参照してください。

"supports"

サポートされているプラットフォームとビルドの構成。 Platform 式。 省略可能。

このフィールドは、プロジェクトが特定のプラットフォーム構成で正常にビルドまたは実行されることが想定されていないことを示します。

たとえば、ライブラリで Linux 用のビルドがサポートされていない場合は、 "supports": "!linux"を使用します。

"vcpkg-configuration"

vcpkg.json ファイル内に vcpkg 構成プロパティを埋め込むことができます。 vcpkg-configuration プロパティ内のすべてのものが、vcpkg-configuration.json ファイルで定義されているかのように扱われます。 詳細については、 vcpkg-configuration.json ドキュメントを参照してください。

vcpkg.jsonでvcpkg-configurationが定義されている一方で、vcpkg-configuration.json ファイルを持つことは許可されず、vcpkg コマンドがエラー メッセージで終了します。

埋め込み例 vcpkg-configuration

{
  "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"、 "version-semver"、 "version-date"、 "version-string"

アップストリーム プロジェクトのバージョン。 文字列。 ライブラリの場合は必須。トップレベル プロジェクトの場合は省略可能です。

マニフェストには、最大 1 つのバージョン フィールドが含まれている必要があります。 各バージョン フィールドは、異なるバージョン管理 scheme に対応します:

• "version" - 緩やかな Semantic バージョン 2.0.0、3 つ以上のプライマリ番号を許可します。 例: 1.2.3.4.10-alpha1
• "version-semver" - Strict Semantic バージョン 2.0.0。 例: 2.0.1-rc5
• "version-date" - 省略可能なドット区切りの数値シーケンスを使用して、 YYYY-MM-DD 形式の日付。 数値リリースがないパッケージ (Live-at-HEAD など) に使用されます。 例: 2022-12-09.314562
• "version-string" - 任意の文字列。 注文可能なバージョンがないパッケージに使用されます。 これはまれに使用する必要があります。ただし、他のバージョン フィールドが導入される前に作成されたすべてのポートでは、このスキームが使用されます。

詳細については、 バージョン管理 を参照してください。

依存関係フィールド

各依存関係は、次のフィールドを持つ文字列またはオブジェクトです。

文字列は、 name 文字列値に定義されたオブジェクトとして解釈されます。

依存関係: "default-features"

プロジェクトが依存関係の "既定でオン" の機能に依存していることを示すブール値。 既定値は true です。

ほとんどの場合、これは false に定義する必要があり、必要な機能は明示的に依存する必要があります。

依存関係: "features"

必要な追加機能の一覧。 Feature オブジェクトの配列。 省略可能。

Feature Object は、次のフィールドを持つオブジェクトです。

• name - 機能の名前。 文字列。 必須。
• platform - Platform 式 機能が必要なプラットフォームを制限します。 省略可能。

単純な文字列は、{ "name": "<feature-name>" }と同等の有効なFeature Objectでもあります。

たとえば、 にします。

{
  "name": "ffmpeg",
  "default-features": false,
  "features": [
    "mp3lame",
    {
      "name": "avisynthplus",
      "platform": "windows"
    }  
  ]
}

mp3 エンコードをサポートする ffmpeg ライブラリを使用します。 Windows でのみ、 avisynthplus サポートも有効になります。

依存関係: "host"

現在のポートのトリプレットではなく、 host triplet の依存関係を構築する必要があることを示すブール値。 既定値は false です。

ビルド中に "実行" する必要があるツールまたはスクリプト (ビルド システム、コード ジェネレーター、ヘルパーなど) を提供する依存関係は、 "host": trueとしてマークする必要があります。 これにより、ターゲットが実行可能でない場合 ( arm64-android用にコンパイルする場合など) に、適切なクロスコンパイルが可能になります。

詳細については、 Host の依存関係 を参照してください。

依存関係: "name"

依存関係の名前。 文字列。 必須。

これは、プロジェクトの "name" プロパティと同じ制限に従います。

依存関係: "platform"

依存関係が必要なプラットフォームを制限する式。 Platform 式。 省略可能。

式が現在の構成と一致しない場合、依存関係は使用されません。 たとえば、依存関係に "platform": "!windows"がある場合は、Windows 以外のシステムを対象とする場合にのみ必要です。

依存関係: "version>="

依存関係の最小バージョン制約。

このフィールドは依存関係の最小バージョンを指定します。必要に応じて、 #N サフィックスを使用して必要に応じて最小ポート バージョンも指定します。

バージョン管理セマンティクスの詳細については、「 バージョン管理」を参照してください。

特徴フィールド

各機能は、次のフィールドを持つオブジェクトです。

機能の概念の概要については、 Manifest モード ドキュメントを参照してください。

機能を含むポートの例

{
  "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"

featureに必要な依存関係の一覧。 Dependency オブジェクトの配列。 省略可能。

このフィールドには、この機能をビルドして使用するために必要な追加の依存関係が一覧表示されます。

機能: "description"

featureの説明。 文字列または文字列の配列。 必須。

これは、ユーザーが search または find コマンドの一部として機能を検出し、その機能の機能を学習するのに役立ちます。

機能: "supports"

feature でサポートされているプラットフォームとビルドの構成。 Platform 式。 省略可能。

このフィールドには、機能が正常にビルドされて実行されるプラットフォーム構成が記載されています。

機能: "license"

機能の SPDX の短いライセンス式。 文字列または null。 省略可能。 指定しない場合、ライセンスは最上位レベルの license フィールドで指定したのと同じです。

プラットフォーム式

プラットフォーム式は、依存関係が必要な場合、またはライブラリまたは機能のビルドが必要な場合を記述する JSON 文字列です。

式は、プリミティブ識別子、論理演算子、およびグループ化から構築されます。

• !<expr>、 not <expr> - 否定
• <expr>|<expr>、 <expr>,<expr> - 論理 OR (キーワード or は予約されていますが、プラットフォーム式では無効です)
• <expr>&<expr>、 <expr> and <expr> - 論理 AND
• (<expr>) - グループ化/優先順位

次の識別子は、 triplet 設定 ビルド構成に基づいて定義されます。

プラットフォーム式の例

• Windows 以外の場合は sha256 の picosha2 が必要ですが、Windows 上の OS から取得します (BCrypt)

{
  "name": "picosha2",
  "platform": "!windows"
}

• arm64 Windows および amd64 Linux で zlib を要求する

{
  "name": "zlib",
  "platform": "(windows & arm64) | (linux & x64)"
}