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.

Sign up for GitHub

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

binarycaching.md: Move Configuration section to the top. Add table of… #17060

Merged
merged 2 commits into from
Apr 30, 2021
Merged

binarycaching.md: Move Configuration section to the top. Add table of… #17060

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
75fb78f
binarycaching.md: Move Configuration section to the top. Add table of…
autoantwort Apr 3, 2021
21f4060
Apply suggestions from code review
autoantwort Apr 15, 2021
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
81 changes: 47 additions & 34 deletions docs/users/binarycaching.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,51 @@ 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 `<source>;<source>;...`), and the command line option `--binarysource=<source>`. 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 (`<source>`)

| form | description
|-----------------------------|---------------
| `clear` | Removes all previous sources (including the default)
| `default[,<rw>]` | Adds the default file-based location
| `files,<absolute path>[,<rw>]` | Adds a custom file-based location
| `nuget,<uri>[,<rw>]` | Adds a NuGet-based source; equivalent to the `-Source` parameter of the NuGet CLI
| `nugetconfig,<path>[,<rw>]` | 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,<baseuri>,<sas>[,<rw>]` | **Experimental: will change or be removed without warning**<br> 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 `<rw>` 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

Expand Down Expand Up @@ -146,40 +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.

## Configuration

Binary caching is configured via a combination of defaults, the environment variable `VCPKG_BINARY_SOURCES` (set to `<source>;<source>;...`), and the command line option `--binarysource=<source>`. 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 (`<source>`)

| form | description
|-----------------------------|---------------
| `clear` | Removes all previous sources (including the default)
| `default[,<rw>]` | Adds the default file-based location
| `files,<path>[,<rw>]` | Adds a custom file-based location
| `nuget,<uri>[,<rw>]` | Adds a NuGet-based source; equivalent to the `-Source` parameter of the NuGet CLI
| `nugetconfig,<path>[,<rw>]` | 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,<baseuri>,<sas>[,<rw>]` | **Experimental: will change or be removed without warning**<br> 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 `<rw>` 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
### 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`.

Expand Down