Merge pull request #101 from microsoft/main

Push main to live (2023.06.29)
microsoft · Jul 17, 2023 · 38ec178 · 38ec178
2 parents f04b0a5 + 6722aab
commit 38ec178
Show file tree

Hide file tree

Showing 6 changed files with 156 additions and 59 deletions.
diff --git a/vcpkg/TOC.yml b/vcpkg/TOC.yml
@@ -232,6 +232,8 @@
         href: maintainers/functions/internal/z_vcpkg_restore_pkgconfig_path.md
       - name: z_vcpkg_setup_pkgconfig_path
         href: maintainers/functions/internal/z_vcpkg_setup_pkgconfig_path.md
+  - name: Provide usage documentation for your packages
+    href: maintainers/handling-usage-files.md
   - name: CONTROL Files (deprecated)
     href: maintainers/control-files.md
 - name: Reference

diff --git a/vcpkg/docfx.json b/vcpkg/docfx.json
@@ -48,7 +48,7 @@
       "feedback_github_repo": "Microsoft/vcpkg-docs",
       "feedback_product_url": "https://github.com/Microsoft/vcpkg/issues/",
       "ROBOTS": "INDEX,FOLLOW",
-      "manager": "roschuma",
+      "manager": "aupopa",
       "ms.date": "11/16/2020",
       "ms.prod": "vcpkg",
       "ms.topic": "conceptual",
@@ -59,35 +59,35 @@
         "cplusplus"
       ],
       "ms.reviewer": [
-        "roschuma",
         "aupopa",
-        "corob",
+        "viromer",
         "twhitney"
+
       ],
       "searchScope": [
         "vcpkg"
       ]
     },
     "fileMetadata": {
       "author": {
-        "index.md": "ras0219-msft",
-        "about/**.md": "ras0219-msft",
-        "commands/**.md": "ras0219-msft",
-        "examples/**.md": "ras0219-msft",
-        "maintainers/**.md": "ras0219-msft",
-        "contributing/**.md": "ras0219-msft",
-        "users/**.md": "ras0219-msft",
-        "reference/**.md": "ras0219-msft"
+        "index.md": "vicroms",
+        "about/**.md": "vicroms",
+        "commands/**.md": "vicroms",
+        "examples/**.md": "vicroms",
+        "maintainers/**.md": "vicroms",
+        "contributing/**.md": "vicroms",
+        "users/**.md": "vicroms",
+        "reference/**.md": "vicroms"
       },
       "ms.author": {
-        "index.md": "roschuma",
-        "about/**.md": "roschuma",
-        "commands/**.md": "roschuma",
-        "examples/**.md": "roschuma",
-        "maintainers/**.md": "roschuma",
-        "contributing/**.md": "roschuma",
-        "users/**.md": "roschuma",
-        "reference/**.md": "roschuma"
+        "index.md": "viromer",
+        "about/**.md": "viromer",
+        "commands/**.md": "viromer",
+        "examples/**.md": "viromer",
+        "maintainers/**.md": "viromer",
+        "contributing/**.md": "viromer",
+        "users/**.md": "viromer",
+        "reference/**.md": "viromer"
       }
     },
     "template": [],

diff --git a/vcpkg/examples/asset-caching-source-nuget.md b/vcpkg/examples/asset-caching-source-nuget.md
@@ -8,29 +8,50 @@ ms.date: 4/18/2023
 
 [!INCLUDE [experimental](../../includes/experimental.md)]
 
-In this example, we will set up a NuGet feed as a source, meaning we will use `nuget.exe` to pull and push assets.
+In this example, we'll set up a NuGet feed as an asset caching source by using a script to restore and push artifacts.
 
-First, we will set up the environment before any call to `vcpkg install`:
-```powershell
-$env:X_VCPKG_ASSET_SOURCES="clear;x-script,C:/path/to/asset-provider.bat {url} {sha512} {dst};x-block-origin"
-$env:NUGET=C:/path/to/nuget.exe
-$env:VCPKG_KEEP_ENV_VARS=NUGET
+## Prerequisites
+
+* nuget.exe
+* A NuGet packages feed
+
+## Step 1: Create `asset-source.nuspec`
+
+Create a NuGet package spec template with the following contents:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
+    <metadata>
+        <id>$sha$</id>
+        <version>1.0.0</version>
+        <description>vcpkg download asset</description>
+        <authors>vcpkg</authors>
+    </metadata>
+    <files>
+        <file src="$file$" />
+    </files>
+</package>
 ```
-[`X_VCPKG_ASSET_SOURCES`](../users/config-environment.md#x_vcpkg_asset_sources) defines a single [`x-script`](../users/assetcaching.md#x-script) asset source while blocking fallback to the original url ([`x-block-origin`](../users/assetcaching.md#x-block-origin)). The `x-script` source is defined to call a script `sources.bat` which will handle `nuget` push and pull commands. This script must be able to run both inside and outside the inner build environment, so we pass it the path to `nuget.exe` in the environment with `NUGET` and [`VCPKG_KEEP_ENV_VARS`](../users/config-environment.md#vcpkg_keep_env_vars).
 
-The script `asset-provider.bat` checks if the asset is stored in the feed, and if so, installs it to the destination path. If the asset is not stored on the feed, the script fetches the url via curl, packs the asset in a `nuget` package and pushes it to the feed.
+## Step 2: Create an asset provider script
 
+Now you need to create a script that downloads packages from the NuGet feed if available and uploads
+missing packages to your feed if they are not.
+
+Create `asset-provider.bat` with the contents provided below, make sure to replace the NuGet feed URL and path to `asset-source.nuspec` with their correct values on your system.
 
-Create a `asset-provider.bat` file in your project with the following content:
 ```bat
+@echo off
 set url=%1
 set sha512=%2
 set dst=%3
 set "_dst=%dst:/=\%"
 set "_sha512=%sha512:~0,90%"
 
 cd /d %~dp3
-%NUGET% install %sha512:~0,90% -Source <feed url>
+%NUGET% install %sha512:~0,90% -Source https://your-nuget-feed-url
+echo.
 if exist %_sha512%.1.0.0 (
     echo "Pull from the NuGet feed"
     cd %_sha512%.1.0.0
@@ -40,25 +61,36 @@ if exist %_sha512%.1.0.0 (
 ) else (
     echo "Fetch from the url"
     curl.exe -L %url% --create-dirs --output %dst%
+    REM Replace with the correct path
     %NUGET% pack C:\path\to\asset-source.nuspec -BasePath %~dp3 -Properties "sha=%_sha512%;file=%dst%" -OutputDirectory %TEMP%
-    %NUGET% push %TEMP%\%_sha512%.1.0.0.nupkg -Source <feed url>
+    %NUGET% push -ApiKey az -SkipDuplicate %TEMP%\%_sha512%.1.0.0.nupkg -Source https://your-nuget-feed-url
 )
 ```
 
-Create a `asset-source.nuspec` file with the following content:
-```
-<?xml version="1.0" encoding="utf-8"?>
-<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
-    <metadata>
-        <id>$sha$</id>
-        <version>1.0.0</version>
-        <description>example</description>
-        <authors>example</authors>
-    </metadata>
-    <files>
-        <file src="$file$" />
-    </files>
-</package>
+## Step 3: Configure the asset caching sources
+
+Now that you have created the asset provider script, you need to instruct vcpkg to use it as an
+asset caching source. To do that, set the following environment variables:
+
+```powershell
+$env:X_VCPKG_ASSET_SOURCES="clear;x-script,C:/path/to/asset-provider.bat {url} {sha512} {dst};x-block-origin"
+$env:NUGET="C:/path/to/nuget.exe"
+$env:VCPKG_KEEP_ENV_VARS="NUGET"
 ```
 
-You will notice that the NuGet package pushed to the feed is named the only the first 90 characters of the `sha`. This is because `nuget` feed ids are limited to 100 characters.
+NOTE: Make sure to replace the placeholder paths to the asset provider script and nuget.exe with the correct paths in your system.
+
+[`X_VCPKG_ASSET_SOURCES`](../users/config-environment.md#x_vcpkg_asset_sources) is the environment variable used to set asset caching sources for vcpkg to use. In this example we set the following values:
+
+* `clear` gets rid of the default asset caching location.
+* [`x-script`](../users/assetcaching.md#x-script) adds your script as an asset caching source, the first parameter indicates the command line vcpkg should invoke, in this example we call the `asset-provider.bat` script and forward some required parameters.
+* `x-block-origin` forces all downloads to come from the configured asset caching sources.
+
+[`VCPKG_KEEP_ENV_VARS`](../users/config-environment.md) is used to forward environment variables to
+vcpkg's build environmet. During builds vcpkg creates a clean environment, by adding `NUGET` to
+`VCPKG_KEEP_ENV_VARS` we ensure that the NuGet executable location is forwarded during builds.
+
+Once all has been properly set up, any time that vcpkg downloads an asset it will upload it to your
+NuGet feed to use in future downloads. You'll notice that cached assets are named after their file
+SHA512 and the version specified in `asset-source.nuspec`. If you'd like to have more meaninful
+names for your packages, you can modify the package template and asset provider script with your own logic.
diff --git a/vcpkg/github-integration.md b/vcpkg/github-integration.md
@@ -50,7 +50,7 @@ You must enable the GitHub dependency graph in your repository's settings (enabl
 
 ### Known limitations
 
-* The version of vcpkg bundled with GitHub Actions runners may not be up to date. Ensure you are using tool version `2022-06-22` or later (merged with [commit SHA 8f3e8d6](https://github.com/microsoft/vcpkg/commit/8f3e8d6e95c7f91edea60c47a7d1414ab5ca9492)).
+* The version of vcpkg bundled with GitHub Actions runners may not be up to date. Ensure you are using tool version `2023-06-22` or later (merged with [commit SHA 8f3e8d6](https://github.com/microsoft/vcpkg/commit/8f3e8d6e95c7f91edea60c47a7d1414ab5ca9492)).
 * Features that depend on the dependency graph, such as Dependabot alerts and Dependabot pull requests, are not yet available. Please let us know if you are interested in those features!
 
 ### Example GitHub Actions workflow

diff --git a/vcpkg/maintainers/handling-usage-files.md b/vcpkg/maintainers/handling-usage-files.md
@@ -0,0 +1,62 @@
+---
+title: Provide usage documentation for your ports
+description: Guidance for adding usage documentation to vcpkg ports
+author: JavierMatosD
+ms.author: javiermat
+ms.date: 07/17/2023
+ms.prod: vcpkg
+---
+# 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 `configure_file()` function in
+`portfile.cmake`.
+
+For example:
+
+```cmake
+configure_file("${CMAKE_CURRENT_LIST_DIR}/usage" "${CURRENT_PACKAGES_DIR}/share/${PORT}/usage" COPYONLY)
+```
+
+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](../users/manifests.md) so users can learn more about your library.
+
+Use the following templates as a pattern for your `usage` files:
+
+Packages with CMake targets:
+
+```text
+<port> provides CMake targets:
+
+    <instructions>
+```
+
+Header-only libraries:
+
+```text
+<port> is header-only and can be used from CMake via:
+
+    <instructions>
+```
+
+#### Example of `usage` file
+
+```text
+proj provides CMake targets:
+
+    find_package(PROJ CONFIG REQUIRED)
+    target_link_libraries(main PRIVATE PROJ::proj)
+```
diff --git a/vcpkg/reference/vcpkg-json.md b/vcpkg/reference/vcpkg-json.md
@@ -53,7 +53,7 @@ This example demonstrates a manifest for an application using `boost-system`, `c
 
 A shortcut for specifying the `"baseline"` for version resolution in the default registry. A string. Optional, only used by top-level projects.
 
-This field indicates the commit of https://github.com/microsoft/vcpkg which provides global minimum version information for your manifest. It is required for top-level manifest files using versioning without a specified [`"default-registry"`](vcpkg-configuration-json.md#default-registry). It has the same semantic as defining your default registry to be:
+This field indicates the commit of <https://github.com/microsoft/vcpkg> which provides global minimum version information for your manifest. It is required for top-level manifest files using versioning without a specified [`"default-registry"`](vcpkg-configuration-json.md#default-registry). It has the same semantic as defining your default registry to be:
 
 ```json
 {
@@ -91,7 +91,7 @@ The list of dependencies required by the project. An array of [Dependency object
 
 This field lists all the dependencies needed to build and use your library or application.
 
-### Example
+#### Example port dependencies
 
 ```json
 "dependencies": [
@@ -129,17 +129,17 @@ The SPDX short license expression of the project. A string or null. Optional.
 
 The `"license"` should either be an [SPDX 3.19 license expression](https://spdx.org/licenses/) or should be `null` to indicate that users must read the deployed `/share/<port>/copyright` file. DocumentRefs are not supported.
 
-#### Example License Strings
+#### Example license strings
 
 - `MIT`
 - `LGPL-2.1-only AND BSD-2-Clause`
 - `GPL-2.0-or-later WITH Bison-exception-2.2`
 
 #### EBNF
 
-vcpkg uses the following EBNF to parse the license field:
+vcpkg uses the following [EBNF](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form) to parse the license field:
 
-```ebnf
+```text
 idchar = ? regex /[-.a-zA-Z0-9]/ ?
 idstring = ( idchar ), { idchar } ;
 
@@ -195,7 +195,6 @@ Exact version pins to use for specific dependencies. An array of Override object
 
 `"overrides"` from transitive manifests (i.e. from dependencies) are ignored. Only overrides defined by the top-level project are used.
 
-
 | Name | Required | Type   | Description |
 |------|----------|--------|-------------|
 | name | Yes      | string | The port name |
@@ -206,7 +205,7 @@ Exact version pins to use for specific dependencies. An array of Override object
 
 See also [versioning](../users/versioning.md#overrides) for more semantic details.
 
-#### Example
+#### Example of version overrides
 
 ```json
   "overrides": [
@@ -238,7 +237,7 @@ Allows to embed vcpkg configuration properties inside the `vcpkg.json` file. Eve
 
 Having a `vcpkg-configuration` defined in `vcpkg.json` while also having a `vcpkg-configuration.json` file is not allowed and will result in the vcpkg command terminating with an error message.
 
-#### Example
+#### Example embedded `vcpkg-configuration`
 
 ```json
 {
@@ -311,6 +310,7 @@ For example,
   "features": [ "mp3lame" ]
 }
 ```
+
 Uses the `ffmpeg` library but only requires mp3 encoding support.
 
 ### <a name="dependency-host"></a> [Dependency][]: `"host"`
@@ -357,7 +357,7 @@ Check out the [Manifest mode](../users/manifests.md#features) documentation for
 
 [Feature]: #feature
 
-### Example
+### Example port with features
 
 ```json
 {
@@ -421,7 +421,7 @@ A Platform Expression is a JSON string which describes when a dependency is requ
 Expressions are built from primitive identifiers, logical operators, and grouping:
 
 - `!<expr>`, `not <expr>` - negation
-- `<expr>|<expr>`, `<expr>||<expr>`, `<expr>,<expr>`, `<expr> or <expr>` - logical OR
+- `<expr>|<expr>`, `<expr>||<expr>`, `<expr>,<expr>` - logical OR (the keyword `or` is reserved but not valid in platform expressions)
 - `<expr>&<expr>`, `<expr>&&<expr>`, `<expr> and <expr>` - logical AND
 - `(<expr>)` - grouping/precedence
 
@@ -432,6 +432,7 @@ The following identifiers are defined based on the [triplet settings](../users/t
 | `x64` | `VCPKG_TARGET_ARCHITECTURE` == `"x64"` |
 | `x86` | `VCPKG_TARGET_ARCHITECTURE` == `"x86"` |
 | `arm` | `VCPKG_TARGET_ARCHITECTURE` == `"arm"` or</br> `VCPKG_TARGET_ARCHITECTURE` == `"arm64"` |
+| `arm32` | `VCPKG_TARGET_ARCHITECTURE` == `"arm"` |
 | `arm64` | `VCPKG_TARGET_ARCHITECTURE` == `"arm64"` |
 | `wasm32` | `VCPKG_TARGET_ARCHITECTURE` == `"wasm32"` |
 | `windows` | `VCPKG_CMAKE_SYSTEM_NAME` == `""` or</br> `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"` or</br> `VCPKG_CMAKE_SYSTEM_NAME` == `"MinGW"` |
@@ -449,11 +450,11 @@ The following identifiers are defined based on the [triplet settings](../users/t
 | `staticcrt` | `VCPKG_CRT_LINKAGE` == `"static"` |
 | `native` | `TARGET_TRIPLET` == `HOST_TRIPLET` |
 
-### Examples
+### Example platform expression
 
 - **Needs `picosha2` for sha256 on non-Windows, but get it from the OS on Windows (BCrypt)**
 
-```jsonc
+```json
 {
   "name": "picosha2",
   "platform": "!windows"
@@ -462,7 +463,7 @@ The following identifiers are defined based on the [triplet settings](../users/t
 
 - **Require zlib on arm64 Windows and amd64 Linux**
 
-```jsonc
+```json
 {
   "name": "zlib",
   "platform": "(windows & arm64) | (linux & x64)"