Merge pull request #1 from Microsoft/master

Update vcpkg from upstream

2 files changed, 180 insertions, 0 deletions

diff --git a/docs/users/integration.md b/docs/users/integration.md
new file mode 100644
index 000000000..f1b5014bf
--- /dev/null
+++ b/docs/users/integration.md
@@ -0,0 +1,121 @@
+## Buildsystem Integration
+
+Vcpkg offers many ways to integrate into your build so you can do what's right for your project. There are two main categories of integration:
+
+- [`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
+```
+This will implicitly add Include Directories, Link Directories, and Link Libraries for all packages installed with Vcpkg to all VS2015 and VS2017 MSBuild projects. We also add a post-build action for executable projects that will analyze and copy any DLLs you need to the output folder, enabling a seamless F5 experience.
+
+For the vast majority of libraries, this is all you need to do -- just File -> New Project and write code! However, some libraries perform conflicting behaviors such as redefining `main()`. Since you need to choose per-project which of these conflicting options you want, you will need to add those libraries to your linker inputs manually.
+
+Here are some examples, though this is not an exhaustive list:
+- Gtest provides `gtest`, `gmock`, `gtest_main`, and `gmock_main`
+- SDL2 provides `SDL2main`
+- SFML provides `sfml-main`
+- Boost.Test provides `boost_test_exec_monitor`
+
+To get a full list for all your installed packages, run `vcpkg owns manual-link`.
+
+#### CMake toolchain file (Recommended for Open Source CMake projects)
+```no-highlight
+cmake ../my/project -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake
+```
+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.
+
+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)
+include_directories(${CATCH_INCLUDE_DIR})
+```
+
+#### 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.
+```no-highlight
+PS D:\src\vcpkg> .\vcpkg integrate project
+Created nupkg: D:\src\vcpkg\scripts\buildsystems\vcpkg.D.src.vcpkg.1.0.0.nupkg
+
+With a project open, go to Tools->NuGet Package Manager->Package Manager Console and paste:
+    Install-Package vcpkg.D.src.vcpkg -Source "D:/src/vcpkg/scripts/buildsystems"
+```
+*Note: The generated NuGet package does not contain the actual libraries. It instead acts like a shortcut (or symlink) to the vcpkg install and will "automatically" update with any changes (install/remove) to the libraries. You do not need to regenerate or update the NuGet package.*
+
+#### Manual compiler settings
+
+Libraries are installed into the `installed\` subfolder, partitioned by architecture (e.g. x86-windows):
+* The header files are installed to `installed\x86-windows\include`
+* Release `.lib` files are installed to `installed\x86-windows\lib` or `installed\x86-windows\lib\manual-link`
+* Release `.dll` files are installed to `installed\x86-windows\bin`
+* Debug `.lib` files are installed to `installed\x86-windows\debug\lib` or `installed\x86-windows\debug\lib\manual-link`
+* Debug `.dll` files are installed to `installed\x86-windows\debug\bin`
+
+See your build system specific documentation for how to use prebuilt binaries.
+
+Generally, to run any produced executables you will also need to either copy the needed DLL files to the same folder as your executable or *prepend* the correct `bin\` directory to your path.
+
+<a name="export"></a>
+### Export Command
+This command creates a shrinkwrapped archive containing a specific set of libraries (and their dependencies) that can be quickly and reliably shared with build servers or other users in your organization.
+
+- `--nuget`: NuGet package (Recommended for MSBuild projects)
+- `--zip`: Zip archive
+- `--7zip`: 7Zip archive (Recommended for CMake projects)
+- `--raw`: Raw, uncompressed folder
+
+Each of these have the same layout, which mimics the layout of a full vcpkg:
+
+- `installed\` contains the installed package files
+- `scripts\buildsystems\vcpkg.cmake` is a toolchain file suitable for use with CMake
+
+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.
+
+<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="'$(Platform)'=='Win32'">x86-windows-static</VcpkgTriplet>
+  <VcpkgTriplet Condition="'$(Platform)'=='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..911ab5469
--- /dev/null
+++ b/docs/users/triplets.md
@@ -0,0 +1,59 @@
+# 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.
+
+Visual Studio 2015 platform toolset is `v140`  
+Visual Studio 2017 platform toolset is `v141`
+
+## 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).
+
+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.