[docs] Add Authoring-script-ports.md #22396

ras0219-msft · 2022-01-06T23:57:02Z

Add documentation covering vcpkg-port-config.cmake and how to author script ports

dg0yt

It seems that this PR lacks the addition of docs/maintainers/authoring-script-ports.md.

strega-nil-ms

It'd also be good to talk about how to add docs to a script port; adding the port to docs/regenerate.ps1.

docs/README.md

strega-nil-ms · 2022-01-11T23:44:38Z

docs/maintainers/authoring-script-ports.md

@@ -0,0 +1,28 @@
+# 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.


Can you split this up into multiple lines? Having a single paragraph all on one line makes this difficult to review...

Also, s/, for example/: as an example,/

docs/maintainers/authoring-script-ports.md

strega-nil-ms · 2022-01-11T23:47:09Z

docs/maintainers/authoring-script-ports.md

+
+Script ports are technically 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/${DEP}/vcpkg-port-config.cmake`).
+
+Note that only direct dependencies are checked. This means that if a script relies on another script transitively, it must explicitly import the relevant config.


s/direct dependencies/the `vcpkg-port-config.cmake` of direct dependencies/

s/are checked/are included in this way/

s/relevant config/relevant `vcpkg-port-config.cmake`/

docs/maintainers/authoring-script-ports.md

strega-nil-ms · 2022-01-11T23:49:48Z

docs/users/host-dependencies.md

@@ -62,4 +60,4 @@ endif()

 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`.
+This supports expression is true when `TARGET_TRIPLET == HOST_TRIPLET` / `VCPKG_CROSSCOMPILING` is true.


Suggested change

This supports expression is true when `TARGET_TRIPLET == HOST_TRIPLET` / `VCPKG_CROSSCOMPILING` is true.

This supports expression is true when `VCPKG_CROSSCOMPILING` is false (when `TARGET_TRIPLET == HOST_TRIPLET`).

dg0yt · 2022-01-12T04:15:59Z

It'd also be good to talk about how to add docs to a script port; adding the port to docs/regenerate.ps1.

Actually this concept is controversial. It breaks documentation fixes without CI rebuild.
Related: Discussion at #21763 (comment)

ras0219-msft · 2022-01-27T02:47:12Z

I have resolved the comments that were more-or-less directly applied but left open the ones where I chose to format at least part of the suggestion differently.

docs/maintainers/authoring-script-ports.md

strega-nil-ms · 2022-02-01T17:54:20Z

docs/maintainers/authoring-script-ports.md

+
+Ports should never provide a `vcpkg-port-config.cmake` file under a different
+`share/` subdirectory than the current port (`${PORT}`).
+


You should probably add some information on docs; there's a list in docs/regenerate.ps1 that one should update when adding a new script port.

I would prefer to merge this PR as-is; then that content can be easily added separately.

Co-authored-by: nicole mazzuca <83086508+strega-nil-ms@users.noreply.github.com>

* master: (221 commits) [vcpkg-tool] update to 2022-02-03 (microsoft#22924) [opencv4] Disable building cpufeatures since it conflict with libwebp (microsoft#22844) [rhasheq] New port (microsoft#22905) [sfml] Add arm64 patch to allow SFML to compile on apple silicon (microsoft#22937) [popsift] Fix missing Thrust include, already merged upstream. (microsoft#22929) [python3][python2] Use MKDIR_P to create directories to avoid race conditions (microsoft#22902) Added libe57format port (microsoft#22909) update polyhook2 (microsoft#22906) [botan] Fix debug info (microsoft#22911) [opentelemetry-cpp] update version to v1.2.0 (microsoft#22925) [docs] document VCPKG_INSTALLED_DIR variable (microsoft#22695) [c89stringutils] New port (microsoft#22904) [randomstr] New port (microsoft#22921) [docs] Add Authoring-script-ports.md (microsoft#22396) [vcpkg_fail_port_install] Deprecate function (microsoft#21489) [vcpkg-cmake-config] add missing TOOLS_PATH (microsoft#22863) Ace Build Windows - Missing files in include package (microsoft#22880) [opendnp3] Disable FetchContent in favor of predownloading (microsoft#22894) libraqm update to 0.9.0 (microsoft#22907) [google-cloud-cpp] update to latest release (v1.36.0) (microsoft#22897) ...

ras0219-msft requested a review from strega-nil-ms January 6, 2022 23:57

github-actions bot approved these changes Jan 6, 2022

View reviewed changes

PhoebeHui self-assigned this Jan 7, 2022

PhoebeHui added category:documentation To resolve the issue, documentation will need to be updated info:internal This PR or Issue was filed by the vcpkg team. labels Jan 7, 2022

PhoebeHui approved these changes Jan 7, 2022

View reviewed changes

PhoebeHui added the info:reviewed Pull Request changes follow basic guidelines label Jan 7, 2022

dg0yt suggested changes Jan 7, 2022

View reviewed changes

PhoebeHui added requires:author-response and removed info:reviewed Pull Request changes follow basic guidelines labels Jan 7, 2022

[docs] Add Authoring-script-ports.md

755b733

ras0219-msft force-pushed the dev/roschuma/docs branch from 38b2866 to 755b733 Compare January 11, 2022 20:50

github-actions bot approved these changes Jan 11, 2022

View reviewed changes

strega-nil-ms suggested changes Jan 11, 2022

View reviewed changes

Address CR comments

90a9ca8

github-actions bot approved these changes Jan 27, 2022

View reviewed changes

ras0219-msft requested a review from strega-nil-ms January 27, 2022 02:46

PhoebeHui removed the requires:author-response label Jan 28, 2022

PhoebeHui approved these changes Jan 28, 2022

View reviewed changes

PhoebeHui added the info:reviewed Pull Request changes follow basic guidelines label Jan 28, 2022

strega-nil-ms suggested changes Feb 1, 2022

View reviewed changes

Update docs/maintainers/authoring-script-ports.md

c7b6d6f

Co-authored-by: nicole mazzuca <83086508+strega-nil-ms@users.noreply.github.com>

ras0219-msft requested a review from strega-nil-ms February 2, 2022 23:12

github-actions bot approved these changes Feb 2, 2022

View reviewed changes

strega-nil-ms approved these changes Feb 3, 2022

View reviewed changes

BillyONeal merged commit c06dfc0 into microsoft:master Feb 3, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs] Add Authoring-script-ports.md #22396

[docs] Add Authoring-script-ports.md #22396

ras0219-msft commented Jan 6, 2022

dg0yt left a comment

strega-nil-ms left a comment

strega-nil-ms Jan 11, 2022

strega-nil-ms Jan 11, 2022

strega-nil-ms Jan 11, 2022

dg0yt commented Jan 12, 2022

ras0219-msft commented Jan 27, 2022

strega-nil-ms Feb 1, 2022

ras0219-msft Feb 2, 2022

		@@ -0,0 +1,28 @@
		# 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 technically 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/${DEP}/vcpkg-port-config.cmake`).

		Note that only direct dependencies are checked. This means that if a script relies on another script transitively, it must explicitly import the relevant config.

	This supports expression is true when `TARGET_TRIPLET == HOST_TRIPLET` / `VCPKG_CROSSCOMPILING` is true.
	This supports expression is true when `VCPKG_CROSSCOMPILING` is false (when `TARGET_TRIPLET == HOST_TRIPLET`).


		Ports should never provide a `vcpkg-port-config.cmake` file under a different
		`share/` subdirectory than the current port (`${PORT}`).

[docs] Add Authoring-script-ports.md #22396

[docs] Add Authoring-script-ports.md #22396

Conversation

ras0219-msft commented Jan 6, 2022

dg0yt left a comment

Choose a reason for hiding this comment

strega-nil-ms left a comment

Choose a reason for hiding this comment

strega-nil-ms Jan 11, 2022

Choose a reason for hiding this comment

strega-nil-ms Jan 11, 2022

Choose a reason for hiding this comment

strega-nil-ms Jan 11, 2022

Choose a reason for hiding this comment

dg0yt commented Jan 12, 2022

ras0219-msft commented Jan 27, 2022

strega-nil-ms Feb 1, 2022

Choose a reason for hiding this comment

ras0219-msft Feb 2, 2022

Choose a reason for hiding this comment