Initial commit

6 files changed, 649 insertions, 0 deletions

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
new file mode 100644
index 000000000..6e019d977
--- /dev/null
+++ b/docs/CONTRIBUTING.md
@@ -0,0 +1,33 @@
+# Contribution Guidelines
+
+Vcpkg is a community driven effort to build a productive and robust ecosystem of native libraries - your contributions are invaluable!
+
+## Issues
+
+The easiest way to contribute is by reporting issues with either `vcpkg.exe` or an existing package on [GitHub](https://github.com/Microsoft/vcpkg). When reporting an issue with `vcpkg.exe`, make sure to clearly state:
+- The machine setup: "I'm using Windows 10 Anniversary Update. My machine is using the fr-fr locale. I successfully ran 'install boost'." 
+- The steps to reproduce: "I run 'vcpkg list'"
+- The outcome you expected: "I expected to see 'boost:x86-windows'"
+- The actual outcome: "I get no output at all" or "I get a crash dialog"
+
+When reporting an issue with a package, make sure to clearly state:
+- The machine setup (as above)
+- What package and version you're building: "opencv 3.1.0"
+- Any relevant error logs from the build process.
+
+## Pull Requests
+
+We are happy to accept pull requests for fixes, features, new packages, and updates to existing packages. In order to avoid wasting your time, we highly encourage opening an issue to discuss whether the PR you're thinking about making will be acceptable. This is doubly true for features and new packages.
+
+### New package Guidelines
+
+We're glad you're interested in submitting a new package! Here are some guidelines to help you author an excellent portfile:
+- Avoid functional patches. Patches should be considered a last resort to implement compatibility when there's no other way. 
+- When patches can't be avoided, do not modify the default behavior. The ideal lifecycle of a patch is to get merged upstream and no longer be needed. Try to keep this goal in mind when deciding how to patch something.
+- Prefer to use the `vcpkg_xyz` functions over raw `execute_command` calls. This makes long term maintenance easier when new features (such as custom compiler flags or generators) are added.
+
+## Legal
+
+You will need to complete a Contributor License Agreement (CLA) before your pull request can be accepted. This agreement testifies that you are granting us permission to use the source code you are submitting, and that this work is being submitted under appropriate license that we can use it.
+
+You can complete the CLA by going through the steps at https://cla.microsoft.com. Once we have received the signed CLA, we'll review the request. You will only need to do this once.
diff --git a/docs/EXAMPLES.md b/docs/EXAMPLES.md
new file mode 100644
index 000000000..723e49bed
--- /dev/null
+++ b/docs/EXAMPLES.md
@@ -0,0 +1,269 @@
+# Vcpkg
+
+## Overview
+Vcpkg helps you get C and C++ libraries on Windows.
+
+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-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>
+    - <a href="#example-1-2-b">Option B: CMake (Toolchain file)</a>
+    - <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 name="example-1"></a>
+## Example 1: C++ REST SDK
+<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:
+```
+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
+```
+Looking at the list, we can see that the port is named "cpprestsdk".
+
+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).
+```
+PS D:\src\vcpkg> .\vcpkg install cpprestsdk
+-- 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
+-- Configuring x86-windows-rel
+-- Configuring x86-windows-rel done
+-- Configuring x86-windows-dbg
+-- Configuring x86-windows-dbg done
+-- Build x86-windows-rel
+-- Build x86-windows-rel done
+-- Build x86-windows-dbg
+-- Build x86-windows-dbg done
+-- Package x86-windows-rel
+-- Package x86-windows-rel done
+-- Package x86-windows-dbg
+-- Package x86-windows-dbg done
+Package cpprestsdk: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.
+
+We can check that cpprestsdk 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...
+```
+
+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
+```
+
+See `vcpkg help arch` for all supported targets.
+
+<a name="example-1-2"></a>
+### Step 2: Use
+<a name="example-1-2-a"></a>
+#### Option A: VS 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 require administrator access the first time it is used on a given machine. After the first use, administrator access is no longer required and the integration is on a per-user basis.
+```
+PS D:\src\vcpkg> .\vcpkg integrate install
+Applied user-wide integration for this vcpkg root.
+
+All C++ projects can now #include any installed libraries.
+Linking will be handled automatically.
+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`.
+
+<a name="example-1-2-b"></a>
+#### Option B: CMake (Toolchain File)
+
+The best way to use installed libraries with cmake is via the toolchain file `scripts\buildsystems\vcpkg.cmake`. To use this file, you simply need to add it onto your CMake command line as `-DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake`.
+
+Let's first make a simple CMake project with a main file.
+```cmake
+# CMakeLists.txt
+cmake_minimum_required(VERSION 3.0)
+project(test)
+
+find_library(CPPREST_LIBRARY cpprest_2_8)
+find_path(CPPREST_INCLUDE_DIR cpprest/version.h)
+
+include_directories(${CPPREST_INCLUDE_DIR})
+link_libraries(${CPPREST_LIBRARY})
+add_executable(main main.cpp)
+```
+```cpp
+// main.cpp
+#include <cpprest/json.h>
+#include <stdio.h>
+
+int main()
+{
+    auto v = web::json::value::parse(U("[1,2,3,4]"));
+    printf("Success\n");
+    return 0;
+}
+```
+
+Then, we build our project in the normal CMake way:
+```
+PS D:\src\cmake-test> mkdir build
+PS D:\src\cmake-test> cd build
+PS D:\src\cmake-test\build> cmake .. "-DCMAKE_TOOLCHAIN_FILE=D:\src\vcpkg\scripts\buildsystems\vcpkg.cmake"
+    // omitted CMake output here //
+-- Build files have been written to: D:/src/cmake-test/build
+PS D:\src\cmake-test\build> cmake --build .
+    // omitted MSBuild output here //
+Build succeeded.
+    0 Warning(s)
+    0 Error(s)
+
+Time Elapsed 00:00:02.38
+PS D:\src\cmake-test\build> .\Debug\main.exe
+Success
+```
+
+<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 `.dll` files are installed to `installed\x86-windows\bin`
+* Debug `.lib` files are installed to `installed\x86-windows\debug\lib`
+* 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 `exe` or *prepend* the correct `bin` directory to your path.
+
+Example for setting the path for debug mode in powershell:
+```
+PS D:\src\vcpkg> $env:path = "D:\src\vcpkg\installed\x86-windows\debug\bin;" + $env:path
+```
+<a name="example-1-2-d"></a>
+#### Option D: VS Project (Individual Project integration)
+
+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.
+```
+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.*
+
+<a name="example-2"></a>
+## Example 2: Package a remote project (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.*
+
+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.
+
+*Since zlib is already packaged as zlib, we will use the name zlib2 for this example.*
+
+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.*
+
+All this information can then be passed into the `create` command, which will download the sources and bootstrap the packaging process inside `ports\<packagename>`.
+
+```
+PS D:\src\vcpkg> .\vcpkg create zlib2 http://zlib.net/zlib128.zip zlib128.zip
+-- Generated portfile: D:/src/vcpkg/ports/zlib2/portfile.cmake
+```
+
+### 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.
+
+*For zlib2, we'll create the file `ports\zlib2\CONTROL` with the following contents:*
+```
+Source: zlib2
+Version: 1.2.8
+Description: A Massively Spiffy Yet Delicately Unobtrusive Compression Library
+```
+
+### Tweak the generated portfile
+The generated `portfile.cmake` will need some editing to correctly package most libraries in the wild, however we can start by trying out the build.
+
+```
+PS D:\src\vcpkg> .\vcpkg build zlib2
+-- CURRENT_INSTALLED_DIR=D:/src/vcpkg/installed/x86-windows
+-- DOWNLOADS=D:/src/vcpkg/downloads
+-- CURRENT_PACKAGES_DIR=D:/src/vcpkg/packages/zlib2_x86-windows
+-- CURRENT_BUILDTREES_DIR=D:/src/vcpkg/buildtrees/zlib2
+-- CURRENT_PORT_DIR=D:/src/vcpkg/ports/zlib2
+-- Using cached D:/src/vcpkg/downloads/zlib128.zip
+-- Extracting source D:/src/vcpkg/downloads/zlib128.zip
+-- Extracting done
+-- Configuring x86-windows-rel
+CMake Error at scripts/cmake/vcpkg_execute_required_process.cmake:13 (message):
+  Command failed: C:/Program Files
+  (x86)/CMake/bin/cmake.exe;D:/src/vcpkg/buildtrees/zlib2/src/zlib128;-G;Ninja;-DCMAKE_VERBOSE_MAKEFILE=ON;-DCMAKE_BUILD_TYPE=Release;-DCMAKE_TOOLCHAIN_FILE=D:/src/vcpkg/triplets/x86-windows.cmake;-DCMAKE_PREFIX_PATH=D:/src/vcpkg/installed/x86-windows;-
+DCMAKE_INSTALL_PREFIX=D:/src/vcpkg/packages/zlib2_x86-windows
+
+
+  Working Directory: D:/src/vcpkg/buildtrees/zlib2/x86-windows-rel
+
+  See logs for more information:
+
+      D:/src/vcpkg/buildtrees/zlib2/config-x86-windows-rel-out.log
+      D:/src/vcpkg/buildtrees/zlib2/config-x86-windows-rel-err.log
+
+Call Stack (most recent call first):
+  scripts/cmake/vcpkg_configure_cmake.cmake:15 (vcpkg_execute_required_process)
+  ports/zlib2/portfile.cmake:8 (vcpkg_configure_cmake)
+  scripts/ports.cmake:105 (include)
+  scripts/ports.cmake:184 (build)
+```
+
+At this point, it is a matter of reading the error messages and log files while steadily improving the quality of the portfile. Zlib required providing a discrete copy of the LICENSE to copy into the package, suppressing the build and installation of executables and headers, and removing the static libraries after they were installed.
+
+### 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
+    - mpg123
+    - glew
+- Non-CMake, custom buildsystem
+    - openssl
+    - boost
diff --git a/docs/EXAMPLE_fix_libpng.md b/docs/EXAMPLE_fix_libpng.md
new file mode 100644
index 000000000..5b97457d5
--- /dev/null
+++ b/docs/EXAMPLE_fix_libpng.md
@@ -0,0 +1,206 @@
+Fixing libpng:x86-uwp
+=====================
+
+First, try building:
+
+```
+PS D:\src\cpp-packages> vcpkg install libpng:x86-uwp
+-- SYSROOT=D:/src/cpp-packages/sysroot/x86-uwp
+-- DISTDIR=D:/src/cpp-packages/distdir
+-- CURRENT_SOFTWARE_DIR=D:/src/cpp-packages/software/libpng_x86-uwp
+-- CURRENT_WORKSRC_DIR=D:/src/cpp-packages/worksrc/libpng
+-- CURRENT_PORT_DIR=D:/src/cpp-packages/ports/libpng/.
+-- Using cached D:/src/cpp-packages/distdir/libpng-1.6.24.tar.xz
+-- Extracting done
+-- Configuring x86-uwp-rel
+-- Configuring x86-uwp-rel done
+-- Configuring x86-uwp-dbg
+-- Configuring x86-uwp-dbg done
+-- Build x86-uwp-rel
+CMake Error at scripts/cmake/execute_required_process.cmake:14 (message):
+  Command failed: C:/Program
+  Files/CMake/bin/cmake.exe;--build;.;--config;Release
+
+  Working Directory: D:/src/cpp-packages/worksrc/libpng/x86-uwp-rel
+
+  See logs for more information:
+
+      D:\src\cpp-packages\worksrc\libpng\build-x86-uwp-rel-out.log
+      D:\src\cpp-packages\worksrc\libpng\build-x86-uwp-rel-err.log
+
+Call Stack (most recent call first):
+  scripts/cmake/build_standard_cmake.cmake:3 (execute_required_process)
+  ports/libpng/portfile.cmake:22 (build_standard_cmake)
+  scripts/ports.cmake:84 (include)
+
+
+Error: build command failed
+```
+
+Next, looking at the above logs (build-...-out.log and build-...-err.log).
+
+```
+// build-x86-uwp-rel-out.log
+...
+"D:\src\cpp-packages\worksrc\libpng\x86-uwp-rel\ALL_BUILD.vcxproj" (default target) (1) ->
+"D:\src\cpp-packages\worksrc\libpng\x86-uwp-rel\png.vcxproj" (default target) (3) ->
+(ClCompile target) -> 
+  D:\src\cpp-packages\worksrc\libpng\src\libpng-1.6.24\pngerror.c(775): warning C4013: 'ExitProcess' undefined; assuming extern returning int [D:\src\cpp-packages\worksrc\libpng\x86-uwp-rel\png.vcxproj]
+
+
+"D:\src\cpp-packages\worksrc\libpng\x86-uwp-rel\ALL_BUILD.vcxproj" (default target) (1) ->
+"D:\src\cpp-packages\worksrc\libpng\x86-uwp-rel\png.vcxproj" (default target) (3) ->
+(Link target) -> 
+  pngerror.obj : error LNK2019: unresolved external symbol _ExitProcess referenced in function _png_longjmp [D:\src\cpp-packages\worksrc\libpng\x86-uwp-rel\png.vcxproj]
+  D:\src\cpp-packages\worksrc\libpng\x86-uwp-rel\Release\libpng16.dll : fatal error LNK1120: 1 unresolved externals [D:\src\cpp-packages\worksrc\libpng\x86-uwp-rel\png.vcxproj]
+
+    1 Warning(s)
+    2 Error(s)
+
+Time Elapsed 00:00:04.19
+```
+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
+/* worksrc\libpng\src\libpng-1.6.24\pngerror.c:769 */
+    /* If control reaches this point, png_longjmp() must not return. The only
+    * choice is to terminate the whole process (or maybe the thread); to do
+    * this the ANSI-C abort() function is used unless a different method is
+    * implemented by overriding the default configuration setting for
+    * PNG_ABORT().
+    */
+    PNG_ABORT();
+```
+
+A recursive search for `PNG_ABORT` reveals the definition:
+```
+PS D:\src\cpp-packages\worksrc\libpng\src\libpng-1.6.24> findstr /snipl "PNG_ABORT" *
+CHANGES:701:  Added PNG_SETJMP_SUPPORTED, PNG_SETJMP_NOT_SUPPORTED, and PNG_ABORT() macros
+libpng-manual.txt:432:errors will result in a call to PNG_ABORT() which defaults to abort().
+libpng-manual.txt:434:You can #define PNG_ABORT() to a function that does something
+libpng-manual.txt:2753:errors will result in a call to PNG_ABORT() which defaults to abort().
+libpng-manual.txt:2755:You can #define PNG_ABORT() to a function that does something
+libpng-manual.txt:4226:PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()),
+libpng.3:942:errors will result in a call to PNG_ABORT() which defaults to abort().
+libpng.3:944:You can #define PNG_ABORT() to a function that does something
+libpng.3:3263:errors will result in a call to PNG_ABORT() which defaults to abort().
+libpng.3:3265:You can #define PNG_ABORT() to a function that does something
+libpng.3:4736:PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()),
+png.h:994: * will use it; otherwise it will call PNG_ABORT().  This function was
+pngerror.c:773:    * PNG_ABORT().
+pngerror.c:775:   PNG_ABORT();
+pngpriv.h:459:#ifndef PNG_ABORT
+pngpriv.h:461:#    define PNG_ABORT() ExitProcess(0)
+pngpriv.h:463:#    define PNG_ABORT() abort()
+```
+
+This already gives us some great clues, but the full definition tells the complete story.
+
+```c
+/* worksrc\libpng\src\libpng-1.6.24\pngpriv.h:459 */
+#ifndef PNG_ABORT
+#  ifdef _WINDOWS_
+#    define PNG_ABORT() ExitProcess(0)
+#  else
+#    define PNG_ABORT() abort()
+#  endif
+#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).
+
+I recommend using git to create the patch file, since you'll already have it installed.
+```
+PS D:\src\cpp-packages\worksrc\libpng\src\libpng-1.6.24> git init .
+Initialized empty Git repository in D:/src/cpp-packages/worksrc/libpng/src/libpng-1.6.24/.git/
+
+PS D:\src\cpp-packages\worksrc\libpng\src\libpng-1.6.24> git add .
+warning: LF will be replaced by CRLF in ANNOUNCE.
+The file will have its original line endings in your working directory.
+...
+
+PS D:\src\cpp-packages\worksrc\libpng\src\libpng-1.6.24> git commit -m "temp"
+[master (root-commit) 68f253f] temp
+ 422 files changed, 167717 insertions(+)
+...
+```
+
+Now we can modify `pngpriv.h` to use `abort()` everywhere.
+```c
+/* worksrc\libpng\src\libpng-1.6.24\pngpriv.h:459 */
+#ifndef PNG_ABORT
+#  define PNG_ABORT() abort()
+#endif
+```
+
+The output of `git diff` is already in patch format, so we just need to save the patch into the `ports/libpng` directory.
+```
+PS worksrc\libpng\src\libpng-1.6.24> git diff | out-file -enc ascii ..\..\..\..\ports\libpng\use-abort-on-all-platforms.patch
+```
+
+Finally, we need to apply the patch after extracting the source.
+```cmake
+# ports\libpng\portfile.cmake
+...
+extract_source_archive(${ARCHIVE})
+
+find_program(GIT git)
+execute_required_process(
+    COMMAND ${GIT} init
+    WORKING_DIRECTORY ${CURRENT_WORKSRC_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_WORKSRC_DIR}/src/libpng-1.6.24
+)
+
+configure_standard_cmake(
+...
+```
+
+To be completely sure this works from the top, we need to clear out all the caches.
+
+```
+PS D:\src\cpp-packages> vcpkg remove libpng:x86-uwp
+Package libpng:x86-uwp was successfully removed
+PS D:\src\cpp-packages> vcpkg purge libpng:x86-uwp
+Cleaned up D:\src\cpp-packages\software\libpng_x86-uwp
+PS D:\src\cpp-packages> vcpkg clean libpng
+Cleaned up D:\src\cpp-packages\worksrc\libpng
+```
+
+Now we try a fresh, from scratch install.
+```
+PS D:\src\cpp-packages> vcpkg install libpng:x86-uwp
+-- SYSROOT=D:/src/cpp-packages/sysroot/x86-uwp
+-- DISTDIR=D:/src/cpp-packages/distdir
+-- CURRENT_SOFTWARE_DIR=D:/src/cpp-packages/software/libpng_x86-uwp
+-- CURRENT_WORKSRC_DIR=D:/src/cpp-packages/worksrc/libpng
+-- CURRENT_PORT_DIR=D:/src/cpp-packages/ports/libpng/.
+-- Using cached D:/src/cpp-packages/distdir/libpng-1.6.24.tar.xz
+-- Extracting source D:/src/cpp-packages/distdir/libpng-1.6.24.tar.xz
+-- Extracting done
+-- Configuring x86-uwp-rel
+-- Configuring x86-uwp-rel done
+-- Configuring x86-uwp-dbg
+-- Configuring x86-uwp-dbg done
+-- Build x86-uwp-rel
+-- Build x86-uwp-rel done
+-- Build x86-uwp-dbg
+-- Build x86-uwp-dbg done
+-- Package x86-uwp-rel
+-- Package x86-uwp-rel done
+-- Package x86-uwp-dbg
+-- Package x86-uwp-dbg done
+Package libpng:x86-uwp is installed
+```
+
+Finally, to fully commit and publish the changes, we need to bump the internal release number and add the patch file to source control.
+
+```
+# ports\libpng\CONTROL
+Source: libpng
+Version: 1.6.24-1
+Build-Depends: zlib
+```
diff --git a/docs/FAQ.md b/docs/FAQ.md
new file mode 100644
index 000000000..53ef6fa7c
--- /dev/null
+++ b/docs/FAQ.md
@@ -0,0 +1,90 @@
+# Frequently Asked Questions: Vcpkg
+
+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).
+
+## 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?
+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.
+
+## 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.
+
+## 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).
+
+## 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.
+
+To use different versions of a library (for different projects), we recommend making separate instances of Vcpkg and using the [per-project integration mechanisms](EXAMPLES.md#example-1-2-d). The versions of each library are specified by the files in `ports\`, so they are easily manipulated using standard VCS techniques. This makes it very easy to roll back the entire set of libraries to a consistent set of older versions which all work with each other. If you need to then pin a specific library forward, that is as easy as checking out the appropriate version of `ports\package\`.
+
+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?
+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.
+
+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.
+
+## 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.
+
+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.
+
+## 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.
+
+## 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.
+
+- **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.
+
+- **Per-dll vs Per-application**. NuGet is highly project centric. This works well in managed languages with naturally stable ABIs, because base libraries can continue to evolve without breaking those higher up. However, in native languages where the ABI is much more fragile, the only robust strategy is to explicitly build each library against the exact dependencies that will be included in the final application. This is difficult to ensure in NuGet and leads to a highly disconnected and independently versioned ecosystem.
+
+## Why not Conan?
+Conan.io is a publicly-federated, project-centric, cross-platform, C++ package manager written in python. Our primary differences are:
+
+- **Public federation vs private federation**. Conan relies on individuals publishing independent copies of each package. We believe this approach encourages a large number of packages that are all broken in different ways. We believe it is a waste of user's time to pick through the list of 20+ public packages for Boost 1.56 to determine the handful that will work for their particular situation. In contrast, we believe there should be a single, collaboratively maintained version which works for the vast majority of cases and allow users to hack freely on their private versions. We believe this will result in a set of high quality packages that are heavily tested with each other and form a fantastic base for any private modifications you need.
+
+- **Per-dll vs Per-application**. When dependencies are independently versioned on a library level, it encourages every build environment to be a completely unique, unable to take advantage of or contribute to a solid, well tested ecosystem. In contrast, by versioning all libraries together as a platform (similar to a system package manager), we hope to congregate testing and effort on very common sets of library versions to maximize the quality and stability of the ecosystem. This also completely designs out the ability for a library to ask for versions that conflict with the application's choices (I want openssl Z and boost X but X only works with openssl Y).
+
+- **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.
+
+## Why not Chocolatey?
+Chocolatey is an excellent system for distributing desktop utilities. However, it is not 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/PRIVACY.md b/docs/PRIVACY.md
new file mode 100644
index 000000000..f50c2938f
--- /dev/null
+++ b/docs/PRIVACY.md
@@ -0,0 +1,48 @@
+
+# Privacy document for vcpkg 
+
+
+## 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. 
+
+
+## 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": 
+```
+[{
+    "ver": 1, 
+    "name": "Microsoft.ApplicationInsights.Event", 
+    "time": "2016-09-01T00:19:10.949Z", 
+    "sampleRate": 100.000000, 
+    "seq": "0:0", 
+    "iKey": "aaaaaaaa-4393-4dd9-ab8e-97e8fe6d7603", 
+    "flags": 0.000000, 
+    "tags": { 
+        "ai.device.os": "Windows", 
+        "ai.device.osVersion": "10.0.14912", 
+        "ai.session.id": "aaaaaaaa-7c69-4b83-7d82-8a4198d7e88d", 
+        "ai.user.id": "aaaaaaaa-c9ab-4bf5-0847-a3455f539754", 
+        "ai.user.accountAcquisitionDate": "2016-08-20T00:38:09.860Z" 
+    }, 
+    "data": { 
+        "baseType": "EventData", 
+        "baseData": { 
+            "ver": 2, 
+            "name": "commandline_test7", 
+            "properties": { "version":"0.0.30-9b4e44a693459c0a618f370681f837de6dd95a30","cmdline":"install zlib","command":"install","installplan":"zlib:x86-windows" }, 
+            "measurements": { "elapsed_us":68064.355736 } 
+        } 
+    } 
+}] 
+```
+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. 
+
+
+## Is the data stored on my system? 
+
+We store each event document in your temporary files directory. These will be cleaned out whenever you clear your temporary files. 
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
new file mode 100644
index 000000000..df6e3853e
--- /dev/null
+++ b/docs/ROADMAP.md
@@ -0,0 +1,3 @@
+# Roadmap
+
+