diff --git a/vcpkg/contributing/maintainer-guide.md b/vcpkg/contributing/maintainer-guide.md index d78f99c6..f266fed3 100644 --- a/vcpkg/contributing/maintainer-guide.md +++ b/vcpkg/contributing/maintainer-guide.md @@ -127,6 +127,14 @@ This is discouraged in favour of [`vcpkg_install_copyright()`](../maintainers/fu `vcpkg_install_copyright` also includes the functionallity to handle multiple copyright files. See its [documentation](../maintainers/functions/vcpkg_install_copyright.md) for more info. +### Special Ports + +Apart from normal ports for libraries there are different types of special ports which have fullfill different purposes. One the one hand there are [script ports](../maintainers/authoring-script-ports.md) like `vcpkg-cmake` which are designed to enable additional portfile functions with the added benefit of being versioned. + +Then there are ports like e.g. `blas`/`lapack` which are metaports and give users an easy way to switch out the default `blas`/`lapack` implementation by providing an appropiate overlay for these ports. + +Ports commonly named like `vcpkg-tool-x` are ports which are [tool ports](../maintainers/authoring-tool-ports.md) and provide a required tool for other ports either by downloading a prebuild binary or by building a tool from source. + ## Features ### Do not use features to implement alternatives diff --git a/vcpkg/maintainers/authoring-tool-ports.md b/vcpkg/maintainers/authoring-tool-ports.md new file mode 100644 index 00000000..9938f9d5 --- /dev/null +++ b/vcpkg/maintainers/authoring-tool-ports.md @@ -0,0 +1,18 @@ +--- +title: Authoring Tool Ports +description: Learn to create a Tool Port for usage in other ports. +ms.date: 11/30/2022 +--- +# Authoring tool ports + +Ports providing a binary or tool for other ports are tool ports. For example the `vcpkg-tool-meson` port exposes the required meson python script to run meson based builds in a versioned manner. Tool ports are generally ment to replace `vcpkg_find_acquire_program` calls since the latter is not versioned and triggers an CI world rebuild if changed. + +Tool ports are implemented in different ways depending on their expected usage. +1. If a tool is expected to be provided in binary form and not ment for the user to be used the port should be named `vcpkg-tool-`. The port should work like `vcpkg_find_acquire_program` and only download/provide the tool if another port requests its usage. This is done via `vcpkg-port-config.cmake` which has to included all logic to find or provide the tool. The artifacts of the tool have to be put into `${DOWNLOADS}/tools/-`. (This means that the tool port is actually just a [script port](./authoring-script-ports.md)) +2. If a tool is required to be build from source but is not to be used by the user the tools build artifacts should be stored into `${CURRENT_PACKAGES_DIR}/manual-tools/${PORT}`. Furthermore a `vcpkg-port-config.cmake` needs to be installed setting a variable to path of the relevant tool. +3. If a tool is expected to be used outside of vcpkg and inside the users `CMakeLists.txt`. The tools build artifacts are installed to `${CURRENT_PACKAGES_DIR}/tools/${PORT}` and the port name should follow the normal vcpkg naming rules. A `vcpkg-port-config.cmake` is required to be installed like in case 2. + +Most (if not all) tool ports are required to be marked with `"supports" : "native"`. Furthermore `VCPKG_FORCE_SYSTEM_BINARIES` should be honored if possible with a version check if the system provided binary fullfills the version requirements of the tool port itself (if any). +For 1. this means to do a simple `find_program`. For case 2./3. this means not building/providing the tool from within vcpkg but still fullfilling the set variables in `vcpkg-port-config.cmake` of the tool port. + +If a tool port is a dependency in another port, the tool port should is requried to be marked with `"host" : true`