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

25 files changed, 549 insertions, 37 deletions

diff --git a/docs/about/faq.md b/docs/about/faq.md
index b345b4fd0..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.
@@ -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?
-No, for this preview we are focusing on Windows as a host platform. If you'd be interested in having Vcpkg run on Linux or OSX, please let us know in [this issue](https://github.com/microsoft/vcpkg/issues/57)!
+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!
 
 ## 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.
@@ -35,14 +35,14 @@ To use different versions of a library for different projects, we recommend maki
 
 If your application is very sensitive to the versions of libraries, we recommend checking in the specific set of portfiles you need into your source control along with your project sources and using the `--vcpkg-root` option to redirect the working directory of `vcpkg.exe`.
 
-## How does Vcpkg protect my Privacy?
+## How does Vcpkg protect my privacy?
 See the [Privacy document](privacy.md) for all information regarding privacy.
 
 ## Can I use my own CMake toolchain file with Vcpkg's toolchain file?
 Yes. If you already have a CMake toolchain file, you will need to include our toolchain file at the end of yours. This should be as simple as an `include(<vcpkg_root>\scripts\buildsystems\vcpkg.cmake)` directive. Alternatively, you could copy the contents of our `scripts\buildsystems\vcpkg.cmake` into the end of your existing toolchain file.
 
 ## Can I use my own/specific flags for rebuilding libs?
-Yes. In the current preview, there is not yet a standardized global way to change them, however you can edit individual portfiles and tweak the exact build process however you'd like.
+Yes. In the current version, there is not yet a standardized global way to change them, however you can edit individual portfiles and tweak the exact build process however you'd like.
 
 By saving the changes to the portfile (and checking them in), you'll get the same results even if you're rebuilding from scratch in the future and forgot what exact settings you used.
 
@@ -93,7 +93,7 @@ Enabling user-wide integration (`vcpkg integrate install`) changes the default f
 ## Why not NuGet?
 NuGet is a package manager for .NET libraries with a strong dependency on MSBuild. It does not meet the specific needs of Native C++ customers in at least three ways.
 
-- **Compilation Flavors**. With so many possible combinations of compilation options, the task of providing a truly complete set of options is intrinsicly impossible. Furthermore, the download size for reasonably complete binary packages becomes enormous. This makes it a requirement to split the results into multiple packages, but then searching becomes very difficult.
+- **Compilation Flavors**. With so many possible combinations of compilation options, the task of providing a truly complete set of options is intrinsically impossible. Furthermore, the download size for reasonably complete binary packages becomes enormous. This makes it a requirement to split the results into multiple packages, but then searching becomes very difficult.
 
 - **Binary vs Source**. Very closely tied to the first point, NuGet is designed from the ground up to provide relatively small, prebuilt binaries. Due to the nature of native code, developers need to have access to the source code to ensure ABI compatibility, performance, integrity, and debuggability.
 
@@ -108,7 +108,7 @@ Conan.io is a publicly-federated, project-centric, cross-platform, C++ package m
 
 - **Cross-platform vs single-platform**. While being hosted on many platforms is an excellent north star, we believe the level of system integration and stability provided by apt-get, yum, and homebrew is well worth needing to exchange `apt-get install libboost-all-dev` with `brew install boost` in automated scripts. We chose to make our system as easy as possible to integrate into a world with these very successful system managers -- one more line for `vcpkg install boost` -- instead of attempting to replace them where they are already so successful and well-loved.
 
-- **C++/CMake vs python**. While Python is an excellent language loved by many, we believe that transparency and familiarity are the most important factors when choosing a tool as important to your workflow as a package manager. Consequently, we chose to make the implementation languages be as universally accepted as possible: C++ should be used in a C++ package manager for C++ programmers. You should not be required to learn another language just to understand your package manager.
+- **C++/CMake vs python**. While Python is an excellent language loved by many, we believe that transparency and familiarity are the most important factors when choosing a tool as important to your workflow as a package manager. Consequently, we chose to make the implementation languages be as universally accepted as possible: C++ should be used in a C++ package manager for C++ programmers. You should not be required to learn another programming language just to understand your package manager.
 
 ## Why not Chocolatey?
 Chocolatey is an excellent system for managing applications. However, it is not currently designed to acquire redistributable developer assets and help you with debugging. Vcpkg, in comparison, is designed to get you the libraries you need to build your application and help you deliver through any platform you'd like (including Chocolatey!).
diff --git a/docs/about/privacy.md b/docs/about/privacy.md
index 9ff0e7a47..91d709372 100644
--- a/docs/about/privacy.md
+++ b/docs/about/privacy.md
@@ -7,7 +7,14 @@ We do collect telemetry data from usage of "vcpkg.exe". We explicitly ONLY colle
 
 ## What telemetry is collected?
 
-We collect the command line used, the time of invocation, and how long the command took. Some commands also add additional calculated information (such as the full set of libraries to install). We generate a completely random UUID on first use and attach it to each event. For this preview, we do not offer a mechanism to disable this data collection since it is critical for improving the product. In the full release, you will be able to opt-out with a simple configuration. For more information about how Microsoft protects your privacy, see https://privacy.microsoft.com/en-us/privacy.
+We collect the command line used, the time of invocation, and how long execution took. Some commands also add additional calculated information (such as the full set of libraries to install). We generate a completely random UUID on first use and attach it to each event.
+In order to opt-out of data collection, you can re-run the boostrap script with the following flag, for Windows and Linux/OSX, respectively:
+
+```PS> .\bootstrap-vcpkg.bat -disableMetrics```
+
+```~/$ ./bootstrap-vcpkg.sh -disableMetrics```
+
+For more information about how Microsoft protects your privacy, see https://privacy.microsoft.com/en-us/privacy.
 
 Here is an example of an event for the command line `vcpkg install zlib`:
 ```json
diff --git a/docs/examples/using-sqlite.md b/docs/examples/installing-and-using-packages.md
index d12695bfb..50200c877 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
@@ -71,7 +71,7 @@ See `.\vcpkg help triplet` for all supported targets.
 <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 afterwords is no longer required and the integration is configured on a per-user basis.
+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.
@@ -82,7 +82,7 @@ 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`.
 
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 ce176d451..ed63637fd 100644
--- a/docs/examples/packaging-zlib.md
+++ b/docs/examples/packaging-zipfiles.md
@@ -1,9 +1,9 @@
-## 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.
 
-*Looking at zlib's website, the URL http://zlib.net/zlib128.zip looks appropriate.*
+*Looking at zlib's website, the URL http://zlib.net/zlib1211.zip 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.
 
@@ -11,7 +11,7 @@ Second, determine a suitable package name. This should be ASCII, lowercase, and
 
 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`.
 
-*`zlib128.zip` is a fine name, so no change needed.*
+*`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>`.
 
@@ -21,12 +21,12 @@ PS D:\src\vcpkg> .\vcpkg create zlib2 http://zlib.net/zlib-1.2.11.tar.gz zlib-1.
 ```
 
 ### Create the CONTROL file
-In addition to the generated `ports\<package>\portfile.cmake`, we also need a `ports\<package>\CONTROL` file. This file is a simply formatted set of fields describing the package's metadata.
+In addition to the generated `ports\<package>\portfile.cmake`, we also need a `ports\<package>\CONTROL` file. This file is a simple set of fields describing the package's metadata.
 
 *For zlib2, we'll create the file `ports\zlib2\CONTROL` with the following contents:*
 ```no-highlight
 Source: zlib2
-Version: 1.2.8
+Version: 1.2.11
 Description: A Massively Spiffy Yet Delicately Unobtrusive Compression Library
 ```
 
diff --git a/docs/examples/patching-libpng.md b/docs/examples/patching.md
index 2337b73da..98115400e 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:
diff --git a/docs/index.md b/docs/index.md
index 1d12b282e..69dbdcd1e 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,14 +1,15 @@
 ### Quick Start
 
-Vcpkg helps you get C and C++ libraries on Windows. This tool and ecosystem are currently in a preview state; your involvement is vital to its success.
+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)
+- [Installing and Using Packages Example: sqlite](examples/installing-and-using-packages.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
 
@@ -26,6 +27,7 @@ Vcpkg helps you get C and C++ libraries on Windows. This tool and ecosystem are
 
 ### 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/)
+- [Vcpkg: Using multiple enlistments to handle multiple versions of a library](https://blogs.msdn.microsoft.com/vcblog/2017/10/23/vcpkg-using-multiple-enlistments/)
 - [Vcpkg: introducing the export command](https://blogs.msdn.microsoft.com/vcblog/2017/05/03/vcpkg-introducing-export-command/)
 - [Binary Compatibility and Pain-free Upgrade Why Moving to Visual Studio 2017 is almost "too easy"](https://blogs.msdn.microsoft.com/vcblog/2017/03/07/binary-compatibility-and-pain-free-upgrade-why-moving-to-visual-studio-2017-is-almost-too-easy/)
 - [Vcpkg recent enhancements](https://blogs.msdn.microsoft.com/vcblog/2017/02/14/vcpkg-recent-enhancements/)
diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
index e16147f7d..f159f7f64 100644
--- a/docs/maintainers/portfile-functions.md
+++ b/docs/maintainers/portfile-functions.md
@@ -2,16 +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_build_cmake.md b/docs/maintainers/vcpkg_build_cmake.md
index ddfa46f6b..1e17eb975 100644
--- a/docs/maintainers/vcpkg_build_cmake.md
+++ b/docs/maintainers/vcpkg_build_cmake.md
@@ -15,6 +15,9 @@ The underlying buildsystem will be instructed to not parallelize
 The target passed to the cmake build command (`cmake --build . --target <target>`). If not specified, no target will
 be passed.
 
+### ADD_BIN_TO_PATH
+Adds the appropriate Release and Debug `bin\` directories to the path during the build such that executables can run against the in-tree DLLs.
+
 ## Notes:
 This command should be preceeded by a call to [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md).
 You can use the alias [`vcpkg_install_cmake()`](vcpkg_configure_cmake.md) function if your CMake script supports the
diff --git a/docs/maintainers/vcpkg_build_msbuild.md b/docs/maintainers/vcpkg_build_msbuild.md
index 37f8d8df2..862587eb4 100644
--- 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.
+Build an msbuild-based project. Deprecated in favor of `vcpkg_install_msbuild()`.
 
 ## Usage
 ```cmake
@@ -15,6 +15,7 @@ vcpkg_build_msbuild(
     [OPTIONS </p:ZLIB_INCLUDE_PATH=X>...]
     [OPTIONS_RELEASE </p:ZLIB_LIB=X>...]
     [OPTIONS_DEBUG </p:ZLIB_LIB=X>...]
+    [USE_VCPKG_INTEGRATION]
 )
 ```
 
diff --git a/docs/maintainers/vcpkg_check_linkage.md b/docs/maintainers/vcpkg_check_linkage.md
new file mode 100644
index 000000000..406325dba
--- /dev/null
+++ b/docs/maintainers/vcpkg_check_linkage.md
@@ -0,0 +1,34 @@
+# vcpkg_check_linkage
+
+Asserts the available library and CRT linkage options for the port.
+
+## Usage
+```cmake
+vcpkg_check_linkage(
+    [ONLY_STATIC_LIBRARY | ONLY_DYNAMIC_LIBRARY]
+    [ONLY_STATIC_CRT | ONLY_DYNAMIC_CRT]
+)
+```
+
+## Parameters
+### ONLY_STATIC_LIBRARY
+Indicates that this port can only be built with static library linkage.
+
+### ONLY_DYNAMIC_LIBRARY
+Indicates that this port can only be built with dynamic/shared library linkage.
+
+### ONLY_STATIC_CRT
+Indicates that this port can only be built with static CRT linkage.
+
+### ONLY_DYNAMIC_CRT
+Indicates that this port can only be built with dynamic/shared CRT linkage.
+
+## Notes
+This command will either alter the settings for `VCPKG_LIBRARY_LINKAGE` or fail, depending on what was requested by the user versus what the library supports.
+
+## Examples
+
+* [libimobiledevice](https://github.com/Microsoft/vcpkg/blob/master/ports/libimobiledevice/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_check_linkage.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_linkage.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_copy_pdbs.md b/docs/maintainers/vcpkg_copy_pdbs.md
index 6bfa488db..1583f777f 100644
--- a/docs/maintainers/vcpkg_copy_pdbs.md
+++ b/docs/maintainers/vcpkg_copy_pdbs.md
@@ -4,12 +4,18 @@ Automatically locate pdbs in the build tree and copy them adjacent to all DLLs.
 
 ## Usage
 ```cmake
-vcpkg_copy_pdbs()
+vcpkg_copy_pdbs([BUILD_PATHS <${CURRENT_PACKAGES_DIR}/bin/*.dll> ...])
 ```
 
 ## Notes
 This command should always be called by portfiles after they have finished rearranging the binary output.
 
+## Parameters
+### BUILD_PATHS
+Path patterns passed to `file(GLOB_RECURSE)` for locating dlls.
+
+Defaults to `${CURRENT_PACKAGES_DIR}/bin/*.dll` and `${CURRENT_PACKAGES_DIR}/debug/bin/*.dll`.
+
 ## Examples
 
 * [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.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_find_acquire_program.md b/docs/maintainers/vcpkg_find_acquire_program.md
index 8107c8dd2..57a2bf75a 100644
--- a/docs/maintainers/vcpkg_find_acquire_program.md
+++ b/docs/maintainers/vcpkg_find_acquire_program.md
@@ -25,6 +25,7 @@ The current list of programs includes:
 - NASM
 - NINJA
 - YASM
+- ARIA2 (Downloader)
 
 Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_acquire_msys.md).
 
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_github.md b/docs/maintainers/vcpkg_from_github.md
index cf50dc445..8f9731629 100644
--- a/docs/maintainers/vcpkg_from_github.md
+++ b/docs/maintainers/vcpkg_from_github.md
@@ -10,6 +10,7 @@ vcpkg_from_github(
     [REF <v2.0.0>]
     [SHA512 <45d0d7f8cc350...>]
     [HEAD_REF <master>]
+    [PATCHES <patch1.patch> <patch2.patch>...]
 )
 ```
 
@@ -23,7 +24,7 @@ This should be set to `SOURCE_PATH` by convention.
 The organization or user and repository on GitHub.
 
 ### REF
-A stable git commit-ish (ideally a tag) that will not change contents. **This should not be a branch.**
+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.
 
@@ -39,6 +40,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_gitlab.md b/docs/maintainers/vcpkg_from_gitlab.md
new file mode 100644
index 000000000..bc312f37a
--- /dev/null
+++ b/docs/maintainers/vcpkg_from_gitlab.md
@@ -0,0 +1,61 @@
+# vcpkg_from_gitlab
+
+Download and extract a project from Gitlab instances. Enables support for `install --head`.
+
+## Usage:
+```cmake
+vcpkg_from_gitlab(
+    GITLAB_URL <https://gitlab.com>
+    OUT_SOURCE_PATH <SOURCE_PATH>
+    REPO <gitlab-org/gitlab-ce>
+    [REF <v10.7.3>]
+    [SHA512 <45d0d7f8cc350...>]
+    [HEAD_REF <master>]
+    [PATCHES <patch1.patch> <patch2.patch>...]
+)
+```
+
+## Parameters:
+
+### GITLAB_URL
+The URL of the Gitlab instance to use.
+
+### OUT_SOURCE_PATH
+Specifies the out-variable that will contain the extracted location.
+
+This should be set to `SOURCE_PATH` by convention.
+
+### REPO
+The organization or user plus the repository name on the Gitlab instance.
+
+### REF
+A stable git commit-ish (ideally a tag) 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.
+
+If `REF` is specified, `SHA512` must also be specified.
+
+### SHA512
+The SHA512 hash that should match the archive (${GITLAB_URL}/${REPO}/-/archive/${REF}/${REPO_NAME}-${REF}.tar.gz).
+The REPO_NAME variable is parsed from the value of REPO.
+
+This is most easily determined by first setting it to `1`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.
+
+### HEAD_REF
+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.
+
+This exports the `VCPKG_HEAD_VERSION` variable during head builds.
+
+
+## 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
new file mode 100644
index 000000000..1de68ce70
--- /dev/null
+++ b/docs/maintainers/vcpkg_install_msbuild.md
@@ -0,0 +1,93 @@
+# vcpkg_install_msbuild
+
+Build and install an msbuild-based project. This replaces `vcpkg_build_msbuild()`.
+
+## Usage
+```cmake
+vcpkg_install_msbuild(
+    SOURCE_PATH <${SOURCE_PATH}>
+    PROJECT_SUBPATH <port.sln>
+    [INCLUDES_SUBPATH <include>]
+    [LICENSE_SUBPATH <LICENSE>]
+    [RELEASE_CONFIGURATION <Release>]
+    [DEBUG_CONFIGURATION <Debug>]
+    [TARGET <Build>]
+    [TARGET_PLATFORM_VERSION <10.0.15063.0>]
+    [PLATFORM <${TRIPLET_SYSTEM_ARCH}>]
+    [PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>]
+    [OPTIONS </p:ZLIB_INCLUDE_PATH=X>...]
+    [OPTIONS_RELEASE </p:ZLIB_LIB=X>...]
+    [OPTIONS_DEBUG </p:ZLIB_LIB=X>...]
+    [USE_VCPKG_INTEGRATION]
+    [ALLOW_ROOT_INCLUDES | REMOVE_ROOT_INCLUDES]
+)
+```
+
+## Parameters
+### SOURCE_PATH
+The path to the root of the source tree.
+
+Because MSBuild uses in-source builds, the source tree will be copied into a temporary location for the build. This
+parameter is the base for that copy and forms the base for all XYZ_SUBPATH options.
+
+### USE_VCPKG_INTEGRATION
+Apply the normal `integrate install` integration for building the project.
+
+By default, projects built with this command will not automatically link libraries or have header paths set.
+
+### PROJECT_SUBPATH
+The subpath to the solution (`.sln`) or project (`.vcxproj`) file relative to `SOURCE_PATH`.
+
+### LICENSE_SUBPATH
+The subpath to the license file relative to `SOURCE_PATH`.
+
+### INCLUDES_SUBPATH
+The subpath to the includes directory relative to `SOURCE_PATH`.
+
+This parameter should be a directory and should not end in a trailing slash.
+
+### ALLOW_ROOT_INCLUDES
+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.
+
+### TARGET_PLATFORM_VERSION
+The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
+
+### TARGET
+The MSBuild target to build. (``/t:<TARGET>``)
+
+### PLATFORM
+The platform (``/p:Platform`` msbuild parameter) used for the build.
+
+### PLATFORM_TOOLSET
+The platform toolset (``/p:PlatformToolset`` msbuild parameter) used for the build.
+
+### OPTIONS
+Additional options passed to msbuild for all builds.
+
+### OPTIONS_RELEASE
+Additional options passed to msbuild for Release builds. These are in addition to `OPTIONS`.
+
+### OPTIONS_DEBUG
+Additional options passed to msbuild for Debug builds. These are in addition to `OPTIONS`.
+
+## 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
+[scripts/cmake/vcpkg_install_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_msbuild.cmake)

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/integration.md b/docs/users/integration.md
index f1b5014bf..fbaea41d9 100644
--- a/docs/users/integration.md
+++ b/docs/users/integration.md
@@ -35,15 +35,37 @@ 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
 # To find and use catch
-find_path(CATCH_INCLUDE_DIR catch.hpp)
+find_path(CATCH_INCLUDE_DIR NAMES catch.hpp PATH_SUFFIXES catch2)
 include_directories(${CATCH_INCLUDE_DIR})
 ```
 
+##### Using an environment variable instead of a command line option
+
+The `CMAKE_TOOLCHAIN_FILE` setting simply must be set before the `project()` directive is first called. This means that you can easily read from an environment variable to avoid passing it on the configure line:
+
+```cmake
+if(DEFINED ENV{VCPKG_ROOT} AND NOT DEFINED CMAKE_TOOLCHAIN_FILE)
+  set(CMAKE_TOOLCHAIN_FILE "${VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
+      CACHE STRING "")
+endif()
+
+project(myproject CXX)
+```
+
+##### Using multiple toolchain files
+
+To use an external toolchain file with a project using vcpkg, you can set the cmake variable `VCPKG_CHAINLOAD_TOOLCHAIN_FILE` on the configure line:
+```no-highlight
+cmake ../my/project \
+   -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake \
+   -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=../my/project/compiler-settings-toolchain.cmake
+```
+
 #### Linking NuGet file
 
 We also provide individual VS project integration through a NuGet package. This will modify the project file, so we do not recommend this approach for open source projects.
diff --git a/docs/users/triplets.md b/docs/users/triplets.md
index eb83aeb10..9ff372aed 100644
--- a/docs/users/triplets.md
+++ b/docs/users/triplets.md
@@ -12,10 +12,10 @@ To change the triplet used by your project, such as to enable static linking, se
 ### VCPKG_TARGET_ARCHITECTURE
 Specifies the target machine architecture.
 
-Valid options are `x86`, `x64`, and `arm`.
+Valid options are `x86`, `x64`, `arm`, and `arm64`.
 
 ### VCPKG_CRT_LINKAGE
-Specifies the desired MSVCRT linkage.
+Specifies the desired CRT linkage (for MSVC).
 
 Valid options are `dynamic` and `static`.
 
@@ -27,30 +27,78 @@ Valid options are `dynamic` and `static`. Note that libraries can ignore this se
 ### VCPKG_CMAKE_SYSTEM_NAME
 Specifies the target platform.
 
-Valid options are `WindowsStore` or empty. Empty corresponds to Windows Desktop and `WindowsStore` corresponds to UWP.
-When setting this variable to `WindowsStore`, you must also set `VCPKG_CMAKE_SYSTEM_VERSION` to `10.0`.
+Valid options include any CMake system name, such as:
+- Empty (Windows Desktop for legacy reasons)
+- `WindowsStore` (Universal Windows Platform)
+- `Darwin` (Mac OSX)
+- `Linux` (Linux)
 
 ### VCPKG_PLATFORM_TOOLSET
-Specifies the C/C++ compiler toolchain to use.
+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.
+
+This (if set) will override all other compiler detection logic. By default, a toolchain file is selected from `scripts/toolchains/` appropriate to the platform.
+
+See also the CMake documentation for toolchain files: https://cmake.org/cmake/help/v3.11/manual/cmake-toolchains.7.html.
+
+### VCPKG_CXX_FLAGS
+Sets additional compiler flags to be used when not using `VCPKG_CHAINLOAD_TOOLCHAIN_FILE`.
+
+This option also has forms for configuration-specific and C flags:
+- `VCPKG_CXX_FLAGS`
+- `VCPKG_CXX_FLAGS_DEBUG`
+- `VCPKG_CXX_FLAGS_RELEASE`
+- `VCPKG_C_FLAGS`
+- `VCPKG_C_FLAGS_DEBUG`
+- `VCPKG_C_FLAGS_RELEASE`
+
+## macOS Variables
+
+### VCPKG_INSTALL_NAME_DIR
+Sets the install name used when building macOS dynamic libraries. Default value is `@rpath`. See the CMake documentation for [CMAKE_INSTALL_NAME_DIR](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_NAME_DIR.html) for more information.
+
+### VCPKG_OSX_DEPLOYMENT_TARGET
+Sets the minimum macOS version for compiled binaries. This also changes what versions of the macOS platform SDK that CMake will search for. See the CMake documentation for [CMAKE_OSX_DEPLOYMENT_TARGET](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_DEPLOYMENT_TARGET.html) for more information.
+
+### VCPKG_OSX_SYSROOT
+Set the name or path of the macOS platform SDK that will be used by CMake. See the CMake documentation for [CMAKE_OSX_SYSROOT](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_SYSROOT.html) for more information.
+
 ## Per-port customization
 The CMake Macro `PORT` will be set when interpreting the triplet file and can be used to change settings (such as `VCPKG_LIBRARY_LINKAGE`) on a per-port basis.
 
 Example:
 ```cmake
 set(VCPKG_LIBRARY_LINKAGE static)
-set(VCPKG_CRT_LINKAGE dynamic)
 if(PORT MATCHES "qt5-")
     set(VCPKG_LIBRARY_LINKAGE dynamic)
 endif()
 ```
-This will build all the `qt5-*` libraries as DLLs against the dynamic CRT, but every other library as a static library (still against the dynamic CRT).
+This will build all the `qt5-*` libraries as DLLs, but every other library as a static library.
 
 For an example in a real project, see https://github.com/Intelight/vcpkg/blob/master/triplets/x86-windows-mixed.cmake.
 
 ## Additional Remarks
-The default triplet when running any vcpkg command is `%VCPKG_DEFAULT_TRIPLET%` or `x86-windows` if that environment variable is undefined.
+The default triplet when running any vcpkg command is `%VCPKG_DEFAULT_TRIPLET%` or a platform-specific choice if that environment variable is undefined.
+
+- Windows: `x86-windows`
+- Linux: `x64-linux`
+- OSX: `x64-osx`
 
 We recommend using a systematic naming scheme when creating new triplets. The Android toolchain naming scheme is a good source of inspiration: https://developer.android.com/ndk/guides/standalone_toolchain.html.