Merge pull request #1 from Microsoft/master

pull changes from upstream

4 files changed, 103 insertions, 10 deletions

diff --git a/docs/index.md b/docs/index.md
index 9b279baf0..3fa5784e9 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -13,6 +13,7 @@ Vcpkg helps you get C and C++ libraries on Windows. This tool and ecosystem are
 ### User Help
 
 - [Integration with build systems](users/integration.md)
+- [Triplet files](users/triplets.md)
 
 ### Maintainer help
 
diff --git a/docs/maintainers/control-files.md b/docs/maintainers/control-files.md
index 1cb444df3..e446fe6fa 100644
--- a/docs/maintainers/control-files.md
+++ b/docs/maintainers/control-files.md
@@ -1,16 +1,16 @@
-## `CONTROL` files
-Each port has some static metadata in the form of a `CONTROL` file. This file uses the same rough syntax as and a subset of the fields from [the Debian `control` format][debian].
+# CONTROL files
+Each port has some static metadata in the form of a `CONTROL` file. This file uses the same syntax and a subset of the fields from [the Debian `control` format][debian].
 
-Fields are case-sensitive.
+Field names are case-sensitive.
 
 [debian]: https://www.debian.org/doc/debian-policy/ch-controlfields.html
 
-### Recognized fields
+## Recognized fields
 
-#### Source
+### Source
 The name of the port.
 
-#### Version
+### Version
 The port version.
 
 This field should be an alphanumeric string which may also contain `.`, `_`, or `-`. No attempt at ordering versions is made; all versions are treated as bitstrings and are only evaluated for equality.
@@ -22,15 +22,15 @@ Example:
 Version: 1.0.5-2
 ```
 
-#### Description
+### Description
 A description of the library
 
 The first sentence of the description should concisely describe the purpose and contents of the library. Then, a larger description including the library's "proper name" should follow.
 
-#### Maintainer
+### Maintainer
 Reserved for future use.
 
-#### Build-Depends
+### Build-Depends
 The list of dependencies required to build and use this library.
 
 Example:
diff --git a/docs/users/integration.md b/docs/users/integration.md
index 38332f1aa..1e52adb88 100644
--- a/docs/users/integration.md
+++ b/docs/users/integration.md
@@ -5,11 +5,14 @@ Vcpkg offers many ways to integrate into your build so you can do what's right f
 - [`integrate` command](#integrate)
 - [`export` command](#export)
 
+Each integration style has heuristics to deduce the correct [triplet][]. This can be overridden using [a common method](#triplet-selection) based on your buildsystem.
+
 <a name="integrate"></a>
 ### Integrate Command
 
 These link your project(s) to a specific copy of Vcpkg on your machine so any updates or new package installations will be instantly available for the next build of your project.
 
+<a name="user-wide-msbuild"></a>
 #### User-wide for MSBuild (Recommended for Open Source MSBuild projects)
 ```no-highlight
 vcpkg integrate install
@@ -82,4 +85,37 @@ Each of these have the same layout, which mimics the layout of a full vcpkg:
 
 Additionally, NuGet packages will contain a `build\native\vcpkg.targets` that integrates with MSBuild projects.
 
-Please also see our [blog post](https://blogs.msdn.microsoft.com/vcblog/2017/05/03/vcpkg-introducing-export-command/) for additional examples.
\ No newline at end of file
+Please also see our [blog post](https://blogs.msdn.microsoft.com/vcblog/2017/05/03/vcpkg-introducing-export-command/) for additional examples.
+
+<a name="triplet-selection"></a>
+### Triplet selection
+Every integration mechanism besides manually adding the folders will deduce a [triplet][] for your project as one of:
+- x86-windows
+- x64-windows
+- x86-uwp
+- x64-uwp
+- arm-uwp
+
+#### With MSBuild
+You can see the automatically deduced triplet by setting your MSBuild verbosity to Normal or higher:
+
+> *Shortcut: Ctrl+Q "build and run"*
+>
+> Tools -> Options -> Projects and Solutions -> Build and Run -> MSBuild project build output verbosity
+
+To override the automatically chosen [triplet][], you can specify the MSBuild property `VcpkgTriplet` in your `.vcxproj`. We recommend adding this to the `Globals` PropertyGroup.
+```xml
+<PropertyGroup Label="Globals">
+  <!-- .... -->
+  <VcpkgTriplet Condition="'$(Configuration)'=='Win32'">x86-windows-static</VcpkgTriplet>
+  <VcpkgTriplet Condition="'$(Configuration)'=='x64'">x64-windows-static</VcpkgTriplet>
+</PropertyGroup>
+```
+
+#### With CMake
+Simply set `VCPKG_TARGET_TRIPLET` on the configure line.
+```no-highlight
+cmake ../my/project -DVCPKG_TARGET_TRIPLET=x64-windows-static -DCMAKE_TOOLCHAIN_FILE=...
+```
+
+[triplet]: triplets.md
diff --git a/docs/users/triplets.md b/docs/users/triplets.md
new file mode 100644
index 000000000..06f77e63f
--- /dev/null
+++ b/docs/users/triplets.md
@@ -0,0 +1,56 @@
+# Triplet files
+
+Triplet is a standard term used in cross compiling as a way to completely capture the target environment (cpu, os, compiler, runtime, etc) in a single convenient name.
+
+In Vcpkg, we use triplets to describe self-consistent builds of library sets. This means every library will be built using the same target cpu, OS, and compiler toolchain, but also CRT linkage and preferred library type.
+
+We currently provide many triplets by default (run `vcpkg help triplet`). However, you can easily add your own by creating a new file in the `triplets\` directory. The new triplet will immediately be available for use in commands, such as `vcpkg install boost:x86-windows-custom`.
+
+To change the triplet used by your project, such as to enable static linking, see our [Integration Document](integration.md#triplet-selection).
+
+## Variables
+### VCPKG_TARGET_ARCHITECTURE
+Specifies the target machine architecture.
+
+Valid options are `x86`, `x64`, and `arm`.
+
+### VCPKG_CRT_LINKAGE
+Specifies the desired MSVCRT linkage.
+
+Valid options are `dynamic` and `static`.
+
+### VCPKG_LIBRARY_LINKAGE
+Specifies the preferred library linkage.
+
+Valid options are `dynamic` and `static`. Note that libraries can ignore this setting if they do not support the preferred linkage type.
+
+### 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`.
+
+### VCPKG_PLATFORM_TOOLSET
+Specifies the 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.
+
+## 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 STREQUAL "qt5")
+    set(VCPKG_LIBRARY_LINKAGE dynamic)
+endif()
+```
+This will build `qt5` as DLLs against the dynamic CRT, but every other library as a static library (still against the dynamic CRT).
+
+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.
+
+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.