microsoft · ras0219-msft · Feb 9, 2019 · Feb 9, 2019 · Feb 9, 2019 · Feb 11, 2019
diff --git a/.gitignore b/.gitignore
@@ -309,3 +309,4 @@ __pycache__/
 ############################################################
 # vcpkg - End
 ############################################################
+archives
diff --git a/README.md b/README.md
@@ -42,11 +42,12 @@ For more information, see our [using a package](docs/examples/installing-and-usi
 Additional notes on macOS and Linux support can be found in the [official announcement](https://blogs.msdn.microsoft.com/vcblog/2018/04/24/announcing-a-single-c-library-manager-for-linux-macos-and-windows-vcpkg/).
 
 ## Tab-Completion / Auto-Completion
-`vcpkg` supports auto-completion of commands, package names, options etc. To enable tab-completion in Powershell, use
+`vcpkg` supports auto-completion of commands, package names, options etc in Powershell and bash. To enable tab-completion, use one of the following:
 ```
-.\vcpkg integrate powershell
+PS> .\vcpkg integrate powershell
+Linux:~/$ ./vcpkg integrate bash
 ```
-and restart Powershell.
+and restart your console.
 
 
 ## Examples

diff --git a/docs/about/faq.md b/docs/about/faq.md
@@ -26,7 +26,7 @@ To see an example of this, look at [`ports\opengl\portfile.cmake`](https://githu
 We currently target Windows Desktop (x86 and x64) as well as the Universal Windows Platform (x86, x64, and ARM). See `vcpkg help triplet` for the current list.
 
 ## Does Vcpkg run on Linux/OSX?
-Yes! We continously test on OSX and Ubuntu 16.04, however we know users have been successful with Arch, Fedora, and FreeBSD. If you have trouble with your favorite Linux distribution, let us know in an issue and we'd be happy to help!
+Yes! We continuously test on OSX and Ubuntu 16.04, however we know users have been successful with Arch, Fedora, and FreeBSD. If you have trouble with your favorite Linux distribution, let us know in an issue and we'd be happy to help!
 
 ## How do I use different versions of a library on one machine?
 Within a single instance of Vcpkg (e.g. one set of `installed\`, `packages\`, `ports\` and so forth), you can only have one version of a library installed (otherwise, the headers would conflict with each other!). For those with experience with system-wide package managers, packages in Vcpkg correspond to the `X-dev` or `X-devel` packages.

diff --git 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
@@ -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
@@ -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/maintainers/vcpkg_add_to_path.md b/docs/maintainers/vcpkg_add_to_path.md
@@ -16,5 +16,11 @@ Prepends the directory.
 
 The default is to append.
 
+## Examples:
+* [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake#L75)
+* [folly](https://github.com/Microsoft/vcpkg/blob/master/ports/folly/portfile.cmake#L15)
+* [z3](https://github.com/Microsoft/vcpkg/blob/master/ports/z3/portfile.cmake#L13)
+
+
 ## 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_build_msbuild.md b/docs/maintainers/vcpkg_build_msbuild.md
@@ -1,6 +1,6 @@
 # vcpkg_build_msbuild
 
-Build an msbuild-based project. Deprecated in favor of `vcpkg_install_msbuild()`.
+Build a msbuild-based project. Deprecated in favor of `vcpkg_install_msbuild()`.
 
 ## Usage
 ```cmake

diff --git a/docs/maintainers/vcpkg_download_distfile.md b/docs/maintainers/vcpkg_download_distfile.md
@@ -33,6 +33,11 @@ Skip SHA512 hash check for file.
 
 This switch is only valid when building with the `--head` command line flag.
 
+### HEADERS
+A list of headers to append to the download request. This can be used for authentication during a download.
+
+Headers should be specified as "<header-name>: <header-value>".
+
 ## Notes
 The helper [`vcpkg_from_github`](vcpkg_from_github.md) should be used for downloading from GitHub projects.
 

diff --git a/docs/maintainers/vcpkg_from_gitlab.md b/docs/maintainers/vcpkg_from_gitlab.md
@@ -56,6 +56,11 @@ At least one of `REF` and `HEAD_REF` must be specified, however it is preferable
 
 This exports the `VCPKG_HEAD_VERSION` variable during head builds.
 
+## Examples:
+* [curl][https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake#L75]
+* [folly](https://github.com/Microsoft/vcpkg/blob/master/ports/folly/portfile.cmake#L15)
+* [z3](https://github.com/Microsoft/vcpkg/blob/master/ports/z3/portfile.cmake#L13)
+
 
 ## Source
 [scripts/cmake/vcpkg_from_gitlab.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_gitlab.cmake)
diff --git a/docs/maintainers/vcpkg_install_msbuild.md b/docs/maintainers/vcpkg_install_msbuild.md
@@ -1,6 +1,6 @@
 # vcpkg_install_msbuild
 
-Build and install an msbuild-based project. This replaces `vcpkg_build_msbuild()`.
+Build and install a msbuild-based project. This replaces `vcpkg_build_msbuild()`.
 
 ## Usage
 ```cmake

diff --git a/docs/specifications/export-command.md b/docs/specifications/export-command.md
@@ -5,7 +5,7 @@
 ### A. Build once and share
 
 Customers want to be able to build their set of required libraries once, and then distribute the resulting binaries to all members of the "group". This has been brought up in
-- Enterprise environments, in which there are dedicated teams to acquire libraries and then share them with other team to consume them
+- Enterprise environments, in which there are dedicated teams to acquire libraries and then share them with other teams to consume them
 - Academic environments, in which the professor/teacher wants to build the required libraries and then provide them to all the students
 - CI Systems, in which developers want to quickly distribute their exact set of dependencies to a cloud-based farm of build machines
 
@@ -167,6 +167,6 @@ Alice gives to Bob: a) The links to her project and b) The zip file "vcpkg-expor
 ## 5. Technical model
 
 - Each exported library, must be accompanied with all of its dependencies, even if they are not explicitly specified in the `vcpkg export` command.
-- When exporting a library, a dependency graph will be built, similarly to install, to figure out which packages needs to be exported.
+- When exporting a library, a dependency graph will be built, similarly to install, to figure out which packages need to be exported.
 - It is allowed to have packages from different triplets, so users can include 32/64-bit and dynamic/static binaries in the same export.
 - The exported archives also include the files needed to integrate with MSBuild and/or CMake.
diff --git a/docs/specifications/feature-packages.md b/docs/specifications/feature-packages.md
@@ -1,6 +1,6 @@
 # Proposal: Features / Feature packages (Feb 23 2017)
 
-**Note: this is the proposal as it was initially accepted and does not neccessarily reflect the current behavior.**
+**Note: this is the proposal as it was initially accepted and does not necessarily reflect the current behavior.**
 
 ## 1. Motivation
 
@@ -14,7 +14,7 @@ Therefore, there is significant value in enabling users to choose whether they f
 
 The community around [OpenCV][] has built up a library of extensions called [OpenCV_contrib][]. However, these extensions are a source-level patch onto the main OpenCV codebase and therefore must be applied _during_ the core OpenCV build. Further confounding the problem, it is the author's understanding that these community extensions have only been developed with [CUDA][] enabled and cannot be built without that dependency.
 
-Therefore, if CUDA is disabled, OpenCV\_contrib must also be disabled. Likewise, when a user requests OpenCV\_contrib, CUDA must be enabled. It would be convienent, but not a requirement, to enable CUDA without enabling the community extensions.
+Therefore, if CUDA is disabled, OpenCV\_contrib must also be disabled. Likewise, when a user requests OpenCV\_contrib, CUDA must be enabled. It would be convenient, but not a requirement, to enable CUDA without enabling the community extensions.
 
 Finally, these extensions add additional exports and headers which could be depended upon by other libraries. For maintainers, there must be a way to specify this requirement such that `vcpkg install mylib-depends-ocv-contrib` will verify/build/rebuild OpenCV with the community extensions enabled.
 

diff --git a/docs/users/config-environment.md 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
@@ -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 control 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
@@ -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.

diff --git a/ports/3fd/CONTROL b/ports/3fd/CONTROL
@@ -1,4 +1,4 @@
 Source: 3fd
-Version: 2.6.2
+Version: 2.6.2-1
 Description: C++ Framework For Fast Development
 Build-Depends: boost-lockfree (windows), boost-regex (windows), poco (windows), sqlite3, rapidxml