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

概要

ポートの使用に関するドキュメントを提供すると、ユーザーはプロジェクトでそれらを簡単に採用できます。ビルドシステムとの統合に必要な usage 最小限の手順を説明するポートのディレクトリ (ports/<port name>/usage) 内にファイルを提供することを強くお勧めします。

使用ドキュメントを提供するには、ポートshareのインストールディレクトリに名前を付けたusageテキストファイルを作成します。推奨される方法は、次の関数portfile.cmakeをconfigure_file()呼び出す方法です。

次に例を示します。

configure_file("${CMAKE_CURRENT_LIST_DIR}/usage" "${CURRENT_PACKAGES_DIR}/share/${PORT}/usage" COPYONLY)

ポートをインストールすると、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>

proj provides CMake targets:

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