diff --git a/doc/building.dox b/doc/building.dox index bfc3431e0..6227c37b0 100644 --- a/doc/building.dox +++ b/doc/building.dox @@ -67,14 +67,14 @@ 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-hunter -- @ref building-packages-vcpkg - @ref building-packages-arch - @ref building-packages-msys - @ref building-packages-deb - @ref building-packages-gentoo - @ref building-packages-rpm - @ref building-packages-brew +- @ref building-packages-vcpkg +- @ref building-packages-hunter The engine itself is kept as small as possible with only minimal dependencies. In order to use extra functionality, often depending on external libraries, you @@ -85,93 +85,6 @@ 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-hunter Hunter package - -Starting from version 2019.01, stable releases of Magnum are available in the -[Hunter](https://hunter.readthedocs.io) CMake-driven package manager. See the -[magnum package documentation](https://hunter.readthedocs.io/en/latest/packages/pkg/magnum.html) -for details. - -@subsection building-packages-vcpkg Vcpkg package - -Magnum is available as a [Vcpkg](https://github.com/Microsoft/vcpkg) package. -After setting up Vcpkg as described in their README, it is recommended to set -the "default triplet". You can do this by setting the `VCPKG_DEFAULT_TRIPLET` -variable, e.g. to `x64-windows` --- 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 - -@m_class{m-block m-success} - -@par Installing latest master - The `master` is considered stable for production use and often you may want - to prefer it over a potentially outdated tagged release. To do so, use - the `--head` option, on *both* `corrade` and `magnum`: -@par - @code{.bat} - vcpkg install --head corrade magnum - @endcode -@par - Note that `vcpkg upgrade` doesn't work well with `--head` packages (it will - go back to latest tagged version instead of updated master), you have to - remove both `corrade` and `magnum` and install `--head` again: -@par - @code{.bat} - vcpkg remove magnum --recurse - vcpkg install --head corrade magnum - @endcode - -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 `MAGNUM_WITH_*` options but lowercase, -e.g.: - -@code{.bat} -vcpkg install magnum[glfwapplication,tgaimporter] -@endcode - -To install all features of a package, use `*`, e.g.: - -@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. (Cool, isn't it?) - -@note If Visual Studio doesn't find the packages, check its verbose output, it - might point to a mismatch of the triplet above or broken Vcpkg integration. - -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 Vcpkg to pass additional flags to CMake during installation of a -package, 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 -@ref building-extras-packages-vcpkg "Magnum Extras". - @subsection building-packages-arch ArchLinux packages Package for the latest stable release is maintained in the `community` repo. @@ -371,6 +284,93 @@ There are also Homebrew packages for @ref building-plugins-packages-brew "Magnum @ref building-integration-packages-brew "Magnum Integration" and @ref building-examples-packages-brew "Magnum Examples". +@subsection building-packages-vcpkg Vcpkg package + +Magnum is available as a [Vcpkg](https://github.com/Microsoft/vcpkg) package. +After setting up Vcpkg as described in their README, it is recommended to set +the "default triplet". You can do this by setting the `VCPKG_DEFAULT_TRIPLET` +variable, e.g. to `x64-windows` --- 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 + +@m_class{m-block m-success} + +@par Installing latest master + The `master` is considered stable for production use and often you may want + to prefer it over a potentially outdated tagged release. To do so, use + the `--head` option, on *both* `corrade` and `magnum`: +@par + @code{.bat} + vcpkg install --head corrade magnum + @endcode +@par + Note that `vcpkg upgrade` doesn't work well with `--head` packages (it will + go back to latest tagged version instead of updated master), you have to + remove both `corrade` and `magnum` and install `--head` again: +@par + @code{.bat} + vcpkg remove magnum --recurse + vcpkg install --head corrade magnum + @endcode + +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 `MAGNUM_WITH_*` options but lowercase, +e.g.: + +@code{.bat} +vcpkg install magnum[glfwapplication,tgaimporter] +@endcode + +To install all features of a package, use `*`, e.g.: + +@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. (Cool, isn't it?) + +@note If Visual Studio doesn't find the packages, check its verbose output, it + might point to a mismatch of the triplet above or broken Vcpkg integration. + +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 Vcpkg to pass additional flags to CMake during installation of a +package, 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 +@ref building-extras-packages-vcpkg "Magnum Extras". + +@subsection building-packages-hunter Hunter package + +Starting from version 2019.01, stable releases of Magnum are available in the +[Hunter](https://hunter.readthedocs.io) CMake-driven package manager. See the +[magnum package documentation](https://hunter.readthedocs.io/en/latest/packages/pkg/magnum.html) +for details. + @section building-manual Manual build @subsection building-download Downloading the sources