Merge branch 'master' of https://github.com/microsoft/vcpkg into dev/grdowns/4802

6 files changed, 91 insertions, 29 deletions

diff --git a/docs/examples/installing-and-using-packages.md b/docs/examples/installing-and-using-packages.md
index 50200c877..73f9d29a9 100644
--- a/docs/examples/installing-and-using-packages.md
+++ b/docs/examples/installing-and-using-packages.md
@@ -89,7 +89,8 @@ 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/patching.md b/docs/examples/patching.md
index 98115400e..b152231e2 100644
--- a/docs/examples/patching.md
+++ b/docs/examples/patching.md
@@ -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 69dbdcd1e..cde241e92 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -2,8 +2,6 @@
 
 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!
 
-- [Installing and Using Packages Example: sqlite](examples/installing-and-using-packages.md)
-
 ### Examples
 
 - [Installing and Using Packages Example: sqlite](examples/installing-and-using-packages.md)
@@ -15,6 +13,7 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too
 
 - [Integration with build systems](users/integration.md)
 - [Triplet files](users/triplets.md)
+- [Configuration and Environment](users/config-environment.md)
 
 ### Maintainer help
 
@@ -24,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/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 fbaea41d9..6d56c7c70 100644
--- a/docs/users/integration.md
+++ b/docs/users/integration.md
@@ -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.