Merge branch 'master' of https://github.com/microsoft/vcpkg into dev/philc/4564

19 files changed, 342 insertions, 43 deletions

diff --git a/docs/about/faq.md b/docs/about/faq.md
index 0178e051a..b7c9d67c8 100644
--- a/docs/about/faq.md
+++ b/docs/about/faq.md
@@ -10,12 +10,12 @@ Yes! See [the `export` command](../users/integration.md#export).
 The `vcpkg update` command lists all packages which are out-of-sync with your current portfiles. To update a package, follow the instructions in the command.
 
 ## How do I get more libraries?
-The list of libraries is enumerated from the [`ports\`](https://github.com/Microsoft/vcpkg/blob/master/ports) directory. By design, you can add and remove libraries from this directory as you see fit for yourself or your company -- see [Example #2](../examples/packaging-zlib.md).
+The list of libraries is enumerated from the [`ports\`](https://github.com/Microsoft/vcpkg/blob/master/ports) directory. By design, you can add and remove libraries from this directory as you see fit for yourself or your company -- see our examples on packaging [zipfiles](../examples/packaging-zipfiles.md) and [GitHub repos](../examples/packaging-github-repos.md).
 
 We recommend cloning directly from [GitHub](https://github.com/microsoft/vcpkg) and using `git pull` to update the list of portfiles. Once you've updated your portfiles, `vcpkg update` will indicate any installed libraries that are now out of date.
 
 ## Can I build a private library with this tool?
-Yes. Follow [our Packaging zlib Example](../examples/packaging-zlib.md) for creating a portfile using a fake URL. Then, either pre-seed the `downloads\` folder with a zip containing your private sources or replace the normal calls to `vcpkg_download_distfile` and `vcpkg_extract_source_archive` with functions that unpack your source code.
+Yes. Follow [our packaging zlib Example](../examples/packaging-zipfiles.md) for creating a portfile using a fake URL. Then, either pre-seed the `downloads\` folder with a zip containing your private sources or replace the normal calls to `vcpkg_download_distfile` and `vcpkg_extract_source_archive` with functions that unpack your source code.
 
 ## Can I use a prebuilt private library with this tool?
 Yes. The `portfile.cmake` for a library is fundamentally a script that places the headers and binaries into the correct arrangement in the `${CURRENT_PACKAGES_DIR}`, so to pull in prebuilt binaries you can write a portfile which directly downloads and arranges the files.
diff --git a/docs/examples/using-sqlite.md b/docs/examples/installing-and-using-packages.md
index 35da141d0..73f9d29a9 100644
--- a/docs/examples/using-sqlite.md
+++ b/docs/examples/installing-and-using-packages.md
@@ -1,4 +1,4 @@
-# Example: Using Sqlite
+## Installing and Using Packages Example: SQLite
 
   - [Step 1: Install](#install)
   - [Step 2: Use](#use)
@@ -10,7 +10,7 @@
 <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:
+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
@@ -82,14 +82,15 @@ 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 2015 or Visual Studio 2017 and the library will be automatically available. For Sqlite, you can try out their [C/C++ sample](https://sqlite.org/quickstart.html).
+You can now simply use File -> New Project in Visual Studio 2015 or Visual Studio 2017 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`.
+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 2017 you can define `CMAKE_TOOLCHAIN_FILE` by adding a "variables" section to each of your `CMakeSettings.json` configurations:
 
@@ -109,6 +110,7 @@ If you are using CMake through Open Folder with Visual Studio 2017 you can defin
   }]
 }
 ```
+*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
diff --git a/docs/examples/packaging-github-repos.md b/docs/examples/packaging-github-repos.md
new file mode 100644
index 000000000..af2e6141a
--- /dev/null
+++ b/docs/examples/packaging-github-repos.md
@@ -0,0 +1,59 @@
+## Packaging Github Repos Example: libogg

+### Create the CONTROL file

+The `CONTROL` file is a simple set of fields describing the package's metadata.

+

+*For libogg, we'll create the file `ports\libogg\CONTROL` with the following contents:*

+```no-highlight

+Source: libogg

+Version: 1.3.3

+Description: Ogg is a multimedia container format, and the native file and stream format for the Xiph.org multimedia codecs.

+```

+

+### Create the portfile

+`portfile.cmake` describes how to build and install the package. First we include `vcpkg_common_functions` to give us utilities for carrying this out:

+

+```no-highlight

+include(vcpkg_common_functions)

+```

+

+Now we download the project from Github with [`vcpkg_from_github`](../maintainers/vcpkg_from_github.md):

+

+```no-highlight

+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 `1`, 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:

+

+```no-highlight

+vcpkg_configure_cmake(

+    SOURCE_PATH ${SOURCE_PATH}

+    PREFER_NINJA

+)

+vcpkg_install_cmake()

+file(INSTALL ${SOURCE_PATH}/COPYING DESTINATION ${CURRENT_PACKAGES_DIR}/share/libogg RENAME copyright)

+```

+

+Check the documentation for [`vcpkg_configure_cmake`](../maintainers/vcpkg_configure_cmake.md) and [`vcpkg_install_cmake`](../maintainers/vcpkg_install_cmake.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

+    - cppunit

+    - mpg123

+- Non-CMake, custom buildsystem

+    - openssl

+    - ffmpeg

diff --git a/docs/examples/packaging-zlib.md b/docs/examples/packaging-zipfiles.md
index 1d61cfee1..ed63637fd 100644
--- a/docs/examples/packaging-zlib.md
+++ b/docs/examples/packaging-zipfiles.md
@@ -1,4 +1,4 @@
-## Example 2: Packaging zlib
+## Packaging Zipfiles 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.
diff --git a/docs/examples/patching-libpng.md b/docs/examples/patching.md
index 2337b73da..b152231e2 100644
--- a/docs/examples/patching-libpng.md
+++ b/docs/examples/patching.md
@@ -1,4 +1,4 @@
-## Example 3: Patching libpng to work for x86-uwp
+## Patching Example: Patching libpng to work for x86-uwp
 
 ### Initial error logs
 First, try building:
@@ -147,11 +147,11 @@ Finally, we need to apply the patch after extracting the source.
 ```cmake
 # ports\libpng\portfile.cmake
 ...
-vcpkg_extract_source_archive(${ARCHIVE})
-
-vcpkg_apply_patches(
-    SOURCE_PATH ${CURRENT_BUILDTREES_DIR}/src/libpng-1.6.24
-    PATCHES "${CMAKE_CURRENT_LIST_DIR}/use-abort-on-all-platforms.patch"
+vcpkg_extract_source_archive_ex(
+  OUT_SOURCE_PATH SOURCE_PATH
+  ARCHIVE ${ARCHIVE}
+  PATCHES 
+    "use-abort-on-all-platforms.patch"
 )
 
 vcpkg_configure_cmake(
diff --git a/docs/index.md b/docs/index.md
index 90245d36a..cde241e92 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -2,18 +2,18 @@
 
 Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This tool and ecosystem are constantly evolving; your involvement are vital to its success!
 
-- [How to use Sqlite in your application](examples/using-sqlite.md)
-
 ### Examples
 
-- [Example 1: Using Sqlite](examples/using-sqlite.md)
-- [Example 2: Packaging zlib](examples/packaging-zlib.md)
-- [Example 3: Patching libpng for x86-uwp](examples/patching-libpng.md)
+- [Installing and Using Packages Example: sqlite](examples/installing-and-using-packages.md)
+- [Packaging Zipfiles Example: zlib](examples/packaging-zipfiles.md)
+- [Packaging GitHub Repositories Example: libogg](examples/packaging-github-repos.md)
+- [Patching Example: Patching libpng to work for x86-uwp](examples/patching.md)
 
 ### User Help
 
 - [Integration with build systems](users/integration.md)
 - [Triplet files](users/triplets.md)
+- [Configuration and Environment](users/config-environment.md)
 
 ### Maintainer help
 
@@ -23,6 +23,7 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too
 ### Specifications
 
 - [Export](specifications/export-command.md)
+- [Feature Packages](specifications/feature-packages.md)
 
 ### Blog posts
 - [Announcing a single C++ library manager for Linux, macOS and Windows: Vcpkg](https://blogs.msdn.microsoft.com/vcblog/2018/04/24/announcing-a-single-c-library-manager-for-linux-macos-and-windows-vcpkg/)
diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
index f9476d3a7..f159f7f64 100644
--- a/docs/maintainers/portfile-functions.md
+++ b/docs/maintainers/portfile-functions.md
@@ -2,19 +2,24 @@
 
 # Portfile helper functions

 - [vcpkg\_acquire\_msys](vcpkg_acquire_msys.md)

+- [vcpkg\_add\_to\_path](vcpkg_add_to_path.md)

 - [vcpkg\_apply\_patches](vcpkg_apply_patches.md)

 - [vcpkg\_build\_cmake](vcpkg_build_cmake.md)

 - [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md)

 - [vcpkg\_check\_linkage](vcpkg_check_linkage.md)

+- [vcpkg\_clean\_msbuild](vcpkg_clean_msbuild.md)

 - [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md)

 - [vcpkg\_copy\_pdbs](vcpkg_copy_pdbs.md)

 - [vcpkg\_copy\_tool\_dependencies](vcpkg_copy_tool_dependencies.md)

 - [vcpkg\_download\_distfile](vcpkg_download_distfile.md)

 - [vcpkg\_execute\_required\_process](vcpkg_execute_required_process.md)

 - [vcpkg\_extract\_source\_archive](vcpkg_extract_source_archive.md)

+- [vcpkg\_extract\_source\_archive\_ex](vcpkg_extract_source_archive_ex.md)

 - [vcpkg\_find\_acquire\_program](vcpkg_find_acquire_program.md)

 - [vcpkg\_from\_bitbucket](vcpkg_from_bitbucket.md)

+- [vcpkg\_from\_git](vcpkg_from_git.md)

 - [vcpkg\_from\_github](vcpkg_from_github.md)

 - [vcpkg\_from\_gitlab](vcpkg_from_gitlab.md)

 - [vcpkg\_install\_cmake](vcpkg_install_cmake.md)

 - [vcpkg\_install\_msbuild](vcpkg_install_msbuild.md)

+- [vcpkg\_test\_cmake](vcpkg_test_cmake.md)

diff --git a/docs/maintainers/vcpkg_add_to_path.md b/docs/maintainers/vcpkg_add_to_path.md
new file mode 100644
index 000000000..3657a5ea7
--- /dev/null
+++ b/docs/maintainers/vcpkg_add_to_path.md
@@ -0,0 +1,20 @@
+# vcpkg_add_to_path
+
+Add a directory to the PATH environment variable
+
+## Usage
+```cmake
+vcpkg_add_to_path([PREPEND] <${PYTHON3_DIR}>)
+```
+
+## Parameters
+### <positional>
+The directory to add
+
+### PREPEND
+Prepends the directory.
+
+The default is to append.
+
+## Source
+[scripts/cmake/vcpkg_add_to_path.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_add_to_path.cmake)

diff --git a/docs/maintainers/vcpkg_clean_msbuild.md b/docs/maintainers/vcpkg_clean_msbuild.md
new file mode 100644
index 000000000..39d07077b
--- /dev/null
+++ b/docs/maintainers/vcpkg_clean_msbuild.md
@@ -0,0 +1,15 @@
+# vcpkg_clean_msbuild
+
+Clean intermediate files generated by `vcpkg_install_msbuild()`.
+
+## Usage
+```cmake
+vcpkg_clean_msbuild()
+```
+
+## Examples
+
+* [xalan-c](https://github.com/Microsoft/vcpkg/blob/master/ports/xalan-c/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_clean_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_clean_msbuild.cmake)

diff --git a/docs/maintainers/vcpkg_extract_source_archive.md b/docs/maintainers/vcpkg_extract_source_archive.md
index 104032ffc..4971df960 100644
--- a/docs/maintainers/vcpkg_extract_source_archive.md
+++ b/docs/maintainers/vcpkg_extract_source_archive.md
@@ -1,6 +1,6 @@
 # vcpkg_extract_source_archive
 
-Extract an archive into the source directory.
+Extract an archive into the source directory. Deprecated in favor of [`vcpkg_extract_source_archive_ex`](vcpkg_extract_source_archive_ex.md).
 
 ## Usage
 ```cmake
diff --git a/docs/maintainers/vcpkg_extract_source_archive_ex.md b/docs/maintainers/vcpkg_extract_source_archive_ex.md
new file mode 100644
index 000000000..92c90b296
--- /dev/null
+++ b/docs/maintainers/vcpkg_extract_source_archive_ex.md
@@ -0,0 +1,52 @@
+# vcpkg_extract_source_archive_ex
+
+Extract an archive into the source directory. Replaces [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md).
+
+## Usage
+```cmake
+vcpkg_extract_source_archive_ex(
+    OUT_SOURCE_PATH <SOURCE_PATH>
+    ARCHIVE <${ARCHIVE}>
+    [REF <1.0.0>]
+    [NO_REMOVE_ONE_LEVEL]
+    [WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/src>]
+    [PATCHES <a.patch>...]
+)
+```
+## Parameters
+### OUT_SOURCE_PATH
+Specifies the out-variable that will contain the extracted location.
+
+This should be set to `SOURCE_PATH` by convention.
+
+### ARCHIVE
+The full path to the archive to be extracted.
+
+This is usually obtained from calling [`vcpkg_download_distfile`](vcpkg_download_distfile.md).
+
+### REF
+A friendly name that will be used instead of the filename of the archive.
+
+By convention, this is set to the version number or tag fetched
+
+### WORKING_DIRECTORY
+If specified, the archive will be extracted into the working directory instead of `${CURRENT_BUILDTREES_DIR}/src/`.
+
+Note that the archive will still be extracted into a subfolder underneath that directory (`${WORKING_DIRECTORY}/${REF}-${HASH}/`).
+
+### PATCHES
+A list of patches to be applied to the extracted sources.
+
+Relative paths are based on the port directory.
+
+### NO_REMOVE_ONE_LEVEL
+Specifies that the default removal of the top level folder should not occur.
+
+## Examples
+
+* [bzip2](https://github.com/Microsoft/vcpkg/blob/master/ports/bzip2/portfile.cmake)
+* [sqlite3](https://github.com/Microsoft/vcpkg/blob/master/ports/sqlite3/portfile.cmake)
+* [cairo](https://github.com/Microsoft/vcpkg/blob/master/ports/cairo/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_extract_source_archive_ex.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive_ex.cmake)

diff --git a/docs/maintainers/vcpkg_from_bitbucket.md b/docs/maintainers/vcpkg_from_bitbucket.md
index c8850b725..7e699f8ea 100644
--- a/docs/maintainers/vcpkg_from_bitbucket.md
+++ b/docs/maintainers/vcpkg_from_bitbucket.md
@@ -11,6 +11,7 @@ vcpkg_from_bitbucket(
     [REF <v2.0.0>]
     [SHA512 <45d0d7f8cc350...>]
     [HEAD_REF <master>]
+    [PATCHES <patch1.patch> <patch2.patch>...]
 )
 ```
 
@@ -40,6 +41,11 @@ The unstable git commit-ish (ideally a branch) to pull for `--head` builds.
 
 For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms.
 
+### PATCHES
+A list of patches to be applied to the extracted sources.
+
+Relative paths are based on the port directory.
+
 ## Notes:
 At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present.
 
diff --git a/docs/maintainers/vcpkg_from_git.md b/docs/maintainers/vcpkg_from_git.md
new file mode 100644
index 000000000..6b24a558d
--- /dev/null
+++ b/docs/maintainers/vcpkg_from_git.md
@@ -0,0 +1,48 @@
+# vcpkg_from_git
+
+Download and extract a project from git
+
+## Usage:
+```cmake
+vcpkg_from_git(
+    OUT_SOURCE_PATH <SOURCE_PATH>
+    URL <https://android.googlesource.com/platform/external/fdlibm>
+    REF <59f7335e4d...>
+    SHA512 <abcdef123...>
+    [PATCHES <patch1.patch> <patch2.patch>...]
+)
+```
+
+## Parameters:
+### OUT_SOURCE_PATH
+Specifies the out-variable that will contain the extracted location.
+
+This should be set to `SOURCE_PATH` by convention.
+
+### URL
+The url of the git repository.
+
+### SHA512
+The SHA512 hash that should match the archive form of the commit.
+
+This is most easily determined by first setting it to `0`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.
+
+### REF
+A stable git commit-ish (ideally a tag or commit) that will not change contents. **This should not be a branch.**
+
+For repositories without official releases, this can be set to the full commit id of the current latest master.
+
+### PATCHES
+A list of patches to be applied to the extracted sources.
+
+Relative paths are based on the port directory.
+
+## Notes:
+`OUT_SOURCE_PATH`, `REF`, `SHA512`, and `URL` must be specified.
+
+## Examples:
+
+* [fdlibm](https://github.com/Microsoft/vcpkg/blob/master/ports/fdlibm/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_from_git.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_git.cmake)

diff --git a/docs/maintainers/vcpkg_from_gitlab.md b/docs/maintainers/vcpkg_from_gitlab.md
index 69deea933..bc312f37a 100644
--- a/docs/maintainers/vcpkg_from_gitlab.md
+++ b/docs/maintainers/vcpkg_from_gitlab.md
@@ -11,6 +11,7 @@ vcpkg_from_gitlab(
     [REF <v10.7.3>]
     [SHA512 <45d0d7f8cc350...>]
     [HEAD_REF <master>]
+    [PATCHES <patch1.patch> <patch2.patch>...]
 )
 ```
 
@@ -45,6 +46,11 @@ The unstable git commit-ish (ideally a branch) to pull for `--head` builds.
 
 For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms.
 
+### PATCHES
+A list of patches to be applied to the extracted sources.
+
+Relative paths are based on the port directory.
+
 ## Notes:
 At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present.
 
diff --git a/docs/maintainers/vcpkg_install_msbuild.md b/docs/maintainers/vcpkg_install_msbuild.md
index 76578c2ef..1de68ce70 100644
--- a/docs/maintainers/vcpkg_install_msbuild.md
+++ b/docs/maintainers/vcpkg_install_msbuild.md
@@ -52,12 +52,16 @@ Indicates that top-level include files (e.g. `include/zlib.h`) should be allowed
 ### REMOVE_ROOT_INCLUDES
 Indicates that top-level include files (e.g. `include/Makefile.am`) should be removed.
 
+### SKIP_CLEAN
+Indicates that the intermediate files should not be removed.
+
+Ports using this option should later call [`vcpkg_clean_msbuild()`](vcpkg_clean_msbuild.md) to manually clean up.
+
 ### RELEASE_CONFIGURATION
 The configuration (``/p:Configuration`` msbuild parameter) used for Release builds.
 
 ### DEBUG_CONFIGURATION
-The configuration (``/p:Configuration`` msbuild parameter)
-used for Debug builds.
+The configuration (``/p:Configuration`` msbuild parameter) used for Debug builds.
 
 ### TARGET_PLATFORM_VERSION
 The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
@@ -82,6 +86,7 @@ Additional options passed to msbuild for Debug builds. These are in addition to
 
 ## Examples
 
+* [xalan-c](https://github.com/Microsoft/vcpkg/blob/master/ports/xalan-c/portfile.cmake)
 * [libimobiledevice](https://github.com/Microsoft/vcpkg/blob/master/ports/libimobiledevice/portfile.cmake)
 
 ## Source
diff --git a/docs/maintainers/vcpkg_test_cmake.md b/docs/maintainers/vcpkg_test_cmake.md
new file mode 100644
index 000000000..15b3ad797
--- /dev/null
+++ b/docs/maintainers/vcpkg_test_cmake.md
@@ -0,0 +1,20 @@
+# vcpkg_test_cmake
+
+Tests a built package for CMake `find_package()` integration.
+
+## Usage:
+```cmake
+vcpkg_test_cmake(PACKAGE_NAME <name> [MODULE])
+```
+
+## Parameters:
+
+### PACKAGE_NAME
+The expected name to find with `find_package()`.
+
+### MODULE
+Indicates that the library expects to be found via built-in CMake targets.
+
+
+## Source
+[scripts/cmake/vcpkg_test_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_test_cmake.cmake)

diff --git a/docs/users/config-environment.md b/docs/users/config-environment.md
new file mode 100644
index 000000000..f25df89a3
--- /dev/null
+++ b/docs/users/config-environment.md
@@ -0,0 +1,42 @@
+## Environment and Configuration

+

+### 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.

+

+Non-exhaustive list of off-by-default features:

+

+- `binarycaching`

+

+#### 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` triplet setting](triplets.md#VCPKG_VISUAL_STUDIO_PATH).

+

+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_FORCE_SYSTEM_BINARIES

+

+This environment variable, if set, suppresses the downloading of CMake and Ninja and forces the use of the system binaries.

diff --git a/docs/users/integration.md b/docs/users/integration.md
index ce52abe23..6d56c7c70 100644
--- a/docs/users/integration.md
+++ b/docs/users/integration.md
@@ -35,7 +35,7 @@ cmake ../my/project -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.c
 ```
 Projects configured with the Vcpkg toolchain file will have the appropriate Vcpkg folders added to the cmake search paths. This makes all libraries available to be found through `find_package()`, `find_path()`, and `find_library()`.
 
-See [Example: Using Sqlite](../examples/using-sqlite.md) for a fully worked example using our CMake toolchain.
+See [Installing and Using Packages Example: sqlite](../examples/installing-and-using-packages.md) for a fully worked example using our CMake toolchain.
 
 Note that we do not automatically add ourselves to your compiler include paths. To use a header-only library, simply use `find_path()`, which will correctly work on all platforms:
 ```cmake
@@ -50,7 +50,7 @@ The `CMAKE_TOOLCHAIN_FILE` setting simply must be set before the `project()` dir
 
 ```cmake
 if(DEFINED ENV{VCPKG_ROOT} AND NOT DEFINED CMAKE_TOOLCHAIN_FILE)
-  set(CMAKE_TOOLCHAIN_FILE "${VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
+  set(CMAKE_TOOLCHAIN_FILE "$ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
       CACHE STRING "")
 endif()
 
@@ -135,9 +135,16 @@ To override the automatically chosen [triplet][], you can specify the MSBuild pr
 ```
 
 #### With CMake
-Simply set `VCPKG_TARGET_TRIPLET` on the configure line.
+You can set `VCPKG_TARGET_TRIPLET` on the configure line:
 ```no-highlight
 cmake ../my/project -DVCPKG_TARGET_TRIPLET=x64-windows-static -DCMAKE_TOOLCHAIN_FILE=...
 ```
+If you use `VCPKG_DEFAULT_TRIPLET` [environment variable](config-environment.md) to contoll the unqualified triplet in vcpkg command lines you can default `VCPKG_TARGET_TRIPLET` in CMake like [Using an environment variable instead of a command line option](#using-an-environment-variable-instead-of-a-command-line-option):
+
+```cmake
+if(DEFINED ENV{VCPKG_DEFAULT_TRIPLET} AND NOT DEFINED VCPKG_TARGET_TRIPLET)
+  set(VCPKG_TARGET_TRIPLET "$ENV{VCPKG_DEFAULT_TRIPLET}" CACHE STRING "")
+endif()
+```
 
 [triplet]: triplets.md
diff --git a/docs/users/triplets.md b/docs/users/triplets.md
index 9ff372aed..87fa72fd3 100644
--- a/docs/users/triplets.md
+++ b/docs/users/triplets.md
@@ -33,24 +33,6 @@ Valid options include any CMake system name, such as:
 - `Darwin` (Mac OSX)
 - `Linux` (Linux)
 
-### VCPKG_PLATFORM_TOOLSET
-Specifies the VS-based C/C++ compiler toolchain to use.
-
-This can be set to `v141`, `v140`, or left blank. If left blank, we select the latest compiler toolset available on your machine.
-
-Visual Studio 2015 platform toolset is `v140`  
-Visual Studio 2017 platform toolset is `v141`
-
-### VCPKG_VISUAL_STUDIO_PATH
-Specifies the Visual Studio installation to use.
-
-When unspecified, a Visual Studio instance is selected automatically, preferring Stable 2017, then Preview 2017, then 2015.
-
-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_CHAINLOAD_TOOLCHAIN_FILE
 Specifies an alternate CMake Toolchain file to use.
 
@@ -69,7 +51,36 @@ This option also has forms for configuration-specific and C flags:
 - `VCPKG_C_FLAGS_DEBUG`
 - `VCPKG_C_FLAGS_RELEASE`
 
-## macOS Variables
+## Windows Variables
+
+<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`.
+
+## 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.