Merge 407c6f5e89 into bff7ae8d7e

doc/building.dox

@@ -3,6 +3,7 @@
 
     Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018
               Vladimír Vondruš <mosra@centrum.cz>
+    Copyright © 2018 Jonathan Hale <squareys@googlemail.com>
 
     Permission is hereby granted, free of charge, to any person obtaining a
     copy of this software and associated documentation files (the "Software"),
@@ -58,42 +59,45 @@ 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 latest
+After setting up Vcpkg as described in their README, it is recommended to set
-stable version of Magnum with all its dependencies like this:
+the "default triplet". You can do this by setting the `VCPKG_DEFAULT_TRIPLET`
+variable, e.g. to @code x64-windows @ce --- refer to the
+[documentation on triplets](https://vcpkg.readthedocs.io/en/latest/users/triplets/#additional-remarks)
+for other options.
+
+You can then install latest stable 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
+Often you may want to install the latest Git revision of all Magnum projects instead:
-projects instead:
 
 @code{.bat}
-vcpkg install corrade --head
+vcpkg install --head corrade magnum
-vcpkg install magnum --head
 @endcode
 
-This by default installs a 32-bit dynamic version of the package, you can use
+Not all features are installed by default; only those that are implicitly enabled
-@cb{.bat} vcpkg install magnum:x64-windows @ce or
+in @ref building-features together with @ref Platform::Sdl2Application "Sdl2Application".
-@cb{.bat} vcpkg install magnum:x64-windows-static @ce to install a 64-bit
-(static) version instead. You can also use the `VCPKG_DEFAULT_TRIPLET` variable
-to change the default --- see the
-<a href="https://github.com/Microsoft/vcpkg/blob/master/docs/users/triplets.md">Vcpkg triplet documentation</a>
-for more information.
-
-Not all features are installed by default, only those that are implicitly
-enabled in @ref building-features together with @ref Platform::Sdl2Application "Sdl2Application".
 To opt-in or opt-out of additional features, you can use the following syntax;
-feature names are simply names of CMake `WITH_*` options but lowercase. See the
+feature names are simply names of CMake `WITH_*` options but lowercase, e.g.:
-<a href="https://github.com/Microsoft/vcpkg/blob/master/docs/specifications/feature-packages.md">feature documentation</a>
-for more information.
 
 @code{.bat}
 vcpkg install magnum[glfwapplication,tgaimporter]
 @endcode
 
-Packages installed using Vcpkg can be used straight away in Visual Studio ---
+To install all features of a package, use `*`, e.g.:
-all you need to do is to @cpp #include @ce the headers you want, the
+
+@code{.bat}
+vcpkg install magnum[*]
+@endcode
+
+For more information, see the
+[documentation on feature packages](https://vcpkg.readthedocs.io/en/latest/specifications/feature-packages/).
+
+Packages installed using Vcpkg can be used in Visual Studio straight away ---
+all you need to do is to @cpp #include @ce the headers you want and the
 buildsystem will do all needed library linking and setup behind the scenes
 automatically. <em>(Cool, isn't it?)</em>
 
@@ -109,8 +113,9 @@ 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, run @cb{.bat} vcpkg edit magnum @ce
+If you want Vcpkg to pass additional flags to CMake during installation of a package,
-and edit `OPTIONS` in @cmake vcpkg_configure_cmake() @ce.
+use the `edit` command, e.g. @cb{.bat} vcpkg edit magnum @ce, and edit `OPTIONS`
+in @cmake vcpkg_configure_cmake() @ce.
 
 There is also a Vcpkg package for @ref building-plugins-packages-vcpkg "Magnum Plugins",
 @ref building-integration-packages-vcpkg "Magnum Integration" and
@@ -155,7 +160,8 @@ sudo pacman -U magnum-*.pkg.tar.xz
 Edit the PKGBUILDs if you want to pass additional flags to CMake or
 @ref building-features "enable / disable additional features".
 
-There are also ArchLinux packages for @ref building-plugins-packages-arch "Magnum Plugins", @ref building-integration-packages-arch "Magnum Integration",
+There are also ArchLinux packages for @ref building-plugins-packages-arch "Magnum Plugins",
+@ref building-integration-packages-arch "Magnum Integration",
 @ref building-extras-packages-arch "Magnum Extras" and
 @ref building-examples-packages-arch "Magnum Examples".
 
@@ -200,7 +206,8 @@ If you want to pass additional flags to CMake or
 `dh_auto_configure` at the bottom of `debian/rules`. Watch out, as
 indentation has to be done using tabs, not spaces.
 
-There are also Debian packages for @ref building-plugins-packages-deb "Magnum Plugins", @ref building-integration-packages-deb "Magnum Integration",
+There are also Debian packages for @ref building-plugins-packages-deb "Magnum Plugins",
+@ref building-integration-packages-deb "Magnum Integration",
 @ref building-extras-packages-deb "Magnum Extras" and
 @ref building-examples-packages-deb "Magnum Examples".
 
@@ -220,7 +227,8 @@ If you want to pass additional flags to CMake or
 @ref building-features "enable / disable additional features", add them to
 `mycmakeargs` in the `*.ebuild` file.
 
-There are also Gentoo packages for @ref building-plugins-packages-gentoo "Magnum Plugins", @ref building-integration-packages-gentoo "Magnum Integration",
+There are also Gentoo packages for @ref building-plugins-packages-gentoo "Magnum Plugins",
+@ref building-integration-packages-gentoo "Magnum Integration",
 @ref building-extras-packages-gentoo "Magnum Extras" and
 @ref building-examples-packages-gentoo "Magnum Examples".
 
@@ -249,7 +257,8 @@ want to pass additional flags to CMake or
 @ref building-features "enable / disable additional features", edit the `*.rb`
 file.
 
-There are also Homebrew packages for @ref building-plugins-packages-brew "Magnum Plugins", @ref building-integration-packages-brew "Magnum Integration",
+There are also Homebrew packages for @ref building-plugins-packages-brew "Magnum Plugins",
+@ref building-integration-packages-brew "Magnum Integration",
 @ref building-extras-packages-brew "Magnum Extras" and
 @ref building-examples-packages-brew "Magnum Examples".