hdkv/yuzu
1
Fork 0
Code Issues Pull Requests Releases 1 Activity

early-access version 2853

Browse Source
This commit is contained in:
pineappleEA
2022-07-23 03:01:36 +02:00
parent 1f2b5081b5
commit 1f111bb69c
8955 changed files with 418777 additions and 999 deletions
Download Patch File Download Diff File Expand all files Collapse all files

221
externals/vcpkg/docs/users/android.md vendored Executable file
View File

@@ -0,0 +1,221 @@
# Vcpkg and Android
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/android.md).**
*Android is not tested as part of vcpkg repository's CI process, so regressions can occur as part of library updates. PRs improving support are welcome!*
## Android build requirements
1. Download the [android ndk](https://developer.android.com/ndk/downloads/)
2. Set environment variable `ANDROID_NDK_HOME` to your android ndk installation.
For example:
````bash
export ANDROID_NDK_HOME=/home/your-account/Android/Sdk/ndk-bundle
````
Or:
````bash
export ANDROID_NDK_HOME=/home/your-account/Android/android-ndk-r21b
````
3. Install [vcpkg](https://github.com/microsoft/vcpkg)
4. Set environment variable `VCPKG_ROOT` to your vcpkg installation.
````bash
export VCPKG_ROOT=/path/to/vcpkg
````
## vcpkg triplets and their corresponding android ABI
There are four different Android ABI, each of which maps to
a vcpkg triplet. The following table outlines the mapping from vcpkg architectures to android architectures
|VCPKG_TARGET_TRIPLET | ANDROID_ABI |
|---------------------------|----------------------|
|arm64-android | arm64-v8a |
|arm-android | armeabi-v7a |
|x64-android | x86_64 |
|x86-android | x86 |
## Install libraries for Android using vcpkg
Example for jsoncpp:
````bash
cd $VCPKG_ROOT
# specify the triplet like this
./vcpkg install jsoncpp --triplet arm-android
# or like this
./vcpkg install jsoncpp:arm64-android
./vcpkg install jsoncpp:x86-android
./vcpkg install jsoncpp:x64-android
````
### Using Vulkan SDK
Vcpkg has a [`vulkan` package](https://github.com/microsoft/vcpkg/blob/master/ports/vulkan/portfile.cmake) which allows you to `find_package(Vulkan)`. To use it you have to provide `VULKAN_SDK` environment variable.
```bash
export VULKAN_SDK=/usr/local
./vcpkg install vulkan
```
NDK already contains [Vulkan](https://developer.android.com/ndk/guides/graphics/getting-started) headers and `libvulkan.so` binaries for each of its architecture.
To expose them to VcPkg, you can consider `export VULKAN_SDK=...` for each installation.
But by placing `set(ENV{VULKAN_SDK} ...)` in the triplet files, you can skip the tedious work.
If you are using NDK 21.3.6528147 or earlier version, it will be like the following.
```cmake
# In android triplets... (e.g. arm64-android.cmake)
set(VCPKG_CMAKE_SYSTEM_NAME Android)
# ...
# If your API level is 30, libvulkan.so is at $ENV{ANDROID_NDK_HOME}/platforms/android-30/arch-arm64/usr/lib
set(ENV{VULKAN_SDK} $ENV{ANDROID_NDK_HOME}/sysroot/usr)
```
Notice that **the location of the sysroot has changed since NDK 22**. (see https://github.com/android/ndk/issues/1407)
If you prefer using [the latest version](https://developer.android.com/studio/projects/install-ndk#default-ndk-per-agp), check the [BuildSystemMaintainers.md of the NDK document](https://android.googlesource.com/platform/ndk/+/master/docs/BuildSystemMaintainers.md#sysroot) and then put appropriate path for your system.
For example, Mac OS users will use the path like this.
```cmake
# In android triplets... (e.g. arm64-android.cmake)
set(VCPKG_CMAKE_SYSTEM_NAME Android)
# ...
# If your API level is 30, libvulkan.so is at $ENV{ANDROID_NDK_HOME}/toolchains/llvm/prebuilt/darwin-x86_64/sysroot/usr/lib/aarch64-linux-android/30
set(ENV{VULKAN_SDK} $ENV{ANDROID_NDK_HOME}/toolchains/llvm/prebuilt/darwin-x86_64/sysroot/usr)
```
By doing this for all android triplets, you can install `vulkan` and the packages that require it. (e.g. `vulkan-hpp`)
<details>
<summary markdown="span">`vcpkg install vulkan-hpp:arm64-android`</summary>
```console
user@host$ ./vcpkg install vulkan-hpp:arm64-android
Computing installation plan...
The following packages will be built and installed:
* vulkan[core]:arm64-android -> 1.1.82.1-1
vulkan-hpp[core]:arm64-android -> 2019-05-11-1
Additional packages (*) will be modified to complete this operation.
Detecting compiler hash for triplet arm64-android...
...
Starting package 1/2: vulkan:arm64-android
Building package vulkan[core]:arm64-android...
-- Using community triplet arm64-android. This triplet configuration is not guaranteed to succeed.
-- [COMMUNITY] Loading triplet configuration from: /.../vcpkg/triplets/community/arm64-android.cmake
-- Querying VULKAN_SDK Environment variable
-- Searching /.../Library/Android/sdk/ndk/22.1.7171670/toolchains/llvm/prebuilt/darwin-x86_64/sysroot/usr/include/vulkan/ for vulkan.h
-- Found vulkan.h
-- Performing post-build validation
-- Performing post-build validation done
...
Building package vulkan[core]:arm64-android... done
Installing package vulkan[core]:arm64-android...
Installing package vulkan[core]:arm64-android... done
Elapsed time for package vulkan:arm64-android: 35.9 ms
Starting package 2/2: vulkan-hpp:arm64-android
Building package vulkan-hpp[core]:arm64-android...
-- Using community triplet arm64-android. This triplet configuration is not guaranteed to succeed.
-- [COMMUNITY] Loading triplet configuration from: /.../vcpkg/triplets/community/arm64-android.cmake
-- Using cached /.../vcpkg/downloads/KhronosGroup-Vulkan-Hpp-5ce8ae7fd0d9c0543d02f33cfa8a66e6a43e2150.tar.gz
-- Cleaning sources at /.../vcpkg/buildtrees/vulkan-hpp/src/e6a43e2150-4f344cd911.clean. Use --editable to skip cleaning for the packages you specify.
-- Extracting source /.../vcpkg/downloads/KhronosGroup-Vulkan-Hpp-5ce8ae7fd0d9c0543d02f33cfa8a66e6a43e2150.tar.gz
-- Using source at /.../vcpkg/buildtrees/vulkan-hpp/src/e6a43e2150-4f344cd911.clean
-- Performing post-build validation
-- Performing post-build validation done
...
Building package vulkan-hpp[core]:arm64-android... done
Installing package vulkan-hpp[core]:arm64-android...
Installing package vulkan-hpp[core]:arm64-android... done
Elapsed time for package vulkan-hpp:arm64-android: 144.5 ms
Total elapsed time: 1.013 s
The package vulkan-hpp:arm64-android is header only and can be used from CMake via:
find_path(VULKAN_HPP_INCLUDE_DIRS "vulkan/vulkan.hpp")
target_include_directories(main PRIVATE ${VULKAN_HPP_INCLUDE_DIRS})
```
</details>
## Consume libraries using vpckg, cmake and the android toolchain
1. Combine vcpkg and Android toolchains
vcpkg and android both provide dedicated toolchains:
````bash
vcpkg_toolchain_file=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
android_toolchain_file=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake
````
When using vcpkg, the vcpkg toolchain shall be specified first.
However, vcpkg provides a way to preload and additional toolchain, with the VCPKG_CHAINLOAD_TOOLCHAIN_FILE option.
````bash
cmake \
-DCMAKE_TOOLCHAIN_FILE=$vcpkg_toolchain_file \
-DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=$android_toolchain_file \
...
````
2. Specify the android abi and vcpkg triplet
When compiling for android, you need to select a matching "android abi" / "vcpkg triplet" pair.
For example:
````bash
android_abi=armeabi-v7a
vcpkg_target_triplet=arm-android
cmake
...
-DVCPKG_TARGET_TRIPLET=$vcpkg_target_triplet \
-DANDROID_ABI=$android_abi
````
### Test on an example
The folder [docs/examples/vcpkg_android_example_cmake](../examples/vcpkg_android_example_cmake) provides a working example, with an android library that consumes the jsoncpp library:
*Details*
* The [CMakeLists](../examples/vcpkg_android_example_cmake/CMakeLists.txt) simply uses `find_package` and `target_link_library`
* The [compile.sh](../examples/vcpkg_android_example_cmake/compile.sh) script enables you to select any matching pair of "android abi" / "vcpkg triplet" and to test the compilation
* The dummy [my_lib.cpp](../examples/vcpkg_android_example_cmake/my_lib.cpp) file uses the jsoncpp library
*Note*: this example only compiles an Android library, as the compilation of a full fledged Android App is beyond the scope of this document.
### Test on an example, using [vcpkg_android.cmake](../examples/vcpkg_android_example_cmake_script/cmake/vcpkg_android.cmake)
The folder [docs/examples/vcpkg_android_example_cmake_script](../examples/vcpkg_android_example_cmake_script) provides the same example, and uses a cmake script in order to simplify the usage.
*Details*
* The main [CMakeLists](../examples/vcpkg_android_example_cmake_script/CMakeLists.txt) loads [vcpkg_android.cmake](../examples/vcpkg_android_example_cmake_script/cmake/vcpkg_android.cmake) if the flag `VCPKG_TARGET_ANDROID` is set:
````cmake
if (VCPKG_TARGET_ANDROID)
include("cmake/vcpkg_android.cmake")
endif()
````
*Important: place these lines before calling project() !*
* The [compile.sh](../examples/vcpkg_android_example_cmake_script/compile.sh) script shows that it is then possible to compile for android using a simple cmake invocation, for example:
````bash
cmake .. -DVCPKG_TARGET_ANDROID=ON -DANDROID_ABI=armeabi-v7a
````
## Consume libraries using vpckg, and Android prefab Archives (AAR files)
See [prefab.md](../specifications/prefab.md)

58
externals/vcpkg/docs/users/assetcaching.md vendored Executable file
View File

@@ -0,0 +1,58 @@
# Asset Caching
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/assetcaching.md).**
**Experimental feature: this may change or be removed at any time**
Vcpkg can utilize mirrors to cache downloaded assets, ensuring continued operation even if the original source changes
or disappears.
In-tool help is available via `vcpkg help assetcaching`.
## Configuration
Asset caching can be configured by setting the environment variable `X_VCPKG_ASSET_SOURCES` to a semicolon-delimited
list of source strings. Characters can be escaped using backtick (\`).
### Valid source strings
The `<rw>` optional parameter for certain strings controls how they will be accessed. It can be specified as `read`,
`write`, or `readwrite` and defaults to `read`.
#### `clear`
Syntax: `clear`
Removes all previous sources
#### `x-azurl`
Syntax: `x-azurl,<url>[,<sas>[,<rw>]]`
Adds an Azure Blob Storage source, optionally using Shared Access Signature validation. URL should include the container
path and be terminated with a trailing `/`. SAS, if defined, should be prefixed with a `?`. Non-Azure servers will also
work if they respond to GET and PUT requests of the form: `<url><sha512><sas>`. As an example, if you set
`X_VCPKG_ASSET_SOURCES` to `x-azurl,https://mydomain.com/vcpkg/,token=abc123,readwrite` your server should respond to
`GET` and `PUT` requests of the form `https://mydomain.com/vcpkg/<sha512>?token=abc123`.
You can also use the filesystem (e.g. a network drive) via `file://` as asset cache. For example you then set
`X_VCPKG_ASSET_SOURCES` to `x-azurl,file:///Z:/vcpkg/assetcache/,,readwrite` when you have a network folder mounted at
`Z:/`.
The workflow of this asset source is:
1. Attemp to read from the mirror
2. (If step 1 failed) Read from the original url
3. (If step 2 succeeded) Write back to the mirror
You can enable/disable steps 1 and 3 via the [`<rw>`](#valid-source-strings) specifier and you can disable step 2 via
`x-block-origin` below.
See also the [binary caching documentation for Azure Blob Storage](binarycaching.md#azure-blob-storage-experimental) for
more information on how to set up an `x-azurl` source.
#### `x-block-origin`
Syntax: `x-block-origin`
Disables use of the original URLs in case the mirror does not have the file available.

91
externals/vcpkg/docs/users/authentication.md vendored Executable file
View File

@@ -0,0 +1,91 @@
# Authentication for Source Code
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/authentication.md).**
Registries and `vcpkg_from_git()` directly use the git command line tools to fetch remote resources. Some of these resources may be protected from anonymous access and need authentication or credentials.
The strategies below all seek to achieve the same fundamental goal: `git clone https://....` should succeed without interaction. This enables vcpkg to be separated from the specifics of your authentication scheme, ensuring forwards compatibility with any additional security improvements in the future.
## Pre-seed git credentials
You can pre-seed git credentials via `git credential approve`:
Powershell:
```powershell
"url=https://github.com`npath=Microsoft/vcpkg`nusername=unused`npassword=$MY_PAT`n" | git credential approve
```
Bash:
```sh
echo "url=https://github.com"$'\n'"path=Microsoft/vcpkg"$'\n'"username=unused"$'\n'"password=$MY_PAT"$'\n' | git credential approve
```
## Bearer auth
For systems which need bearer auth, you can use `git config`:
**Note: you must make these config changes with `--global`**
```
git config --global --unset-all http.<uri>.extraheader
git config --global http.<uri>.extraheader "AUTHORIZATION: bearer <System_AccessToken>"
```
The `<uri>` can be filled in with a variety of options, documented in https://git-scm.com/docs/git-config#Documentation/git-config.txt-httplturlgt. For example, `https://dev.azure.com/MYORG/`.
(Original Source: https://github.com/Microsoft/azure-pipelines-agent/issues/1601#issuecomment-394511048).
**Note for Azure DevOps users:** You may need to enable access via Job authorization scope https://docs.microsoft.com/en-us/azure/devops/pipelines/process/access-tokens?view=azure-devops&tabs=yaml#job-authorization-scope. You may also need to "reference" the repo in your yaml via:
```yaml
resources:
repositories:
- repository: <FRIENDLYNAME>
type: git
name: <ORG>/<REPO>
tag: tags/<TAG>
...
jobs:
- job: Build
uses:
repositories: [<FRIENDLYNAME>]
```
## Pass credentials in an environment variable (not recommended)
Using `VCPKG_KEEP_ENV_VARS` or `VCPKG_ENV_PASSTHROUGH_UNTRACKED`, we can smuggle credential info via another var like `MY_TOKEN_VAR`.
```sh
export VCPKG_KEEP_ENV_VARS=MY_TOKEN_VAR
export MY_TOKEN_VAR=abc123
```
This can then be used in your private ports:
```cmake
# some/private/portfile.cmake
set(MY_TOKEN_VAR "")
if(DEFINED ENV{MY_TOKEN_VAR})
set(MY_TOKEN_VAR "$ENV{MY_TOKEN_VAR}@")
endif()
vcpkg_from_git(
URLS "https://${MY_TOKEN_VAR}host.com/normal/url/path"
...
)
```
```cmake
# some/other/private/portfile.cmake
vcpkg_from_github(
AUTHORIZATION_TOKEN "$ENV{MY_TOKEN_VAR}"
)
```
For private ports, we recommend using `vcpkg_from_git()` instead of `vcpkg_from_github()` and the pre-seeding method above.
## Pass Jenkins gitUsernamePassword credentials
The simplest and most secure option to Git authentication to GitHub from Jenkins is using [GitHub App](https://github.com/jenkinsci/github-branch-source-plugin/blob/master/docs/github-app.adoc) and the following:
```groovy
withCredentials([gitUsernamePassword(credentialsId: 'jenkins-github-app')]) {
withEnv(['VCPKG_KEEP_ENV_VARS=GIT_ASKPASS']) {
bat 'cmake'
}
}
```
This sets the GIT_ASKPASS with a path to helper script which responds with git credentials query and instructs `vcpkg` to keep this environment variable. The password is a [GitHub App token](https://github.blog/2021-04-05-behind-githubs-new-authentication-token-formats/) with 1 hour lifetime.

285
externals/vcpkg/docs/users/binarycaching.md vendored Executable file
View File

@@ -0,0 +1,285 @@
# Binary Caching
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/binarycaching.md).**
Libraries installed with vcpkg can always be built from source. However, that can duplicate work and waste time when working across multiple projects.
Binary caching is a vcpkg feature that saves copies of library binaries in a shared location that can be accessed by vcpkg for future installs. This means that, as a user, you should only need to build dependencies from source once. If vcpkg is asked to install the same library with the same build configuration in the future, it will just copy the built binaries from the cache and finish the operation in seconds.
Binary caching is especially effective when using Continuous Integration, since local developers can reuse the binaries produced during a CI run. It also greatly enhances the performance of "ephemeral" or "hosted" build agents, since all local changes are otherwise lost between runs. By using binary caching backed by a cloud service, such as GitHub, Azure, or many others, you can ensure your CI runs at maximum speed and only rebuilds your dependencies when they've changed.
Caches can be hosted in a variety of environments. The most basic examples are a folder on the local machine or a network file share. Caches can also be stored in any NuGet feed (such as GitHub or Azure DevOps Artifacts), Azure Blob Storage*, or Google Cloud Storage*.
\* (experimental)
If your CI provider offers a native "caching" function, we recommend using both vcpkg binary caching and the native method for the most performant results.
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.
| `nugettimeout,<seconds>` | Specifies a timeout for NuGet network operations; equivalent to the `-Timeout` parameter of the NuGet CLI.
| `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
If your CI system of choice is not listed, we welcome PRs to add them!
### GitHub Packages
To use vcpkg with GitHub Packages, we recommend using the `NuGet` backend.
>**NOTE 2020-09-21**: GitHub's hosted agents come with an older, pre-installed copy of vcpkg on the path that does not support the latest binary caching. This means that direct calls to `bootstrap-vcpkg` or `vcpkg` without a path prefix may call an unintended vcpkg instance. We recommend taking the following two steps to avoid issues if you want to use your own copy of vcpkg:
> 1. Run the equivalent of `rm -rf "$VCPKG_INSTALLATION_ROOT"` using `shell: 'bash'`
> 2. Always call `vcpkg` and `bootstrap-vcpkg` with a path prefix, such as `./vcpkg`, `vcpkg/vcpkg`, `.\bootstrap-vcpkg.bat`, etc
```yaml
# actions.yaml
#
# In this example, vcpkg has been added as a submodule (`git submodule add https://github.com/Microsoft/vcpkg`).
env:
VCPKG_BINARY_SOURCES: 'clear;nuget,GitHub,readwrite'
matrix:
os: ['windows-2019', 'ubuntu-20.04']
include:
- os: 'windows-2019'
triplet: 'x86-windows'
mono: ''
- os: 'ubuntu-20.04'
triplet: 'x64-linux'
# To run `nuget.exe` on non-Windows platforms, we must use `mono`.
mono: 'mono'
steps:
# This step assumes `vcpkg` has been bootstrapped (run `./vcpkg/bootstrap-vcpkg`)
- name: 'Setup NuGet Credentials'
shell: 'bash'
# Replace <OWNER> with your organization name
run: >
${{ matrix.mono }} `./vcpkg/vcpkg fetch nuget | tail -n 1`
sources add
-source "https://nuget.pkg.github.com/<OWNER>/index.json"
-storepasswordincleartext
-name "GitHub"
-username "<OWNER>"
-password "${{ secrets.GITHUB_TOKEN }}"
# Omit this step if you're using manifests
- name: 'vcpkg package restore'
shell: 'bash'
run: >
./vcpkg/vcpkg install sqlite3 cpprestsdk --triplet ${{ matrix.triplet }}
```
If you're using [manifests](../specifications/manifests.md), you can omit the `vcpkg package restore` step: it will be run automatically as part of your build.
More information about GitHub Packages' NuGet support is available on [GitHub Docs][github-nuget].
[github-nuget]: https://docs.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-dotnet-cli-for-use-with-github-packages
### Azure DevOps Artifacts
To use vcpkg with Azure DevOps Artifacts, we recommend using the `NuGet` backend.
First, you need to ensure Artifacts has been enabled on your DevOps instance; this can be done by an Administrator through `Project Settings > General > Overview > Azure DevOps Services > Artifacts`.
Next, you will need to create a feed for your project; see the [Azure DevOps Artifacts Documentation][devops-nuget] for more information. Your feed URL will be an `https://` link ending with `/nuget/v3/index.json`.
```yaml
# azure-pipelines.yaml
variables:
- name: VCPKG_BINARY_SOURCES
value: 'clear;nuget,<FEED_URL>,readwrite'
steps:
# Remember to add this task to allow vcpkg to upload archives via NuGet
- task: NuGetAuthenticate@0
```
If you are using custom agents with a non-Windows OS, you will need to install Mono to run `nuget.exe` (`apt install mono-complete`, `brew install mono`, etc).
More information about Azure DevOps Artifacts' NuGet support is available in the [Azure DevOps Artifacts Documentation][devops-nuget].
[devops-nuget]: https://docs.microsoft.com/en-us/azure/devops/artifacts/get-started-nuget?view=azure-devops
### Azure Blob Storage (experimental)
> Note: This is an experimental feature and may change or be removed at any time
Vcpkg supports interfacing with Azure Blob Storage via the `x-azblob` source type.
```
x-azblob,<baseuri>,<sas>[,<rw>]
```
First, you need to create an Azure Storage Account as well as a container ([Quick Start Documentation](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal)].
Next, you will need to create a Shared Access Signature, which can be done from the storage account under Settings -> Shared access signature. This SAS will need:
- Allowed services: Blob
- Allowed resource types: Object
- Allowed permissions: Read, Create (if using `write` or `readwrite`)
The blob endpoint plus the container must be passed as the `<baseuri>` and the generated SAS without the `?` prefix must be passed as the `<sas>`.
Example:
```
x-azblob,https://<storagename>.blob.core.windows.net/<containername>,sv=2019-12-12&ss=b&srt=o&sp=rcx&se=2020-12-31T06:20:36Z&st=2020-12-30T22:20:36Z&spr=https&sig=abcd,readwrite
```
Vcpkg will attempt to avoid revealing the SAS during normal operations, however:
1. It will be printed in full if `--debug` is passed
2. It will be passed as a command line parameter to subprocesses, such as `curl.exe`
Azure Blob Storage includes a feature to remove cache entries that haven't been accessed in a given number of days which can be used to reduce the size of your cache. See [Data Lifecycle Management on Microsoft Docs](https://docs.microsoft.com/en-us/azure/storage/blobs/lifecycle-management-overview) for more information, or look for "Data management > Lifecycle management" in the Azure Portal for your storage account. If you wish to be able to be resilient to upstream libraries' servers but still want to remove entries from the binary cache, consider using [asset caching](assetcaching.md#x-azurl) in a different storage account without a lifecycle management policy.
### Google Cloud Storage (experimental)
> Note: This is an experimental feature and may change or be removed at any time
Vcpkg supports interfacing with Google Cloud Storage (GCS) via the `x-gcs` source type.
```
x-gcs,<prefix>[,<rw>]
```
First, you need to create an Google Cloud Platform Account as well as a storage bucket ([GCS Quick Start](https://cloud.google.com/storage/docs/quickstart-gsutil)].
As part of this quickstart you would have configured the `gsutil` command-line tool to authenticate with Google Cloud.
Vcpkg will use this command-line tool, make sure it is in your search path for executables.
Example 1 (using a bucket without a common prefix for the objects):
```
x-gcs,gs://<bucket-name>/,readwrite
```
Example 2 (using a bucket and a prefix for the objects):
```
x-gcs,gs://<bucket-name>/my-vcpkg-cache/maybe/with/many/slashes/,readwrite
x-gcs,gs://<bucket-name>/my-vcpkg-cache/maybe/with`,commas/too!/,readwrite
```
Commas (`,`) are valid as part of a object prefix in GCS, just remember to escape them in the vcpkg configuration, as
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
### 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`.
However, it is still possible to authenticate against many servers using NuGet's built-in credential providers or via customizing your environment's default `nuget.config`. The default config can be extended via nuget client calls such as
```
nuget sources add -Name MyRemote -Source https://... -Username $user -Password $pass
```
and then passed to vcpkg via `--binarysource=nuget,MyRemote,readwrite`. You can get a path to the precise copy of NuGet used by vcpkg by running `vcpkg fetch nuget`, which will report something like:
```
$ vcpkg fetch nuget
/vcpkg/downloads/tools/nuget-5.5.1-linux/nuget.exe
```
Non-Windows users will need to call this through mono via `mono /path/to/nuget.exe sources add ...`.
##### Credential Example for Azure Dev Ops
```bash
# On Linux or OSX
$ mono `vcpkg fetch nuget | tail -n1` sources add \
-name ADO \
-Source https://pkgs.dev.azure.com/$ORG/_packaging/$FEEDNAME/nuget/v3/index.json \
-Username $USERNAME \
-Password $PAT
$ export VCPKG_BINARY_SOURCES="nuget,ADO,readwrite"
```
```powershell
# On Windows Powershell
PS> & $(vcpkg fetch nuget | select -last 1) sources add `
-name ADO `
-Source https://pkgs.dev.azure.com/$ORG/_packaging/$FEEDNAME/nuget/v3/index.json `
-Username $USERNAME `
-Password $PAT
PS> $env:VCPKG_BINARY_SOURCES="nuget,ADO,readwrite"
```
We recommend using a Personal Access Token (PAT) as the password for maximum security. You can generate a PAT in User Settings -> Personal Access Tokens or `https://dev.azure.com/$ORG/_usersSettings/tokens`.
#### `metadata.repository`
The `nuget` and `nugetconfig` source providers additionally respect certain environment variables while generating nuget packages. The `metadata.repository` field of any packages will be generated as:
```
<repository type="git" url="${VCPKG_NUGET_REPOSITORY}"/>
```
or
```
<repository type="git"
url="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}.git"
branch="${GITHUB_REF}"
commit="${GITHUB_SHA}"/>
```
if the appropriate environment variables are defined and non-empty. This is specifically used to associate packages in GitHub Packages with the _building_ project and not intended to associate with the original package sources.
#### NuGet's cache
NuGet's cache is not used by default. To use it for every nuget-based source, set the [environment variable](config-environment.md) `VCPKG_USE_NUGET_CACHE` to `true` (case-insensitive) or `1`.
## Implementation Notes (internal details subject to change without notice)
Binary caching relies on hashing everything that contributes to a particular package build. This includes:
- Every file in the port directory
- The triplet file and name
- The C++ compiler executable
- The C compiler executable
- The set of features selected
- Every dependency's package hash (note: this is that package's input hash, not contents)
- All helper scripts referenced by `portfile.cmake` (heuristic)
- The version of CMake used
- The contents of any environment variables listed in `VCPKG_ENV_PASSTHROUGH`
- The hash of the toolchain file (builtin or `VCPKG_CHAINLOAD_TOOLCHAIN_FILE`)
Despite this extensive list, it is possible to defeat the cache and introduce nondeterminism. If you have additional details that you'd like to be tracked, the easiest resolution is to generate a triplet file with your additional information in a comment. That additional information will be included in the package's input set and ensure a unique universe of binaries.
The hashes used are stored in the package and in the current installed directory at `/share/<port>/vcpkg_abi_info.txt`.
The original specification for binary caching is available [here](../specifications/binarycaching.md).

224
externals/vcpkg/docs/users/buildsystems/cmake-integration.md vendored Executable file
View File

@@ -0,0 +1,224 @@
# CMake Integration
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/buildsystems/cmake-integration.md).**
See [Installing and Using Packages Example: sqlite](../../examples/installing-and-using-packages.md) for a fully worked example using CMake.
## Table of Contents
- [`CMAKE_TOOLCHAIN_FILE`](#cmake_toolchain_file)
- [IDE Integration](#ide-integration)
- [Visual Studio Code (CMake Tools extension)](#visual-studio-code-cmake-tools-extension)
- [Visual Studio](#visual-studio)
- [CLion](#clion)
- [Using Multiple Toolchain Files](#using-multiple-toolchain-files)
- [Settings Reference](#settings-reference)
## `CMAKE_TOOLCHAIN_FILE`
Projects configured to use the vcpkg toolchain file (via the CMake setting `CMAKE_TOOLCHAIN_FILE`) can find libraries from vcpkg using the standard CMake functions: `find_package()`, `find_path()`, and `find_library()`.
```no-highlight
cmake ../my/project -DCMAKE_TOOLCHAIN_FILE=[vcpkg-root]/scripts/buildsystems/vcpkg.cmake
```
Since version 3.21, CMake will use the environment variable `CMAKE_TOOLCHAIN_FILE`[1] as the default value for `CMAKE_TOOLCHAIN_FILE`.
**cmd**
```cmd
set CMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake
```
**Powershell**
```powershell
$env:CMAKE_TOOLCHAIN_FILE="[vcpkg root]/scripts/buildsystems/vcpkg.cmake"
```
**bash**
```sh
export CMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake
```
vcpkg does not automatically add any include or links paths into your project. To use a header-only library you can use `find_path()` which will correctly work on all platforms:
```cmake
# To find and use catch2
find_path(CATCH_INCLUDE_DIR NAMES catch.hpp PATH_SUFFIXES catch2)
include_directories(${CATCH_INCLUDE_DIR})
```
[1]: https://cmake.org/cmake/help/latest/envvar/CMAKE_TOOLCHAIN_FILE.html
## IDE Integration
### Visual Studio Code (CMake Tools Extension)
Adding the following to your workspace `settings.json` will make CMake Tools automatically use vcpkg for libraries:
```json
{
"cmake.configureSettings": {
"CMAKE_TOOLCHAIN_FILE": "[vcpkg root]/scripts/buildsystems/vcpkg.cmake"
}
}
```
### Visual Studio
In the CMake Settings Editor, add the path to the vcpkg toolchain file under `CMake toolchain file`:
```
[vcpkg root]/scripts/buildsystems/vcpkg.cmake
```
### CLion
Open the Toolchains settings (`File > Settings` on Windows and Linux, `CLion > Preferences` on macOS), and go to the CMake settings (`Build, Execution, Deployment > CMake`). In `CMake options`, add the following line:
```
-DCMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake
```
You must add this line to each profile separately.
## Using Multiple Toolchain Files
To combine vcpkg's toolchain file with another toolchain file, you can set the cmake variable `VCPKG_CHAINLOAD_TOOLCHAIN_FILE`:
```no-highlight
cmake ../my/project \
-DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake \
-DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=../my/project/toolchain.cmake
```
Alternatively, you can include the vcpkg toolchain at the end of the primary toolchain file:
```cmake
# MyToolchain.cmake
set(CMAKE_CXX_COMPILER ...)
set(VCPKG_TARGET_TRIPLET x64-my-custom-windows-triplet)
include(/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake)
```
**Note: vcpkg does not automatically apply your toolchain's settings, such as your compiler or compilation flags, while building libraries. To change vcpkg's library settings, you must make a [custom triplet file](../triplets.md) (which can [share your toolchain](../triplets.md#VCPKG_CHAINLOAD_TOOLCHAIN_FILE))**
## Settings Reference
All vcpkg-affecting variables must be defined before the first `project()` directive, such as via the command line or `set()` statements.
### `VCPKG_TARGET_TRIPLET`
This setting controls the [triplet](../triplets.md) vcpkg will install and consume libraries from.
If unset, vcpkg will automatically detect an appropriate default triplet given the current compiler settings. If you change this CMake variable, you must delete your cache and reconfigure.
### `VCPKG_HOST_TRIPLET`
This variable controls which [triplet](../triplets.md) host dependencies will be installed for.
If unset, vcpkg will automatically detect an appropriate native triplet (x64-windows, x64-osx, x64-linux).
See also [Host Dependencies](../host-dependencies.md).
### `VCPKG_INSTALLED_DIR`
This variable sets the location where libraries will be installed and consumed from.
In manifest mode, the default is `${CMAKE_BINARY_DIR}/vcpkg_installed`.
In classic mode, the default is `${VCPKG_ROOT}/installed`.
### `VCPKG_MANIFEST_MODE`
This variable forces vcpkg to operate in either manifest mode or classic mode.
Defaults to `ON` when `VCPKG_MANIFEST_DIR` is non-empty or `${CMAKE_SOURCE_DIR}/vcpkg.json` exists.
To disable manifest mode while a `vcpkg.json` is detected, set this to `OFF`.
### `VCPKG_MANIFEST_DIR`
This variable specifies an alternate folder containing a `vcpkg.json` manifest.
Defaults to `${CMAKE_SOURCE_DIR}` if `${CMAKE_SOURCE_DIR}/vcpkg.json` exists.
### `VCPKG_MANIFEST_INSTALL`
This variable controls whether vcpkg will be automatically run to install your dependencies during your configure step.
Defaults to `ON` if `VCPKG_MANIFEST_MODE` is `ON`.
### `VCPKG_BOOTSTRAP_OPTIONS`
This variable can be set to additional command parameters to pass to `./bootstrap-vcpkg`.
In manifest mode, vcpkg will be automatically bootstrapped if the executable does not exist.
### `VCPKG_OVERLAY_TRIPLETS`
This variable can be set to a list of paths to be passed on the command line as `--overlay-triplets=...`
### `VCPKG_OVERLAY_PORTS`
This variable can be set to a list of paths to be passed on the command line as `--overlay-ports=...`
### `VCPKG_MANIFEST_FEATURES`
This variable can be set to a list of features to activate when installing from your manifest.
For example, features can be used by projects to control building with additional dependencies to enable tests or samples:
```json
{
"name": "mylibrary",
"version": "1.0",
"dependencies": [ "curl" ],
"features": {
"samples": {
"description": "Build Samples",
"dependencies": [ "fltk" ]
},
"tests": {
"description": "Build Tests",
"dependencies": [ "gtest" ]
}
}
}
```
```cmake
# CMakeLists.txt
option(BUILD_TESTING "Build tests" OFF)
if(BUILD_TESTING)
list(APPEND VCPKG_MANIFEST_FEATURES "tests")
endif()
option(BUILD_SAMPLES "Build samples" OFF)
if(BUILD_SAMPLES)
list(APPEND VCPKG_MANIFEST_FEATURES "samples")
endif()
project(myapp)
# ...
```
### `VCPKG_MANIFEST_NO_DEFAULT_FEATURES`
This variable controls activation of default features in addition to those listed in `VCPKG_MANIFEST_FEATURES`. If set to `ON`, default features will not be automatically activated.
Defaults to `OFF`.
### `VCPKG_INSTALL_OPTIONS`
This variable can be set to a list of additional command line parameters to pass to the vcpkg tool during automatic installation.
### `VCPKG_PREFER_SYSTEM_LIBS`
This variable controls whether vcpkg will append instead of prepend its paths to `CMAKE_PREFIX_PATH`, `CMAKE_LIBRARY_PATH` and `CMAKE_FIND_ROOT_PATH` so that vcpkg libraries/packages are found after toolchain/system libraries/packages.
Defaults to `OFF`.
### `VCPKG_FEATURE_FLAGS`
This variable can be set to a list of feature flags to pass to the vcpkg tool during automatic installation to opt-in to experimental behavior.
See the `--feature-flags=` command line option for more information.

20
externals/vcpkg/docs/users/buildsystems/export-command.md vendored Executable file
View File

@@ -0,0 +1,20 @@
# `export` Command
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/buildsystems/export-command.md).**
The `export` command creates a shrinkwrapped archive containing a specific set of libraries (and their dependencies) that can be quickly and reliably shared with build servers or other users in your organization. `export` only supports classic mode at this time.
- `--nuget`: NuGet package
- `--zip`: Zip archive
- `--7zip`: 7Zip archive
- `--raw`: Raw, uncompressed folder
Each of these have the same internal layout which mimics the layout of a full vcpkg instance:
- `installed/` contains the library files
- `scripts/buildsystems/vcpkg.cmake` is the [CMake toolchain file](cmake-integration.md)
- `scripts/buildsystems/msbuild/vcpkg.props` and `scripts/buildsystems/msbuild/vcpkg.targets` are the [MSBuild integration files](msbuild-integration.md)
NuGet package exports will also contain a `build\native\vcpkg.targets` that integrates with MSBuild projects using the NuGet package manager.
Please also see our [blog post](https://blogs.msdn.microsoft.com/vcblog/2017/05/03/vcpkg-introducing-export-command/) for additional examples.

10
externals/vcpkg/docs/users/buildsystems/integration.md vendored Executable file
View File

@@ -0,0 +1,10 @@
# Buildsystem Integration
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/buildsystems/integration.md).**
vcpkg supports use from any buildsystem and has specific native integration into MSBuild and CMake.
- [MSBuild Integration (Visual Studio)](msbuild-integration.md)
- [CMake Integration](cmake-integration.md)
- [Manual Integration](manual-integration.md)
- [`export` Command](export-command.md)

31
externals/vcpkg/docs/users/buildsystems/manual-integration.md vendored Executable file
View File

@@ -0,0 +1,31 @@
# Manual Integration
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/buildsystems/manual-integration.md).**
When installing libraries, vcpkg creates a single common layout partitioned by triplet.
The root of the tree in classic mode is `[vcpkg root]/installed`. The root of the tree in manifest mode is `[vcpkg.json directory]/vcpkg_installed`.
Underneath this root, in a subfolder named after the triplet:
* Header files: `include/`
* Release `.lib`, `.a`, and `.so` files: `lib/` or `lib/manual-link/`
* Release `.dll` files: `bin/`
* Release `.pc` files: `lib/pkgconfig/`
* Debug `.lib`, `.a`, and `.so` files: `debug/lib/` or `debug/lib/manual-link/`
* Debug `.dll` files: `debug/bin/`
* Debug `.pc` files: `debug/lib/pkgconfig/`
* Tools: `tools/[portname]/`
For example, `zlib.h` for `zlib:x64-windows` in classic mode is located at `[vcpkg root]/installed/x64-windows/include/zlib.h`.
See your build system specific documentation for how to use prebuilt binaries. For example, `Makefile` projects often accept environment variables:
```sh
export CXXFLAGS=-I$(pwd)/installed/x64-linux/include
export CFLAGS=-I$(pwd)/installed/x64-linux/include
export LDFLAGS=-L$(pwd)/installed/x64-linux/lib
export PKG_CONFIG_PATH=$(pwd)/installed/x64-linux/lib/pkgconfig:$PKG_CONFIG_PATH
```
_On Windows dynamic triplets, such as x64-windows:_ To run any produced executables you will also need to either copy the needed DLL files to the same folder as your executable or *prepend* the correct `bin\` directory to your path.

138
externals/vcpkg/docs/users/buildsystems/msbuild-integration.md vendored Executable file
View File

@@ -0,0 +1,138 @@
# MSBuild Integration (Visual Studio)
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/buildsystems/msbuild-integration.md).**
## Table of Contents
- [Integration Methods](#integration-methods)
- [User-wide integration](#user-wide-integration)
- [Import `.props` and `.targets`](#import-props-and-targets)
- [Linked NuGet Package](#linked-nuget-package)
- [Common Configuration](#common-configuration)
- [Manifest Mode Configuration](#manifest-mode-configuration)
## Integration Methods
### User-wide integration
```no-highlight
vcpkg integrate install
```
This will implicitly add Include Directories, Link Directories, and Link Libraries for all packages installed with Vcpkg to all VS2015, VS2017 and VS2019 MSBuild projects. We also add a post-build action for executable projects that will analyze and copy any DLLs you need to the output folder, enabling a seamless F5 experience.
For the vast majority of libraries, this is all you need to do -- just File -> New Project and write code! However, some libraries perform conflicting behaviors such as redefining `main()`. Since you need to choose per-project which of these conflicting options you want, you will need to add those libraries to your linker inputs manually.
Here are some examples, though this is not an exhaustive list:
- Gtest provides `gtest`, `gmock`, `gtest_main`, and `gmock_main`
- SDL2 provides `SDL2main`
- SFML provides `sfml-main`
- Boost.Test provides `boost_test_exec_monitor`
To get a full list for all your installed packages, run `vcpkg owns manual-link`.
### Import `.props` and `.targets`
vcpkg can also be integrated into MSBuild projects by explicitly importing the `scripts/buildsystems/vcpkg.props` and `scripts/buildsystems/vcpkg.targets` files into each `.vcxproj`. By using relative paths, this enables vcpkg to be consumed by a submodule and automatically acquired by users when they run `git clone`.
The easiest way to add these to every project in your solution is to create `Directory.Build.props` and `Directory.Build.targets` files at the root of your repository.
The following examples assume they are at the root of your repository with a submodule of `microsoft/vcpkg` at `vcpkg`.
**Example `Directory.Build.props`**:
```xml
<Project>
<Import Project="$(MSBuildThisFileDirectory)vcpkg\scripts\buildsystems\vcpkg.props" />
</Project>
```
**Example `Directory.Build.targets`**:
```xml
<Project>
<Import Project="$(MSBuildThisFileDirectory)vcpkg\scripts\buildsystems\vcpkg.targets" />
</Project>
```
More information about `Directory.Build.targets` and `Directory.Build.props` can be found in the [Customize your build][1] section of the official MSBuild documentation.
[1]: https://docs.microsoft.com/visualstudio/msbuild/customize-your-build#directorybuildprops-and-directorybuildtargets
### Linked NuGet Package
**Note: This approach is not recommended for new projects, since it makes them difficult to share with others. For a portable, self-contained NuGet package, see the [`export command`](export-command.md)**
VS projects can also be integrated through a NuGet package. This will modify the project file, so we do not recommend this approach for open source projects.
```no-highlight
PS D:\src\vcpkg> .\vcpkg integrate project
Created nupkg: D:\src\vcpkg\scripts\buildsystems\vcpkg.D.src.vcpkg.1.0.0.nupkg
With a project open, go to Tools->NuGet Package Manager->Package Manager Console and paste:
Install-Package vcpkg.D.src.vcpkg -Source "D:/src/vcpkg/scripts/buildsystems"
```
*Note: The generated NuGet package does not contain the actual libraries. It instead acts like a shortcut (or symlink) to the vcpkg install and will "automatically" update with any changes (install/remove) to the libraries. You do not need to regenerate or update the NuGet package.*
## Common Configuration
### `VcpkgEnabled` (Use Vcpkg)
This can be set to "false" to explicitly disable vcpkg integration for the project
### `VcpkgConfiguration` (Vcpkg Configuration)
If your configuration names are too complex for vcpkg to guess correctly, you can assign this property to `Release` or `Debug` to explicitly tell vcpkg what variant of libraries you want to consume.
### `VcpkgEnableManifest` (Use Vcpkg Manifest)
This property must be set to `true` in order to consume from a local `vcpkg.json` file. If set to `false`, any local `vcpkg.json` files will be ignored.
This currently defaults to `false`, but will default to `true` in the future.
### `VcpkgTriplet` (Triplet)
This property controls the triplet to consume libraries from, such as `x64-windows-static` or `arm64-windows`.
If this is not explicitly set, vcpkg will deduce the correct triplet based on your Visual Studio settings. vcpkg will only deduce triplets that use dynamic library linkage and dynamic CRT linkage; if you want static dependencies or to use the static CRT (`/MT`), you will need to set the triplet manually.
You can see the automatically deduced triplet by setting your MSBuild verbosity to Normal or higher:
> *Shortcut: Ctrl+Q "build and run"*
>
> Tools -> Options -> Projects and Solutions -> Build and Run -> MSBuild project build output verbosity
See also [Triplets](../triplets.md)
### `VcpkgHostTriplet` (Host Triplet)
This can be set to a custom triplet to use for resolving host dependencies.
If unset, this will default to the "native" triplet (x64-windows).
See also [Host Dependencies](../host-dependencies.md).
### `VcpkgInstalledDir` (Installed Directory)
This property defines the location vcpkg will install and consume libraries from.
In manifest mode, this defaults to `$(VcpkgManifestRoot)\vcpkg_installed\$(VcpkgTriplet)\`. In classic mode, this defaults to `$(VcpkgRoot)\installed\`.
## Manifest Mode Configuration
To use manifests (`vcpkg.json`) with MSBuild, first you need to use one of the integration methods above. Then, add a vcpkg.json above your project file (such as in the root of your source repository) and set the property `VcpkgEnableManifest` to `true`. You can set this property via the IDE in `Project Properties -> Vcpkg -> Use Vcpkg Manifest` (note: you may need to reload the IDE to see the vcpkg Property Page).
vcpkg will automatically run during your project's build and install any listed dependencies to `vcpkg_installed/$(VcpkgTriplet)/` adjacent to the `vcpkg.json` file; these libraries will then automatically be included in and linked to your MSBuild projects.
**Known issues**
* Visual Studio 2015 does not correctly track edits to the `vcpkg.json` and `vcpkg-configuration.json` files, and will not respond to changes unless a `.cpp` is edited.
<a id="vcpkg-additional-install-options"></a>
### `VcpkgAdditionalInstallOptions` (Additional Options)
When using a manifest, this option specifies additional command line flags to pass to the underlying vcpkg tool invocation. This can be used to access features that have not yet been exposed through another option.
### `VcpkgManifestInstall` (Install Vcpkg Dependencies)
This property can be set to `false` to disable automatic dependency restoration during project build. Dependencies must be manually restored via the vcpkg command line separately.

100
externals/vcpkg/docs/users/config-environment.md vendored Executable file
View File

@@ -0,0 +1,100 @@
## Environment and Configuration
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/config-environment.md).**
### Environment Variables
#### VCPKG_DOWNLOADS
This environment variable can be set to an existing directory to use for storing downloads instead of the internal
`downloads/` directory. It should always be set to an absolute path.
#### VCPKG_FEATURE_FLAGS
This environment variable can be set to a comma-separated list of off-by-default features in vcpkg. These features are
subject to change without notice and should be considered highly unstable.
There are no off-by-default feature flags at this time.
#### EDITOR
This environment variable can be set to the full path of an executable to be used for `vcpkg edit`. Please see
`vcpkg help edit` for command-specific help.
#### VCPKG_ROOT
This environment variable can be set to a directory to use as the root of the vcpkg instance. Note that mixing vcpkg
repo versions and executable versions can cause issues.
#### VCPKG_VISUAL_STUDIO_PATH
This environment variable can be set to the full path to a Visual Studio instance on the machine. This Visual Studio instance
will be used if the triplet does not override it via the [`VCPKG_VISUAL_STUDIO_PATH`](triplets.md#VCPKG_VISUAL_STUDIO_PATH) triplet setting.
Example: `D:\2017`
#### VCPKG_DEFAULT_TRIPLET
This environment variable can be set to a triplet name which will be used for unqualified triplet references in command lines.
#### VCPKG_DEFAULT_HOST_TRIPLET
This environment variable can be set to a triplet name which will be used for unqualified host port references in command lines and all host port references in dependency lists. See [the host-dependencies documentation](host-dependencies.md) for more information.
#### VCPKG_OVERLAY_PORTS
This environment variable allows users to override ports with alternate versions according to the
[ports overlay](../specifications/ports-overlay.md) specification. List paths to overlays using
the platform dependent PATH separator (Windows `;` | others `:`)
Example (Windows): `C:\custom-ports\boost;C:\custom-ports\sqlite3`
#### VCPKG_OVERLAY_TRIPLETS
This environment variable allows users to add directories to search for triplets.
[Example: overlay triplets](../examples/overlay-triplets-linux-dynamic.md).
List paths to overlays using the platform dependent PATH separator (Windows `;`, others `:`)
#### VCPKG_FORCE_SYSTEM_BINARIES
This environment variable, if set, suppresses the downloading of CMake and Ninja and forces the use of the system binaries.
#### VCPKG_FORCE_DOWNLOADED_BINARIES
This environment variable, if set, ignores the use of the system binaries and will always download and use the version defined by vcpkg.
#### VCPKG_KEEP_ENV_VARS
This environment variable can be set to a list of environment variables, separated by `;`, which will be propagated to
the build environment.
The values of the kept variables will not be tracked in package ABIs and will not cause rebuilds when they change. To
pass in environment variables that should cause rebuilds on change, see [`VCPKG_ENV_PASSTHROUGH`](triplets.md#VCPKG_ENV_PASSTHROUGH).
Example: `FOO_SDK_DIR;BAR_SDK_DIR`
#### VCPKG_MAX_CONCURRENCY
This environment variables limits the amount of concurrency requested by underlying buildsystems. If unspecified, this defaults to logical cores + 1.
#### VCPKG_DEFAULT_BINARY_CACHE
This environment variable redirects the default location to store binary packages. See [Binary Caching](binarycaching.md#configuration) for more details.
#### VCPKG_BINARY_SOURCES
This environment variable adds or removes binary sources. See [Binary Caching](binarycaching.md#configuration) for more details.
#### VCPKG_NUGET_REPOSITORY
This environment variable changes the metadata of produced NuGet packages. See [Binary Caching](binarycaching.md#configuration) for more details.
#### VCPKG_USE_NUGET_CACHE
This environment variable allows using NuGet's cache for every nuget-based binary source. See [Binary Caching](binarycaching.md#nuget-provider-configuration) for more details.
#### X_VCPKG_ASSET_SOURCES
> Note: This is an experimental feature and may change or be removed at any time
This environment variable allows using a private mirror for all SHA512-tagged assets. See [Asset Caching](assetcaching.md) for more details.

65
externals/vcpkg/docs/users/host-dependencies.md vendored Executable file
View File

@@ -0,0 +1,65 @@
# Host Dependencies
Tools used at build time by other ports to generate code or implement a custom build system can be packaged inside vcpkg.
## Consuming
When consuming a port as a tool, you must set the dependency's `"host"` field to true. For example:
```json
{
"name": "contoso-http-library",
"version-string": "1.0.0",
"description": "Contoso's http runtime library",
"dependencies": [
"contoso-core-library",
{
"name": "contoso-code-generator",
"host": true
},
{
"name": "contoso-build-system",
"host": true
}
]
}
```
In this case, the `contoso-code-generator` and `contoso-build-system` (including any transitive dependencies) will be built and installed for the host triplet before `contoso-http-library` is built.
>Note: Consumers must use `vcpkg.json` instead of `CONTROL` as their metadata format. You can easily convert an existing `CONTROL` file using `vcpkg format-manifest /path/to/CONTROL`.
Then, within the portfile of the consumer (`contoso-http-library` in the example), the CMake variable `CURRENT_HOST_INSTALLED_DIR` will be defined to `installed/<host-triplet>` and should be used to locate any required assets. In the example, `contoso-code-generator` might have installed `tools/contoso-code-generator/ccg.exe` which the consumer would add to its local path via
```cmake
# ports/contoso-http-library/portfile.cmake
vcpkg_add_to_path(${CURRENT_HOST_INSTALLED_DIR}/tools/contoso-code-generator)
```
## Specifying the Host Triplet
The default host triplets are chosen based on the host architecture and operating system, for example `x64-windows`, `x64-linux`, or `x64-osx`. They can be overridden via:
1. In CMake-based manifest mode, calling `set(VCPKG_HOST_TRIPLET "<triplet>" CACHE STRING "")` before the first `project()` directive
2. In MSBuild-based manifest mode, setting the `VcpkgHostTriplet` property
3. On the command line, via the flag `--host-triplet=...`
4. The `VCPKG_DEFAULT_HOST_TRIPLET` environment variable
## Producing
Producing a tool has no special requirements; tools should be authored as a standard port, following all the normal policies and practices. Notably, they should build against `TARGET_TRIPLET`, not `HOST_TRIPLET` within the context of their portfile.
If the current context is cross-compiling (`TARGET_TRIPLET` is not `HOST_TRIPLET`), then `VCPKG_CROSSCOMPILING` will be set to a truthy value.
```cmake
if(VCPKG_CROSSCOMPILING)
# This is a native build
else()
# This is a cross build
endif()
```
## Host-only ports
Some ports should only be depended upon via a host dependency; script ports and
tool ports are common examples. In this case, you can use the `"native"`
supports expression to describe this. This supports expression is true when
`VCPKG_CROSSCOMPILING` is false (implying that `TARGET_TRIPLET ==
HOST_TRIPLET`).

312
externals/vcpkg/docs/users/manifests.md vendored Executable file
View File

@@ -0,0 +1,312 @@
# Manifest Mode
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/manifests.md).**
vcpkg has two modes of consuming dependencies - classic mode and manifest mode.
In classic mode, vcpkg produces an "installed" tree, whose contents are changed by explicit calls to `vcpkg install` or
`vcpkg remove`. The installed tree is intended for consumption by any number of projects: for example, installing a
bunch of libraries and then using those libraries from Visual Studio, without additional configuration. Because the
installed tree is not associated with an individual project, it's similar to tools like `brew` or `apt`, except that the
installed tree is vcpkg-installation-local, rather than global to a system or user.
In manifest mode, an installed tree is associated with a particular project rather than the vcpkg installation. The set
of installed ports is controlled by editing the project's "manifest file", and the installed tree is placed in the
project directory or build directory. This mode acts more similarly to language package managers like Cargo, or npm. We
recommend using this manifest mode whenever possible, because it allows one to encode a project's dependencies
explicitly in a project file, rather than in the documentation, making your project much easier to consume.
Check out the [manifest cmake example](../examples/manifest-mode-cmake.md) for an example project using CMake and
manifest mode.
## Table of Contents
- [Simple Example Manifest](#simple-example-manifest)
- [Manifest Syntax Reference](#manifest-syntax-reference)
- [`"name"`](#name)
- [Version Fields](#version-fields)
- [`"description"`](#description)
- [`"builtin-baseline"`](#builtin-baseline)
- [`"dependencies"`](#dependencies)
- [`"name"`](#dependencies-name)
- [`"default-features"`](#dependencies-default-features)
- [`"features"`](#dependencies-features)
- [`"platform"`](#platform)
- [`"version>="`](#version-gt)
- [`"overrides"`](#overrides)
- [`"supports"`](#supports)
- [`"features"`](#features)
- [`"default-features"`](#default-features)
See also [the original specification](../specifications/manifests.md) for more low-level details.
## Simple Example Manifest
```json
{
"$schema": "https://raw.githubusercontent.com/microsoft/vcpkg/master/scripts/vcpkg.schema.json",
"name": "my-application",
"version": "0.15.2",
"dependencies": [
"boost-system",
{
"name": "cpprestsdk",
"default-features": false
},
"libxml2",
"yajl"
]
}
```
## Manifest Syntax Reference
A manifest is a JSON-formatted file named `vcpkg.json` which lies at the root of your project.
It contains all the information a person needs to know to get dependencies for your project,
as well as all the metadata about your project that a person who depends on you might be interested in.
Manifests follow strict JSON: they can't contain C++-style comments (`//`) nor trailing commas. However
you can use field names that start with `$` to write your comments in any object that has a well-defined set of keys.
These comment fields are not allowed in any objects which permit user-defined keys (such as `"features"`).
Each manifest contains a top level object with the fields documented below; the most important ones are
[`"name"`](#name), the [version fields](#version-fields), and [`"dependencies"`](#dependencies):
<a id="name"></a>
### `"name"`
This is the name of your project! It must be formatted in a way that vcpkg understands - in other words,
it must be lowercase alphabetic characters, digits, and hyphens, and it must not start nor end with a hyphen.
For example, `Boost.Asio` might be given the name `boost-asio`.
This is a required field.
### Version Fields
There are four version field options, depending on how the port orders its
releases.
* [`"version"`](versioning.md#version) - Generic, dot-separated numeric
sequence.
* [`"version-semver"`](versioning.md#version-semver) - [Semantic Version
2.0.0](https://semver.org/#semantic-versioning-specification-semver)
* [`"version-date"`](versioning.md#version-date) - Used for packages which do
not have numeric releases (for example, Live-at-HEAD). Matches `YYYY-MM-DD`
with optional trailing dot-separated numeric sequence.
* [`"version-string"`](versioning.md#version-string) - Used for packages that
don't have orderable versions. This should be rarely used, however all ports
created before the other version fields were introduced use this scheme.
Additionally, the optional `"port-version"` field is used to indicate revisions
to the port with the same upstream source version. For pure consumers, this
field should not be used.
See [versioning](versioning.md#version-schemes) for more details.
<a id="description"></a>
### `"description"`
This is where you describe your project. Give it a good description to help in searching for it!
This can be a single string, or it can be an array of strings;
in the latter case, the first string is treated as a summary,
while the remaining strings are treated as the full description.
<a id="builtin-baseline"></a>
### `"builtin-baseline"`
This field indicates the commit of vcpkg which provides global minimum version
information for your manifest. It is required for top-level manifest files using
versioning.
This is a convenience field that has the same semantic as replacing your default
registry in
[`vcpkg-configuration.json`](registries.md#configuration-default-registry).
See [versioning](versioning.md#builtin-baseline) for more semantic details.
<a id="dependencies"></a>
### `"dependencies"`
This field lists all the dependencies you'll need to build your library (as well as any your dependents might need,
if they were to use you). It's an array of strings and objects:
* A string dependency (e.g., `"dependencies": [ "zlib" ]`) is the simplest way one can depend on a library;
it means you don't depend on a single version, and don't need to write down any more information.
* On the other hand, an object dependency (e.g., `"dependencies": [ { "name": "zlib" } ]`)
allows you to add that extra information.
#### Example:
```json
"dependencies": [
{
"name": "arrow",
"default-features": false,
"features": [ "json" ]
},
"boost-asio",
"openssl",
{
"name": "picosha2",
"platform": "!windows"
}
]
```
<a id="dependencies-name"></a>
#### `"name"` Field
The name of the dependency. This follows the same restrictions as the [`"name"`](#name) property for a project.
<a id="dependencies-default-features"></a>
<a id="dependencies-features"></a>
#### `"features"` and `"default-features"` Fields
`"features"` is an array of feature names which tell you the set of features that the
dependencies need to have at a minimum,
while `"default-features"` is a boolean that tells vcpkg whether or not to
install the features the package author thinks should be "most common for most people to use".
For example, `ffmpeg` is a library which supports many, many audio and video codecs;
however, for your specific project, you may only need mp3 encoding.
Then, you might just ask for:
```json
{
"name": "ffmpeg",
"default-features": false,
"features": [ "mp3lame" ]
}
```
<a id="platform"></a>
#### `"platform"` Field
The `"platform"` field defines the platforms where the dependency should be installed - for example,
you might need to use sha256, and so you use platform primitives on Windows, but `picosha2` on non-Windows platforms.
```json
{
"name": "picosha2",
"platform": "!windows"
}
```
This is a string field which takes boolean expressions of the form `<identifier>`,
`!expression`, `expression { & expression & expression...}`, and `expression { | expression | expression...}`,
along with parentheses to denote precedence.
For example, a dependency that's only installed on the Windows OS, for the ARM64 architecture,
and on Linux on x64, would be written `(windows & arm64) | (linux & x64)`.
The common identifiers are:
- The operating system: `windows`, `uwp`, `linux`, `osx` (includes macOS), `android`, `emscripten`
- The architecture: `x86`, `x64`, `wasm32`, `arm64`, `arm` (includes both arm32 and arm64 due to backwards compatibility)
although one can define their own.
<a id="version-gt"></a>
#### `"version>="` Field
A minimum version constraint on the dependency.
This field specifies the minimum version of the dependency, optionally using a
`#N` suffix to denote port-version if non-zero.
See also [versioning](versioning.md#version-1) for more semantic details.
<a id="overrides"></a>
### `"overrides"`
This field pins exact versions for individual dependencies.
`"overrides"` from transitive manifests (i.e. from dependencies) are ignored.
See also [versioning](versioning.md#overrides) for more semantic details.
#### Example:
```json
"overrides": [
{
"name": "arrow", "version": "1.2.3", "port-version": 7
}
]
```
<a id="supports"></a>
### `"supports"`
If your project doesn't support common platforms, you can tell your users this with the `"supports"` field.
It uses the same platform expressions as [`"platform"`](#platform), from dependencies, as well as the
`"supports"` field of features.
For example, if your library doesn't support linux, you might write `{ "supports": "!linux" }`.
<a id="default-features"></a>
<a id="features"></a>
### `"features"` and `"default-features"`
The `"features"` field defines _your_ project's optional features, that others may either depend on or not.
It's an object, where the keys are the names of the features, and the values are objects describing the feature.
`"description"` is required,
and acts exactly like the [`"description"`](#description) field on the global package,
and `"dependencies"` are optional,
and again act exactly like the [`"dependencies"`](#dependencies) field on the global package.
There's also the `"supports"` field,
which again acts exactly like the [`"supports"`](#supports) field on the global package.
You also have control over which features are default, if a person doesn't ask for anything specific,
and that's the `"default-features"` field, which is an array of feature names.
#### Example:
```json
{
"name": "libdb",
"version": "1.0.0",
"description": [
"An example database library.",
"Optionally can build with CBOR, JSON, or CSV as backends."
],
"$default-features-explanation": "Users using this library transitively will get all backends automatically",
"default-features": [ "cbor", "csv", "json" ],
"features": {
"cbor": {
"description": "The CBOR backend",
"dependencies": [
{
"$explanation": [
"This is how you tell vcpkg that the cbor feature depends on the json feature of this package"
],
"name": "libdb",
"default-features": false,
"features": [ "json" ]
}
]
},
"csv": {
"description": "The CSV backend",
"dependencies": [
"fast-cpp-csv-parser"
]
},
"json": {
"description": "The JSON backend",
"dependencies": [
"jsoncons"
]
}
}
}
```

155
externals/vcpkg/docs/users/mingw.md vendored Executable file
View File

@@ -0,0 +1,155 @@
# Vcpkg and Mingw-w64
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/mingw.md).**
*MinGW is not tested as part of vcpkg repository's CI process, so regressions can occur as part of library updates. PRs improving support are welcome!*
## Table of Contents
- [Mingw-w64 community triplets](#mingw-w64-community-triplets)
- [Using Mingw-w64 natively on Windows](#mingw-native)
- [How to avoid mixing different installations](#how-to-avoid-mixing-different-installations)
- [Using Mingw-w64 to build Windows programs on other systems](#mingw-cross)
## Mingw-w64 community triplets
Vcpkg includes
[x64, x86, arm64 and arm community triplets](https://github.com/microsoft/vcpkg/tree/master/triplets/community)
for [Mingw-w64](http://mingw-w64.org/). They don't depend on Visual Studio and
can be used natively on Windows as well as for cross-compiling on
other operating systems. There are two variants of each triplet,
selecting between static and dynamic linking. The actual tools
(g++ etc.) are expected to be named with particular prefixes.
| architecture | vcpkg community triplets | tool name prefix |
|--------------|-----------------------------------------|----------------------|
| x64 | x64-mingw-dynamic, x64-mingw-static | x86_64-w64-mingw32- |
| x86 | x86-mingw-dynamic, x86-mingw-static | i686-w64-mingw32- |
| arm64 | arm64-mingw-dynamic, arm64-mingw-static | aarch64-w64-mingw32- |
| arm | arm-mingw-dynamic, arm-mingw-static | armv7-w64-mingw32- |
These triplets are not tested by continuous integration, so many ports
do not build, and even existing ports may break on port updates.
Because of this, community involvement is paramount!
- [Discussions](https://github.com/microsoft/vcpkg/discussions?discussions_q=mingw)
- [Open issues](https://github.com/microsoft/vcpkg/issues?q=is%3Aissue+is%3Aopen+mingw)
- [Open pull requests](https://github.com/microsoft/vcpkg/pulls?q=is%3Apr+is%3Aopen+mingw)
<a id="mingw-native"></a>
## Using Mingw-w64 natively on Windows
With [MSYS2](https://www.msys2.org/), it is possible to easily create
a full environment for building ports with Mingw-w64 on a Windows PC.
Note that for building software for native windows environments, you
must use a mingw subsystem of MSYS2, and install some packages
(with a specific prefix) for this subsystem.
| architecture | vcpkg triplets | subsystem | package prefix |
|--------------|-------------------------------------|-----------|-------------------|
| x64 | x64-mingw-dynamic, x64-mingw-static | mingw64 | mingw-w64-x86_64- |
| x86 | x86-mingw-dynamic, x86-mingw-static | mingw32 | mingw-w64-i686- |
After the basic installation of MSYS2, you will need to install a few
additional packages for software development, e.g. for x64:
```bash
pacman -S --needed git base-devel mingw-w64-x86_64-toolchain
```
The active subsystem is selected by running the MSYS2 MinGW app, or
changed in a running terminal by
```bash
source shell mingw64 # for x64, or "mingw32" for x86
```
The bootstrapping of vcpkg shall be done by running bootstrap-vcpkg.bat.
This will download the official vcpkg.exe.
```bash
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.bat
```
For building packages, you need to tell vcpkg that you want to use the
mingw triplet. This can be done in different ways. When Visual Studio
is not installed, you must also set the host triplet to mingw. This is
needed to resolve host dependencies. For convenience, you can use
environment variables to set both triplets:
```bash
export VCPKG_DEFAULT_TRIPLET=x64-mingw-dynamic
export VCPKG_DEFAULT_HOST_TRIPLET=x64-mingw-dynamic
```
Now you can test your setup:
```bash
./vcpkg install zlib
```
### How to avoid mixing different installations
[The MSYS2 project explicitly warns](https://www.msys2.org/wiki/MSYS2-introduction/#path)
that "mixing in programs from other MSYS2 installations, Cygwin installations,
compiler toolchains or even various other programs is not supported and will
probably break things in unexpected ways." For example, the proper passing of
command line arguments with quoting and escaping may fail.
But Vcpkg ports implicitly create MSYS2 installations, e.g. for `pkg-config`
and for various other build tools needed to deal with packages based on
autoconf. In particular, when ports prepend the directory of tools to the
`PATH` environment variable, this may change which tool with a particular
name is actually invoked, and how arguments are passed between tools.
To mitigate such issues when working with a full MSYS2 installation,
try to keep the directories of the msys subsystem (`/usr/bin`, `bin`)
out of the `PATH` environment variable as found by vcpkg. In bash, you
may modify the `PATH` just for a single call of vcpkg:
```bash
PATH="${PATH/:\/usr\/bin:\/bin:/:}" ./vcpkg install libpq
```
Alternatively, you may run vcpkg from a regular Command Prompt, after
adding *only* the desired mingw directory (e.g. `C:\msys64\mingw64\bin`)
to the `PATH`.
When using vcpkg for CI with standard images on Azure Pipelines, Github Actions
or similar, note that the default `PATH` might contain more directories
which create a mix of MSYS2 programs from different installations. You may
want to set the desired `PATH` manually, or remove directories which contain
`sh.exe`, `bash.exe`, `msys-2.0.dll` or `cygwin1.dll`.
<a id="mingw-cross"></a>
## Using Mingw-w64 to build Windows programs on other systems
You can use the vcpkg mingw community triplets with toolchains on
non-Windows computers to cross-compile software to be run on Windows.
Many Linux distributions offer such toolchains in optional packages
with a mingw-w64 [suffix](https://repology.org/projects/?search=-mingw-w64)
or [prefix](https://repology.org/projects/?search=mingw-w64-).
As an example, for Debian-based distributions, you would start with
this installation command for the x64 toolchain:
```
sudo apt-get install gcc-mingw-w64-x86-64 g++-mingw-w64-x86-64
```
Note that the packaged versions of Mingw-w64 toolchains on Linux distributions
might be older releases which lack some useful features or bug fixes.
An alternative independent toolchain is offered by [MXE](https://mxe.cc/).
For vcpkg bootstrapping, clone the github repository and run the
`bootstrap-vcpkg.sh` script:
```bash
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg install zlib:x64-mingw-dynamic
```

135
externals/vcpkg/docs/users/registries.md vendored Executable file
View File

@@ -0,0 +1,135 @@
# Using Registries
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/registries.md).**
There are two parts to using registries; this documents the use side of the
relationship. In order to learn more about creating registries for others to
use, please read [this documentation](../maintainers/registries.md).
## Table of Contents
- [Using Registries](#using-registries)
- [Table of Contents](#table-of-contents)
- [`vcpkg-configuration.json`](#vcpkg-configurationjson)
- [Registry Objects](#registry-objects)
- [Registry Objects: `"kind"`](#registry-objects-kind)
- [Registry Objects: `"baseline"`](#registry-objects-baseline)
- [Registry Objects: `"repository"`](#registry-objects-repository)
- [Registry Objects: `"path"`](#registry-objects-path)
- [Configuration: `"default-registry"`](#configuration-default-registry)
- [Configuration: `"registries"`](#configuration-registries)
- [Example Configuration File](#example-configuration-file)
- [Package Name Resolution](#package-name-resolution)
- [Versioning Support](#versioning-support)
## `vcpkg-configuration.json`
From a high level perspective, everything that a project needs to define
about registries is contained in the vcpkg configuration file. In classic
mode, the configuration file lies in the vcpkg root; for manifest mode,
the file must exist next to the project's `vcpkg.json` file.
This file is named `vcpkg-configuration.json`, and it's a simple top-level
object file.
### Registry Objects
Registries are defined in JSON as objects. They must contain at least the
`"kind"` and `"baseline"` fields, and additionally the different kinds of
registry will have their own way of defining where the registry can be found:
- git registries require the `"repository"` field
- filesystem registries require the `"path"` field
- built-in registries do not require a field, since there is only one
built-in registry.
#### Registry Objects: `"kind"`
The `"kind"` field must be a string:
- For git registries: `"git"`
- For filesystem registries: `"filesystem"`
- For the builtin registry: `"builtin"`
#### Registry Objects: `"baseline"`
The `"baseline"` field must be a string. For git registries and for the
built-in registry, it should be a 40-character commit ID.
For filesystem registries, it can be any string that the registry defines.
#### Registry Objects: `"repository"`
This should be a string, of any repository format that git understands:
- `"https://github.com/microsoft/vcpkg"`
- `"git@github.com:microsoft/vcpkg"`
- `"/dev/vcpkg-registry"`
#### Registry Objects: `"path"`
This should be a path; it can be either absolute or relative; relative paths
will be based at the directory the `vcpkg-configuration.json` lives in.
### Configuration: `"default-registry"`
The `"default-registry"` field should be a registry object. It defines
the registry that is used for all packages that are not claimed by any
package registries. It may also be `null`, in which case no packages that
are not claimed by package registries may be installed.
### Configuration: `"registries"`
The `"registries"` field should be an array of registry objects, each of
which additionally contain a `"packages"` field, which should be an array of
package names. These define the package registries, which are used for
the specific packages named by the `"packages"` field.
The `"packages"` fields of all the package registries must be disjoint.
### Example Configuration File
Let's assume that you have mirrored <https://github.com/microsoft/vcpkg> at
<https://git.example.com/vcpkg>: this will be your default registry.
Additionally, you want to use North Wind Trader's registry for their
beison and beicode libraries. The following `vcpkg-configuration.json`
will work:
```json
{
"default-registry": {
"kind": "git",
"repository": "https://internal/mirror/of/github.com/Microsoft/vcpkg",
"baseline": "eefee7408133f3a0fef711ef9c6a3677b7e06fd7"
},
"registries": [
{
"kind": "git",
"repository": "https://github.com/northwindtraders/vcpkg-registry",
"baseline": "dacf4de488094a384ca2c202b923ccc097956e0c",
"packages": [ "beicode", "beison" ]
}
]
}
```
## Package Name Resolution
The way package name resolution works in vcpkg is fairly distinct from many
package managers. It is very carefully designed to _never_ implicitly choose
the registry that a package is fetched from. Just from
`vcpkg-configuration.json`, one can tell exactly from which registry a
package definition will be fetched from.
The name resolution algorithm is as follows:
- If there is a package registry that claims the package name,
use that registry; otherwise
- If there is a default registry defined, use that registry; otherwise
- If the default registry is set to `null`, error out; otherwise
- use the built-in registry.
### Versioning Support
Versioning with custom registries works exactly as it does in the built-in
registry. You can read more about that in the [versioning documentation].
[versioning documentation]: versioning.md

92
externals/vcpkg/docs/users/selecting-library-features.md vendored Executable file
View File

@@ -0,0 +1,92 @@
# Selecting Library Features
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/selecting-library-features.md).**
## Installing a library
We will look at [llvm](https://llvm.org/) as an example. You could install it using:
```powershell
> vcpkg install llvm
```
or via a manifest with
```json
{
"dependencies": ["llvm"]
}
```
With llvm now installed, we can execute:
```powershell
> installed\x86-windows\bin\llc.exe --version
```
we see:
```powershell
Registered Targets:
x86 - 32-bit X86: Pentium-Pro and above
x86-64 - 64-bit X86: EM64T and AMD64
```
## Installing additional features
But [llvm supports many more targets](https://llvm.org/docs/GettingStarted.html#local-llvm-configuration), from ARM to SPARC to SystemZ.
However, clearly our current installation doesn't include ARM as a target;
thus, we need to learn how vcpkg allows us to install other LLVM targets.
The llvm port allows this via the "target-*" features.
If we do:
```powershell
> vcpkg search llvm
```
We can see:
```
llvm 10.0.0#6 The LLVM Compiler Infrastructure
llvm[clang] Build C Language Family Front-end.
llvm[clang-tools-extra] Build Clang tools.
...
llvm[target-all] Build with all backends.
llvm[target-amdgpu] Build with AMDGPU backend.
llvm[target-arm] Build with ARM backend.
...
```
We can install any of these targets by using the install-feature syntax:
```powershell
> vcpkg install llvm[target-arm] # Installs LLVM with the ARM target
```
```json
{
"dependencies": [{ "name": "llvm", "features": ["target-arm"] }]
}
```
## Opting out of default features
The llvm port includes a few default features that you as a user may not want: for example,
the `clang` feature is default, which means that `vcpkg install llvm` will also build and install clang.
If you are writing a compiler that uses LLVM as a backend,
you're likely not interested in installing clang as well,
and we can do that by disabling default features with the special `core` "feature":
```powershell
> vcpkg install llvm[core,target-arm] # removing the default-feature with "core" also removes all of the default targets you get
```
or in manifest files:
```json
{
"dependencies": [{
"name": "llvm",
"default-features": false,
"features": ["target-arm"]
}]
}
```
# Further reading
- The [Feature Packages](../specifications/feature-packages.md) specification was the initial design for features.

229
externals/vcpkg/docs/users/triplets.md vendored Executable file
View File

@@ -0,0 +1,229 @@
# Triplet Files
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/triplets.md).**
Triplet is a standard term used in cross compiling as a way to completely capture the target environment (cpu, os, compiler, runtime, etc) in a single convenient name.
In Vcpkg, we use triplets to describe an imaginary "target configuration set" for every library. Within a triplet, libraries are generally built with the same configuration, but it is not a requirement. For example, you could have one triplet that builds `openssl` statically and `zlib` dynamically, one that builds them both statically, and one that builds them both dynamically (all for the same target OS and architecture). A single build will consume files from a single triplet.
We currently provide many triplets by default (run `vcpkg help triplet`). However, you can easily customize or add your own by copying a built-in triplet from the `triplets\` directory into a project local location. Then, use `--overlay-triplets=` (or equivalent such as [`$VCPKG_OVERLAY_TRIPLETS`](config-environment.md#vcpkg_overlay_triplets), [CMake `VCPKG_OVERLAY_TRIPLETS`](buildsystems/cmake-integration.md#vcpkg_overlay_triplets), or [MSBuild Additional Options](buildsystems/msbuild-integration.md#vcpkg-additional-install-options)) to add that directory to vcpkg. See our [overlay triplets example](../examples/overlay-triplets-linux-dynamic.md) for a more detailed walkthrough.
To change the triplet used by your project, you can pass `--triplet=<triplet>` on the command line or see our [Buildsystem-Specific Documentation](buildsystems/integration.md).
## Community triplets
Triplets contained in the `triplets\community` folder are not tested by continuous integration, but are commonly requested by the community.
Because we do not have continuous coverage, port updates may break compatibility with community triplets. Because of this, community involvement is paramount!
We will gladly accept and review contributions that aim to solve issues with these triplets.
### Usage
Community Triplets are enabled by default, when using a community triplet a message like the following one will be printed during a package install:
```no-highlight
-- Using community triplet x86-uwp. This triplet configuration is not guaranteed to succeed.
-- [COMMUNITY] Loading triplet configuration from: D:\src\viromer\vcpkg\triplets\community\x86-uwp.cmake
```
## Variables
### VCPKG_TARGET_ARCHITECTURE
Specifies the target machine architecture.
Valid options are `x86`, `x64`, `arm`, `arm64` and `wasm32`.
### VCPKG_CRT_LINKAGE
Specifies the desired CRT linkage (for MSVC).
Valid options are `dynamic` and `static`.
### VCPKG_LIBRARY_LINKAGE
Specifies the preferred library linkage.
Valid options are `dynamic` and `static`. Note that libraries can ignore this setting if they do not support the preferred linkage type.
### VCPKG_BUILD_TYPE
You can set this value to `release` to only build release versions of the ports. By default this value is empty and release and debug versions of a port are built.
### VCPKG_CMAKE_SYSTEM_NAME
Specifies the target platform.
Valid options include any CMake system name, such as:
- Empty (Windows Desktop for legacy reasons)
- `WindowsStore` (Universal Windows Platform)
- `MinGW` (Minimalist GNU for Windows)
- `Darwin` (Mac OSX)
- `iOS` (iOS)
- `Linux` (Linux)
- `Emscripten` (WebAssembly)
### VCPKG_CMAKE_SYSTEM_VERSION
Specifies the target platform system version.
This field is optional and, if present, will be passed into the build as `CMAKE_SYSTEM_VERSION`.
See also the CMake documentation for `CMAKE_SYSTEM_VERSION`: https://cmake.org/cmake/help/latest/variable/CMAKE_SYSTEM_VERSION.html.
<a name="VCPKG_CHAINLOAD_TOOLCHAIN_FILE"></a>
### VCPKG_CHAINLOAD_TOOLCHAIN_FILE
Specifies an alternate CMake Toolchain file to use.
This (if set) will override all other compiler detection logic. By default, a toolchain file is selected from `scripts/toolchains/` appropriate to the platform.
See also the CMake documentation for toolchain files: https://cmake.org/cmake/help/v3.11/manual/cmake-toolchains.7.html.
### VCPKG_CXX_FLAGS
Sets additional compiler flags to be used when not using `VCPKG_CHAINLOAD_TOOLCHAIN_FILE`.
This option also has forms for configuration-specific and C flags:
- `VCPKG_CXX_FLAGS`
- `VCPKG_CXX_FLAGS_DEBUG`
- `VCPKG_CXX_FLAGS_RELEASE`
- `VCPKG_C_FLAGS`
- `VCPKG_C_FLAGS_DEBUG`
- `VCPKG_C_FLAGS_RELEASE`
### VCPKG_LINKER_FLAGS
Sets additional linker flags to be used while building dynamic libraries and
executables in the absence of `VCPKG_CHAINLOAD_TOOLCHAIN_FILE`.
This option also has forms for configuration-specific flags:
- `VCPKG_LINKER_FLAGS`
- `VCPKG_LINKER_FLAGS_DEBUG`
- `VCPKG_LINKER_FLAGS_RELEASE`
### VCPKG_CMAKE_CONFIGURE_OPTIONS
Set additional CMake configure options that are appended to the configure command (in [`vcpkg_cmake_configure`](../maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md)).
This field is optional.
Also available as build-type specific `VCPKG_CMAKE_CONFIGURE_OPTIONS_DEBUG` and `VCPKG_CMAKE_CONFIGURE_OPTIONS_RELEASE` variables.
### VCPKG_MAKE_CONFIGURE_OPTIONS
Set additional automake / autoconf configure options that are appended to the configure command (in [`vcpkg_configure_make`](../maintainers/vcpkg_configure_make.md)).
This field is optional.
For example, to skip certain libtool checks that may errantly fail:
```cmake
set(VCPKG_MAKE_CONFIGURE_OPTIONS "lt_cv_deplibs_check_method=pass_all")
```
Also available as build-type specific `VCPKG_MAKE_CONFIGURE_OPTIONS_DEBUG` and `VCPKG_MAKE_CONFIGURE_OPTIONS_RELEASE` variables.
<a name="VCPKG_DEP_INFO_OVERRIDE_VARS"></a>
### VCPKG_DEP_INFO_OVERRIDE_VARS
Replaces the default computed list of triplet "Supports" terms.
This option (if set) will override the default set of terms used for qualified dependency resolution and "Supports" field evaluation.
See the [`"supports"`](../maintainers/manifest-files.md#supports) manifest file field documentation for more details.
> Implementers' Note: this list is extracted via the `vcpkg_get_dep_info` mechanism.
### VCPKG_DISABLE_COMPILER_TRACKING
When this option is set to (true|1|on), the compiler is ignored in the abi tracking.
## Windows Variables
<a name="VCPKG_ENV_PASSTHROUGH"></a>
### VCPKG_ENV_PASSTHROUGH
Instructs vcpkg to allow additional environment variables into the build process.
On Windows, vcpkg builds packages in a special clean environment that is isolated from the current command prompt to
ensure build reliability and consistency. This triplet option can be set to a list of additional environment variables
that will be added to the clean environment. The values of these environment variables will be hashed into the package
abi -- to pass through environment variables without abi tracking, see `VCPKG_ENV_PASSTHROUGH_UNTRACKED`.
See also the `vcpkg env` command for how you can inspect the precise environment that will be used.
> Implementers' Note: this list is extracted via the `vcpkg_get_tags` mechanism.
### VCPKG_ENV_PASSTHROUGH_UNTRACKED
Instructs vcpkg to allow additional environment variables into the build process without abi tracking.
See `VCPKG_ENV_PASSTHROUGH`.
<a name="VCPKG_VISUAL_STUDIO_PATH"></a>
### VCPKG_VISUAL_STUDIO_PATH
Specifies the Visual Studio installation to use.
To select the precise combination of Visual Studio instance and toolset version, we walk through the following algorithm:
1. Determine the setting for `VCPKG_VISUAL_STUDIO_PATH` from the triplet, or the environment variable `VCPKG_VISUAL_STUDIO_PATH`, or consider it unset
2. Determine the setting for `VCPKG_PLATFORM_TOOLSET` from the triplet or consider it unset
3. Gather a list of all pairs of Visual Studio Instances with all toolsets available in those instances
1. This is ordered first by instance type (Stable, Prerelease, Legacy) and then by toolset version (v142, v141, v140)
4. Filter the list based on the settings for `VCPKG_VISUAL_STUDIO_PATH` and `VCPKG_PLATFORM_TOOLSET`.
5. Select the best remaining option
The path should be absolute, formatted with backslashes, and have no trailing slash:
```cmake
set(VCPKG_VISUAL_STUDIO_PATH "C:\\Program Files (x86)\\Microsoft Visual Studio\\Preview\\Community")
```
### VCPKG_PLATFORM_TOOLSET
Specifies the VS-based C/C++ compiler toolchain to use.
See [`VCPKG_VISUAL_STUDIO_PATH`](#VCPKG_VISUAL_STUDIO_PATH) for the full selection algorithm.
Valid settings:
* The Visual Studio 2019 platform toolset is `v142`.
* The Visual Studio 2017 platform toolset is `v141`.
* The Visual Studio 2015 platform toolset is `v140`.
### VCPKG_PLATFORM_TOOLSET_VERSION
Specifies the detailed MSVC C/C++ compiler toolchain to use.
By default, [`VCPKG_PLATFORM_TOOLSET`] always chooses the latest installed minor version of the selected toolset.
If you need more granularity, you can use this variable.
Valid values are, for example, `14.25` or `14.27.29110`.
### VCPKG_LOAD_VCVARS_ENV
If `VCPKG_CHAINLOAD_TOOLCHAIN_FILE` is used, VCPKG will not setup the Visual Studio environment.
Setting `VCPKG_LOAD_VCVARS_ENV` to (true|1|on) changes this behavior so that the Visual Studio environment is setup following the same rules as if `VCPKG_CHAINLOAD_TOOLCHAIN_FILE` was not set.
## MacOS Variables
### VCPKG_INSTALL_NAME_DIR
Sets the install name used when building macOS dynamic libraries. Default value is `@rpath`. See the CMake documentation for [CMAKE_INSTALL_NAME_DIR](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_NAME_DIR.html) for more information.
### VCPKG_OSX_DEPLOYMENT_TARGET
Sets the minimum macOS version for compiled binaries. This also changes what versions of the macOS platform SDK that CMake will search for. See the CMake documentation for [CMAKE_OSX_DEPLOYMENT_TARGET](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_DEPLOYMENT_TARGET.html) for more information.
### VCPKG_OSX_SYSROOT
Set the name or path of the macOS platform SDK that will be used by CMake. See the CMake documentation for [CMAKE_OSX_SYSROOT](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_SYSROOT.html) for more information.
### VCPKG_OSX_ARCHITECTURES
Set the macOS / iOS target architecture which will be used by CMake. See the CMake documentation for [CMAKE_OSX_ARCHITECTURES](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_ARCHITECTURES.html) for more information.
## Per-port customization
The CMake Macro `PORT` will be set when interpreting the triplet file and can be used to change settings (such as `VCPKG_LIBRARY_LINKAGE`) on a per-port basis.
Example:
```cmake
set(VCPKG_LIBRARY_LINKAGE static)
if(PORT MATCHES "qt5-")
set(VCPKG_LIBRARY_LINKAGE dynamic)
endif()
```
This will build all the `qt5-*` libraries as DLLs, but every other library as a static library.
For an example in a real project, see https://github.com/Intelight/vcpkg/blob/master/triplets/x86-windows-mixed.cmake.
## Additional Remarks
The default triplet when running any vcpkg command is `%VCPKG_DEFAULT_TRIPLET%` or a platform-specific choice if that environment variable is undefined.
- Windows: `x86-windows`
- Linux: `x64-linux`
- OSX: `x64-osx`
We recommend using a systematic naming scheme when creating new triplets. The Android toolchain naming scheme is a good source of inspiration: https://developer.android.com/ndk/guides/standalone_toolchain.html.
## Android triplets
See [android.md](android.md)
## Mingw-w64 triplets
See [mingw.md](mingw.md)

134
externals/vcpkg/docs/users/versioning.implementation-details.md vendored Executable file
View File

@@ -0,0 +1,134 @@
# Versioning: Implementation details
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/versioning.implementation-details.md).**
## Contents
* [Minimum versioning](#minimum-versioning)
* [Constraint resolution](#constraint-resolution)
* [Acquiring port versions](#acquiring-port-versions)
### Minimum versioning
Vcpkg uses a minimal selection approach to versioning, inspired by the one [used by Go](https://research.swtch.com/vgo-mvs). But modified in some ways:
* Always starts from a fresh install, eliminates the need for upgrade/downgrade operations.
* Allow unconstrained dependencies by introducing baselines.
The minimal selection principle, however, stays the same. Given a set of constraints, vcpkg will use the "oldest" possible versions of packages that can satisfy all the constraints.
Using a minimum version approach has the following advantages:
* Is predictable and easy to understand.
* User controls when upgrades happen, as in, no upgrades are performed automatically when a new version is released.
* Avoids using a SAT solver.
To give an example, consider the following package graph:
```
(A 1.0) -> (B 1.0)
(A 1.1) -> (B 1.0)
-> (C 3.0)
(A 1.2) -> (B 2.0)
-> (C 3.0)
(C 2.0)
```
And the following manifest:
```
{
"name": "example",
"version": "1.0.0",
"dependencies": [
{ "name": "A", "version>=": "1.1" },
{ "name": "C", "version>=": "2.0" }
],
"builtin-baseline": "<some git commit with A's baseline at 1.0>"
}
```
After accounting for transitive dependencies we have the following set of constraints:
* A >= 1.1
* B >= 1.0
* C >= 3.0
* C >= 2.0
Since vcpkg has to satisfy all the constraints, the set of installed packages becomes:
* `A 1.1`, even when `A 1.2` exists, there are no constraints higher than `1.1` so vcpkg selects the minimum version possible.
* `B 1.0`, transitively required by `A 1.1`.
* `C 3.0`, upgraded by the transitive constraint added by `B 1.0` in order to satisfy version constraints.
## Constraint resolution
Given a manifest with a set of versioned dependencies, vcpkg will attempt to calculate a package installation plan that satisfies all the constraints.
Version constraints come in the following flavors:
* **Declared constraints**: Constraints declared explicitly in the top-level manifest using `version>=`.
* **Baseline constraints**: Constraints added implicitly by the `builtin-baseline`.
* **Transitive constraints**: Constraints added indirectly by dependencies of your dependencies.
* **Overridden constraints**: Constraints overridden in the top-level manifest using `overrides` declarations.
To compute an installation plan, vcpkg follows roughly these steps:
* Add all top-level constraints to the plan.
* Recursively add transitive constraints to the plan.
* Each time a new package is added to the plan, also add its baseline constraint to the plan.
* Each time a constraint is added:
* If an override exists for the package
* Select the version in the override.
* Otherwise:
* If there is no previous version selected.
* Select the minimal version that satisfies the constraint.
* If there is a previous version selected:
* If the versioning scheme of the new constraint does not match that of the previously selected version:
* Add a version conflict.
* If the constraint's version is not comparable to the previously selected version. For example, comparing "version-string: apple" to "version-string: orange":
* Add a version conflict.
* If the constraints version is higher than the previously selected version:
* Select the highest version.
* Otherwise:
* Keep the previous selection.
* Review the plan:
* If there are no conflicts
* Install the selected packages
* Otherwise:
* Report the conflicts to the user
## Acquiring port versions
Although the concept of package versions has always been present in vcpkg, the concept of version constraints has been not.
With the introduction of versioning constraints, it is now possible that a package depends on a port version that does not match the one available locally. This raises a problem as vcpkg needs to know how to acquire the port files for the requested version.
To solve this problem, a new set of metadata files was introduced. These files are located in the `versions/` directory at the root level of the vcpkg repository.
The `versions/` directory, will contain JSON files for each one of the ports available in the registry. Each file will list all the versions available for a package and contain a Git tree-ish object that vcpkg can check out to obtain that version's portfiles.
Example: `zlib.json`
```
{
"versions": [
{
"git-tree": "2dfc991c739ab9f2605c2ad91a58a7982eb15687",
"version-string": "1.2.11",
"port-version": 9
},
...
{
"git-tree": "a516e5ee220c8250f21821077d0e3dd517f02631",
"version-string": "1.2.10",
"port-version": 0
},
{
"git-tree": "3309ec82cd96d752ff890c441cb20ef49b52bf94",
"version-string": "1.2.8",
"port-version": 0
}
]
}
```
For each port, its corresponding versions file should be located in `versions/{first letter of port name}-/{port name}.json`. For example, zlib's version file will be located in `versions/z-/zlib.json`. Aside from port version files, the current baseline file is located in `versions/baseline.json`.

188
externals/vcpkg/docs/users/versioning.md vendored Executable file
View File

@@ -0,0 +1,188 @@
# Versioning
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/versioning.md).**
Versioning allows you to deterministically control the precise revisions of dependencies used by
your project from within your manifest file.
See our guide to [getting started with versioning](../examples/versioning.getting-started.md).
## Contents
* [Version schemes](#version-schemes)
* [`version`](#version)
* [`version-semver`](#version-semver)
* [`version-date`](#version-date)
* [`version-string`](#version-string)
* [Version constraints](#version-constraints)
## Version schemes
Ports in vcpkg should attempt to follow the versioning conventions used by the package's authors. For that reason, when declaring a package's version the appropriate scheme should be used.
Each versioning scheme defines its own rules on what is a valid version string and more importantly the rules for how to sort versions using the same scheme.
The versioning schemes understood by vcpkg are:
Manifest property | Versioning scheme
------------------|------------------------------------
`version` | For dot-separated numeric versions
`version-semver` | For SemVer compliant versions
`version-date` | For dates in the format YYYY-MM-DD
`version-string` | For arbitrary strings
A manifest must contain only one version declaration.
_NOTE: By design, vcpkg does not compare versions that use different schemes. For example, a package
that has a `version-string: 7.1.3` cannot be compared with the same package using `version: 7.1.4`, even if the
conversion seems obvious._
#### `version`
Accepts version strings that follow a relaxed, dot-separated-, semver-like scheme.
The version is logically composed of dot-separated (`.`) numeric sections. Each section must contain an integer positive number with no leading zeroes.
The regex pattern for this versioning scheme is: `(0|[1-9]\d*)(\.(0|[1-9]\d*))*`
_Sorting behavior_: When comparing two versions, each section is compared from left to right by their numeric value, until the first difference is found. A version with the smallest set of sections takes precedence over another with a larger set of sections, given that all their preceding sections compare equally.
Example:
`0` < `0.1` < `0.1.0` < `1` < `1.0.0` < `1.0.1` < `1.1`< `2.0.0`
#### `version-semver`
Accepts version strings that follow semantic versioning conventions as described in the [semantic versioning specification](https://semver.org/#semantic-versioning-specification-semver).
_Sorting behavior_: Strings are sorted following the rules described in the semantic versioning specification.
Example:
`1.0.0-1` < `1.0.0-alpha` < `1.0.0-beta` < `1.0.0` < `1.0.1` < `1.1.0`
#### `version-date`
Accepts version strings that can be parsed to a date following the ISO-8601 format `YYYY-MM-DD`. Disambiguation identifiers are allowed in the form of dot-separated-, positive-, integer-numbers with no leading zeroes.
This is the recommended versioning scheme for "Live at HEAD" libraries that don't have established release versions.
The regex pattern for this versioning scheme is: `\d{4}-\d{2}-\d{2}(\.(0|[1-9]\d*))*`
_Sorting behavior_: Strings are sorted first by their date part, then by numeric comparison of their disambiguation identifiers. Disambiguation identifiers follow the rules of the relaxed (`version`) scheme.
Examples:
`2021-01-01` < `2021-01-01.1` < `2021-02-01.1.2` < `2021-02-01.1.3` < `2021-02-01`
#### `version-string`
For packages using version strings that do not fit any of the other schemes, it accepts most arbitrary strings. The `#` which is used to denote port versions is disallowed.
_Sorting behavior_: No sorting is attempted on the version string itself. However, if the strings match exactly, their port versions can be compared and sorted.
Examples:
* `apple` <> `orange` <> `orange.2` <> `orange2`
* `watermelon#0`< `watermelon#1`
#### `port-version`
A positive integer value that increases each time a vcpkg-specific change is made to the port.
The rules for port versions are:
* Start at 0 for the original version of the port,
* increase by 1 each time a vcpkg-specific change is made to the port that does not increase the version of the package,
* and reset to 0 each time the version of the package is updated.
_NOTE: Whenever vcpkg output a version it follows the format `<version>#<port version>`. For example `1.2.0#2` means version `1.2.0` port version `2`. When the port version is `0` the `#0` suffix is omitted (`1.2.0` implies version `1.2.0` port version `0`)._
_Sorting behavior_: If two versions compare equally, their port versions are compared by their numeric value, lower port versions take precedence.
Examples:
* `1.2.0` < `1.2.0#1` < `1.2.0#2` < `1.2.0#10`
* `2021-01-01#20` < `2021-01-01.1`
* `windows#7` < `windows#8`
## Version constraints
### `builtin-baseline`
Accepts a Git commit ID. vcpkg will try to find a baseline file in the given
commit ID and use that to set the baseline versions (lower bounds) of all
dependencies.
Baselines provide stability and ease of development for top-level manifest
files. They are not considered from ports consumed as a dependency. If a minimum
version constraint is required during transitive version resolution, the port
should use `version>=`.
Example:
```json
{
"name": "project",
"version": "1.0.0",
"dependencies": ["zlib", "fmt"],
"builtin-baseline":"9fd3bd594f41afb8747e20f6ac9619f26f333cbe"
}
```
You can get the current commit of your vcpkg instance either by adding an empty
`"builtin-baseline"` field, installing, and examining the error message or by
running `git rev-parse HEAD` in the root of the vcpkg instance.
When resolving version constraints for a package, vcpkg will look for a baseline
version by looking at the baseline file in the given commit ID. If the given
commit ID doesn't have a `versions/baseline.json` file or if the baseline file
exists but it does not declare a baseline version for the package the invocation
will fail.
This field is a convenience field that has the same semantic as replacing your
default registry in
[`vcpkg-configuration.json`](registries.md#configuration-default-registry).
```json
{
"default-registry": {
"kind": "builtin",
"baseline": "<baseline>"
}
}
```
### `version>=`
Expresses a minimum version requirement, `version>=` declarations put a lower boundary on the versions that can be used to satisfy a dependency.
**Note: Vcpkg selects the lowest version that matches all constraints, so a less-than constraint is not required.**
Example:
```json
{
"name": "project",
"version-semver": "1.0.0",
"dependencies": [
{ "name": "zlib", "version>=": "1.2.11#9" },
{ "name": "fmt", "version>=": "7.1.3#1" }
],
"builtin-baseline":"3426db05b996481ca31e95fff3734cf23e0f51bc"
}
```
As part of a version constraint declaration, a port version can be specified by adding the suffix `#<port-version>`, in the previous example `1.2.11#9` refers to version `1.2.11` port version `9`.
### `overrides`
Declaring an override forces vcpkg to ignore all other version constraints and use the version specified in the override. This is useful for pinning exact versions and for resolving version conflicts.
Overrides are declared as an array of package version declarations.
For an override to take effect, the overridden package must form part of the dependency graph. That means that a dependency must be declared either by the top-level manifest or be part of a transitive dependency.
```json
{
"name": "project",
"version-semver": "1.0.0",
"dependencies": [
{ "name": "zlib", "version>=": "1.2.11#9" },
"fmt"
],
"builtin-baseline":"3426db05b996481ca31e95fff3734cf23e0f51bc",
"overrides": [
{ "name": "fmt", "version": "6.0.0" }
]
}
```
## See Also
* The [implementation details](versioning.implementation-details.md)
* The [original specification](../specifications/versioning.md)