Merge pull request #1111 from Microsoft/docs

[vcpkg] Documentation revamp using MkDocs & readthedocs

3 files changed, 461 insertions, 0 deletions

diff --git a/docs/examples/packaging-zlib.md b/docs/examples/packaging-zlib.md
new file mode 100644
index 000000000..81bc58314
--- /dev/null
+++ b/docs/examples/packaging-zlib.md
@@ -0,0 +1,80 @@
+## Example 2: Packaging 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>`.
+
+```no-highlight
+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:*
+```no-highlight
+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.
+
+```no-highlight
+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/examples/patching-libpng.md b/docs/examples/patching-libpng.md
new file mode 100644
index 000000000..2337b73da
--- /dev/null
+++ b/docs/examples/patching-libpng.md
@@ -0,0 +1,204 @@
+## Example 3: Patching libpng to work for x86-uwp
+
+### Initial error logs
+First, try building:
+
+```no-highlight
+PS D:\src\vcpkg> vcpkg install libpng:x86-uwp
+-- CURRENT_INSTALLED_DIR=D:/src/vcpkg/installed/x86-uwp
+-- DOWNLOADS=D:/src/vcpkg/downloads
+-- CURRENT_PACKAGES_DIR=D:/src/vcpkg/packages/libpng_x86-uwp
+-- CURRENT_BUILDTREES_DIR=D:/src/vcpkg/buildtrees/libpng
+-- CURRENT_PORT_DIR=D:/src/vcpkg/ports/libpng/.
+-- Using cached D:/src/vcpkg/downloads/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/vcpkg/buildtrees/libpng/x86-uwp-rel
+
+  See logs for more information:
+
+      D:\src\vcpkg\buildtrees\libpng\build-x86-uwp-rel-out.log
+      D:\src\vcpkg\buildtrees\libpng\build-x86-uwp-rel-err.log
+
+Call Stack (most recent call first):
+  scripts/cmake/vcpkg_build_cmake.cmake:3 (execute_required_process)
+  ports/libpng/portfile.cmake:22 (vcpkg_build_cmake)
+  scripts/ports.cmake:84 (include)
+
+
+Error: build command failed
+```
+
+Next, looking at the above logs (build-...-out.log and build-...-err.log).
+
+```no-highlight
+// build-x86-uwp-rel-out.log
+...
+"D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\ALL_BUILD.vcxproj" (default target) (1) ->
+"D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\png.vcxproj" (default target) (3) ->
+(ClCompile target) -> 
+  D:\src\vcpkg\buildtrees\libpng\src\libpng-1.6.24\pngerror.c(775): warning C4013: 'ExitProcess' undefined; assuming extern returning int [D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\png.vcxproj]
+
+
+"D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\ALL_BUILD.vcxproj" (default target) (1) ->
+"D:\src\vcpkg\buildtrees\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\vcpkg\buildtrees\libpng\x86-uwp-rel\png.vcxproj]
+  D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\Release\libpng16.dll : fatal error LNK1120: 1 unresolved externals [D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\png.vcxproj]
+
+    1 Warning(s)
+    2 Error(s)
+
+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
+/* buildtrees\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:
+```no-highlight
+PS D:\src\vcpkg\buildtrees\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
+/* buildtrees\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 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
+
+We recommend using git to create the patch file, since you'll already have it installed.
+```no-highlight
+PS D:\src\vcpkg\buildtrees\libpng\src\libpng-1.6.24> git init .
+Initialized empty Git repository in D:/src/vcpkg/buildtrees/libpng/src/libpng-1.6.24/.git/
+
+PS D:\src\vcpkg\buildtrees\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\vcpkg\buildtrees\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
+/* buildtrees\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.
+```no-highlight
+PS buildtrees\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
+...
+vcpkg_extract_source_archive(${ARCHIVE})
+
+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(
+...
+```
+
+### Verification
+
+To be completely sure this works from scratch, we need to remove the package and rebuild it:
+
+```no-highlight
+PS D:\src\vcpkg> vcpkg remove libpng:x86-uwp
+Package libpng:x86-uwp was successfully removed
+```
+and complete delete the building directory: D:\src\vcpkg\buildtrees\libpng
+
+Now we try a fresh, from scratch install.
+```no-highlight
+PS D:\src\vcpkg> vcpkg install libpng:x86-uwp
+-- CURRENT_INSTALLED_DIR=D:/src/vcpkg/installed/x86-uwp
+-- DOWNLOADS=D:/src/vcpkg/downloads
+-- CURRENT_PACKAGES_DIR=D:/src/vcpkg/packages/libpng_x86-uwp
+-- CURRENT_BUILDTREES_DIR=D:/src/vcpkg/buildtrees/libpng
+-- CURRENT_PORT_DIR=D:/src/vcpkg/ports/libpng/.
+-- Using cached D:/src/vcpkg/downloads/libpng-1.6.24.tar.xz
+-- Extracting source D:/src/vcpkg/downloads/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, then make a Pull Request!
+
+```no-highlight
+# ports\libpng\CONTROL
+Source: libpng
+Version: 1.6.24-1
+Build-Depends: zlib
+```
diff --git a/docs/examples/using-sqlite.md b/docs/examples/using-sqlite.md
new file mode 100644
index 000000000..d12695bfb
--- /dev/null
+++ b/docs/examples/using-sqlite.md
@@ -0,0 +1,177 @@
+# Example: Using Sqlite
+
+  - [Step 1: Install](#install)
+  - [Step 2: Use](#use)
+    - [VS/MSBuild Project (User-wide integration)](#msbuild)
+    - [CMake (Toolchain file)](#cmake)
+    - [Other integration options](../users/integration.md)
+
+---
+<a name="install"></a>
+## Step 1: Install
+
+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:
+```no-highlight
+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 "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.
+```no-highlight
+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/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
+-- 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
+-- Performing post-build validation
+-- Performing post-build validation done
+Package sqlite3:x86-windows is installed
+```
+
+We can check that sqlite3 was successfully installed for x86 windows desktop by running the `list` command.
+```no-highlight
+PS D:\src\vcpkg> .\vcpkg list
+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>`.
+```no-highlight
+PS D:\src\vcpkg> .\vcpkg install sqlite3:x86-uwp zlib:x64-windows
+```
+
+See `.\vcpkg help triplet` for all supported targets.
+
+---
+<a name="use"></a>
+## Step 2: Use
+<a name="msbuild"></a>
+#### VS/MSBuild 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 prompt for administrator access the first time it is used on a given machine, but afterwords is no longer required and the integration is configured on a per-user basis.
+```no-highlight
+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.* 
+
+You can now simply use File -> New Project in Visual Studio 2015 or Visual Studio 2017 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="cmake"></a>
+#### 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`.
+
+If you are using CMake through Open Folder with Visual Studio 2017 you can define `CMAKE_TOOLCHAIN_FILE` by adding a "variables" section to each of your `CMakeSettings.json` configurations:
+
+```json
+{
+  "configurations": [{
+    "name": "x86-Debug",
+    "generator": "Visual Studio 15 2017",
+    "configurationType" : "Debug",
+    "buildRoot":  "${env.LOCALAPPDATA}\\CMakeBuild\\${workspaceHash}\\build\\${name}",
+    "cmakeCommandArgs": "",
+    "buildCommandArgs": "-m -v:minimal",
+    "variables": [{
+      "name": "CMAKE_TOOLCHAIN_FILE",
+      "value": "D:\\src\\vcpkg\\scripts\\buildsystems\\vcpkg.cmake"
+    }]
+  }]
+}
+```
+
+Now let's make a simple CMake project with a main file.
+```cmake
+# CMakeLists.txt
+cmake_minimum_required(VERSION 3.0)
+project(test)
+
+find_package(Sqlite3 REQUIRED)
+
+add_executable(main main.cpp)
+target_link_libraries(main sqlite3)
+```
+```cpp
+// main.cpp
+#include <sqlite3.h>
+#include <stdio.h>
+
+int main()
+{
+    printf("%s\n", sqlite3_libversion());
+    return 0;
+}
+```
+
+Then, we build our project in the normal CMake way:
+```no-highlight
+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
+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.*
+
+##### Handling libraries without native cmake support
+
+Unlike other platforms, we do not automatically add the `include\` directory to your compilation line by default. If you're using a library that does not provide CMake integration, you will need to explicitly search for the files and add them yourself using [`find_path()`][1] and [`find_library()`][2].
+
+```cmake
+# To find and use catch
+find_path(CATCH_INCLUDE_DIR catch.hpp)
+include_directories(${CATCH_INCLUDE_DIR})
+
+# To find and use azure-storage-cpp
+find_path(WASTORAGE_INCLUDE_DIR was/blob.h)
+find_library(WASTORAGE_LIBRARY wastorage)
+include_directories(${WASTORAGE_INCLUDE_DIR})
+link_libraries(${WASTORAGE_LIBRARY})
+
+# Note that we recommend using the target-specific directives for a cleaner cmake:
+#     target_include_directories(main ${LIBRARY})
+#     target_link_libraries(main PRIVATE ${LIBRARY})
+```
+
+[1]: https://cmake.org/cmake/help/latest/command/find_path.html
+[2]: https://cmake.org/cmake/help/latest/command/find_library.html