[docs] Add Authoring-script-ports.md

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)

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/<port>/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/<port>/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")
+```

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`).