From c06dfc0ac2649834da8b9f3092b907fb037accab Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Thu, 3 Feb 2022 13:08:10 -0800 Subject: [PATCH] [docs] Add Authoring-script-ports.md (#22396) * [docs] Add Authoring-script-ports.md * Address CR comments * Update docs/maintainers/authoring-script-ports.md Co-authored-by: nicole mazzuca <83086508+strega-nil-ms@users.noreply.github.com> Co-authored-by: nicole mazzuca <83086508+strega-nil-ms@users.noreply.github.com> --- docs/README.md | 9 +++-- docs/maintainers/authoring-script-ports.md | 45 ++++++++++++++++++++++ docs/users/host-dependencies.md | 14 +++---- 3 files changed, 57 insertions(+), 11 deletions(-) create mode 100644 docs/maintainers/authoring-script-ports.md diff --git a/docs/README.md b/docs/README.md index 598cb7eaf1..6b770e189b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -29,10 +29,11 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too ### Maintainer Help -- [Manifest files - vcpkg.json](maintainers/manifest-files.md) -- [Control files](maintainers/control-files.md) -- [Portfile functions](maintainers/portfile-functions.md) -- [Common CMake definitions](maintainers/vcpkg_common_definitions.md) +- [Manifest Files - vcpkg.json](maintainers/manifest-files.md) +- [Control Files](maintainers/control-files.md) +- [Portfile Functions](maintainers/portfile-functions.md) +- [Authoring Script Ports](maintainers/authoring-script-ports.md) +- [Common CMake Definitions](maintainers/vcpkg_common_definitions.md) - [Maintainer Guidelines](maintainers/maintainer-guide.md) - [Creating Registries](maintainers/registries.md) - [CMake Guidelines](maintainers/cmake-guidelines.md) diff --git a/docs/maintainers/authoring-script-ports.md b/docs/maintainers/authoring-script-ports.md new file mode 100644 index 0000000000..f14eaa4407 --- /dev/null +++ b/docs/maintainers/authoring-script-ports.md @@ -0,0 +1,45 @@ +# Authoring Script Ports + +Ports can expose functions for other ports to consume during their build. For +example, the `vcpkg-cmake` helper port exposes the `vcpkg_cmake_configure()` +helper function. Packaging common scripts into a shared helper port makes +maintenance easier because all consumers can be updated from a single place. +Because the scripts come from a port, they can be versioned and depended upon +via all the same mechanisms as any other port. + +Script ports are implemented via the `vcpkg-port-config.cmake` extension +mechanism. Before invoking the `portfile.cmake` of a port, vcpkg will first +import `share//vcpkg-port-config.cmake` from each direct dependency. If +the direct dependency is a host dependency, the import will be performed in the +host installed tree (e.g. +`${HOST_INSTALLED_DIR}/share//vcpkg-port-config.cmake`). + +Only direct dependencies are considered for `vcpkg-port-config.cmake` inclusion. +This means that if a script port relies on another script port, it must +explicitly import the `vcpkg-port-config.cmake` of its dependency. + +Script-to-script dependencies should not be marked as host. The dependency from +a target port to a script should be marked host, which means that scripts should +always already be natively compiling. By making script-to-script dependencies +`"host": false`, it ensures that one script can depend upon the other being in +its same install directory. + +Ports should never provide a `vcpkg-port-config.cmake` file under a different +`share/` subdirectory than the current port (`${PORT}`). + +## Example + +```cmake +# ${CURRENT_PACKAGES_DIR}/share/my-helper/vcpkg-port-config.cmake + +# This include guard ensures the file will be loaded only once +include_guard(GLOBAL) + +# This is how you could pull in a transitive dependency +include("${CMAKE_CURRENT_LIST_DIR}/../my-other-helper/vcpkg-port-config.cmake") + +# Finally, it is convention to put each public function into a separate file with a matching name +include("${CMAKE_CURRENT_LIST_DIR}/my_helper_function_01.cmake") +include("${CMAKE_CURRENT_LIST_DIR}/my_helper_function_02.cmake") +include("${CMAKE_CURRENT_LIST_DIR}/my_helper_function_03.cmake") +``` diff --git a/docs/users/host-dependencies.md b/docs/users/host-dependencies.md index 6521d28dd9..4e7cf39a34 100644 --- a/docs/users/host-dependencies.md +++ b/docs/users/host-dependencies.md @@ -46,12 +46,10 @@ The default host triplets are chosen based on the host architecture and operatin Producing a tool has no special requirements; tools should be authored as a standard port, following all the normal policies and practices. Notably, they should build against `TARGET_TRIPLET`, not `HOST_TRIPLET` within the context of their portfile. -Sometimes, it can be useful to determine whether the current context is a cross-compiling one or not. This should be done by comparing the strings `TARGET_TRIPLET` and `HOST_TRIPLET`. For example: +If the current context is cross-compiling (`TARGET_TRIPLET` is not `HOST_TRIPLET`), then `VCPKG_CROSSCOMPILING` will be set to a truthy value. ```cmake -string(COMPARE EQUAL "${TARGET_TRIPLET}" "${HOST_TRIPLET}" I_AM_NOT_CROSSCOMPILING) - -if(TARGET_TRIPLET STREQUAL HOST_TRIPLET) +if(VCPKG_CROSSCOMPILING) # This is a native build else() # This is a cross build @@ -60,6 +58,8 @@ endif() ## Host-only ports -Some ports are host-only: script ports and tool ports are common examples. -In this case, you can use the `"native"` supports expression to describe this. -This supports expression is true when `TARGET_TRIPLET == HOST_TRIPLET`. +Some ports should only be depended upon via a host dependency; script ports and +tool ports are common examples. In this case, you can use the `"native"` +supports expression to describe this. This supports expression is true when +`VCPKG_CROSSCOMPILING` is false (implying that `TARGET_TRIPLET == +HOST_TRIPLET`).