Merge pull request #1 from Microsoft/master

pull

4 files changed, 75 insertions, 81 deletions

diff --git a/docs/EXAMPLES.md b/docs/EXAMPLES.md
index 3415dc754..1a2bacc99 100644
--- a/docs/EXAMPLES.md
+++ b/docs/EXAMPLES.md
@@ -3,10 +3,10 @@
 ## Overview
 Vcpkg helps you get C and C++ libraries on Windows.
 
-For short description of available commands, run `vcpkg help`.
+For short description of available commands, run `.\vcpkg help`.
 
 ## Table of Contents
-- <a href="#example-1">Example 1: Using the C++ REST SDK</a>
+- <a href="#example-1">Example 1: Using Sqlite</a>
   - <a href="#example-1-1">Step 1: Build</a>
   - <a href="#example-1-2">Step 2: Use</a>
     - <a href="#example-1-2-a">Option A: VS Project (User-wide integration)</a>
@@ -14,51 +14,38 @@ For short description of available commands, run `vcpkg help`.
     - <a href="#example-1-2-c">Option C: Other buildsystems</a>
     - <a href="#example-1-2-d">Option D: VS Project (Individual Project integration)</a>
 - <a href="#example-2">Example 2: Package a remote project (zlib)</a>
+- <a href="example-3-patch-libpng.md">Example 3: Patching libpng to work for uwp-x86</a>
 
 <a name="example-1"></a>
-## Example 1: C++ REST SDK
+## Example 1: Using Sqlite
 <a name="example-1-1"></a>
 ### Step 1: Build
 
-First, we need to know what name C++ REST SDK 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:
 ```
-PS D:\src\vcpkg> .\vcpkg search
-boost                1.60             Peer-reviewed portable C++ source libraries
-cpprestsdk           2.8              C++11 JSON, REST, and OAuth library The C++ RES...
-curl                 7.48.0           A library for transferring data with URLs
-expat                2.1.1            XML parser library written in C
-freetype             2.6.3            A library to render fonts.
-glew                 1.13.0           The OpenGL Extension Wrangler Library (GLEW) is a...
-glfw3                3.1.2            GLFW is a free, Open Source, multi-platform libra...
-libjpeg-turbo        1.4.90-1         libjpeg-turbo is a JPEG image codec that uses SIM...
-libpng               1.6.24-1         libpng is a library implementing an interface for...
-libuv                1.9.1            libuv is a multi-platform support library with a ...
-libwebsockets        2.0.0            Libwebsockets is a lightweight pure C library bui...
-mpg123               1.23.3           mpg123 is a real time MPEG 1.0/2.0/2.5 audio play...
-openal-soft          1.17.2           OpenAL Soft is an LGPL-licensed, cross-platform, ...
-opencv               3.1.0            computer vision library
-opengl               10.0.10240.0     Open Graphics Library (OpenGL)[3][4][5] is a cros...
-openssl              1.0.2h           OpenSSL is an open source project that provides a...
-range-v3             0.0.0-1          Range library for C++11/14/17.
-rapidjson            1.0.2-1          A fast JSON parser/generator for C++ with both SA...
-sdl2                 2.0.4            Simple DirectMedia Layer is a cross-platform deve...
-sqlite3              3120200          SQLite is a software library that implements a se...
-tiff                 4.0.6            A library that supports the manipulation of TIFF ...
-tinyxml2             3.0.0            A simple, small, efficient, C++ XML parser
-zlib                 1.2.8            A compression library
+PS D:\src\vcpkg> .\vcpkg search sqlite
+libodb-sqlite        2.4.0            Sqlite support for the ODB ORM library
+sqlite3              3.15.0           SQLite is a software library that implements a se...
+
+If your library is not listed, please open an issue at:
+    https://github.com/Microsoft/vcpkg/issues
 ```
-Looking at the list, we can see that the port is named "cpprestsdk".
+Looking at the list, we can see that the port is named "sqlite3". You can also run the `search` command without arguments to see the full list of packages.
 
-Installing is then as simple as using the `install` command. Since we haven't built this library before, we'll first see an error message indicating that the control file failed to load, then the port will automatically begin building (and install when completed).
+Installing is then as simple as using the `install` command.
 ```
-PS D:\src\vcpkg> .\vcpkg install cpprestsdk
+PS D:\src\vcpkg> .\vcpkg install sqlite3
 -- CURRENT_INSTALLED_DIR=D:/src/vcpkg/installed/x86-windows
 -- DOWNLOADS=D:/src/vcpkg/downloads
--- CURRENT_PACKAGES_DIR=D:/src/vcpkg/packages/cpprestsdk_x86-windows
--- CURRENT_BUILDTREES_DIR=D:/src/vcpkg/buildtrees/cpprestsdk
--- CURRENT_PORT_DIR=D:/src/vcpkg/ports/cpprestsdk/.
--- Cloning done
--- Adding worktree and patching done
+-- CURRENT_PACKAGES_DIR=D:/src/vcpkg/packages/sqlite3_x86-windows
+-- CURRENT_BUILDTREES_DIR=D:/src/vcpkg/buildtrees/sqlite3
+-- CURRENT_PORT_DIR=D:/src/vcpkg/ports/sqlite3/.
+-- Downloading https://sqlite.org/2016/sqlite-amalgamation-3150000.zip...
+-- Downloading https://sqlite.org/2016/sqlite-amalgamation-3150000.zip... OK
+-- Testing integrity of downloaded file...
+-- Testing integrity of downloaded file... OK
+-- Extracting source D:/src/vcpkg/downloads/sqlite-amalgamation-3150000.zip
+-- Extracting done
 -- Configuring x86-windows-rel
 -- Configuring x86-windows-rel done
 -- Configuring x86-windows-dbg
@@ -71,22 +58,24 @@ PS D:\src\vcpkg> .\vcpkg install cpprestsdk
 -- Package x86-windows-rel done
 -- Package x86-windows-dbg
 -- Package x86-windows-dbg done
-Package cpprestsdk:x86-windows is installed
+-- Performing post-build validation
+-- Performing post-build validation done
+Package sqlite3:x86-windows is installed
 ```
-In addition to installing, `vcpkg` caches a pristine copy of the built library inside the `packages\` directory (in this case, `packages\cpprestsdk_x86-windows`). This allows you to quickly uninstall and reinstall the library in the future using the `remove` and `install` commands.
+In addition to installing, `vcpkg` caches a pristine copy of the built library inside the `packages\` directory -- in this case, `packages\sqlite3_x86-windows`. This allows you to quickly uninstall and reinstall the library in the future using the `remove` and `install` commands.
 
-We can check that cpprestsdk was successfully installed for x86 windows desktop by running the `list` command.
+We can check that sqlite3 was successfully installed for x86 windows desktop by running the `list` command.
 ```
 PS D:\src\vcpkg> .\vcpkg list
-cpprestsdk:x86-windows      2.8              A modern C++11 library to connect with web servic...
+sqlite3:x86-windows         3.15.0           SQLite is a software library that implements a se...
 ```
 
 To install for other architectures and platforms such as Universal Windows Platform or x64 Desktop, you can suffix the package name with `:<target>`.
 ```
-PS D:\src\vcpkg> .\vcpkg install cpprestsdk:x86-uwp zlib:x64-windows
+PS D:\src\vcpkg> .\vcpkg install sqlite3:x86-uwp zlib:x64-windows
 ```
 
-See `vcpkg help triplet` for all supported targets.
+See `.\vcpkg help triplet` for all supported targets.
 
 <a name="example-1-2"></a>
 ### Step 2: Use
@@ -104,7 +93,9 @@ 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.* 
 
-To remove the integration for your user, you can use `vcpkg integrate remove`.
+You can now simply use File -> New Project in Visual Studio 2015 or Visual Studio "15" Preview 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`.
 
 <a name="example-1-2-b"></a>
 #### Option B: CMake (Toolchain File)
@@ -117,22 +108,19 @@ Let's first make a simple CMake project with a main file.
 cmake_minimum_required(VERSION 3.0)
 project(test)
 
-find_library(CPPREST_LIBRARY cpprest_2_8)
-find_path(CPPREST_INCLUDE_DIR cpprest/version.h)
+find_package(Sqlite3 REQUIRED)
 
-include_directories(${CPPREST_INCLUDE_DIR})
-link_libraries(${CPPREST_LIBRARY})
+link_libraries(sqlite3)
 add_executable(main main.cpp)
 ```
 ```cpp
 // main.cpp
-#include <cpprest/json.h>
+#include <sqlite3.h>
 #include <stdio.h>
 
 int main()
 {
-    auto v = web::json::value::parse(U("[1,2,3,4]"));
-    printf("Success\n");
+    printf("%s\n", sqlite3_libversion());
     return 0;
 }
 ```
@@ -152,17 +140,19 @@ Build succeeded.
 
 Time Elapsed 00:00:02.38
 PS D:\src\cmake-test\build> .\Debug\main.exe
-Success
+3.15.0
 ```
 
+*Note: The correct sqlite3.dll is automatically copied to the output folder when building for x86-windows. You will need to distribute this along with your application.*
+
 <a name="example-1-2-c"></a>
 #### Option C: Other buildsystems
 
 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`
+* 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`
+* 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.
diff --git a/docs/FAQ.md b/docs/FAQ.md
index aff30468b..0a82d320e 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -3,29 +3,34 @@
 Vcpkg is a tool to acquire C++ open source library and rebuild them on Windows. 
 
 ## Can I contribute a new library?
-Yes! Start out by reading our [contribution guidelines](CONTRIBUTING.md).
+Yes! Start out by reading our [contribution guidelines](../CONTRIBUTING.md).
 
 ## Can Vcpkg create pre-built binary packages? What is the binary format used by Vcpkg?
 In the preview release, we do not have a supported way to distribute individual binary packages. This avoids the issue of trying to use a specific pre-built package against differently built dependencies. As such, we have also not specified a stable format for the built library packages.
 
 We instead recommend copying the entire system as a whole (which ensures that every package and its dependencies stay in sync with each other).
 
-## How will the libs will be updated locally?
+## How do I update libraries?
 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\`](../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.md#example-2)).
+
+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 [Example #2](EXAMPLES.md#example-2) 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 `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.
 
-To see an example of this, look at the [`opengl`](../ports/opengl/portfile.cmake) package which simply copies files out of the Windows SDK.
+To see an example of this, look at [`ports\opengl\portfile.cmake`](../ports/opengl/portfile.cmake) package which simply copies files out of the Windows SDK.
 
 ## Which platforms I can target with Vcpkg?
 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.exe` 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 an [issue](https://github.com/microsoft/vcpkg/issues).
+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).
 
 ## 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!). This is because a package in Vcpkg corresponds to the `X-dev` or `X-devel` packages in other system package managers.
@@ -48,23 +53,21 @@ By saving the changes to the portfile (and checking them in), you'll get the sam
 ## How is CMake used internally by Vcpkg?
 Vcpkg uses CMake internally as a build scripting language. This is because CMake is already an extremely common build system for cross-platform open source libraries and is becoming very popular for C++ projects in general. It is easy to acquire on Windows (does not require system-wide installation) and reasonably legible for unfamiliar users.
 
-## How does my list of libraries get updated?
-The list of libraries is enumerated from the `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.md#example-2)).
-
-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.
-
-## Will it support also downloading compiled binaries from a public or private server?
-We do plan to eventually support downloading precompiled binaries, similar to other systems package managers.
+## Will Vcpkg support downloading compiled binaries from a public or private server?
+We do plan to eventually support downloading precompiled binaries, similar to other system package managers.
 
 In a corporate scenario, we currently recommend building the libraries once and distributing the entire vcpkg root directory to everyone else on the project through some raw file transport such as a network share or HTTP host.
 
 ## What Visual C++ toolsets are supported?
 We plan to only support Visual Studio 2015 and above.
 
+## Why does Visual Studio not use my libraries with user-wide integration enabled?
+Enabling user-wide integration (`vcpkg integrate install`) changes the default for some project properties. In particular, "C/C++/General/Additional Include Directories" and "Linker/General/Additional Library Directories" are normally blank *without* user-wide integration. *With* integration, a blank value means that the augmented default supplied by vcpkg is overridden, and headers/libraries will not be found. To reinstate the default, set the properties to inherit from parent.
+
 ## Can I acquire my package's sources by Git url+tag?
 Yes, however we prefer compressed archives of the specific release/commit since the internal downloads and build trees are meant to be read only. Github provides archives for every commit, tag, and branch, so it's always possible to perform this substitution for repositories hosted there.
 
-See `ports\cpprestsdk\portfile.cmake` and `ports\opencv\portfile.cmake` for examples of using git directly.
+See [`ports\cpprestsdk\portfile.cmake`](../ports/cpprestsdk/portfile.cmake) for an example of using git directly.
 
 ## 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.
diff --git a/docs/PRIVACY.md b/docs/PRIVACY.md
index f50c2938f..ad345c809 100644
--- a/docs/PRIVACY.md
+++ b/docs/PRIVACY.md
@@ -5,14 +5,14 @@
 ## Do you collect telemetry data? What is it used for? 
 
 We do collect telemetry data from usage of "vcpkg.exe". We explicitly ONLY collect information from invocations of the tool itself; we do NOT add any tracking information into the produced libraries. 
-We use this information to understand the usage the issue and what we can do to improve the tool. 
+We use this information to understand usage issues and to guide tool improvements.
 
 
 ## 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.
 
-Here is an example of an event for the command line "vcpkg install zlib": 
+Here is an example of an event for the command line `vcpkg install zlib`:
 ```
 [{
     "ver": 1, 
@@ -40,7 +40,7 @@ Here is an example of an event for the command line "vcpkg install zlib":
     } 
 }] 
 ```
-In the source code (included in every release), you can search for calls to the functions "TrackProperty" and "TrackMetric" to see every specific data point we collect. 
+In the source code (included in `toolsrc\`), you can search for calls to the functions `TrackProperty()` and `TrackMetric()` to see every specific data point we collect.
 
 
 ## Is the data stored on my system? 
diff --git a/docs/EXAMPLE_fix_libpng.md b/docs/example-3-patch-libpng.md
index 535927c16..cc963cbfc 100644
--- a/docs/EXAMPLE_fix_libpng.md
+++ b/docs/example-3-patch-libpng.md
@@ -1,6 +1,6 @@
-Fixing libpng:x86-uwp
-=====================
+## Example 3: Patching libpng to work for uwp-x86
 
+### Initial error logs
 First, try building:
 
 ```
@@ -59,6 +59,9 @@ Next, looking at the above logs (build-...-out.log and build-...-err.log).
 
 Time Elapsed 00:00:04.19
 ```
+
+### Identify the problematic code
+
 Taking a look at [MSDN](https://msdn.microsoft.com/en-us/library/windows/desktop/ms682658(v=vs.85).aspx) shows that `ExitProcess` is only available for desktop apps. Additionally, it's useful to see the surrounding context:
 
 ```c
@@ -107,7 +110,9 @@ This already gives us some great clues, but the full definition tells the comple
 #endif
 ```
 
-`abort()` is a standard CRT call and certainly available in UWP, so we just need to convince libpng to be more platform agnostic. The easiest and most reliable way to achive is to patch the code; while in this particular case we could pass in a compiler flag to override `PNG_ABORT` because this is a private header, in general it is more reliable to avoid adding more required compiler switches when possible (especially when it isn't already exposed as a CMake option).
+`abort()` is a standard CRT call and certainly available in UWP, so we just need to convince libpng to be more platform agnostic. The easiest and most reliable way to achieve this is to patch the code; while in this particular case we could pass in a compiler flag to override `PNG_ABORT` because this is a private header, in general it is more reliable to avoid adding more required compiler switches when possible (especially when it isn't already exposed as a CMake option).
+
+### Patching the code to improve compatibility
 
 I recommend using git to create the patch file, since you'll already have it installed.
 ```
@@ -144,22 +149,18 @@ Finally, we need to apply the patch after extracting the source.
 ...
 vcpkg_extract_source_archive(${ARCHIVE})
 
-find_program(GIT git)
-vcpkg_execute_required_process(
-    COMMAND ${GIT} init
-    WORKING_DIRECTORY ${CURRENT_BUILDTREES_DIR}/src/libpng-1.6.24
-    LOGNAME git-init
-)
-execute_process(
-    COMMAND ${GIT} apply "${CMAKE_CURRENT_LIST_DIR}/use-abort-on-all-platforms.patch" --ignore-whitespace --whitespace=nowarn
-    WORKING_DIRECTORY ${CURRENT_BUILDTREES_DIR}/src/libpng-1.6.24
+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_configure_cmake(
 ...
 ```
 
-To be completely sure this works from the top, we need to purge the package:
+### Verification
+
+To be completely sure this works from scratch, we need to purge the package:
 
 ```
 PS D:\src\vcpkg> vcpkg remove --purge libpng:x86-uwp