Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Push main to live (2023.06.29) #101

Merged
merged 54 commits into from
Jul 17, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
54 commits
Select commit Hold shift + click to select a range
6c8fad1
Add docs for x-gha.
quyykk Mar 10, 2023
f6ee7de
Add mention of --x-binary-cache-github-actions.
quyykk Mar 10, 2023
7a53b9d
ACTIONS_CACHE_URL is the actual name
quyykk Mar 11, 2023
eddd3d1
Revert "Add mention of --x-binary-cache-github-actions."
quyykk Mar 11, 2023
80f9733
Add environment variables reference
quyykk Mar 16, 2023
61f6a7f
Improve GitHub Actions binary caching docs
davisp Mar 16, 2023
1dc5c90
fix
dan-shaw Apr 12, 2023
bd8c4c0
fix
dan-shaw Apr 12, 2023
030fdc9
fix
dan-shaw Apr 18, 2023
4bef8ca
fix
dan-shaw Apr 18, 2023
7d986cc
fix
dan-shaw Apr 18, 2023
5861ff6
fix
dan-shaw Apr 20, 2023
7a07eb4
fix
dan-shaw Apr 20, 2023
9641348
Merge pull request #62 from dan-shaw/android
dan-shaw Apr 26, 2023
46fd888
guidance for usage files
JavierMatosD May 11, 2023
989633c
add usage example and fix formatting
JavierMatosD May 11, 2023
ac2f07d
format
JavierMatosD May 11, 2023
becd72a
Remove internal only facing documents.
BillyONeal May 17, 2023
cdd7ab3
Merge pull request #81 from BillyONeal/remove-internal
BillyONeal May 17, 2023
bc1daae
Fix misspellings
myd7349 May 23, 2023
5c695a4
wip
JavierMatosD May 23, 2023
f27b4e1
Add missing depend-info entry to the table of contents.
BillyONeal May 24, 2023
1216d0d
Update depend-info for --format.
BillyONeal May 24, 2023
2c24d31
Merge pull request #88 from BillyONeal/add-index
ras0219-msft May 24, 2023
939d3a0
modify usage instructions
JavierMatosD May 25, 2023
fcc5e50
Change title
JavierMatosD May 25, 2023
64997d9
remove absolute links
JavierMatosD May 25, 2023
1cdd0f5
Merge pull request #87 from myd7349/fix-typo
BillyONeal Jun 5, 2023
b482685
Update binarycaching.md
AugP Jun 6, 2023
f9f1a6a
Update binarycaching.md
AugP Jun 6, 2023
3048854
Merge pull request #45 from quyykk/gha-docs
AugP Jun 6, 2023
6618000
update depend-info documentation with mermaid support and format changes
WimLeflere Jun 13, 2023
06abce5
change examples to match our heuristics
JavierMatosD Jun 16, 2023
6d91484
CPub style
JavierMatosD Jun 17, 2023
de12405
Merge pull request #89 from BillyONeal/update-depend-info
vicroms Jun 19, 2023
8dc0164
Merge branch 'main' into depend-info-mermaid-support
WimLeflere Jun 19, 2023
523a8fb
update main help message with mermaid support
WimLeflere Jun 19, 2023
4303896
Merge pull request #80 from JavierMatosD/add_usage_guidance
vicroms Jun 23, 2023
65d5fd9
Merge pull request #91 from WimLeflere/depend-info-mermaid-support
vicroms Jun 23, 2023
d119002
Initial documentation for GitHub dependency graph integration (#86)
michaelbprice Jun 26, 2023
e576c9a
Feature/license features (#93)
autoantwort Jun 26, 2023
4996c61
Updated repo notification recipients .openpublishing.publish.config.json
AugP Jun 26, 2023
cd7d711
Merge pull request #94 from microsoft/AugP-repo-notifications
vicroms Jun 26, 2023
7928cba
Revert "Add guidance for handling usage files"
vicroms Jun 26, 2023
0444602
Merge pull request #96 from microsoft/revert-80-add_usage_guidance
vicroms Jun 26, 2023
3f30ddb
Fixing incorrect minimum vcpkg-tool version for the GitHub dependency…
michaelbprice Jun 29, 2023
c0498de
Push main to live (2023.06.26) (#95) (#100)
vicroms Jun 29, 2023
8a4239a
Merge branch 'live' of https://github.com/microsoft/vcpkg-docs
vicroms Jun 29, 2023
d981e52
Merge pull request #102 from microsoft/sync-main-to-live
vicroms Jun 29, 2023
5daed28
change ownership (#107)
TylerMSFT Jul 11, 2023
0d83965
Add arm32 to the platform expressions table. (#108)
BillyONeal Jul 14, 2023
72bc960
Rewrite asset caching x-script example (#78)
vicroms Jul 17, 2023
b1ab726
Remove keywords 'or' in Platform Expression (#90)
LilyWangLL Jul 17, 2023
6722aab
Add guidance for supplying usage files (#105)
vicroms Jul 17, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions vcpkg/TOC.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
38 changes: 19 additions & 19 deletions vcpkg/docfx.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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": [],
Expand Down
84 changes: 58 additions & 26 deletions vcpkg/examples/asset-caching-source-nuget.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
2 changes: 1 addition & 1 deletion vcpkg/github-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
62 changes: 62 additions & 0 deletions vcpkg/maintainers/handling-usage-files.md
Original file line number Diff line number Diff line change
@@ -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)
```
27 changes: 14 additions & 13 deletions vcpkg/reference/vcpkg-json.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand Down Expand Up @@ -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": [
Expand Down Expand Up @@ -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 } ;

Expand Down Expand Up @@ -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 |
Expand All @@ -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": [
Expand Down Expand Up @@ -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
{
Expand Down Expand Up @@ -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"`
Expand Down Expand Up @@ -357,7 +357,7 @@ Check out the [Manifest mode](../users/manifests.md#features) documentation for

[Feature]: #feature

### Example
### Example port with features

```json
{
Expand Down Expand Up @@ -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

Expand All @@ -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"` |
Expand All @@ -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"
Expand All @@ -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)"
Expand Down