From 75fb78f2baad324462880d6a54af4c5ecc4287d2 Mon Sep 17 00:00:00 2001 From: Leander Schulten Date: Sat, 3 Apr 2021 15:33:03 +0200 Subject: [PATCH 1/2] binarycaching.md: Move Configuration section to the top. Add table of contents. Make clear that file location must be absolute. Add that read is the default mode. --- docs/users/binarycaching.md | 77 +++++++++++++++++++++---------------- 1 file changed, 44 insertions(+), 33 deletions(-) diff --git a/docs/users/binarycaching.md b/docs/users/binarycaching.md index b7783698454fb4..0545c278a93a17 100644 --- a/docs/users/binarycaching.md +++ b/docs/users/binarycaching.md @@ -6,7 +6,49 @@ Binary caching is vcpkg's method for reusing package builds between projects and If your CI provider offers a native "caching" function, we recommend using both methods for the most performant results. -In-tool help is available via `vcpkg help binarycaching` and a [detailed configuration reference is provided below](#Configuration). +In-tool help is available via `vcpkg help binarycaching`. + +Table of Contents + - [Configuration](#configuration) + - [CI Examples](#ci-examples) + - [GitHub Packages](#github-packages) + - [Azure DevOps Artifacts](#azure-devops-artifacts) + - [Azure Blob Storage](#azure-blob-storage-experimental) + - [Google Cloud Storage](#google-cloud-storage-experimental) + - [Nuget Provider Configuration](#nuget-provider-configuration) + - [Implementation Notes](#implementation-notes-internal-details-subject-to-change-without-notice) + + +## Configuration + +Binary caching is configured via a combination of defaults, the environment variable `VCPKG_BINARY_SOURCES` (set to `;;...`), and the command line option `--binarysource=`. Source options are evaluated in order of defaults, then environment, then command line. Binary caching can be completely disabled by passing `--binarysource=clear` as the last command line option. + +By default, zip-based archives will be cached at the first valid location of: + +**Windows** +1. `%VCPKG_DEFAULT_BINARY_CACHE%` +2. `%LOCALAPPDATA%\vcpkg\archives` +3. `%APPDATA%\vcpkg\archives` + +**Non-Windows** +1. `$VCPKG_DEFAULT_BINARY_CACHE` +2. `$XDG_CACHE_HOME/vcpkg/archives` +3. `$HOME/.cache/vcpkg/archives` + +### Valid source strings (``) + +| form | description +|-----------------------------|--------------- +| `clear` | Removes all previous sources (including the default) +| `default[,]` | Adds the default file-based location +| `files,[,]` | Adds a custom file-based location +| `nuget,[,]` | Adds a NuGet-based source; equivalent to the `-Source` parameter of the NuGet CLI +| `nugetconfig,[,]` | Adds a NuGet-config-file-based source; equivalent to the `-Config` parameter of the NuGet CLI. This config should specify `defaultPushSource` for uploads. +| `x-azblob,,[,]` | **Experimental: will change or be removed without warning**
Adds an Azure Blob Storage source. Uses Shared Access Signature validation. URL should include the container path. +| `interactive` | Enables interactive credential management for NuGet (for debugging; requires `--debug` on the command line) + +The `` optional parameter for certain sources controls whether they will be consulted for +downloading binaries (`read`)(default), whether on-demand builds will be uploaded to that remote (`write`), or both (`readwrite`). ## CI Examples @@ -146,38 +188,7 @@ Commas (`,`) are valid as part of a object prefix in GCS, just remember to escap shown in the previous example. Note that GCS does not have folders (some of the GCS tools simulate folders), it is not necessary to create or otherwise manipulate the prefix used by your vcpkg cache. -## Configuration - -Binary caching is configured via a combination of defaults, the environment variable `VCPKG_BINARY_SOURCES` (set to `;;...`), and the command line option `--binarysource=`. Source options are evaluated in order of defaults, then environment, then command line. Binary caching can be completely disabled by passing `--binarysource=clear` as the last command line option. - -By default, zip-based archives will be cached at the first valid location of: - -**Windows** -1. `%VCPKG_DEFAULT_BINARY_CACHE%` -2. `%LOCALAPPDATA%\vcpkg\archives` -3. `%APPDATA%\vcpkg\archives` - -**Non-Windows** -1. `$VCPKG_DEFAULT_BINARY_CACHE` -2. `$XDG_CACHE_HOME/vcpkg/archives` -3. `$HOME/.cache/vcpkg/archives` - -### Valid source strings (``) - -| form | description -|-----------------------------|--------------- -| `clear` | Removes all previous sources (including the default) -| `default[,]` | Adds the default file-based location -| `files,[,]` | Adds a custom file-based location -| `nuget,[,]` | Adds a NuGet-based source; equivalent to the `-Source` parameter of the NuGet CLI -| `nugetconfig,[,]` | Adds a NuGet-config-file-based source; equivalent to the `-Config` parameter of the NuGet CLI. This config should specify `defaultPushSource` for uploads. -| `x-azblob,,[,]` | **Experimental: will change or be removed without warning**
Adds an Azure Blob Storage source. Uses Shared Access Signature validation. URL should include the container path. -| `interactive` | Enables interactive credential management for NuGet (for debugging; requires `--debug` on the command line) - -The `` optional parameter for certain sources controls whether they will be consulted for -downloading binaries (`read`), whether on-demand builds will be uploaded to that remote (`write`), or both (`readwrite`). - -### Nuget Provider Configuration +## Nuget Provider Configuration #### Credentials From 21f4060b0f3a901a5fa0eff71fa209ef523c00c3 Mon Sep 17 00:00:00 2001 From: autoantwort <41973254+autoantwort@users.noreply.github.com> Date: Thu, 15 Apr 2021 02:10:52 +0200 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: ras0219 <533828+ras0219@users.noreply.github.com> --- docs/users/binarycaching.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/users/binarycaching.md b/docs/users/binarycaching.md index 0545c278a93a17..101ddb98c0126a 100644 --- a/docs/users/binarycaching.md +++ b/docs/users/binarycaching.md @@ -15,7 +15,7 @@ Table of Contents - [Azure DevOps Artifacts](#azure-devops-artifacts) - [Azure Blob Storage](#azure-blob-storage-experimental) - [Google Cloud Storage](#google-cloud-storage-experimental) - - [Nuget Provider Configuration](#nuget-provider-configuration) + - [NuGet Provider Configuration](#nuget-provider-configuration) - [Implementation Notes](#implementation-notes-internal-details-subject-to-change-without-notice) @@ -50,6 +50,8 @@ By default, zip-based archives will be cached at the first valid location of: The `` optional parameter for certain sources controls whether they will be consulted for downloading binaries (`read`)(default), whether on-demand builds will be uploaded to that remote (`write`), or both (`readwrite`). +Additional configuration details for NuGet-based providers can be found below in [NuGet Provider Configuration](#nuget-provider-configuration). + ## CI Examples If your CI system of choice is not listed, we welcome PRs to add them! @@ -188,9 +190,9 @@ Commas (`,`) are valid as part of a object prefix in GCS, just remember to escap shown in the previous example. Note that GCS does not have folders (some of the GCS tools simulate folders), it is not necessary to create or otherwise manipulate the prefix used by your vcpkg cache. -## Nuget Provider Configuration +## NuGet Provider Configuration -#### Credentials +### Credentials Many NuGet servers require additional credentials to access. The most flexible way to supply credentials is via the `nugetconfig` provider with a custom `nuget.config` file. See https://docs.microsoft.com/en-us/nuget/consume-packages/consuming-packages-authenticated-feeds for more information on authenticating via `nuget.config`.