Provide usage documentation for your ports

Overview

Providing usage documentation for ports allows users to easily adopt them in their projects. We highly encourage providing a usage file within the port's directory (ports/<port name>/usage) that describes the minimal steps necessary to integrate with a build system.

Supplying a usage file

To provide usage documentation create a text file named usage in the port's share installation directory. The recommended method is to call the file(INSTALL ...) function in portfile.cmake.

For example:

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

After installing ports, vcpkg detects files installed to ${CURRENT_PACKAGES_DIR}/share/${PORT}/usage and prints their usage instructions.

Content format

Provide clear instructions on how to use the package. The content should be concise, well-structured, and emphasize the minimum build system integration required to use the library.

Be clear and concise about how to utilize the package effectively. Avoid overwhelming users with code snippets, command-line instructions, or configuration details. Instead, use the "documentation" property in the port's vcpkg.json file so users can learn more about your library.

Use the following templates as a pattern for your usage files:

Packages with CMake targets:

<port> provides CMake targets:

  <instructions>

Header-only libraries:

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

  <instructions>

Example of usage file

proj provides CMake targets:

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