ポートの使用状況に関するドキュメントを提供する

概要

ポートの正確な使用ドキュメントを提供することで、ユーザーはプロジェクトでそれらを簡単に採用できます。 vcpkg は、ポートによってインストールされたファイルを調べることで、使用状況情報を自動的に生成します。 生成された使用状況情報が正しくないか不完全な場合にのみ、カスタム usage ファイルを指定します。

ポートをインストールした後、 vcpkg print-usage を実行して使用状況情報を調べます。

vcpkg print-usage <port>:<triplet>

ポートにカスタム usage ファイルが既にインストールされている場合は、 --generated を使用して、そのファイルなしで vcpkg によって生成される内容を調べることができます。

vcpkg print-usage --generated <port>:<triplet>

生成された使用状況を確認する

生成された使用状況情報が正しい場合は、空の usage-accurate マーカー ファイルをインストールします。

file(TOUCH "${CURRENT_PACKAGES_DIR}/share/${PORT}/usage-accurate")

このマーカーは、生成された命令が正確であることを確認するため、vcpkg は命令がヒューリスティックに生成され、正しくない可能性があることを示す警告を省略します。

マーカーを追加する前に、 --affirm を使用して、生成された出力を警告なしでプレビューできます。

vcpkg print-usage --generated --affirm <port>:<triplet>

使用状況ファイルの提供

生成された使用状況情報でパッケージの使用方法が正しく記述されていない場合は、ポート ディレクトリに usage という名前のテキスト ファイルを作成し、ポートの share ディレクトリにインストールします。 推奨される方法は、file(INSTALL ...)でportfile.cmake関数を呼び出す方法です。

例えば次が挙げられます。

file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}")

ポートをインストールすると、vcpkg は ${CURRENT_PACKAGES_DIR}/share/${PORT}/usage にインストールされているファイルを検出し、使用状況情報を生成する代わりにその指示を出力します。

コンテンツ形式

パッケージの使用方法に関する明確な手順を提供します。 コンテンツは簡潔で、適切に構造化され、ライブラリを使用するために必要な最小ビルド システム統合を強調する必要があります。

パッケージを効果的に利用する方法については、明確かつ簡潔にしてください。 コード スニペット、コマンド ライン命令、または構成の詳細を使用してユーザーを圧倒しないようにします。 代わりに、ポートの"documentation" ファイルで vcpkg.json プロパティを使用して、ユーザーがライブラリの詳細を確認できるようにします。

usage ファイルのパターンとして、次のテンプレートを使用します。

CMake ターゲットを含むパッケージ:

<port> provides CMake targets:

  <instructions>

ヘッダーのみのライブラリ:

<port> is header-only and can be used from CMake via:

  <instructions>

usage ファイルの例

proj provides CMake targets:

  find_package(PROJ CONFIG REQUIRED)
  target_link_libraries(main PRIVATE PROJ::proj)