magnum/doc/getting-started.dox

/*
    This file is part of Magnum.

    Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019,
                2020, 2021 Vladimír Vondruš <mosra@centrum.cz>

    Permission is hereby granted, free of charge, to any person obtaining a
    copy of this software and associated documentation files (the "Software"),
    to deal in the Software without restriction, including without limitation
    the rights to use, copy, modify, merge, publish, distribute, sublicense,
    and/or sell copies of the Software, and to permit persons to whom the
    Software is furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included
    in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
    DEALINGS IN THE SOFTWARE.
*/

namespace Magnum {
/** @page getting-started Getting started
@brief Get started with Magnum using a bootstrap project

@tableofcontents

Setting up a new project can be pretty gruesome and nobody likes repeating the
same process every time. Magnum provides "bootstrap" project structures for
many target uses with the essentials and best practices laid out. This guide,
as well as Magnum itself, uses the CMake build system.

@section getting-started-bootstrap 1. Download the bootstrap project

The [bootstrap repository](https://github.com/mosra/magnum-bootstrap) is
located on GitHub. The `master` branch contains just a README file and the
actual bootstrap projects are in various other branches, each covering some
particular use case. For the first project you'll need the `base` branch, which
contains only the essential files. Download the branch as an archive and
extract it somewhere:

@m_div{m-button m-primary} <a href="https://github.com/mosra/magnum-bootstrap/archive/base.zip">@m_div{m-big}base.zip@m_enddiv @m_div{m-small} download the project @m_enddiv </a> @m_enddiv

@subsection getting-started-setup-subproject 1a. Option A: add Magnum as a CMake subproject

The easiest option to start without having to install anything is adding all
dependencies as CMake subprojects. While it has an advantage of making your
project nicely self-contained, it'll make your full rebuild times longer
compared to magnum installed separately. For an alternative, see
@ref getting-started-setup-install below. Clone the Corrade and Magnum sources
like this (or use `git submodule add`, if you already have a Git repository):

@code{.sh}
cd /path/to/the/extracted/bootstrap/project
git clone https://github.com/mosra/corrade.git
git clone https://github.com/mosra/magnum.git
@endcode

Then open the `CMakeLists.txt` file in the root of the bootstrap project and
add these two new subdirectories using @cmake add_subdirectory() @ce so the
file looks like below. The `EXCLUDE_FROM_ALL` argument ensures only the parts
you actually use are built (and excluding the subdirectory from the `install`
target as well).

@code{.cmake}
cmake_minimum_required(VERSION 3.4)
project(MyApplication)

set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/modules/" ${CMAKE_MODULE_PATH})

# Add Corrade as a subproject
add_subdirectory(corrade EXCLUDE_FROM_ALL)

# Add Magnum as a subproject, enable Sdl2Application
set(WITH_SDL2APPLICATION ON CACHE BOOL "" FORCE)
add_subdirectory(magnum EXCLUDE_FROM_ALL)

add_subdirectory(src)
@endcode

The last missing piece before you can continue is the [SDL](http://libsdl.org/)
library --- the bootstrap project (and most examples) use it to do window
management and event handling. If you are on Linux or macOS, you can get it
easily from your package manager:

@code{.sh}
sudo pacman -S sdl2             # on ArchLinux
sudo apt install libsdl2-dev    # on Ubuntu / Debian
brew install sdl2               # on macOS (via Homebrew)
@endcode

If you are on Windows, by far the easiest is to bundle the prebuilt binaries
into your project. Depending on whether you use Visual Studio or MinGW,
download either [SDL2-devel-2.0.10-VC.zip](https://www.libsdl.org/release/SDL2-devel-2.0.10-VC.zip)
or [SDL2-devel-2.0.10-mingw.tar.gz](https://www.libsdl.org/release/SDL2-devel-2.0.10-mingw.tar.gz),
extract the archive to root of the project and tell CMake where it is by adding
the `SDL2-2.0.10` directory to `CMAKE_PREFIX_PATH`:

@code{.cmake}
...

set(CMAKE_PREFIX_PATH ${PROJECT_SOURCE_DIR}/SDL2-2.0.10 ${CMAKE_PREFIX_PATH})
set(WITH_SDL2APPLICATION ON CACHE BOOL "" FORCE)
add_subdirectory(magnum EXCLUDE_FROM_ALL)
@endcode

This is of course not the only possibility --- if you don't feel like bundling
the binaries, you can put them outside of the project and then specify
`CMAKE_PREFIX_PATH` externally on the command line.

@subsection getting-started-setup-install 1b. Option B: install Magnum separately and let CMake find it

An alternative to the above is building & installing Magnum separately. Both
approaches are equally-well supported and each has its pros and cons --- the
subproject way shines when experimenting or when the project is developed on
multiple workstations by multiple developers and you need to ensure the
dependencies are the same version everywhere; while the separate installation
makes sense when you have multiple projects depending on Magnum and want to
integrate new upstream changes without having to update and compile it several
times.

If you are lucky, you may already have Magnum packages ready for your platform:

-   @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-brew

If not, follow the full installation guides for @ref building-corrade "Corrade"
and @ref building "Magnum" to build & install everything; don't forget to
enable `WITH_SDL2APPLICATION` when building Magnum so the bootstrap project can
correctly find and use it. This is "the hard way" and it's recommended only if
you have at least some prior experience with building projects from source
using CMake.

Compared to @ref getting-started-setup-subproject "Option A", you don't need to
clone the subprojects and modify the `CMakeLists.txt` file, however you'll need
to set `CMAKE_PREFIX_PATH` if you installed Corrade and Magnum to a
non-standard location (i.e., anything else than `/usr` or `/usr/local` on Unix
systems, and outside of the standard prefix if using MinGW on Windows).

@section getting-started-review 2. Review project structure

The base project consists of just six files in two subfolders (plus the three
extra directories with dependencies you might have added):

    modules/FindCorrade.cmake
    modules/FindMagnum.cmake
    modules/FindSDL2.cmake
    src/MyApplication.cpp
    src/CMakeLists.txt
    CMakeLists.txt

In root there is the project-wide `CMakeLists.txt`, which you have seen above.
It just sets up project name, specifies module directory and delegates
everything important to `CMakeLists.txt` in the `src/` subdirectory.

The `modules/` directory contains CMake modules for finding the needed
dependencies. These are needed mainly with externally installed dependencies
(@ref getting-started-setup-install "Option B" above), less so for the CMake
subproject setup. Unlike modules for finding e.g. OpenGL, which are a part of
the standard CMake installation, these aren't and thus have to be distributed
with the project. These files are verbatim copied from the
[modules/](https://github.com/mosra/magnum/tree/master/modules) directory in
the Magnum repository.

The `src/` directory contains the actual project. To keep things simple, the
project consists of just a single `MyApplication.cpp` file with the most
minimal code possible:

@snippet getting-started.cpp 0

The application essentially does nothing, just clears the screen framebuffer to
a dark gray color and then does buffer swap to actually display it on the
screen. The `src/CMakeLists.txt` file finds Magnum, creates the executable and
links all needed libraries to it:

@code{.cmake}
find_package(Magnum REQUIRED GL Sdl2Application)

set_directory_properties(PROPERTIES CORRADE_USE_PEDANTIC_FLAGS ON)

add_executable(MyApplication MyApplication.cpp)
target_link_libraries(MyApplication PRIVATE
    Magnum::Application
    Magnum::GL
    Magnum::Magnum)
@endcode

The `CORRADE_USE_PEDANTIC_FLAGS` property enables a set of useful compiler
warnings. It's not required, but recommended to enforce good C++ coding
practices.

@section getting-started-build 3. Build the project

@subsection getting-started-build-linux Linux, macOS and other Unix-based OSes

The application along with the subprojects is built using the following three
commands --- create an out-of-source build directory, run `cmake` to generate a
project with a debug build type and then build everything.

@code{.sh}
mkdir -p build && cd build
cmake -DCMAKE_BUILD_TYPE=Debug ..
cmake --build .
@endcode

By default, CMake generates Makefile projects on Unix platforms. You can change
that to for example [Ninja](https://ninja-build.org/) by running CMake with
`-G Ninja`; on macOS you can generate an Xcode project in the build directory
using `-G Xcode`. If you have CMake 3.15 or newer, the default generator can be
changed using the [CMAKE_GENERATOR](https://cmake.org/cmake/help/v3.15/envvar/CMAKE_GENERATOR.html)
environment variable.

@subsection getting-started-build-windows Windows

On Windows you can use either Visual Studio or MinGW-w64. With Visual Studio
the most straightforward way to generate the project file is by executing the
below two commands in the Developer Command Prompt, you can also use CMake GUI
--- navigate it to the source directory, create a fresh build directory, select
a generator and press @m_class{m-label m-default} **Configure** and
@m_class{m-label m-default} **Generate**.

@code{.bat}
mkdir build && cd build
cmake ..
@endcode

Once that's done, open the `MyApplication.sln` project file generated by CMake
in the `build/` directory (or in the CMake GUI, use the
@m_class{m-label m-default} **Open Project** button).

With QtCreator just open project's root `CMakeLists.txt` file. It then asks you
where to create build directory, allows you to specify initial CMake parameters
and then you can just press @m_class{m-label m-default} **Configure** and
everything is ready to be built.

@section getting-started-run 4. Run the application

If you went with the CMake subproject approach (@ref getting-started-setup-subproject "Option A"
above), the project is configured to place all binaries into a common location
--- the application will be placed in `Debug/bin/MyApplication` (on Windows
along with all DLLs it needs), and libraries into `Debug/lib`; if you switch to
a Release build, it'll be `Release/bin` instead. If you went with externally
installed Magnum, the executable gets placed into its default location in
`src/MyApplication` and dependency libraries stay where CMake found them --- on
Windows you might need to adjust @cb{.sh} %PATH% @ce to make the application
run.

Once built, if everything went well and the application starts, you will see a
blank window like this:

@image html getting-started.png width=410px

Now you can try to change something in the code. Without going too deep into
the concepts of graphics programming, we can change the clear color to
something else and also print basic information about the GPU the engine is
running on. First include the needed headers:

@snippet getting-started-blue.cpp 0

And in the constructor (which is currently empty) change the clear color and
print something to debug output:

@snippet getting-started-blue.cpp 1

After rebuilding and starting the application, the clear color changes to
blueish one and something like this would be printed to the console:

@code{.shell-session}
$ ./MyApplication
[...]
Hello! This application is running on OpenGL 4.5 using GeForce GT 740M
@endcode

@image html getting-started-blue.png width=410px

The barebones application accepts various @ref GL-Context-usage-command-line "command-line arguments",
pass `--magnum-help` to see them all. Depending on your platform, these can
adjust HiDPI scaling, enable GPU command validation or for example switch to a
different GPU device.

@m_class{m-block m-success}

@par Making the executable a Windows application
    If you're on Windows, you noticed that, unlike common graphical apps, the
    application has a terminal window lurking in the background. That's because
    the default executable type in CMake is a console application. The terminal
    is useful for printing logs (as we just did), but if you don't want it, it
    can be hidden by specifying @cb{.cmake} add_executable(... WIN32 ...) @ce
    and linking to the @ref main "Corrade::Main" library. Apart from this, the
    library does other useful things such as enabling Unicode-aware environment
    interaction on Windows.
@par
    @code{.cmake}
    find_package(Corrade REQUIRED Main)
    ...

    add_executable(MyApplication WIN32 MyApplication.cpp)
    target_link_libraries(MyApplication PRIVATE
        Corrade::Main
        ...)
    @endcode

@section getting-started-glfw Using GLFW and other toolkits instead of SDL2

By no means Magnum forces you to use SDL2 --- it's only the default. If you
want to try it with other toolkits such as [GLFW](https://www.glfw.org/) or
[Qt](https://www.qt.io/) there are similar projects in other branches of the
[bootstrap repository](https://github.com/mosra/magnum-bootstrap). If you
download [base-glfw.zip](https://github.com/mosra/magnum-bootstrap/archive/base-glfw.zip), you get a GLFW-based project. It's mostly the same, with only minor
differences. Enable `WITH_GLFWAPPLICATION` instead of `WITH_SDL2APPLICATION`,
on Linux or Mac install one of the following packages:

@code{.sh}
sudo pacman -S glfw-x11         # on ArchLinux
sudo apt install libglfw3-dev   # on Ubuntu / Debian
brew install glfw               # on macOS (via Homebrew)
@endcode

On Windows download either [glfw-3.3.bin.WIN32.zip](https://github.com/glfw/glfw/releases/download/3.3/glfw-3.3.bin.WIN32.zip)
or [glfw-3.3.bin.WIN64.zip](https://github.com/glfw/glfw/releases/download/3.3/glfw-3.3.bin.WIN64.zip), extract it to root of the bootstrap project and point
`CMAKE_PREFIX_PATH` to it:

@code{.cmake}
...
                                       # or glfw-3.3.bin.WIN32 here
set(CMAKE_PREFIX_PATH ${PROJECT_SOURCE_DIR}/glfw-3.3.bin.WIN64 ${CMAKE_PREFIX_PATH})
set(WITH_GLFWAPPLICATION ON)
add_subdirectory(magnum EXCLUDE_FROM_ALL)
@endcode

The rest is very similar to above. With the `Platform::*Application` classes,
Magnum tries to have a common API for all toolkits to make switching from one
to another easy, allowing you to choose the best fit for a particular platform.
See @ref platform for more information.

@section getting-started-tutorials Follow tutorials and learn the principles

Now that you have your first application up and running, the best way to
continue is to get familiar with the basic workflows and render your first
triangle. Then you can dig deeper and try other examples, read about basic
building blocks in the documentation and start experimenting on your own!

@m_class{m-row}

@parblock

@m_div{m-col-m-6} @m_div{m-button m-info} <a href="features.html">@m_div{m-big}The Fundamentals@m_enddiv @m_div{m-small} make yourself comfortable first @m_enddiv </a> @m_enddiv @m_enddiv

@m_div{m-col-m-6} @m_div{m-button m-success} <a href="examples-triangle.html">@m_div{m-big}Your First Triangle@m_enddiv @m_div{m-small} a step-by-step tutorial @m_enddiv </a> @m_enddiv @m_enddiv

@endparblock

@section getting-started-more Additional information

-   @subpage building --- @copybrief building
-   @subpage building-plugins --- @copybrief building-plugins
-   @subpage building-integration --- @copybrief building-integration
-   @subpage building-extras --- @copybrief building-extras
-   @subpage building-examples --- @copybrief building-examples
-   @subpage cmake --- @copybrief cmake
-   @subpage cmake-plugins --- @copybrief cmake-plugins
-   @subpage cmake-integration --- @copybrief cmake-integration
-   @subpage cmake-extras --- @copybrief cmake-extras
-   @subpage singles --- @copybrief singles
-   @subpage custom-buildsystems --- @copybrief custom-buildsystems

*/
}