Предоставление документации по использованию портов

Обзор

Предоставление документации по использованию портов позволяет пользователям легко внедрять их в свои проекты. Мы настоятельно рекомендуем предоставить usage файл в каталоге порта (ports/<port name>/usage), который описывает минимальные шаги, необходимые для интеграции с системой сборки.

Предоставление файла использования

Чтобы предоставить документацию по использованию, создайте текстовый файл с именем 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)