From 4acb40f9bf905d3e88adff3079ca60330d8a7a36 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Sun, 14 Jan 2018 21:30:53 +0100
Subject: [PATCH] doc: document using Vcpkg packages.

---
 doc/building.dox        | 40 ++++++++++++++++++++++++++++++++++++++++
 doc/getting-started.dox |  1 +
 2 files changed, 41 insertions(+)

diff --git a/doc/building.dox b/doc/building.dox
index 0fc74bfa7..b8b2cd907 100644
--- a/doc/building.dox
+++ b/doc/building.dox
@@ -37,6 +37,7 @@ The easiest way to install Magnum is to use one of the ready-made packages for
 your platform of choice. See @ref building-manual if you want to have more
 control and @ref building-cross for cross-compiling to other platforms.
 
+-   @ref building-packages-vcpkg
 -   @ref building-packages-arch
 -   @ref building-packages-deb
 -   @ref building-packages-gentoo
@@ -51,6 +52,45 @@ physics libraries is provided by @ref building-integration "Integration librarie
 and other extra features are in the @ref building-extras "Extra libraries".
 Various examples are provided by the @ref building-examples "Example repository".
 
+@subsection building-packages-vcpkg Vcpkg packages on Windows
+
+Magnum is available as a [Vcpkg](https://github.com/Microsoft/vcpkg) package.
+After setting up Vcpkg like described in the README, you can install a stable
+pinned version of Magnum with all its dependencies like this:
+
+@code{.bat}
+vcpkg install magnum
+@endcode
+
+But often you may want to install the latest Git revision of all Magnum
+projects instead:
+
+@code{.bat}
+vcpkg install corrade --head
+vcpkg install magnum --head
+@endcode
+
+Packages installed using Vcpkg can be used straight away in Visual Studio ---
+all you need to do is to @cpp #include @ce the headers you want, the
+buildsystem will do all needed library linking and setup behind the scenes
+automatically. <em>(Cool, isn't it?)</em>
+
+In order to make Magnum projects installed using Vcpkg available to CMake-based
+projects, specify the Vcpkg toolchain file on the command line when invoking
+CMake in a fresh build directory, for example:
+
+@code{.bat}
+mkdir build && cd build
+cmake .. -DCMAKE_TOOLCHAIN_FILE=C:/src/vcpkg/scripts/buildsystems/vcpkg.cmake
+@endcode
+
+If you want to pass additional flags to CMake or
+@ref building-features "enable / disable additional features", add them to
+`OPTIONS` in @cmake vcpkg_configure_cmake() @ce inside the
+`ports/magnum/portfile.cmake` file in your local Vcpkg installation.
+
+There is also a Vcpkg package for @ref building-plugins-packages-vcpkg "Magnum Plugins".
+
 @subsection building-packages-arch ArchLinux packages
 
 In `package/archlinux/magnum-git` there is a package for Git development build.
diff --git a/doc/getting-started.dox b/doc/getting-started.dox
index 9de065846..0bb9d4560 100644
--- a/doc/getting-started.dox
+++ b/doc/getting-started.dox
@@ -50,6 +50,7 @@ Magnum libraries support both separate compilation/installation and CMake
 subprojects. If you are lucky, you may already have Magnum packages ready for
 your platform and you can skip the rest of this section:
 
+-   @ref building-packages-vcpkg
 -   @ref building-packages-arch
 -   @ref building-packages-deb
 -   @ref building-packages-gentoo