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

2 files changed, 80 insertions, 10 deletions

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.