Skip to content

Commit

Permalink
[docs] binarycaching.md: Move Configuration section to the top. Add t…
Browse files Browse the repository at this point in the history
…able of… (#17060)

* 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.

* Apply suggestions from code review

Co-authored-by: ras0219 <[email protected]>

Co-authored-by: ras0219 <[email protected]>
  • Loading branch information
autoantwort and ras0219 authored Apr 30, 2021
1 parent 8badb23 commit 44d94c2
Showing 1 changed file with 47 additions and 34 deletions.
81 changes: 47 additions & 34 deletions docs/users/binarycaching.md
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

0 comments on commit 44d94c2

Please sign in to comment.