Tutorial: Set up a vcpkg binary cache using a NuGet feed
Note
This tutorial uses a NuGet feed hosted in Azure Artifacts but the same instructions can be used for other NuGet feed providers, for example: GitHub Packages, with some changes.
vcpkg supports using NuGet package feeds to upload and restore binary packages in a convenient way.
NuGet package feeds have access control capabilities which make them ideal to limit access to resources across your organization or workgroup. NuGet feeds are supported by several cloud-storage providers, such as, Azure Artifacts and GitHub package registry.
In this tutorial, you'll learn how to:
Prerequisites
- A terminal
- vcpkg
- A NuGet package feed, or if you don't, an Azure DevOps account to follow along
- A terminal
- vcpkg
- A NuGet package feed, or if you don't, an Azure DevOps account to follow along
- The
mono
package installed in your system
1 - Set up a NuGet feed
Skip this step if you already have an existing NuGet packages feed.
Follow the instructions to set up an Azure Artifacts NuGet feed.
You can also use any other NuGet packages feed provider of your choice.
2 - Add a NuGet source
Note
On Linux you need mono
to execute nuget.exe
. You can install mono
using your distribution's
system package manager.
vcpkg acquires its own copy of the nuget.exe
executable that it uses during binary caching
operations. This tutorial uses the vcpkg-acquired nuget.exe
. The vcpkg fetch nuget
command
outputs the location of the vcpkg-acquired nuget.exe
, downloading the executable if necessary.
Run the following command to add your NuGet feed as a source, replace <feed name>
with any name of
your choosing and <feed url>
with the URL to your NuGet feed.
.$(vcpkg fetch nuget) sources add -Name <feed name> -Source <feed url>
Execute the command below to fetch the path to the NuGet executable:
vcpkg fetch nuget
This will provide an output that looks something like C:\path\to\nuget.exe
. Make a note of this path.
Using the path obtained from the previous step, run the following command:
C:\path\to\nuget.exe sources add -Name <feed name> -Source <feed url>
mono `vcpkg fetch nuget | tail -n 1` sources add -Name <feed name> -Source <feed url>
Provide an API key
Some providers require that you push your NuGet packages to the feed using an API key. For example,
GitHub Packages requires a GitHub PAT (Personal Access Token) as the API key; if you're using Azure
Artifacts the API key is AzureDevOps
instead.
Use the following command to set the API key for all the packages pushed to your NuGet feed, replace
<apiKey>
with your feed's API key.
.$(vcpkg fetch nuget) setapikey <apikey> -Source <feed url>
Execute the command below to fetch the path to the NuGet executable:
vcpkg fetch nuget
This will provide an output that looks something like C:\path\to\nuget.exe
. Make a note of this path.
Using the path obtained from the previous step, run the following command:
C:\path\to\nuget.exe setapikey <apikey> -Source <feed url>
mono `vcpkg fetch nuget | tail -n 1` setapikey <apiKey> -Source <feed url>
Provide authentication credentials
Your NuGet feed may require authentication to let you download and upload packages. If that's the
case you can provide credentials by adding them as parameters to the nuget sources add
command.
For example:
nuget sources add -Name my-packages -Source https://my.nuget.feed/vcpkg-cache/index.json -UserName myusername -Password mypassword -StorePasswordInClearText
Some providers like Azure Artifacts may require different authentication methods, read the Authenticate to private NuGet feeds article to learn more.
Use a nuget.config
file
Alternatively, you can use a nuget.config
file to configure your NuGet sources, following the
template below:
nuget.config
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<config>
<add key="defaultPushSource" value="<feed url>" />
</config>
<apiKeys>
<add key="<feed url>" value="<apikey>" />
</apiKeys>
<packageSources>
<clear />
<add key="<feed name>" value="<feed url>" />
</packageSources>
<packageSourcesCredentials>
<<feed name>>
<add key="Username" value="<username>" />
<add key="Password" value="<password>" />
</<feed name>>
</packageSourcesCredentials>
</configuration>
Example nuget.config
file :
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<config>
<add key="defaultPushSource" value="https://contoso.org/packages/" />
</config>
<apikeys>
<add key="https://contoso.org/packages/" value="encrypted_api_key" />
</apikeys>
<packageSources>
<clear />
<add key="Contoso" value="https://contoso.org/packages/" />
</packageSources>
<packageSourcesCredentials>
<Contoso>
<add key="Username" value="user" />
<add key="Password" value="..." />
</Contoso>
</packageSourcesCredentials>
</configuration>
vcpkg requires that you set a defaultPushSource
in your nuget.config
file, use your NuGet feed's
URL as the default source to push binary packages.
If you're uploading your packages to an Azure Artifacts NuGet feed, use AzureDevOps
as your
source's API Key by running nuget setApiKey AzureDevOps -Source <feed url> -ConfigFile <path to nuget.config>
.
Otherwise, replace the value with your feed's proper API Key if you have one.
Add the <clear />
source to ignore other previously configured values. If you want, you can define multiple
sources in this file, use a <add key="<feed name>" value="<feed url>" />
entry for each source.
Run the following command to add a NuGet source using a nuget.config
file, replace
<path to nuget.config>
with the path to your nuget.config
file:
.$(vcpkg fetch nuget) sources add -ConfigFile <path to nuget.config>
Execute the command below to fetch the path to the NuGet executable:
vcpkg fetch nuget
This will provide an output that looks something like C:\path\to\nuget.exe
. Make a note of this path.
Using the path obtained from the previous step, run the following command:
C:\path\to\nuget.exe sources add -ConfigFile <path to nuget.config>
mono `vcpkg fetch nuget | tail -n 1` sources add -ConfigFile <path to nuget.config>
3 - Configure vcpkg to use your NuGet feed
Set the VCPKG_BINARY_SOURCES
environment variable as follows:
$env:VCPKG_BINARY_SOURCES="clear;nuget,<feed url>,readwrite"
If you're using a nuget.config
file, instead do:
$env:VCPKG_BINARY_SOURCES="clear;nugetconfig,<path to nuget.config>"
set "VCPKG_BINARY_SOURCES=clear;nuget,<feed url>,readwrite"
If you're using a nuget.config
file, instead do:
set "VCPKG_BINARY_SOURCES=clear;nugetconfig,<path to nuget.config>"
Note
Setting VCPKG_BINARY_SOURCES
using the export
command will only affect the current shell
session. To make this change permanent across sessions, you'll need to add the export
command to
your shell's profile script (e.g., ~/.bashrc
or ~/.zshrc
).
export VCPKG_BINARY_SOURCES="clear;nuget,<feed url>,readwrite"
If you're using a nuget.config
file, instead do:
export VCPKG_BINARY_SOURCES="clear;nugetconfig,<path to nuget.config>"
And that's it! vcpkg will now upload or restore packages from your NuGet feed.
Next steps
Here are other tasks to try next: