early-access version 2853

externals/vcpkg/docs/examples/installing-and-using-packages.md

@@ -0,0 +1,182 @@
+## Installing and Using Packages Example: SQLite
+
+_Note: this old example uses Classic Mode, but most developers will be happier with Manifest Mode. See [Manifest Mode: CMake Example](manifest-mode-cmake.md) for an example of converting to Manifest Mode._
+
+  - [Step 1: Install](#install)
+  - [Step 2: Use](#use)
+    - [VS/MSBuild Project (User-wide integration)](#msbuild)
+    - [CMake (Toolchain file)](#cmake)
+    - [Other integration options](../users/buildsystems/integration.md)
+
+---
+<a name="install"></a>
+## Step 1: Install
+
+First, we need to know what name [SQLite](https://sqlite.org) goes by in the ports tree. To do that, we'll run the `search` command and inspect the output:
+```no-highlight
+PS D:\src\vcpkg> .\vcpkg search sqlite
+libodb-sqlite        2.4.0            Sqlite support for the ODB ORM library
+sqlite3              3.32.1           SQLite is a software library that implements a se...
+
+If your library is not listed, please open an issue at:
+    https://github.com/Microsoft/vcpkg/issues
+```
+Looking at the list, we can see that the port is named "sqlite3". You can also run the `search` command without arguments to see the full list of packages.
+
+Installing is then as simple as using the `install` command.
+```no-highlight
+PS D:\src\vcpkg> .\vcpkg install sqlite3
+Computing installation plan...
+The following packages will be built and installed:
+    sqlite3[core]:x86-windows
+Starting package 1/1: sqlite3:x86-windows
+Building package sqlite3[core]:x86-windows...
+-- Downloading https://sqlite.org/2020/sqlite-amalgamation-3320100.zip...
+-- Extracting source C:/src/vcpkg/downloads/sqlite-amalgamation-3320100.zip
+-- Applying patch fix-arm-uwp.patch
+-- Using source at C:/src/vcpkg/buildtrees/sqlite3/src/3320100-15aeda126a.clean
+-- Configuring x86-windows
+-- Building x86-windows-dbg
+-- Building x86-windows-rel
+-- Performing post-build validation
+-- Performing post-build validation done
+Building package sqlite3[core]:x86-windows... done
+Installing package sqlite3[core]:x86-windows...
+Installing package sqlite3[core]:x86-windows... done
+Elapsed time for package sqlite3:x86-windows: 12 s
+
+Total elapsed time: 12.04 s
+
+The package sqlite3:x86-windows provides CMake targets:
+
+    find_package(unofficial-sqlite3 CONFIG REQUIRED)
+    target_link_libraries(main PRIVATE unofficial::sqlite3::sqlite3))
+
+```
+
+We can check that sqlite3 was successfully installed for x86 Windows desktop by running the `list` command.
+```no-highlight
+PS D:\src\vcpkg> .\vcpkg list
+sqlite3:x86-windows         3.32.1           SQLite is a software library that implements a se...
+```
+
+To install for other architectures and platforms such as Universal Windows Platform or x64 Desktop, you can suffix the package name with `:<target>`.
+```no-highlight
+PS D:\src\vcpkg> .\vcpkg install sqlite3:x86-uwp zlib:x64-windows
+```
+
+See `.\vcpkg help triplet` for all supported targets.
+
+---
+<a name="use"></a>
+## Step 2: Use
+<a name="msbuild"></a>
+#### VS/MSBuild Project (User-wide integration)
+
+The recommended and most productive way to use vcpkg is via user-wide integration, making the system available for all projects you build. The user-wide integration will prompt for administrator access the first time it is used on a given machine, but afterwards is no longer required and the integration is configured on a per-user basis.
+```no-highlight
+PS D:\src\vcpkg> .\vcpkg integrate install
+Applied user-wide integration for this vcpkg root.
+
+All C++ projects can now #include any installed libraries.
+Linking will be handled automatically.
+Installing new libraries will make them instantly available.
+```
+*Note: You will need to restart Visual Studio or perform a Build to update intellisense with the changes.* 
+
+You can now simply use File -> New Project in Visual Studio and the library will be automatically available. For SQLite, you can try out their [C/C++ sample](https://sqlite.org/quickstart.html).
+
+To remove the integration for your user, you can use `.\vcpkg integrate remove`.
+
+<a name="cmake"></a>
+#### CMake (Toolchain File)
+
+The best way to use installed libraries with cmake is via the toolchain file `scripts\buildsystems\vcpkg.cmake`. To use this file, you simply need to add it onto your CMake command line as:  
+`-DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake`.
+
+If you are using CMake through Open Folder with Visual Studio you can define `CMAKE_TOOLCHAIN_FILE` by adding a "variables" section to each of your `CMakeSettings.json` configurations:
+
+```json
+{
+  "configurations": [{
+    "name": "x86-Debug",
+    "generator": "Visual Studio 15 2017",
+    "configurationType" : "Debug",
+    "buildRoot":  "${env.LOCALAPPDATA}\\CMakeBuild\\${workspaceHash}\\build\\${name}",
+    "cmakeCommandArgs": "",
+    "buildCommandArgs": "-m -v:minimal",
+    "variables": [{
+      "name": "CMAKE_TOOLCHAIN_FILE",
+      "value": "D:\\src\\vcpkg\\scripts\\buildsystems\\vcpkg.cmake"
+    }]
+  }]
+}
+```
+*Note: It might be necessary to delete the CMake cache folder of each modified configuration, to force a full regeneration. In the `CMake` menu, under `Cache (<configuration name>)` you'll find `Delete Cache Folders`.*
+
+Now let's make a simple CMake project with a main file.
+```cmake
+# CMakeLists.txt
+cmake_minimum_required(VERSION 3.0)
+project(test)
+
+find_package(unofficial-sqlite3 CONFIG REQUIRED)
+
+add_executable(main main.cpp)
+
+target_link_libraries(main PRIVATE unofficial::sqlite3::sqlite3)
+```
+```cpp
+// main.cpp
+#include <sqlite3.h>
+#include <stdio.h>
+
+int main()
+{
+    printf("%s\n", sqlite3_libversion());
+    return 0;
+}
+```
+
+Then, we build our project in the normal CMake way:
+```no-highlight
+PS D:\src\cmake-test> mkdir build 
+PS D:\src\cmake-test> cd build
+PS D:\src\cmake-test\build> cmake .. "-DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake"
+    // omitted CMake output here //
+-- Build files have been written to: D:/src/cmake-test/build
+PS D:\src\cmake-test\build> cmake --build .
+    // omitted MSBuild output here //
+Build succeeded.
+    0 Warning(s)
+    0 Error(s)
+
+Time Elapsed 00:00:02.38
+PS D:\src\cmake-test\build> .\Debug\main.exe
+3.15.0
+```
+
+*Note: The correct sqlite3.dll is automatically copied to the output folder when building for x86-windows. You will need to distribute this along with your application.*
+
+##### Handling libraries without native cmake support
+
+Unlike other platforms, we do not automatically add the `include\` directory to your compilation line by default. If you're using a library that does not provide CMake integration, you will need to explicitly search for the files and add them yourself using [`find_path()`][1] and [`find_library()`][2].
+
+```cmake
+# To find and use catch
+find_path(CATCH_INCLUDE_DIR catch.hpp)
+include_directories(${CATCH_INCLUDE_DIR})
+
+# To find and use azure-storage-cpp
+find_path(WASTORAGE_INCLUDE_DIR was/blob.h)
+find_library(WASTORAGE_LIBRARY wastorage)
+include_directories(${WASTORAGE_INCLUDE_DIR})
+link_libraries(${WASTORAGE_LIBRARY})
+
+# Note that we recommend using the target-specific directives for a cleaner cmake:
+#     target_include_directories(main ${LIBRARY})
+#     target_link_libraries(main PRIVATE ${LIBRARY})
+```
+
+[1]: https://cmake.org/cmake/help/latest/command/find_path.html
+[2]: https://cmake.org/cmake/help/latest/command/find_library.html

externals/vcpkg/docs/examples/manifest-mode-cmake.md

@@ -0,0 +1,200 @@
+# Manifest Mode: CMake Example
+
+We would like to add [vcpkg manifest support](../users/manifests.md) to an existing cmake project!
+Let's create a simple project that prints the fibonacci sequence up to a certain number,
+using some common dependencies.
+
+## Initial Layout
+
+Let's create the following file layout:
+
+```no-highlight
+fibo/
+  src/
+    main.cxx
+  CMakeLists.txt
+```
+
+And we wish to use [fmt](https://github.com/fmtlib/fmt), [range-v3](https://github.com/ericniebler/range-v3),
+and [cxxopts](https://github.com/jarro2783/cxxopts).
+
+Let's write our `CMakeLists.txt` first:
+
+```cmake
+cmake_minimum_required(VERSION 3.15)
+
+project(fibo CXX)
+
+find_package(fmt REQUIRED)
+find_package(range-v3 REQUIRED)
+find_package(cxxopts REQUIRED)
+
+add_executable(fibo src/main.cxx)
+target_compile_features(fibo PRIVATE cxx_std_17)
+
+target_link_libraries(fibo
+  PRIVATE
+    fmt::fmt
+    range-v3::range-v3
+    cxxopts::cxxopts)
+```
+
+And then we should add `main.cxx`:
+
+```cxx
+#include <cxxopts.hpp>
+#include <fmt/format.h>
+#include <range/v3/view.hpp>
+
+namespace view = ranges::views;
+
+int fib(int x) {
+  int a = 0, b = 1;
+
+  for (int it : view::repeat(0) | view::take(x)) {
+    (void)it;
+    int tmp = a;
+    a += b;
+    b = tmp;
+  }
+
+  return a;
+}
+
+int main(int argc, char** argv) {
+  cxxopts::Options options("fibo", "Print the fibonacci sequence up to a value 'n'");
+    options.add_options()
+      ("n,value", "The value to print to", cxxopts::value<int>()->default_value("10"));
+
+  auto result = options.parse(argc, argv);
+  auto n = result["value"].as<int>();
+
+  for (int x : view::iota(1) | view::take(n)) {
+    fmt::print("fib({}) = {}\n", x, fib(x));
+  }
+}
+```
+
+This is a simple project of course, but it should give us a clean project to start with.
+Let's try it out!
+
+Let's assume you have `fmt`, `range-v3`, and `cxxopts` installed with vcpkg classic mode;
+then, you can just do a simple:
+
+```cmd
+D:\src\fibo> cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake
+-- Building for: Visual Studio 16 2019
+-- Selecting Windows SDK version 10.0.18362.0 to target Windows 10.0.19041.
+-- The CXX compiler identification is MSVC 19.27.29111.0
+-- Detecting CXX compiler ABI info
+-- Detecting CXX compiler ABI info - done
+-- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/MSVC/14.27.29110/bin/Hostx64/x64/cl.exe - skipped
+-- Detecting CXX compile features
+-- Detecting CXX compile features - done
+-- Configuring done
+-- Generating done
+-- Build files have been written to: D:/src/fibo/build
+D:\src\fibo> cmake --build build
+Microsoft (R) Build Engine version 16.7.0+b89cb5fde for .NET Framework
+Copyright (C) Microsoft Corporation. All rights reserved.
+
+  Checking Build System
+  Building Custom Rule D:/src/fibo/CMakeLists.txt
+  main.cxx
+  The contents of <span> are available only with C++20 or later.
+  fibo.vcxproj -> D:\src\fibo\build\Debug\fibo.exe
+  Building Custom Rule D:/src/fibo/CMakeLists.txt
+```
+
+And now we can try out the `fibo` binary!
+
+```cmd
+D:\src\fibo> .\build\Debug\fibo.exe -n 7 
+fib(1) = 1
+fib(2) = 1
+fib(3) = 2
+fib(4) = 3
+fib(5) = 5
+fib(6) = 8
+fib(7) = 13
+```
+
+it works!
+
+## Converting to Manifest Mode
+
+We now wish to use manifest mode, so all of our dependencies are managed for us! Let's write a `vcpkg.json`:
+
+```json
+{
+  "name": "fibo",
+  "version-string": "0.1.0",
+  "dependencies": [
+    "cxxopts",
+    "fmt",
+    "range-v3"
+  ]
+}
+```
+
+Let's delete the build directory and rerun the build:
+
+```cmd
+D:\src\fibo> rmdir /S /Q build
+D:\src\fibo> cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake
+-- Running vcpkg install
+Detecting compiler hash for triplet x64-windows...
+The following packages will be built and installed:
+    cxxopts[core]:x64-windows
+    fmt[core]:x64-windows
+    range-v3[core]:x64-windows
+Starting package 1/3: cxxopts:x64-windows
+Building package cxxopts[core]:x64-windows...
+Using cached binary package: C:\Users\me\AppData\Local\vcpkg/archives\d2\d2d1e5302cdfefef2fd090d8eda84cc0c1fbe6f1.zip
+Building package cxxopts[core]:x64-windows... done
+Installing package cxxopts[core]:x64-windows...
+Installing package cxxopts[core]:x64-windows... done
+Elapsed time for package cxxopts:x64-windows: 50.64 ms
+Starting package 2/3: fmt:x64-windows
+Building package fmt[core]:x64-windows...
+Using cached binary package: C:\Users\me\AppData\Local\vcpkg/archives\bf\bf00d5214e912d71414b545b241f54ef87fdf6e5.zip
+Building package fmt[core]:x64-windows... done
+Installing package fmt[core]:x64-windows...
+Installing package fmt[core]:x64-windows... done
+Elapsed time for package fmt:x64-windows: 225 ms
+Starting package 3/3: range-v3:x64-windows
+Building package range-v3[core]:x64-windows...
+Using cached binary package: C:\Users\me\AppData\Local\vcpkg/archives\fe\fe2cdedef6953bf954e8ddca471bf3cc8d9b06d7.zip
+Building package range-v3[core]:x64-windows... done
+Installing package range-v3[core]:x64-windows...
+Installing package range-v3[core]:x64-windows... done
+Elapsed time for package range-v3:x64-windows: 1.466 s
+
+Total elapsed time: 1.742 s
+
+-- Running vcpkg install - done
+-- Selecting Windows SDK version 10.0.18362.0 to target Windows 10.0.19041.
+-- The CXX compiler identification is MSVC 19.27.29111.0
+-- Detecting CXX compiler ABI info
+-- Detecting CXX compiler ABI info - done
+-- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/MSVC/14.27.29110/bin/Hostx64/x64/cl.exe - skipped
+-- Detecting CXX compile features
+-- Detecting CXX compile features - done
+-- Configuring done
+-- Generating done
+-- Build files have been written to: D:/src/fibo/build
+D:\src\fibo> cmake --build build
+Microsoft (R) Build Engine version 16.7.0+b89cb5fde for .NET Framework
+Copyright (C) Microsoft Corporation. All rights reserved.
+
+  Checking Build System
+  Building Custom Rule D:/src/fibo/CMakeLists.txt
+  main.cxx
+  The contents of <span> are available only with C++20 or later.
+  fibo.vcxproj -> D:\src\fibo\build\Debug\fibo.exe
+  Building Custom Rule D:/src/fibo/CMakeLists.txt
+```
+
+You can see that with just a _single file_, we've changed over to manifests without _any_ trouble.
+The build system doesn't change _at all_! We just add a `vcpkg.json` file, delete the build directory,
+and reconfigure. And we're done!

externals/vcpkg/docs/examples/modify-baseline-to-pin-old-boost.md

@@ -0,0 +1,191 @@
+# Pin old Boost versions
+This document will teach you how to set versions of meta-packages like `boost` or `qt5`.
+
+**What is a meta-package?**
+In vcpkg we call meta-packages to ports that by themselves don't install anything but that instead forward installation to another port or ports. The reasons for these meta-packages to exist are plenty: to install different versions of a library depending on platform or to conveniently install/uninstall a catalog of related packages (Boost and Qt).
+
+In the case of Boost, it is unlikely that a user requires all of the 140+ Boost libraries in their project. For the sake of convenience, vcpkg splits Boost into multiple sub-packages broken down to individual libraries. By doing so, users can limit the subset of Boost libraries that they depend on.
+
+If a user wants to install all of the Boost libraries available in vcpkg, they can do so by installing the `boost` meta-package.
+
+Due to the nature of meta-packages, some unexpected issues arise when trying to use them with versioning. If a user writes the following manifest file:
+
+`vcpkg.json`
+```json
+{
+    "name": "demo",
+    "version": "1.0.0",
+    "builtin-baseline": "787fe1418ea968913cc6daf11855ffd8b0b5e9d4",
+    "dependencies": [ "boost-tuple" ],
+    "overrides": [
+        { "name": "boost", "version": "1.72.0" }
+    ]
+}
+```
+
+The resulting installation plan is:
+```
+The following packages will be built and installed:
+    boost-assert[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-assert\3393715b4ebe30fe1c3b68acf7f84363e611f156
+    boost-compatibility[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-compatibility\cda5675366367789659c59aca65fc57d03c51deb
+    boost-config[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-config\ca82ca1b9c1739c91f3cf42c68cee56c896ae6bd
+    boost-container-hash[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-container-hash\bf472c23d29c3d80b562c43471eb92cea998f372
+    boost-core[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-core\20a19f6ece37686a02eed33e1f58add8b7a2582a
+    boost-detail[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-detail\96744251f025f9b3c856a275dfc338031876777b
+    boost-integer[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-integer\de70ce0d1500df1eda3496c4f98f42f5db256b4a
+    boost-io[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-io\7bf3407372f8fc2a99321d24a0e952d44fe25bf3
+    boost-preprocessor[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-preprocessor\8d78b8ba2e9f54cb00137115ddd2ffec1c63c149
+    boost-static-assert[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-static-assert\2a41c4703c7122de25b1c60510c43edc9371f63d
+    boost-throw-exception[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-throw-exception\b13bdf32a20786a0165cc20205ef63765cac0627
+    boost-tuple[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-tuple\22e3d000a178a88992c430d8ae8a0244c7dea674
+    boost-type-traits[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-type-traits\8829793f6c6c913257314caa317599f8d253a5ca
+    boost-uninstall[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-uninstall\08933bad27b6d41caef0940c31e2069ecb6a079c
+    boost-utility[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-utility\47572946bf6a63c731b9c4142eecb8bef3d3b270
+    boost-vcpkg-helpers[core]:x64-windows -> 7#2 -- D:\vcpkg\buildtrees\versioning\versions\boost-vcpkg-helpers\2a21e5ab45d1ce41c185faf85dff0670ea6def1d
+```
+
+It is reasonable to expect that overriding `boost` to version 1.72.0 results in all Boost packages being pinned to version 1.72.0. **However, vcpkg does not treat the `boost` meta-package any differently that any other port.** In other words, vcpkg has no notion that `boost` is related to all the other `boost-*` libraries, other than it depends on all of them. For this reason, all the other boost packages are installed at version 1.75.0, which is the baseline version.
+
+Below, we describe two methods to pin down Boost versions effectively.
+
+## Method 1: Pin specific packages
+Use `"overrides"` to force specific versions in a package-by-package basis.
+
+`vcpkg.json`
+```json
+{
+    "name": "demo",
+    "version": "1.0.0",
+    "builtin-baseline": "787fe1418ea968913cc6daf11855ffd8b0b5e9d4",
+    "dependencies": [ "boost-tuple" ],
+    "overrides": [
+        { "name": "boost-core", "version": "1.72" },
+        { "name": "boost-integer", "version": "1.72" },
+        { "name": "boost-io", "version": "1.72" },
+        { "name": "boost-tuple", "version": "1.72" }
+    ]
+}
+```
+
+This method allows you to quickly set the specific versions you want, but you will need to write an override for each package. Boost libraries are also heavily interdependent, which means that you may end up writing a lot of override lines.
+
+The second method makes it easy to pin the entire Boost collection and end up with a very simple manifest file.
+
+## Method 2: Modify baseline
+An easy way to set the version for the entirety of boost is to use the `"builtin-baseline"` property.
+
+As of right now, it is only possible to go back to Boost version `1.75.0` using a baseline, since that was the contemporary Boost version when the versioning feature was merged. **But, it is possible to modify the baseline to whatever you like and use that instead.**
+
+### Step 1: Create a new branch
+As described in the versioning documentation. The value that goes in `"builtin-baseline"` is a git commit in the microsoft/vcpkg repository's history. If you want to customize the baseline and have control over the vcpkg instance, you can create a new commit with said custom baseline.
+
+Let's start by creating a new branch to hold our modified baseline.
+
+In the directory containing your clone of the vcpkg Git repository run:
+
+```
+git checkout -b custom-boost-baseline
+```
+
+This will create a new branch named `custom-boost-baseline` and check it out immediately.
+
+### Step 2: Modify the baseline
+The next step is to modify the baseline file, open the file in your editor of choice and modify the entries for the Boost libraries.
+
+Change the `"baseline"` version to your desired version.
+_NOTE: Remember to also set the port versions to 0 (or your desired version)._
+
+`${vcpkg-root}/versions/baseline.json`
+```diff
+...
+     "boost": {
+-      "baseline": "1.75.0",
++      "baseline": "1.72.0",
+       "port-version": 0
+     },
+     "boost-accumulators": {
+-      "baseline": "1.75.0",
+-      "port-version": 1
++      "baseline": "1.72.0",
++      "port-version": 0
+     },
+     "boost-algorithm": {
+-      "baseline": "1.75.0",
++      "baseline": "1.72.0",
+       "port-version": 0
+     },
+     "boost-align": {
+-      "baseline": "1.75.0",
++      "baseline": "1.72.0",
+       "port-version": 0
+     },
+...
+    "boost-uninstall: {
+        "baseline": "1.75.0",
+        "port-version": 0
+    },
+...
+```
+
+Some `boost-` packages are helpers used by vcpkg and are not part of Boost. For example, `"boost-uninstall"` is a vcpkg helper to conveniently uninstall all Boost libraries, but it didn't exist for Boost version `1.72.0`, in this case it is fine to leave it at `1.75.0` to avoid baseline errors (since all versions in `baseline.json` must have existed).
+
+### Step 3: Commit your changes
+After saving your modified file, run these commands to commit your changes:
+
+```
+git add versions/baseline.json
+git commit -m "Baseline Boost 1.72.0"
+```
+
+You can set the commit message to whatever you want, just make it useful for you.
+
+### Step 4: Get your baseline commit SHA
+Once all your changes are ready, you can get the commit SHA by running:
+```
+git rev-parse HEAD
+```
+
+The output of that command will be the commit SHA you need to put as the `"builtin-baseline"` in your project's manifest file. Copy the 40-hex digits and save them to use later in your manifest file.
+
+### Step 5: (Optional) Go back to the main repository branch
+Once your changes have been committed locally, you can refer to the commit SHA regardless of the repository branch you're working on. So, let's go back to the main vcpkg repository branch.
+
+```
+git checkout master
+```
+
+### Step 6: Create your manifest file with your custom baseline
+
+```json
+{
+    "name": "demo",
+    "version": "1.0.0",
+    "builtin-baseline": "9b5cf7c3d9376ddf43429671282972ec4f99aa85",
+    "dependencies": [ "boost-tuple" ]
+}
+```
+
+In this example, commit SHA `9b5cf7c3d9376ddf43429671282972ec4f99aa85` is the commit ID with the modified baseline. Even when a different branch (`master` in this case) is checked out, Git is able to find the commit as long as the branch with the modified baseline exists (the `custom-boost-baseline` branch we created in step 1).
+
+We run `vcpkg install` in the directory containing our manifest file and the output looks like this:
+
+```
+The following packages will be built and installed:
+    boost-assert[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-assert\6754398591f48435b28014ca0d60e5375a4c04d1
+    boost-compatibility[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-compatibility\9893ff3c554575bc712df4108a949e07b269f401
+    boost-config[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-config\de2784767046b06ec31eb718f10df512e51f2aad
+    boost-container-hash[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-container-hash\cc19fb0154bbef188f309f49b2664ec7623b96b6
+    boost-core[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-core\0eb5e20df9e267e9eca325be946f52ceb8a60229
+    boost-detail[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-detail\759d7c6a3f9dbaed0b0c69fa0bb764f7606bb02d
+    boost-integer[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-integer\173956c61a26e83b0f8b58b0baf60f06aeee637c
+    boost-preprocessor[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-preprocessor\86eb3938b7875f124feb845331dbe84cbab5d1c6
+    boost-static-assert[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-static-assert\e82d8f7f3ee07e927dc374f5a08ed6d6f4ef81f4
+    boost-throw-exception[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-throw-exception\64df295f7df41de4fcb219834889b126b5020def
+    boost-tuple[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-tuple\b3e1b01ffce6e367e4fed0a5538a8546abacb6b2
+    boost-type-traits[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-type-traits\5e44ec657660eccf4d3b2710b092dd238e1e7a2d
+    boost-uninstall[core]:x64-windows -> 1.75.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-uninstall\08933bad27b6d41caef0940c31e2069ecb6a079c
+    boost-utility[core]:x64-windows -> 1.72.0 -- D:\vcpkg\buildtrees\versioning\versions\boost-utility\7d721b2458d5d595ac341eb54883274f38a4b8c2
+    boost-vcpkg-helpers[core]:x64-windows -> 7#2 -- D:\vcpkg\buildtrees\versioning\versions\boost-vcpkg-helpers\2a21e5ab45d1ce41c185faf85dff0670ea6def1d
+```
+
+Notice how simple our manifest file has become, instead of having a multitude of `"overrides"` you can pin down all Boost packages just by setting the `"builtin-baseline"` to be your modified baseline commit SHA.

externals/vcpkg/docs/examples/overlay-triplets-linux-dynamic.md

@@ -0,0 +1,126 @@
+# Overlay triplets example
+
+## Building dynamic libraries on Linux
+
+Using **vcpkg** you can build libraries for many configurations out of the box. However, this doesn't currently include shared libraries on Linux and Mac OS.
+
+This doesn't mean that you cannot use **vcpkg** to build your dynamic libraries on these platforms! This document will guide you through creating your own custom triplets with `--overlay-triplets` to easily build dynamic libraries on Linux.
+
+### Step 1: Create the custom triplet files
+
+To save time, copy the existing `x64-linux.cmake` triplet file.
+
+```sh
+~/git$ mkdir custom-triplets
+~/git$ cp vcpkg/triplets/x64-linux.cmake custom-triplets/x64-linux-dynamic.cmake
+```
+
+And modify `custom-triplets/x64-linux-dynamic.cmake` to match the contents below:
+```cmake
+# ~/git/custom-triplets/x64-linux-dynamic.cmake
+set(VCPKG_TARGET_ARCHITECTURE x64)
+set(VCPKG_CRT_LINKAGE dynamic)
+set(VCPKG_LIBRARY_LINKAGE dynamic) # This changed from static to dynamic
+
+set(VCPKG_CMAKE_SYSTEM_NAME Linux)
+```
+
+### Step 2: Use `--overlay-triplets` to build dynamic libraries
+
+Use the `--overlay-triplets` option to include the triplets in the `custom-triplets` directory. 
+
+```
+~/git$ vcpkg/vcpkg install sqlite3:x64-linux-dynamic --overlay-triplets=custom-triplets
+The following packages will be built and installed:
+    sqlite3[core]:x64-linux-dynamic
+Starting package 1/1: sqlite3:x64-linux-dynamic
+Building package sqlite3[core]:x64-linux-dynamic...
+-- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux-dynamic.cmake
+-- Downloading https://sqlite.org/2019/sqlite-amalgamation-3280000.zip...
+-- Extracting source /home/victor/git/vcpkg/downloads/sqlite-amalgamation-3280000.zip
+-- Applying patch fix-arm-uwp.patch
+-- Using source at /home/victor/git/vcpkg/buildtrees/sqlite3/src/3280000-6a3ff7ce92
+-- Configuring x64-linux-dynamic-dbg
+-- Configuring x64-linux-dynamic-rel
+-- Building x64-linux-dynamic-dbg
+-- Building x64-linux-dynamic-rel
+-- Performing post-build validation
+-- Performing post-build validation done
+Building package sqlite3[core]:x64-linux-dynamic... done
+Installing package sqlite3[core]:x64-linux-dynamic...
+Installing package sqlite3[core]:x64-linux-dynamic... done
+Elapsed time for package sqlite3:x64-linux-dynamic: 44.82 s
+
+Total elapsed time: 44.82 s
+
+The package sqlite3:x64-linux-dynamic provides CMake targets:
+
+    find_package(unofficial-sqlite3 CONFIG REQUIRED)
+    target_link_libraries(main PRIVATE unofficial::sqlite3::sqlite3)
+```
+
+Overlay triplets enables your custom triplet files when using `vcpkg install`, `vcpkg update`, `vcpkg upgrade`, and `vcpkg remove`.
+
+When using the `--overlay-triplets` option, a message like the following lets you know that a custom triplet is being used: 
+
+```
+-- Loading triplet configuration from: /home/custom-triplets/x64-linux-dynamic.cmake
+```
+
+## Overriding default triplets
+
+As you may have noticed, the default triplets for Windows (`x86-windows` and `x64-windows`) install dynamic libraries, while a suffix (`-static`) is needed for static libraries. This is different with Linux and Mac OS where static libraries are built by `x64-linux` and `x64-osx`.
+
+Using `--overlay-triplets` it is possible to override the default triplets to accomplish the same behavior on Linux:
+
+* `x64-linux`: Builds dynamic libraries,
+* `x64-linux-static`: Builds static libraries.
+
+### Step 1: Create the overlay triplets
+
+Using the custom triplet created in the previous example, rename `custom-triplets/x64-linux-dynamic.cmake` to `custom-triplets/x64-linux.cmake`. Then, copy the default `x64-linux` triplet (which builds static libraries) in your `custom-triplets` folder and rename it to `x64-linux-static.cmake`.
+
+```sh
+~/git$ mv custom-triplets/x64-linux-dynamic.cmake custom-triplets/x64-linux.cmake
+~/git$ cp vcpkg/triplets/x64-linux.cmake custom-triplets/x64-linux-static.cmake
+```
+
+### Step 2: Use `--overlay-triplets` to override default triplets
+
+Use the `--overlay-triplets` option to include the triplets in the `custom-triplets` directory.
+
+```
+~/git$ vcpkg/vcpkg install sqlite3:x64-linux --overlay-triplets=custom-triplets
+The following packages will be built and installed:
+    sqlite3[core]:x64-linux
+Starting package 1/1: sqlite3:x64-linux
+Building package sqlite3[core]:x64-linux...
+-- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux.cmake
+-- Downloading https://sqlite.org/2019/sqlite-amalgamation-3280000.zip...
+-- Extracting source /home/victor/git/vcpkg/downloads/sqlite-amalgamation-3280000.zip
+-- Applying patch fix-arm-uwp.patch
+-- Using source at /home/victor/git/vcpkg/buildtrees/sqlite3/src/3280000-6a3ff7ce92
+-- Configuring x64-linux-dbg
+-- Configuring x64-linux-rel
+-- Building x64-linux-dbg
+-- Building x64-linux-rel
+-- Performing post-build validation
+-- Performing post-build validation done
+Building package sqlite3[core]:x64-linux... done
+Installing package sqlite3[core]:x64-linux...
+Installing package sqlite3[core]:x64-linux... done
+Elapsed time for package sqlite3:x64-linux: 44.82 s
+
+Total elapsed time: 44.82 s
+
+The package sqlite3:x64-linux provides CMake targets:
+
+    find_package(unofficial-sqlite3 CONFIG REQUIRED)
+    target_link_libraries(main PRIVATE unofficial::sqlite3::sqlite3)
+```
+
+Note that the default triplet is masked by your custom triplet:
+
+```
+-- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux.cmake
+```

externals/vcpkg/docs/examples/packaging-github-repos.md

@@ -0,0 +1,54 @@
+## Packaging Github Repos Example: libogg
+### Create the manifest file
+The manifest file (called `vcpkg.json`) is a json file describing the package's metadata.
+
+For libogg, we'll create the file `ports/libogg/vcpkg.json` with the following content:
+
+```json
+{
+  "name": "libogg",
+  "version-string": "1.3.3",
+  "description": "Ogg is a multimedia container format, and the native file and stream format for the Xiph.org multimedia codecs."
+}
+```
+
+You can format the manifest file to our specifications with `vcpkg format-manifest ports/libogg/vcpkg.json`.
+
+### Create the portfile
+`portfile.cmake` describes how to build and install the package. First we download the project from Github with [`vcpkg_from_github`](../maintainers/vcpkg_from_github.md):
+
+```cmake
+vcpkg_from_github(
+    OUT_SOURCE_PATH SOURCE_PATH
+    REPO xiph/ogg
+    REF v1.3.3
+    SHA512 0bd6095d647530d4cb1f509eb5e99965a25cc3dd9b8125b93abd6b248255c890cf20710154bdec40568478eb5c4cde724abfb2eff1f3a04e63acef0fbbc9799b
+    HEAD_REF master
+)
+```
+
+The important parts to update are `REPO` for the GitHub repository path, `REF` for a stable tag/commit to use, and `SHA512` with the checksum of the downloaded zipfile (you can get this easily by setting it to `0`, trying to install the package, and copying the checksum).
+
+Finally, we configure the project with CMake, install the package, and copy over the license file:
+
+```cmake
+vcpkg_cmake_configure(SOURCE_PATH ${SOURCE_PATH})
+vcpkg_cmake_install()
+file(INSTALL "${SOURCE_PATH}/COPYING" DESTINATION "${CURRENT_PACKAGES_DIR}/share/libogg" RENAME copyright)
+```
+
+Check the documentation for [`vcpkg_cmake_configure`](../maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md) and [`vcpkg_cmake_install`](../maintainers/ports/vcpkg-cmake/vcpkg_cmake_install.md) if your package needs additional options. 
+
+Now you can run `vcpkg install libogg` to build and install the package.
+
+### Suggested example portfiles
+In the `ports/` directory are many libraries that can be used as examples, including many that are not based on CMake.
+
+- Header only libraries
+  - rapidjson
+  - range-v3
+- MSBuild-based
+  - mpg123
+- Non-CMake, custom buildsystem
+  - openssl
+  - ffmpeg

externals/vcpkg/docs/examples/packaging-zipfiles.md

@@ -0,0 +1,76 @@
+## Packaging `.zip` Files Example: zlib
+
+### Bootstrap with `create`
+First, locate a globally accessible archive of the library's sources. Zip, gzip, and bzip are all supported. Strongly prefer official sources or mirrors over unofficial mirrors.
+
+*Looking at zlib's website, the URL http://zlib.net/zlib-1.2.11.tar.gz looks appropriate.*
+
+Second, determine a suitable package name. This should be ASCII, lowercase, and recognizable to someone who knows the library's "human name". If the library is already packaged in another package manager, prefer that name.
+
+*Since zlib is already packaged as zlib, we will use the name zlib2 for this example.*
+
+Finally, if the server's name for the archive is not very descriptive (such as downloading a zipped commit or branch from GitHub), choose a nice archive name of the form `<packagename>-<version>.zip`.
+
+*`zlib1211.zip` is a fine name, so no change needed.*
+
+All this information can then be passed into the `create` command, which will download the sources and bootstrap the packaging process inside `ports/<packagename>`.
+
+```no-highlight
+PS D:\src\vcpkg> .\vcpkg create zlib2 http://zlib.net/zlib-1.2.11.tar.gz zlib1211.tar.gz
+-- Generated portfile: D:/src/vcpkg/ports/zlib2/portfile.cmake
+```
+
+### Create the manifest file
+In addition to the generated `ports/<package>/portfile.cmake`, we also need a `ports/<package>/vcpkg.json` file. This file is a simple set of fields describing the package's metadata.
+
+*For zlib2, we'll create the file `ports/zlib2/vcpkg.json` with the following contents:*
+```json
+{
+  "name": "zlib2",
+  "version-string": "1.2.11",
+  "description": "A Massively Spiffy Yet Delicately Unobtrusive Compression Library"
+}
+```
+
+### Tweak the generated portfile
+The generated `portfile.cmake` will need some editing to correctly package most libraries in the wild, however we can start by trying out the build.
+
+```no-highlight
+PS D:\src\vcpkg> .\vcpkg install zlib2
+Computing installation plan...
+The following packages will be built and installed:
+    zlib2[core]:x64-uwp
+Starting package 1/1: zlib2:x64-uwp
+Building package zlib2[core]:x64-uwp...
+-- Using cached C:/src/vcpkg/downloads/zlib1211.tar.gz
+-- Cleaning sources at C:/src/vcpkg/buildtrees/zlib2/src/1.2.11-deec42f53b.clean. Pass --editable to vcpkg to reuse sources.
+-- Extracting source C:/src/vcpkg/downloads/zlib1211.tar.gz
+-- Applying patch cmake_dont_build_more_than_needed.patch
+-- Using source at C:/src/vcpkg/buildtrees/zlib2/src/1.2.11-deec42f53b.clean
+-- Configuring x64-uwp
+-- Building x64-uwp-dbg
+-- Building x64-uwp-rel
+-- Installing: C:/src/vcpkg/packages/zlib2_x64-uwp/share/zlib2/copyright
+-- Performing post-build validation
+Include files should not be duplicated into the /debug/include directory. If this cannot be disabled in the project cmake, use
+    file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/include)
+/debug/share should not exist. Please reorganize any important files, then use
+    file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/share)
+The software license must be available at ${CURRENT_PACKAGES_DIR}/share/zlib2/copyright
+Found 3 error(s). Please correct the portfile:
+    D:\src\vcpkg\ports\zlib2\portfile.cmake
+```
+
+At this point, it is a matter of reading the error messages and log files while steadily improving the quality of the portfile. Zlib required providing a discrete copy of the LICENSE to copy into the package, suppressing the build and installation of executables and headers, and removing the static libraries after they were installed.
+
+### Suggested example portfiles
+In the `ports/` directory are many libraries that can be used as examples, including many that are not based on CMake.
+
+- Header only libraries
+    - rapidjson
+    - range-v3
+- MSBuild-based
+    - mpg123
+- Non-CMake, custom buildsystem
+    - openssl
+    - ffmpeg

externals/vcpkg/docs/examples/patching.md

@@ -0,0 +1,220 @@
+## Patching Example: Patching libpng to work for x64-uwp
+
+### Initial error logs
+First, try building:
+
+```no-highlight
+PS D:\src\vcpkg> vcpkg install libpng:x64-uwp --editable
+Computing installation plan...
+The following packages will be built and installed:
+    libpng[core]:x64-uwp
+Starting package 1/1: libpng:x64-uwp
+Building package libpng[core]:x64-uwp...
+-- Using cached D:/src/vcpkg/downloads/glennrp-libpng-v1.6.37.tar.gz
+-- Extracting source D:/src/vcpkg/downloads/glennrp-libpng-v1.6.37.tar.gz
+-- Using source at D:/src/vcpkg/buildtrees/libpng/src/v1.6.37-c993153cdf
+-- Configuring x64-uwp
+-- Building x64-uwp-rel
+CMake Error at scripts/cmake/execute_required_process.cmake:14 (message):
+  Command failed: C:/Program Files/CMake/bin/cmake.exe;--build;.;--config;Release
+
+  Working Directory: D:/src/vcpkg/buildtrees/libpng/x64-uwp-rel
+
+  See logs for more information:
+
+      D:\src\vcpkg\buildtrees\libpng\build-x64-uwp-rel-out.log
+      D:\src\vcpkg\buildtrees\libpng\build-x64-uwp-rel-err.log
+
+Call Stack (most recent call first):
+  scripts/cmake/vcpkg_build_cmake.cmake:3 (execute_required_process)
+  ports/libpng/portfile.cmake:22 (vcpkg_build_cmake)
+  scripts/ports.cmake:84 (include)
+
+
+Error: build command failed
+```
+
+Next, looking at the above logs (build-xxx-out.log and build-xxx-err.log).
+
+```no-highlight
+// build-x64-uwp-rel-out.log
+...
+"D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\ALL_BUILD.vcxproj" (default target) (1) ->
+"D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj" (default target) (3) ->
+(ClCompile target) -> 
+  D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf\pngerror.c(775): warning C4013: 'ExitProcess' undefined; assuming extern returning int [D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj]
+
+
+"D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\ALL_BUILD.vcxproj" (default target) (1) ->
+"D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj" (default target) (3) ->
+(Link target) -> 
+  pngerror.obj : error LNK2019: unresolved external symbol _ExitProcess referenced in function _png_longjmp [D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj]
+  D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\Release\libpng16.dll : fatal error LNK1120: 1 unresolved externals [D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj]
+
+    1 Warning(s)
+    2 Error(s)
+
+Time Elapsed 00:00:04.19
+```
+
+### Identify the problematic code
+
+Taking a look at [MSDN](https://msdn.microsoft.com/en-us/library/windows/desktop/ms682658(v=vs.85).aspx) shows that `ExitProcess` is only available for desktop apps. Additionally, it's useful to see the surrounding context:
+
+```c
+/* buildtrees\libpng\src\v1.6.37-c993153cdf\pngerror.c:769 */
+    /* If control reaches this point, png_longjmp() must not return. The only
+    * choice is to terminate the whole process (or maybe the thread); to do
+    * this the ANSI-C abort() function is used unless a different method is
+    * implemented by overriding the default configuration setting for
+    * PNG_ABORT().
+    */
+    PNG_ABORT();
+```
+
+A recursive search for `PNG_ABORT` reveals the definition:
+```no-highlight
+PS D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf> findstr /snipl "PNG_ABORT" *
+CHANGES:701:  Added PNG_SETJMP_SUPPORTED, PNG_SETJMP_NOT_SUPPORTED, and PNG_ABORT() macros
+libpng-manual.txt:432:errors will result in a call to PNG_ABORT() which defaults to abort().
+libpng-manual.txt:434:You can #define PNG_ABORT() to a function that does something
+libpng-manual.txt:2753:errors will result in a call to PNG_ABORT() which defaults to abort().
+libpng-manual.txt:2755:You can #define PNG_ABORT() to a function that does something
+libpng-manual.txt:4226:PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()),
+libpng.3:942:errors will result in a call to PNG_ABORT() which defaults to abort().
+libpng.3:944:You can #define PNG_ABORT() to a function that does something
+libpng.3:3263:errors will result in a call to PNG_ABORT() which defaults to abort().
+libpng.3:3265:You can #define PNG_ABORT() to a function that does something
+libpng.3:4736:PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()),
+png.h:994: * will use it; otherwise it will call PNG_ABORT().  This function was
+pngerror.c:773:    * PNG_ABORT().
+pngerror.c:775:   PNG_ABORT();
+pngpriv.h:459:#ifndef PNG_ABORT
+pngpriv.h:461:#    define PNG_ABORT() ExitProcess(0)
+pngpriv.h:463:#    define PNG_ABORT() abort()
+```
+
+This already gives us some great clues, but the full definition tells the complete story.
+
+```c
+/* buildtrees\libpng\src\v1.6.37-c993153cdf\pngpriv.h:459 */
+#ifndef PNG_ABORT
+#  ifdef _WINDOWS_
+#    define PNG_ABORT() ExitProcess(0)
+#  else
+#    define PNG_ABORT() abort()
+#  endif
+#endif
+```
+
+`abort()` is a standard CRT call and certainly available in UWP, so we just need to convince libpng to be more platform agnostic. The easiest and most reliable way to achieve this is to patch the code; while in this particular case we could pass in a compiler flag to override `PNG_ABORT` because this is a private header, in general it is more reliable to avoid adding more required compiler switches when possible (especially when it isn't already exposed as a CMake option).
+
+### Patching the code to improve compatibility
+
+We recommend using git to create the patch file, since you'll already have it installed.
+```no-highlight
+PS D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf> git init .
+Initialized empty Git repository in D:/src/vcpkg/buildtrees/libpng/src/v1.6.37-c993153cdf/.git/
+
+PS D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf> git add .
+warning: LF will be replaced by CRLF in ANNOUNCE.
+The file will have its original line endings in your working directory.
+...
+
+PS D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf> git commit -m "temp"
+[master (root-commit) 68f253f] temp
+ 422 files changed, 167717 insertions(+)
+...
+```
+
+Now we can modify `pngpriv.h` to use `abort()` everywhere.
+```c
+/* buildtrees\libpng\src\v1.6.37-c993153cdf\pngpriv.h:459 */
+#ifndef PNG_ABORT
+#  define PNG_ABORT() abort()
+#endif
+```
+
+The output of `git diff` is already in patch format, so we just need to save the patch into the `ports/libpng` directory.
+```no-highlight
+PS buildtrees\libpng\src\v1.6.37-c993153cdf> git diff --ignore-space-at-eol | out-file -enc ascii ..\..\..\..\ports\libpng\use-abort-on-all-platforms.patch
+```
+
+Finally, we need to apply the patch after extracting the source.
+```cmake
+# ports\libpng\portfile.cmake
+...
+vcpkg_extract_source_archive_ex(
+  OUT_SOURCE_PATH SOURCE_PATH
+  ARCHIVE ${ARCHIVE}
+  PATCHES 
+    "use-abort-on-all-platforms.patch"
+)
+
+vcpkg_cmake_configure(
+...
+```
+
+### Verification
+
+To be completely sure this works from scratch, we need to remove the package and rebuild it:
+
+```no-highlight
+PS D:\src\vcpkg> vcpkg remove libpng:x64-uwp
+Package libpng:x64-uwp was successfully removed
+```
+
+Now we try a fresh, from scratch install.
+
+```no-highlight
+PS D:\src\vcpkg> vcpkg install libpng:x64-uwp
+Computing installation plan...
+The following packages will be built and installed:
+    libpng[core]:x64-uwp
+Starting package 1/1: libpng:x64-uwp
+Building package libpng[core]:x64-uwp...
+Could not locate cached archive: C:\Users\me\AppData\Local\vcpkg/archives\f4\f44b54f818f78b9a4ccd34b3666f566f94286850.zip
+-- Using cached D:/src/vcpkg/downloads/glennrp-libpng-v1.6.37.tar.gz
+-- Extracting source D:/src/vcpkg/downloads/glennrp-libpng-v1.6.37.tar.gz
+-- Applying patch use_abort.patch
+-- Applying patch cmake.patch
+-- Applying patch pkgconfig.patch
+-- Applying patch pkgconfig.2.patch
+-- Using source at D:/src/vcpkg/buildtrees/libpng/src/v1.6.37-10db9f58e4.clean
+-- Configuring x64-uwp
+-- Building x64-uwp-dbg
+-- Building x64-uwp-rel
+-- Fixing pkgconfig file: D:/src/vcpkg/packages/libpng_x64-uwp/lib/pkgconfig/libpng.pc
+-- Fixing pkgconfig file: D:/src/vcpkg/packages/libpng_x64-uwp/lib/pkgconfig/libpng16.pc
+-- Fixing pkgconfig file: D:/src/vcpkg/packages/libpng_x64-uwp/debug/lib/pkgconfig/libpng.pc
+-- Fixing pkgconfig file: D:/src/vcpkg/packages/libpng_x64-uwp/debug/lib/pkgconfig/libpng16.pc
+-- Installing: D:/src/vcpkg/packages/libpng_x64-uwp/share/libpng/copyright
+-- Performing post-build validation
+-- Performing post-build validation done
+Stored binary cache: C:\Users\me\AppData\Local\vcpkg/archives\f4\f44b54f818f78b9a4ccd34b3666f566f94286850.zip
+Building package libpng[core]:x64-uwp... done
+Installing package libpng[core]:x64-uwp...
+Installing package libpng[core]:x64-uwp... done
+Elapsed time for package libpng:x64-uwp: 11.94 s
+
+Total elapsed time: 11.95 s
+
+The package libpng:x64-uwp provides CMake targets:
+
+    find_package(libpng CONFIG REQUIRED)
+    target_link_libraries(main PRIVATE png)
+```
+
+Finally, to fully commit and publish the changes, we need to bump the port version in `vcpkg.json`,
+and add the patch file to source control, then make a Pull Request!
+
+```json
+{
+  "name": "libpng",
+  "version": "1.6.37",
+  "port-version": 1,
+  "dependencies": [
+    "zlib"
+  ]
+}
+```

externals/vcpkg/docs/examples/vcpkg_android_example_cmake/.gitignore

@@ -0,0 +1 @@
+build

externals/vcpkg/docs/examples/vcpkg_android_example_cmake/CMakeLists.txt

@@ -0,0 +1,5 @@
+cmake_minimum_required(VERSION 3.0)
+project(test)
+find_package(jsoncpp CONFIG REQUIRED)
+add_library(my_lib my_lib.cpp)
+target_link_libraries(my_lib jsoncpp_lib)

externals/vcpkg/docs/examples/vcpkg_android_example_cmake/compile.sh

@@ -0,0 +1,54 @@
+#
+# 1. Check the presence of required environment variables
+#
+if [ -z ${ANDROID_NDK_HOME+x} ]; then
+  echo "Please set ANDROID_NDK_HOME"
+  exit 1
+fi
+if [ -z ${VCPKG_ROOT+x} ]; then
+  echo "Please set VCPKG_ROOT"
+  exit 1
+fi
+
+#
+# 2. Set the path to the toolchains
+#
+vcpkg_toolchain_file=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
+android_toolchain_file=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake
+
+
+#
+# 3. Select a pair "Android abi" / "vcpkg triplet"
+# Uncomment one of the four possibilities below
+#
+
+android_abi=armeabi-v7a
+vcpkg_target_triplet=arm-android
+
+# android_abi=x86
+# vcpkg_target_triplet=x86-android
+
+# android_abi=arm64-v8a
+# vcpkg_target_triplet=arm64-android
+
+# android_abi=x86_64
+# vcpkg_target_triplet=x64-android
+
+
+#
+# 4. Install the library via vcpkg
+#
+$VCPKG_ROOT/vcpkg install jsoncpp:$vcpkg_target_triplet
+
+#
+# 5. Test the build
+#
+rm -rf build
+mkdir build
+cd build 
+cmake .. \
+  -DCMAKE_TOOLCHAIN_FILE=$vcpkg_toolchain_file \
+  -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=$android_toolchain_file \
+  -DVCPKG_TARGET_TRIPLET=$vcpkg_target_triplet \
+  -DANDROID_ABI=$android_abi
+make

externals/vcpkg/docs/examples/vcpkg_android_example_cmake/my_lib.cpp

@@ -0,0 +1,8 @@
+#include <json/json.h>
+
+int answer()
+{
+  Json::Value meaning_of;
+  meaning_of["everything"] = 42;
+  return meaning_of["everything"].asInt();
+}

externals/vcpkg/docs/examples/vcpkg_android_example_cmake_script/.gitignore

@@ -0,0 +1 @@
+build

externals/vcpkg/docs/examples/vcpkg_android_example_cmake_script/CMakeLists.txt

@@ -0,0 +1,13 @@
+cmake_minimum_required(VERSION 3.0)
+
+# if -DVCPKG_TARGET_ANDROID=ON is specified when invoking cmake, load cmake/vcpkg_android.cmake
+# !!! Important: place this line before calling project() !!!
+if (VCPKG_TARGET_ANDROID)
+    include("cmake/vcpkg_android.cmake")
+endif()
+
+project(test)
+
+find_package(jsoncpp CONFIG REQUIRED)
+add_library(my_lib my_lib.cpp)
+target_link_libraries(my_lib JsonCpp::JsonCpp)

externals/vcpkg/docs/examples/vcpkg_android_example_cmake_script/cmake/vcpkg_android.cmake

@@ -0,0 +1,99 @@
+#
+# vcpkg_android.cmake 
+#
+# Helper script when using vcpkg with cmake. It should be triggered via the variable VCPKG_TARGET_ANDROID
+#
+# For example:
+# if (VCPKG_TARGET_ANDROID)
+#     include("cmake/vcpkg_android.cmake")
+# endif()
+# 
+# This script will:
+# 1 & 2. check the presence of needed env variables: ANDROID_NDK_HOME and VCPKG_ROOT
+# 3. set VCPKG_TARGET_TRIPLET according to ANDROID_ABI
+# 4. Combine vcpkg and Android toolchains by setting CMAKE_TOOLCHAIN_FILE 
+#    and VCPKG_CHAINLOAD_TOOLCHAIN_FILE
+
+# Note: VCPKG_TARGET_ANDROID is not an official Vcpkg variable. 
+# it is introduced for the need of this script
+
+if (VCPKG_TARGET_ANDROID)
+
+    #
+    # 1. Check the presence of environment variable ANDROID_NDK_HOME
+    #
+    if (NOT DEFINED ENV{ANDROID_NDK_HOME})
+        message(FATAL_ERROR "
+        Please set an environment variable ANDROID_NDK_HOME
+        For example:
+        export ANDROID_NDK_HOME=/home/your-account/Android/Sdk/ndk-bundle
+        Or:
+        export ANDROID_NDK_HOME=/home/your-account/Android/android-ndk-r21b
+        ")
+    endif()
+
+    #
+    # 2. Check the presence of environment variable VCPKG_ROOT
+    #
+    if (NOT DEFINED ENV{VCPKG_ROOT})
+        message(FATAL_ERROR "
+        Please set an environment variable VCPKG_ROOT
+        For example:
+        export VCPKG_ROOT=/path/to/vcpkg
+        ")
+    endif()
+
+
+    #
+    # 3. Set VCPKG_TARGET_TRIPLET according to 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                  |
+    #
+    # The variable must be stored in the cache in order to successfully the two toolchains. 
+    #
+    if (ANDROID_ABI MATCHES "arm64-v8a")
+        set(VCPKG_TARGET_TRIPLET "arm64-android" CACHE STRING "" FORCE)
+    elseif(ANDROID_ABI MATCHES "armeabi-v7a")
+        set(VCPKG_TARGET_TRIPLET "arm-android" CACHE STRING "" FORCE)
+    elseif(ANDROID_ABI MATCHES "x86_64")
+        set(VCPKG_TARGET_TRIPLET "x64-android" CACHE STRING "" FORCE)
+    elseif(ANDROID_ABI MATCHES "x86")
+        set(VCPKG_TARGET_TRIPLET "x86-android" CACHE STRING "" FORCE)
+    else()
+        message(FATAL_ERROR "
+        Please specify ANDROID_ABI
+        For example
+        cmake ... -DANDROID_ABI=armeabi-v7a
+
+        Possible ABIs are: arm64-v8a, armeabi-v7a, x64-android, x86-android
+        ")
+    endif()
+    message("vcpkg_android.cmake: VCPKG_TARGET_TRIPLET was set to ${VCPKG_TARGET_TRIPLET}")
+
+
+    #
+    # 4. Combine vcpkg and Android toolchains
+    #
+
+    # vcpkg and android both provide dedicated toolchains:
+    #
+    # 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.
+    set(VCPKG_CHAINLOAD_TOOLCHAIN_FILE $ENV{ANDROID_NDK_HOME}/build/cmake/android.toolchain.cmake)
+    set(CMAKE_TOOLCHAIN_FILE $ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake)
+    message("vcpkg_android.cmake: CMAKE_TOOLCHAIN_FILE was set to ${CMAKE_TOOLCHAIN_FILE}")
+    message("vcpkg_android.cmake: VCPKG_CHAINLOAD_TOOLCHAIN_FILE was set to ${VCPKG_CHAINLOAD_TOOLCHAIN_FILE}")
+
+endif(VCPKG_TARGET_ANDROID)

externals/vcpkg/docs/examples/vcpkg_android_example_cmake_script/compile.sh

@@ -0,0 +1,37 @@
+# 1. Install the library via vcpkg
+# This install jsoncpp for the 4 android target ABIs and for the host computer.
+# see the correspondence between ABIs and vcpkg triplets in the table below: 
+#
+# |VCPKG_TARGET_TRIPLET       | ANDROID_ABI          |
+# |---------------------------|----------------------|
+# |arm64-android              | arm64-v8a            |
+# |arm-android                | armeabi-v7a          |
+# |x64-android                | x86_64               |
+# |x86-android                | x86                  |
+$VCPKG_ROOT/vcpkg install \
+  jsoncpp \
+  jsoncpp:arm-android \
+  jsoncpp:arm64-android \
+  jsoncpp:x86-android \
+  jsoncpp:x64-android
+
+
+# 2. Test the build
+#
+# First, select an android ABI
+# Uncomment one of the four possibilities below
+#
+android_abi=armeabi-v7a
+# android_abi=x86
+# android_abi=arm64-v8a
+# android_abi=x86_64
+
+rm -rf build 
+mkdir build && cd build 
+
+# DVCPKG_TARGET_ANDROID will load vcpkg_android.cmake,
+# which will then load the android + vcpkg toolchains.
+cmake .. \
+  -DVCPKG_TARGET_ANDROID=ON \
+  -DANDROID_ABI=$android_abi
+make

externals/vcpkg/docs/examples/vcpkg_android_example_cmake_script/my_lib.cpp

@@ -0,0 +1,8 @@
+#include <json/json.h>
+
+int answer()
+{
+  Json::Value meaning_of;
+  meaning_of["everything"] = 42;
+  return meaning_of["everything"].asInt();
+}

externals/vcpkg/docs/examples/versioning.getting-started.md

@@ -0,0 +1,249 @@
+# Getting started with versioning
+
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/examples/versioning.getting-started.md).**
+
+Vcpkg lets you take control of which version of packages to install in your projects using manifests. 
+
+## Using versions with manifests
+
+Let's start with creating a simple CMake project that depends on `fmt` and `zlib`.
+
+Create a folder with the following files:
+
+**vcpkg.json**
+```json
+{
+    "name": "versions-test",
+    "version": "1.0.0",
+    "dependencies": [
+        {
+            "name": "fmt",
+            "version>=": "7.1.3#1"
+        }, 
+        "zlib"
+    ],
+    "builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc"
+}
+```
+
+**main.cpp**
+```c++
+#include <fmt/core.h>
+#include <zlib.h>
+
+int main()
+{
+    fmt::print("fmt version is {}\n"
+               "zlib version is {}\n", 
+               FMT_VERSION, ZLIB_VERSION);
+    return 0;
+}
+```
+
+**CMakeLists.txt**
+```CMake
+cmake_minimum_required(VERSION 3.18)
+
+project(versionstest CXX)
+
+add_executable(main main.cpp)
+
+find_package(ZLIB REQUIRED)
+find_package(fmt CONFIG REQUIRED)
+target_link_libraries(main PRIVATE ZLIB::ZLIB fmt::fmt)
+```
+
+And now we build and run our project with CMake:
+
+1. Create the build directory for the project.
+```
+PS D:\versions-test> mkdir build
+PS D:\versions-test> cd build
+```
+
+2. Configure CMake.  
+```
+PS D:\versions-test\build> cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=D:/vcpkg/scripts/buildsystems/vcpkg.cmake ..
+-- Running vcpkg install
+Detecting compiler hash for triplet x86-windows...
+The following packages will be built and installed:
+    fmt[core]:x64-windows -> 7.1.3#1 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\fmt\4f8427eb0bd40da1856d4e67bde39a4fda689d72
+    vcpkg-cmake[core]:x64-windows -> 2021-02-26 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\vcpkg-cmake\51896aa8073adb5c8450daa423d03eedf0dfc61f
+    vcpkg-cmake-config[core]:x64-windows -> 2021-02-26 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\vcpkg-cmake-config\d255b3d566a8861dcc99a958240463e678528066
+    zlib[core]:x64-windows -> 1.2.11#9 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4
+...
+```
+
+3. Build the project.
+```
+PS D:\versions-test\build> cmake --build .
+[2/2] Linking CXX executable main.exe
+```
+
+4. Run it!
+```
+PS D:\versions-test\build> ./main.exe
+fmt version is 70103
+zlib version is 1.2.11
+```
+
+Take a look at the output:
+
+```
+fmt[core]:x86-windows -> 7.1.3#1 -- D:\vcpkg\buildtrees\versioning\versions\fmt\4f8427eb0bd40da1856d4e67bde39a4fda689d72
+...
+zlib[core]:x86-windows -> 1.2.11#9 -- D:\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4
+```
+
+Instead of using the portfiles in `ports/`, vcpkg is checking out the files for each version in `buildtrees/versioning/versions/`. The files in `ports/` are still used when running vcpkg in classic mode.
+
+_NOTE: Output from vcpkg while configuring CMake is only available when using CMake version `3.18` or newer. If you're using an older CMake you can check the `vcpkg-manifest-install.log` file in your build directory instead._
+
+Read our [manifests announcement blog post](https://devblogs.microsoft.com/cppblog/vcpkg-accelerate-your-team-development-environment-with-binary-caching-and-manifests/#using-manifests-with-msbuild-projects) to learn how to use manifests with MSBuild.
+
+### Manifest changes
+If you have used manifests before you will notice that there are some new JSON properties. Let's review these changes:
+
+#### **`version`**
+```json
+{
+    "name": "versions-test",
+    "version": "1.0.0"
+}
+```
+
+This is your project's version declaration. Previously, you could only declare versions for your projects using the `version-string` property. Now that versioning has come around, vcpkg is aware of some new versioning schemes.
+
+Version scheme   | Description
+---------------- | ---------------
+`version`        | Dot-separated numerics: `1.0.0.5`.
+`version-semver` | Compliant [semantic versions](https://semver.org): `1.2.0` and `1.2.0-rc`.
+`version-date`   | Dates in `YYYY-MM-DD` format: `2021-01-01`
+`version-string` | Arbitrary strings: `vista`, `candy`.
+
+#### **`version>=`** 
+```json
+{
+    "dependencies": [
+        { "name": "fmt", "version>=": "7.1.3" },
+        "zlib"
+    ]
+}
+```
+
+This property is used to express minimum version constraints, it is allowed only as part of the `"dependencies"` declarations. In our example we set an explicit constraint on version `7.1.3#1` of `fmt`. 
+
+Vcpkg is allowed to upgrade this constraint if a transitive dependency requires a newer version. For example, if `zlib` were to declare a dependency on `fmt` version `7.1.4` then vcpkg would install `7.1.4` instead.
+
+Vcpkg uses a minimum version approach, in our example, even if `fmt` version `8.0.0` were to be released, vcpkg would still install version `7.1.3#1` as that is the minimum version that satisfies the constraint. The advantages of this approach are that you don't get unexpected dependency upgrades when you update vcpkg and you get reproducible builds (in terms of version used) as long as you use the same manifest. 
+
+If you want to upgrade your dependencies, you can bump the minimum version constraint or use a newer baseline.
+
+#### **`builtin-baseline`**
+
+```json
+{ "builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc" }
+```
+
+This field declares the versioning baseline for all ports. Setting a baseline is required to enable versioning, otherwise you will get the current versions on the ports directory. You can run 'git rev-parse HEAD' to get the current commit of vcpkg and set it as the builtin-baseline. See the [`builtin-baseline` documentation](../users/versioning.md#builtin-baseline) for more information.
+
+In our example, you can notice that we do not declare a version constraint for `zlib`; instead, the version is taken from the baseline. Internally, vcpkg will look in commit `3426db05b996481ca31e95fff3734cf23e0f51bc` to find out what version of `zlib` was the latest at that point in time (in our case it was `1.2.11#9`).
+
+During version resolution, baseline versions are treated as minimum version constraints. If you declare an explicit constraint that is lower than a baseline version, the explicit constraint will be upgraded to the baseline version. 
+
+For example, if we modified our dependencies like this:
+```json
+{ "dependencies": [
+    {
+        "name": "fmt",
+        "version>=": "7.1.3#1"
+    },
+    {
+        "name": "zlib",
+        "version>=": "1.2.11#7"
+    }
+] }
+```
+
+_NOTE: The value `1.2.11#7` represents version `1.2.11`, port version `7`._
+
+Since the baseline introduces a minimum version constraint for `zlib` at `1.2.11#9` and a higher version does satisfy the minimum version constraint for `1.2.11#7`, vcpkg is allowed to upgrade it. 
+
+Baselines are also a convenient mechanism to upgrade multiple versions at a time, for example, if you wanted to depend on multiple `boost` libraries, it is more convenient to set the `baseline` once than declaring a version constraint on each package.
+
+But what if you want to pin a version older than the baseline? 
+
+#### **`overrides`**
+
+Since baselines establish a version floor for all packages and explicit constraints get upgraded when they are lower than the baseline, we need another mechanism to downgrade versions past the baseline.
+
+The mechanism vcpkg provides for that scenario is `overrides`. When an override is declared on a package, vcpkg will ignore all other version constraints either directly declared in the manifest or from transitive dependencies. In short, `overrides` will force vcpkg to use the exact version declared, period.
+
+Let's modify our example once more, this time to force vcpkg to use version `6.0.0` of `fmt`.
+
+```json
+{
+    "name": "versions-test",
+    "version": "1.0.0",
+    "dependencies": [
+        {
+            "name": "fmt",
+            "version>=": "7.1.3#1"
+        },
+        {
+            "name": "zlib",
+            "version>=": "1.2.11#7"
+        }
+    ],
+    "builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc",
+    "overrides": [
+        {
+            "name": "fmt",
+            "version": "6.0.0"
+        }
+    ]
+}
+```
+
+Rebuild our project:
+
+```
+PS D:\versions-test\build> rm ./CMakeCache.txt
+PS D:\versions-test\build> rm -r ./vcpkg_installed
+PS D:\versions-test\build> cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=D:/vcpkg/scripts/buildsystems/vcpkg.cmake ..
+-- Running vcpkg install
+Detecting compiler hash for triplet x86-windows...
+The following packages will be built and installed:
+    fmt[core]:x86-windows -> 6.0.0 -- D:\vcpkg\buildtrees\versioning\versions\fmt\d99b6a35e1406ba6b6e09d719bebd086f83ed5f3
+    zlib[core]:x86-windows -> 1.2.11#9 -- D:\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4
+...
+PS D:\versions-test\build> cmake --build .
+[2/2] Linking CXX executable main.exe
+```
+
+And run it!
+```
+PS D:\versions-test\build> .\main.exe
+fmt version is 60000
+zlib version is 1.2.11
+```
+
+Notice how the `fmt` is now at version `6.0.0` just like we wanted.
+
+## Versions and custom ports
+
+The last thing to discuss is how overlay ports interact with versioning resolution. The answer is: they don't.
+
+Going into more detail, when you provide an overlay for a port, vcpkg will always use the overlay port without caring what version is contained in it. The reasons are two-fold: (1) it is consistent with the existing behavior of overlay ports of completely masking the existing port, and (2) overlay ports do not (and are not expected to) provide enough information to power vcpkg's versioning feature.
+
+If you want to have flexible port customization along with versioning, you should consider making your own custom registry. See our [registries specification for more details](../specifications/registries.md).
+
+## Further reading
+
+If you're interested in delving deeper into the details of how versioning works we recommended that you read the [original versioning specification](../specifications/versioning.md) and the [implementation details](../users/versioning.implementation-details.md).
+
+See also:
+
+* [Versioning docs](../users/versioning.md)
+* [Original specification](../specifications/versioning.md)
+* [Versioning implementation details](../users/versioning.implementation-details.md)