Поделиться через

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

  • Статья

Обзор

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

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

Чтобы предоставить документацию по использованию, создайте текстовый файл с именем usage в каталоге установки порта share . Рекомендуемый метод — вызвать функцию configure_file() в portfile.cmake.

Например:

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>

usage Пример файла

proj provides CMake targets:

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