メンテナーガイド

2024-10-15

このドキュメントでは、ポートレシピを追加または更新するときに適用する必要がある一連のポリシーの一覧を示します。これは、 Debian のポリシーマニュアル、 Homebrew のメンテナーガイドライン、および Homebrew の数式クックブックの役割を果たすことを目的としています。

レジストリの全体的な設計目標

現在のベースラインのポートを同時にインストールできる必要がある

キュレーションされたレジストリ内のライブラリのダウンストリームユーザーに、発行する特定のベースライン内のライブラリの組み合わせが、少なくとも一部の構成で連携するようにテストされていることを示したいと考えます。ポートを互いに除外できるようにすると、このようなテストに必要なビルドの数が 2^number_of_such_casesに増えるので、このような構成をテストする機能が中断されます。さらに、追加の依存関係のインストールは常に「安全」と見なされます。依存関係が要件にインストールされていないことをポートやエンドユーザーが示す方法はありません。

もし、ユーザーに対してそのような別の状況を表現したい場合、キュレーションされたレジストリの継続的インテグレーションに決して組み込まれない追加ポートを試みるのではなく、オーバーレイポートを作成する方法とportfile.cmakeのコメントでその代替フォームを実装する方法を説明することを検討してください。たとえば、 glad@0.1.36 を参照してください。

registriesの導入前に、オーバーレイポートの作成を容易にする可能性がある、boringsslなど、テストされていないポートをいくつか受け入れることができました。レジストリでは、キュレーションされたレジストリを変更せずに、これらの未テストポートの発行が許可されるため、これは受け入れなくなりました。

16 進数の文字列に小文字を使用する

vcpkg の機能の多くは、16 進数の文字列の比較に依存しています。例としては、SHA512 ハッシュ、Git コミット ID、ツリーオブジェクトハッシュなどがありますが、これらに限定されません。

内部的には、vcpkg は、大文字と小文字が区別されない値の比較で小文字の正規化を使用します。ただし、vcpkg のインフラストラクチャ上に構築されたツールでは、同じ考慮事項が発生しない場合があります。このため、16 進数の文字列が必要です

次のシナリオでは、一貫性を保つために小文字にする必要があります。

vcpkg ヘルパー関数の SHA512 パラメーター。
vcpkg ヘルパー関数の REF パラメーター (値が 16 進数の文字列の場合)。
git-tree内のオブジェクト。
sha512 ファイル内のscripts/vcpkg-tools.json オブジェクト。
16 進文字列の大文字と小文字が重要でないその他の場所。

PR 構造体

ポートごとに個別のプル要求を行う

可能な限り、変更を複数の PR に分割します。これにより、レビューが大幅に容易になり、1 つの変更の問題が他の変更を遅らせるのを防ぐことができます。

変更されていないファイルの簡単な変更を回避する

たとえば、問題を修正する理由がないポートファイル内の変数の再フォーマットや名前変更は避けてください。しかし、PRの主な目的(ライブラリの更新)のためにファイルを変更する必要がある場合は、タイプミスの修正のような明らかに有益な変更が評価されます!

他のリポジトリに対して名前を確認する

ポート名は、ポートがインストールするパッケージを明確にするように試みる必要があります。理想的には、検索エンジンでポートの名前を検索すると、対応するプロジェクトにすばやく移動します。複数のリポジトリにまたがる多数のパッケージ名を一度にチェックする優れたサービスは、 Repologyです。

一般的な単語や短い名前が付けられたプロジェクトは、特定の単語に強い関連付けを持つプロジェクトが存在しない場合には、曖昧さ回避が必要になることがあります。たとえば、 ip という名前のポートは、複数のプロジェクトに同様の名前が付けられる可能性があるため、受け入れできません。

有効なあいまいさの解消手段の例を以下に示します。

リポジトリの所有者のユーザー名または組織: google-cloud-cpp。
プロジェクトが含まれるライブラリスイートの名前: boost-dll。

C++ およびオープンソースプロジェクトで使用される一般的なプレフィックスとサフィックスは、有効なあいまいさを解消できません。一部の例は次のとおりですが、これらに限定されません。

cpp,
free,
lib,
open,
数字

たとえば、次のポート名を比較する場合: ip-cpp、 libip 、および ip5 、無効なあいまいさを除去すると、それらはすべて同じステム (ip) に減少するため、同じ名前であると見なされます。

このガイドラインの例外は、1 つのプロジェクトに厳密に関連付けられている名前に対して行われます。たとえば、libpng、openssl、zlib のようにします。

GitHub ドラフト PR を使用する

GitHub Draft PR は、まだマージする準備ができていない作業に関する CI または人間のフィードバックを得るための優れた方法です。ほとんどの新しい PR は下書きとして開き、CI が通過したら通常の PR に変換する必要があります。

GitHub ドラフト PR の詳細については、「ドラフトプルリクエストの紹介」を参照してください。

ポートファイル

非推奨のヘルパー関数を回避する

現時点では、次のヘルパーは非推奨となっています。

vcpkg_extract_source_archive_ex() は、サポートされているオーバーロードの vcpkg_extract_source_archive() に置き換える必要がある (ARCHIVE を使用)
vcpkg_extract_source_archive()のないARCHIVEの非推奨のオーバーロードは、ARCHIVEでサポートされているオーバーロードに置き換える必要があります。
vcpkg_apply_patches() は、"extract" ヘルパーの PATCHES 引数に置き換える必要があります (例: vcpkg_from_github())
vcpkg_build_msbuild() を vcpkg_install_msbuild() に置き換える必要があります。
vcpkg_copy_tool_dependencies() を vcpkg_copy_tools() に置き換える必要があります。
vcpkg_configure_cmake 削除後に vcpkg_cmake_configure() に置き換える必要があります PREFER_NINJA
vcpkg_build_cmake を vcpkg_cmake_build() に置き換える必要があります。
vcpkg_install_cmake を vcpkg_cmake_install() に置き換える必要があります。
vcpkg_fixup_cmake_targets を vcpkg_cmake_config_fixup に置き換える必要があります。

一部の置換ヘルパー関数は、コンシューマーが特定のバージョンで動作をピン留めし、特定のバージョンでヘルパーの動作をロックできるようにするための "ツールポート" にあります。次のように、ツールポートをポートの "dependencies"に追加する必要があります。

{
  "name": "vcpkg-cmake",
  "host": true
},
{
  "name": "vcpkg-cmake-config",
  "host": true
}

ポートファイル内の過剰なコメントを避ける

理想的には、ポートファイルは短く、単純で、可能な限り宣言型にする必要があります。 PR を送信する前に、 create コマンドによって導入されたボイラープレートコメントを削除します。

ポートはパスに依存してはなりません

ポートは、既にインストールされているポートに基づいて動作を変更し、その結果としてインストールする内容が変わるようなことはあってはなりません。次に例を示します。

> vcpkg install a
> vcpkg install b
> vcpkg remove a

そして

> vcpkg install b

bによってインストールされたファイルは、aの以前のインストールによる影響に関係なく、同じである必要があります。つまり、ポートは、何らかのアクションを実行する前に、別のポートによってインストールされたツリーに何かが提供されているかどうかを検出しようとしないでください。このような "パス依存" 動作の具体的で一般的な原因については、以下の「機能を定義する場合、依存関係を明示的に制御する」で説明します。

一意のポート属性ルール

vcpkg システム全体では、ユーザーが同時に使用する必要がある 2 つのポートが同じファイルを提供する可能性はありません。ポートが別のファイルによって既に提供されているファイルをインストールしようとすると、インストールは失敗します。たとえば、ポートでヘッダーに非常に一般的な名前を使用する場合は、それらのヘッダーを includeではなくサブディレクトリに配置する必要があります。

このプロパティは、レジストリにすべてのポートをインストールしようとする継続的インテグレーション実行によって定期的にチェックされます。これは、2 つのポートが同じファイルを提供する場合、 FILE_CONFLICTS で失敗します。

非公式の名前空間に CMake エクスポートを追加する

vcpkg の中心的な設計の理想は、ユーザーに対して "ロックイン" を作成しないことです。ビルドシステムでは、システムのライブラリに依存することと、vcpkg のライブラリに依存することに違いはありません。そのため、CMake エクスポートまたはターゲットを既存のライブラリに "わかりやすい名前" で追加することは避け、アップストリームは vcpkg と競合することなく独自の公式の CMake エクスポートを追加できます。

そのため、ポートがエクスポートする CMake 構成のうち、アップストリーム　ライブラリにないものには、プレフィックスとして unofficial- を付ける必要があります。追加のターゲットは、 unofficial::<port>:: 名前空間に存在する必要があります。

これは、ユーザーに次の情報が表示されることを意味します。

vcpkg に特有のパッケージを取得する方法としての find_package(unofficial-<port> CONFIG)
unofficial::<port>::<target> そのポートからエクスポートされたターゲットとして。

例 :

brotli は unofficial-brotli パッケージを作成し、ターゲット unofficial::brotli::brotliを生成します。

著作権ファイルをインストールする

各ポートは、フォルダー copyrightに ${CURRENT_PACKAGES_DIR}/share/${PORT} という名前のファイルを提供する必要があります。パッケージのライセンスコンテンツをソースファイル内で使用できる場合は、 vcpkg_install_copyright()の呼び出しによってこのファイルを作成する必要があります。 vcpkg_install_copyright また、必要に応じて複数の著作権ファイルをバンドルします。

vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE")

このファイルを手動で作成する古い方法は、CMake の組み込みの file コマンドです。これは、新しいポートでの vcpkg_install_copyright を優先することはお勧めしませんが、引き続き許可されます。

file(INSTALL "${SOURCE_PATH}/LICENSE" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}" RENAME copyright)

アップストリームソースファイル内のライセンスコンテンツがテキスト形式 (PDF ファイルなど) にない場合は、 copyright ユーザーがライセンス要件を見つける方法に関する説明を含める必要があります。可能であれば、これを示す元のソースファイルへのリンクも含める必要があるため、ユーザーは最新かどうかを確認できます。

file(WRITE "${CURRENT_PACKAGES_DIR}/share/${PORT}/copyright" [[As of 2023-07-25, according to
https://github.com/GPUOpen-LibrariesAndSDKs/display-library/blob/master/Public-Documents/README.md#end-user-license-agreement
this software is bound by the "SOFTWARE DEVELOPMENT KIT LICENSE AGREEMENT" PDF located at
https://github.com/GPUOpen-LibrariesAndSDKs/display-library/blob/master/Public-Documents/ADL%20SDK%20EULA.pdf
]])

ポートのバージョン制約

ポート内のバージョン制約は、プロジェクトの独立した進化を妨げる可能性があるため、通常は避ける必要があります。このような制約の追加は、特定の以前のバージョンとの互換性がない実証済みなど、適切に文書化された正当な理由がある場合にのみ許容されます。これらの制約は、独立したプロジェクトとの同等性を維持するためだけに使用しないでください。

`MAYBE_UNUSED_VARIABLES`内の変数は、少なくとも 1 つの構成に適用する必要があります

CMake 構成手順中に警告を無音にするために新しい変数を MAYBE_UNUSED_VARIABLES に追加する場合は、新しい変数が適用されたときのケースを説明するコメントを追加する必要があります。どの構成にも変数が適用されない場合、基になるバグ (たとえば、スペルミスの変数名) が存在する可能性が非常に高く、追加してもビルドに実際の影響はありません。

vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
  FEATURES
    windowsfeature WINDOWS_OPTION
)

vcpkg_configure_cmake(
  SOURCE_PATH "${SOURCE_PATH}"
  OPTIONS
    ${FEATURE_OPTIONS}
  MAYBE_UNUSED_VARIABLES
    # Applies only on Windows
    WINDOWS_OPTION
)

機能

機能を使用して代替手段を実装しない

特徴は追加機能として扱う必要があります。 port[featureA]をインストールし、port[featureB]をインストールする場合は、port[featureA,featureB]をインストールする必要があります。さらに、2 つ目のポートが [featureA] に依存し、3 つ目のポートが [featureB]に依存している場合は、2 番目と 3 番目のポートの両方をインストールすると、依存関係が満たされている必要があります。

この状況のライブラリでは、vcpkg で表される使用可能なオプションのいずれかを選択する必要があり、別の設定を必要とするユーザーは、現時点でオーバーレイポートを使用する必要があります。

旧バージョンとの互換性を保つために、現在は受け入れられない既存の例:

libgit2 libzip、open62541はすべて、TLS または暗号化バックエンドを選択するための機能を備えています。 curl には異なる暗号化バックエンドオプションがありますが、実行時に選択できます。つまり、上記のテネットが維持されます。
darknet には、依存関係に使用する opencv のバージョンを制御する opencv2、 opencv3機能があります。

機能はプレビュー機能またはベータ版の機能を利用する場合があります

上記にかかわらず、プレビュー機能がプレビュー以外の機能 (API の削除なしなど) を中断しない可能性が高いプレビューブランチなどがある場合は、この設定をモデル化できます。

例 :

(フォーム azure-Xxxの) Azure SDK には、 public-preview 機能があります。
imgui には、公開番号付きリリースごとに添付されたマージコミットを使用するプレビュードッキングブランチを使用する experimental-docking 機能があります。

既定の機能では API を追加できません

既定の機能は、ライブラリを使用していることを知らないお客様に対して、ライブラリの合理的に機能的なビルドが確実にインストールされるようにするためのものです。ライブラリを使用していることを知らない場合は、機能を一覧表示することはできません。たとえば、 libarchive は、圧縮アルゴリズムを有効にする機能を既存の汎用インターフェイスに公開します。そのような機能を使用せずにビルドされた場合、ライブラリにはユーティリティがない可能性があります。

既定の機能の無効化は複雑であるため、機能を既定でオンにする必要があるかどうかを慎重に検討する必要があります。

"推移的" コンシューマーとして既定の機能を無効にする場合は、次のものが必要です。

すべてのお客様は、 "default-features": false を使用して既定の機能を明示的に無効にするか、コマンドラインの機能リストに [core] を含めます。
vcpkg install コマンドラインに推移的な依存関係の名前を付けるか、最上位レベルのマニフェストで直接依存関係として名前を付ける

vcpkg のキュレーションレジストリでは、機能によって追加の API、実行可能ファイル、またはその他のバイナリが追加される場合は、既定でオフになっている必要があります。不明な場合は、機能を既定としてマークしないでください。

発行済みインターフェイスの代替機能を制御するために機能を使用しない

ポートのコンシューマーがそのポートのコア機能のみに依存している場合、機能をオンにしても問題が生じることはほぼ避けなければなりません。これは、代替手段がコンシューマーによって直接制御されるのではなく、 /std:c++17 / -std=c++17などのコンパイラ設定によって制御される場合にさらに重要になります。

旧バージョンとの互換性を保つために、現在は受け入れられない既存の例:

redis-plus-plus[cxx17] はポリフィルを制御しますが、設定をインストール済みのツリーにベイクしません。
ace[wchar]は、const wchar_t*ではなくconst char*を受け入れるようにすべての API を変更します。

インストールされたツリーに置き換えが組み込まれている場合、機能によりポリフィルがエイリアスで置き換えられる場合があります

上記にかかわらず、ポートは、次の場合に限り、機能を備えたポリフィルを削除できます。

この機能をオンにすると、ポリフィルがポリフィルされたエンティティのエイリアスに変更されます
ポリフィルの状態はインストールされたヘッダーに組み込まれているため、ABI の不一致による "不可能な" ランタイムエラーが発生する可能性は低い。
ポートのコンシューマーは、たとえば、ポリフィルされた typedef を使用するかどうかにかかわらず、両方のモードで機能するコードを書くことができます。

例:

abseil[cxx17]はabsl::string_viewを置換またはstd::string_viewに変更します。パッチはベーキング要件を実装します。

推奨されるソリューション

基になる代替手段を公開することが重要な場合は、ビルド時にメッセージを提供して、プライベートオーバーレイにポートをコピーする方法をユーザーに指示することをお勧めします。

set(USING_DOG 0)
message(STATUS "This version of LibContoso uses the Kittens backend. To use the Dog backend instead, create an overlay port of this with USING_DOG set to 1 and the `kittens` dependency replaced with `dog`.")
message(STATUS "This recipe is at ${CMAKE_CURRENT_LIST_DIR}")
message(STATUS "See the overlay ports documentation at https://github.com/microsoft/vcpkg/blob/master/docs/specifications/ports-overlay.md")

ビルド手法

ベンダーの依存関係を使用しない

ライブラリの埋め込みコピーは使用しないでください。更新および保守できるように、すべての依存関係を分割して個別にパッケージ化する必要があります。

ベンダーの依存関係では、信頼性が高く、一貫性があり、保守可能なパッケージ管理システムを提供するという vcpkg の目標と競合するいくつかの課題が発生します。

更新の難しさ: ライブラリの埋め込みコピーにより、アップストリームプロジェクトからのセキュリティパッチを含む更新プログラムの追跡と適用が困難になります。これにより、潜在的なセキュリティリスクと、エコシステム内の古い依存関係が発生します。

シンボルの競合: 複数のパッケージに同じライブラリの異なるバージョンが含まれている場合、ベンダーの依存関係によってシンボルの競合が発生する可能性があります。

たとえば、パッケージ A ベンダーライブラリ X (バージョン 1) とパッケージ B ベンダーライブラリ X (バージョン 2) の場合、両方のパッケージをリンクしているアプリケーションで、シンボルの競合が原因で実行時エラーまたは未定義の動作が発生する可能性があります。

vcpkg は依存関係を個別にパッケージ化することで、すべてのパッケージでライブラリの単一バージョンが使用され、このような競合を排除します。

ライセンスコンプライアンス: ベンダーの依存関係は、組み込みライブラリのライセンスを隠し、使用条件に違反したり、互換性の問題を引き起こしたりする可能性があります。

メンテナンスの負担の増加: ベンダーの依存関係をアップストリームバージョンと同期させるには、手作業が必要であり、パッケージ間で重複する作業につながることがよくあります。

CMake の使用を優先する

複数のビルドシステムが使用可能な場合は、CMake を使用することをお選び下さいます。さらに、必要に応じて、 file(GLOB) ディレクティブを使用して代替ビルドシステムを CMake に書き換える方が簡単で保守しやすくなります。

例: abseil

静的バイナリまたは共有バイナリを選択する

CMake ライブラリをビルドするときに、 vcpkg_cmake_configure() は、ユーザーの要求されたバリアントに基づいて、 BUILD_SHARED_LIBS の正しい値を渡します。

string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" ...)を使用して、代替構成パラメーターを計算できます。

# portfile.cmake

string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "static" KEYSTONE_BUILD_STATIC)
string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "dynamic" KEYSTONE_BUILD_SHARED)

vcpkg_cmake_configure(
    SOURCE_PATH ${SOURCE_PATH}
    OPTIONS
        -DKEYSTONE_BUILD_STATIC=${KEYSTONE_BUILD_STATIC}
        -DKEYSTONE_BUILD_SHARED=${KEYSTONE_BUILD_SHARED}
)

ライブラリでビルドバリアントを選択するための構成オプションが提供されていない場合は、ビルドに修正プログラムを適用する必要があります。ビルドにパッチを適用する場合は、常にポートの将来の保守性を最大限に高める必要があります。通常、これは、目の前の問題を解決するためにタッチする必要がある行の数を最小限にすることを意味します。

例: 不要なバリアントを構築しないように CMake ライブラリにパッチを適用する

たとえば、CMake ベースのライブラリにパッチを適用する場合、不要なターゲットに EXCLUDE_FROM_ALL を追加し、 install(TARGETS ...) 呼び出しを if(BUILD_SHARED_LIBS)でラップするだけで十分な場合があります。これは、不要なバリアントに言及するすべての行を折り返したり削除したりするよりも短くなります。

次の内容を含むプロジェクト CMakeLists.txt の場合:

add_library(contoso SHARED contoso.c)
add_library(contoso_static STATIC contoso.c)

install(TARGETS contoso contoso_static EXPORT ContosoTargets)

install(EXPORT ContosoTargets
  FILE ContosoTargets
  NAMESPACE contoso::
  DESTINATION share/contoso)

install(TARGETS)行にのみ修正プログラムを適用する必要があります。

add_library(contoso SHARED contoso.c)
add_library(contoso_static STATIC contoso.c)

if(BUILD_SHARED_LIBS)
  set_target_properties(contoso_static PROPERTIES EXCLUDE_FROM_ALL 1)
  install(TARGETS contoso EXPORT ContosoTargets)
else()
  set_target_properties(contoso PROPERTIES EXCLUDE_FROM_ALL 1)
  install(TARGETS contoso_static EXPORT ContosoTargets)
endif()

install(EXPORT ContosoTargets
  FILE ContosoTargets
  NAMESPACE contoso::
  DESTINATION share/contoso)

機能を定義する場合は、依存関係を明示的に制御します

オプションの依存関係をキャプチャする機能を定義する場合は、機能が明示的に有効になっていないときに依存関係が誤って使用されないようにします。

set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB ON)
set(CMAKE_REQUIRE_FIND_PACKAGE_ZLIB OFF)
if ("zlib" IN_LIST FEATURES)
  set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB OFF)
  set(CMAKE_REQUIRE_FIND_PACKAGE_ZLIB ON)
endif()

vcpkg_cmake_configure(
  SOURCE_PATH ${SOURCE_PATH}
  OPTIONS
    -DCMAKE_DISABLE_FIND_PACKAGE_ZLIB=${CMAKE_DISABLE_FIND_PACKAGE_ZLIB}
    -DCMAKE_REQUIRE_FIND_PACKAGE_ZLIB=${CMAKE_REQUIRE_FIND_PACKAGE_ZLIB}
)

vcpkg_check_features()を使用する次のスニペットは同等です。

vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
  FEATURES
    "zlib"    CMAKE_REQUIRE_FIND_PACKAGE_ZLIB
  INVERTED_FEATURES
    "zlib"    CMAKE_DISABLE_FIND_PACKAGE_ZLIB
)

vcpkg_cmake_configure(
    SOURCE_PATH ${SOURCE_PATH}
    OPTIONS
      ${FEATURE_OPTIONS}
)

スニペットの ZLIB では大文字と小文字が区別されます。詳細については、 CMAKE_DISABLE_FIND_PACKAGE_<PackageName> と CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> のドキュメントを参照してください。

競合する lib を `manual-link` ディレクトリに配置する

次のいずれかの場合、lib は競合すると見なされます。

main を定義する
malloc の定義
他のライブラリでも宣言されているシンボルを定義する

競合するライブラリは通常、設計上の意図によるものであり、欠陥とは見なされません。一部のビルドシステムは lib ディレクトリ内のすべてにリンクするため、 manual-linkという名前のサブディレクトリに移動する必要があります。

バージョン管理

`"version"` フィールドの一般的な規則に従う

新しいポートを作成するときは、パッケージ作成者が使用するバージョン管理規則に従ってください。ポートを更新する場合は、アップストリームで特に断りがない限り、引き続き同じ規則を使用します。規則の詳細については、バージョン管理に関するドキュメントを参照してください。

アップストリームがしばらくリリースを公開していない場合は、最新の変更を取得するために、ポートのバージョン管理スキームを version-date に変更しないでください。これらのコミットには、運用環境の準備ができていない変更が含まれる場合があります。代わりに、アップストリームリポジトリに新しいリリースを発行するよう依頼してください。

変更されたポートのマニフェストファイルの `"port-version"` フィールドを更新します

vcpkg は、このフィールドを使用して、特定のポートが古く、ポートの動作が変更されるたびに変更する必要があるかどうかを判断します。

この規則では、アップストリームバージョンを変更しないポートへの変更に "port-version" フィールドを使用し、アップストリームバージョンへの更新が行われたときに "port-version" をゼロにリセットします。

例:

Zlib のパッケージバージョンは現在1.2.1です。明示的な"port-version"はなく、これは"port-version"の0に相当します。
間違った著作権ファイルがデプロイされていることを発見し、ポートファイル内で修正しました。
マニフェストファイルの "port-version" フィールドを 1に更新する必要があります。

詳細については、バージョン管理のドキュメントを参照してください。

変更されたポートの `versions/` でバージョンファイルを更新する

vcpkg は、一連のメタデータファイルを使用してバージョン管理機能を強化します。これらのファイルは、次の場所にあります。

${VCPKG_ROOT}/versions/baseline.json、(このファイルはすべてのポートに共通です)、
${VCPKG_ROOT}/versions/${first-letter-of-portname}-/${portname}.json (ポートごとに 1 つ)。

たとえば、関連するファイル zlib 次のようになります。

${VCPKG_ROOT}/versions/baseline.json
${VCPKG_ROOT}/versions/z-/zlib.json

ポートを更新するたびに、そのバージョンファイルも更新される予定です。

これらのファイルを更新するには、次のような x-add-version コマンドを実行することをお勧めします。

vcpkg x-add-version zlib

複数のポートを同時に更新する場合は、代わりに次のコマンドを実行できます。

vcpkg x-add-version --all

変更されたすべてのポートのファイルを一度に更新します。

注

これらのコマンドを実行する前に、変更をポートにコミットしておく必要があります。その理由は、これらのバージョンファイルにはポートディレクトリの Git SHA が必要であるためです。ただし、コミットされていないローカル変更がある場合は、 x-add-version コマンドによって警告が表示されます。

詳細については、バージョン管理のリファレンスとレジストリのに関する記事を参照してください。

パッチを適用すること

vcpkg はパッケージソリューションであり、デプロイするコンポーネントの最終的な所有者ではありません。場合によっては、コンポーネントとプラットフォームの互換性、またはコンポーネントの互換性を向上させるために、パッチを適用する必要があります。

パッチのうち、以下を回避したいと考えています。
- アップストリームは同意しないでしょう
- 脆弱性やクラッシュを引き起こす
- アップストリームバージョンの更新プログラム全体を維持することは不可能です
- は、vcpkg リポジトリ自体とライセンスの絡み合いを引き起こすのに十分な大きさです

アップストリーム関連パッチについてアップストリーム所有者に通知する

アップストリームでパッチが役に立つ可能性がある場合は、アップストリームにパッチの内容を通知する必要があります。 (依存関係の取り外しなど、アップストリームに関係のない vcpkg 固有の動作を適用するパッチでは、通知する必要がありません)。

アップストリームがパッチと一致しない状況を回避するために、そのようなパッチの適用を少なくとも 30 日間待ちます。

変更が正しいという確信が高い場合は、この待機期間をスキップします。信頼度の高いパッチの例としては、次のようなものがありますが、これらに限定されません。

アップストリームでのパッチの受け入れ (アップストリームがマージした pull request から特定の変更をバックポートするなど）。
不足している #includeを追加する。
小規模で明白な製品コードの修正 (初期化されていない変数の初期化など)。
テストや例など、ビルドの無関係な vcpkg コンポーネントを無効にします。

修正プログラムの適用よりもオプションを優先する

設定に直接パッチを適用するよりも vcpkg_configure_xyz() する呼び出しでオプションを設定することをお勧めします。

修正プログラムの適用を回避できる一般的なオプション:

[MSBUILD] <PropertyGroup> プロジェクトファイル内の設定は、 /p: パラメーターを使用してオーバーライドできます
[CMAKE] CMake スクリプトでの find_package(XYz) の呼び出しは -DCMAKE_DISABLE_FIND_PACKAGE_XYz=ON によって無効にすることができます。
[CMAKE]キャッシュ変数 ( set(VAR "value" CACHE STRING "Documentation") または option(VAR "Documentation" "Default Value") として宣言) は、コマンドラインで -DVAR:STRING=Fooとして渡すだけでオーバーライドできます。注目すべき例外の 1 つは、 FORCE パラメーターが set()に渡される場合です。詳細については、 CMake set のドキュメントを参照してください。

承認されたパッチをダウンロードすることを、ポートへのチェックインよりも優先する

承認されたパッチファイルまたはマージされたパッチファイルをアップストリームから取得できる場合は、ポートファイルの一部として取得するのではなく、それらをダウンロードして適用する必要があります。このプロセスは、次の理由で優先されます。

アップストリームがパッチの変更を受け入れたことを確認します
onus をアップストリームにシフトすることで、レビュープロセスを簡略化します。
パッチを使用していないユーザーの vcpkg リポジトリのサイズを小さくします
vcpkg リポジトリとのライセンスの競合を回避します

SHA の競合を回避するには、安定したエンドポイントからパッチをダウンロードする必要があります。プル要求からパッチファイルをダウンロードする場合、または GitHub と GitLab からコミットする場合は、 ?full_index=1 パラメーターをダウンロード URL に追加する必要があります。

例 :

https://github.com/google/farmhash/pull/40.diff?full_index=1
https://github.com/linux-audit/audit-userspace/commit/f8e9bc5914d715cdacb2edc938ab339d5094d017.patch?full_index=1
https://gitlab.kitware.com/paraview/paraview/-/merge_requests/6375.diff?full_index=1

`VCPKG_<VARIABLE>`値のオーバーライドよりも修正プログラムの適用を優先する

VCPKG_<VARIABLE>プレフィックスが付いた一部の変数には、同等のCMAKE_<VARIABLE>があります。ただし、そのすべてが内部パッケージビルド (実装: Windows ツールチェーンを参照) に渡されるわけではありません。

次の例を確認してください。

set(VCPKG_C_FLAGS "-O2 ${VCPKG_C_FLAGS}")
set(VCPKG_CXX_FLAGS "-O2 ${VCPKG_CXX_FLAGS}")

vcpkgの組み込みツールチェーンを使用すると、VCPKG_<LANG>_FLAGSの値が適切なCMAKE_LANG_FLAGS変数に転送されるため、これは機能します。ただし、 vcpkgの変数を認識していないカスタムツールチェーンは、それらを転送しません。

このため、 CMAKE_<LANG>_FLAGS設定するときにビルドシステムに直接パッチを適用することをお勧めしています。

パッチを最小限に抑える

ライブラリに変更を加える場合は、最終的な差分を最小限に抑えるように努めます。つまり、リージョンに影響を与える変更を行うときは、アップストリームのソースコードを再フォーマットしないでください。条件付きを無効にする場合は、条件のすべての行を削除するよりも、条件に AND FALSE または && 0 を追加することをお勧めします。大きなリージョンを無効にする必要がある場合は、パッチ内のすべての行を削除するのではなく、リージョンの周りに if(0) または #if 0 を追加する方が短くなります。

ポートが古く、ポートを新しいリリースバージョンに更新すると同じ問題が解決する場合は、パッチを追加しないでください。 vcpkg では、古いバージョンにパッチを適用するよりも、ポートの更新が優先されます。

これにより、vcpkg リポジトリのサイズを減らしながら、将来のコードバージョンにパッチが適用される可能性が向上します。

パッチに機能を実装しない

vcpkg で修正プログラムを適用する目的は、コンパイラ、ライブラリ、プラットフォームとの互換性を有効にすることです。適切なオープンソースの手順に従う代わりに新機能を実装する (問題/PR などを送信する) ためのものではありません。

既定ではテスト/ドキュメント/例をビルドしないでください

新しいポートを送信するときは、 BUILD_TESTS 、 WITH_TESTS 、 POCO_ENABLE_SAMPLES などのオプションを確認し、追加のバイナリが無効になっていることを確認します。これにより、平均ユーザーのビルド時間と依存関係が最小限に抑えられます。

必要に応じて、テストのビルドを可能にする test 機能を追加できますが、これは Default-Features リストに含めてはなりません。

ライブラリの既存のユーザーが vcpkg に切り替えるようにする

追加しないでください `CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS`

ライブラリの作成者が既に使用している場合を除き、この CMake 機能は C++ テンプレートと十分に対話せず、特定のコンパイラ機能を中断するため、使用しないでください。 .def ファイルを提供せず、__declspec() 宣言を使用しないライブラリは、単に Windows の共有ビルドをサポートしていないため、次のようにマークする必要があります。

if(VCPKG_TARGET_IS_WINDOWS)
    vcpkg_check_linkage(ONLY_STATIC_LIBRARY)
endif()

アップストリームによって指定された名前の外部にあるバイナリの名前を変更しないでください

つまり、アップストリームライブラリの名前がリリースとデバッグで異なる場合 (libx と libxd)、デバッグライブラリの名前を libx に変更しないでください。逆に、アップストリームライブラリがリリースとデバッグで同じ名前を持つ場合は、新しい名前を導入しないでください。

重要な注意事項:

多くの場合、静的バリアントと共有バリアントの名前を共通スキームに変更する必要があります。これにより、コンシューマーは共通名を使用し、ダウンストリームリンケージを無視できます。これは、一度に 1 つしか使用できないため、安全です。

ライブラリで CMake 統合ファイル (foo-config.cmake) が生成される場合は、単に出力アーカイブ/LIB で file(RENAME) を呼び出すのではなく、CMake ビルド自体に修正プログラムを適用して名前を変更する必要があります。

最後に、Windows 上の DLL ファイルは、生成された LIB を壊すので、ビルド後に名前を変更しないでください。

マニフェスト

マニフェストファイルを書式設定する必要があります。すべてのマニフェストファイルを書式設定するには、次のコマンドを使用します。

> vcpkg format-manifest --all

三つ子

現時点では、コミュニティ以外のトリプレットを追加する要求は受け付けていません。コミュニティから完全なトリプレット状態への昇格は、主にハードウェアがこのようなトリプレットをテストするための予算に基づいており、実際に使用するものが完全にテストされる可能性を最大化するために vcpkg によって送信されたメトリックによって駆動されます。

以下の場合、コミュニティトリプレットを追加します。

人々が実際にそのコミュニティトリプレットを使用することが実証されています。
私たちは、そのような三重項が壊れていることを知らない。

たとえば、 https://github.com/microsoft/vcpkg/pull/29034 にトリプレットを追加しませんでした。これは、作成者が実際にそのようなものを使用することを示すのではなく、単に "セットを完了" しようとしていただけであり、結果を再配置可能にするために patchlf ソリューションが作成されるまで linux-dynamic を追加しませんでした。

便利な実装に関する注意事項

ポートファイルはスクリプトモードで実行されます

portfile.cmakeとCMakeLists.txtは共通の構文とコア CMake 言語コンストラクト ("Scripting Commands") を共有していますが、ポートファイルは "スクリプトモード" で実行されますが、CMakeLists.txt ファイルは "プロジェクトモード" で実行されます。これら 2 つのモードの最も重要な違いは、"スクリプトモード" には "Toolchain"、"Language"、"Target" という概念が含まれていないということです。これらのコンストラクト ( CMAKE_CXX_COMPILER、 CMAKE_EXECUTABLE_SUFFIX、 CMAKE_SYSTEM_NAME など) に依存するスクリプトコマンドを含む動作は正しくありません。

Portfile はトリプレットファイルで設定された変数に直接アクセスできますが、 CMakeLists.txtにはアクセスできません (ただし、多くの場合、変換が行われますが、 VCPKG_LIBRARY_LINKAGE と BUILD_SHARED_LIBS)。

ポートファイルによって呼び出されるポートファイルとプロジェクトビルドは、異なるプロセスで実行されます。概念的に言えば

+----------------------------+       +------------------------------------+
| CMake.exe                  |       | CMake.exe                          |
+----------------------------+       +------------------------------------+
| Triplet file               | ====> | Toolchain file                     |
| (x64-windows.cmake)        |       | (scripts/buildsystems/vcpkg.cmake) |
+----------------------------+       +------------------------------------+
| Portfile                   | ====> | CMakeLists.txt                     |
| (ports/foo/portfile.cmake) |       | (buildtrees/../CMakeLists.txt)     |
+----------------------------+       +------------------------------------+

ポートファイル内のホストを特定するために、標準の CMake 変数は問題ありません (CMAKE_HOST_WIN32)。

ポートファイル内のターゲットを決定するには、vcpkg triplet 変数を使用する必要があります (VCPKG_CMAKE_SYSTEM_NAME)。

使用可能な設定の完全な列挙については、 triplet のドキュメントも参照してください。