magnum/doc/getting-started.dox

/*
    This file is part of Magnum.

    Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018
              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 in matter of minutes.

@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 use cases, helping you get up and running in no time.

@section getting-started-bootstrap 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 need the `base` branch, which
contains only the essential files. Download the branch
[as an archive](https://github.com/mosra/magnum-bootstrap/archive/base.zip) and
extract it somewhere. Do it rather than cloning the full repository, as it's
better to init your new project from scratch with clean Git history.

@section getting-started-download Download, build and install Corrade and Magnum

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
-   @ref building-packages-brew

If you don't, don't worry, let's use the subproject approach instead. Adding
the dependencies means just cloning them into your project tree:

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

Then open the `CMakeLists.txt` file in the root of bootstrap project and add
these two new subdirectories using @cmake add_subdirectory() @ce so the file
looks like this:

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

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

add_subdirectory(corrade)
add_subdirectory(magnum)
add_subdirectory(src)
@endcode

@note
    In the long run it's better to install Corrade and Magnum separately
    instead of cloning them into your project tree, as that vastly improves
    your iteration times. Follow @ref building "the full installation guide" if
    you want to go that route; don't forget to enable `WITH_SDL2APPLICATION`
    when building Magnum so the bootstrap project can use it later. There are
    also ready-to-use packages for various OSes and distributions.
@note
    If you have that, you don't need to clone the subprojects and modify the
    `CMakeLists.txt` file like above, you might only need to set
    `CMAKE_PREFIX_PATH` if you installed Corrade and Magnum to a non-standard
    location.

@section getting-started-review Review project structure

The base project consists of just six files in two subfolders. Magnum uses the
CMake build system, you can read more about it in @ref cmake.

    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. Unlike modules for finding e.g. OpenGL, which are part of
standard CMake installation, these aren't part of it and thus must be
distributed with the project. These files are just verbatim copied from Magnum
repository.

@note These modules are just the bare minimum you need for starting. If you
    plan to use additional functionality that isn't part of the core library or
    you are targeting specific platforms, you may need to include additional
    modules. See @ref cmake, @ref cmake-plugins, @ref cmake-integration and
    @ref cmake-extras for more information.

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
default (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 it to all needed libraries:

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

set_directory_properties(PROPERTIES CORRADE_USE_PEDANTIC_FLAGS ON)

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

In the following tutorials the code will be explained more thoroughly.

@section getting-started-build Build it and run

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

In Linux (and other Unix-based OSs) you can build the application along with
the subprojects using the following three commands: create out-of-source build
directory, run `cmake`, enable SDL2 application in the Magnum subproject and
then build everything. The compiled application binary will then appear in
`src/` subdirectory of the build dir:

@code{.sh}
mkdir -p build && cd build
cmake .. -DWITH_SDL2APPLICATION=ON
cmake --build .
./src/MyApplication
@endcode

@note If you installed Corrade and Magnum separately (instead of putting them
    in the project as subprojects), the `-DWITH_SDL2APPLICATION=ON` is not
    needed as that was already done when compiling & installing Magnum before.

@subsection getting-started-windows Windows

On Windows you can use either MSVC 2015+ or MinGW-w64. Prebuilt SDL2 binaries
can be downloaded at https://libsdl.org/download-2.0.php, dependeding on where
you extract them you may need to specify `CMAKE_PREFIX_PATH` so CMake is able
to find them. For running the executable properly, Windows also need to have
all dependency DLLs copied along it. That can be done by setting
`CMAKE_RUNTIME_OUTPUT_DIRECTORY`. It's then up to you whether you will use a
command line, Visual Studio or for example QtCreator. With Visual Studio the
most straightforward way to generate the project file is via the command line:

@code{.bat}
mkdir build && cd build
cmake .. ^
    -DWITH_SDL2APPLICATION=ON ^
    -DCMAKE_PREFIX_PATH="C:/Users/you/where/you/extracted/SDL2-2.0.5" ^
    -DCMAKE_RUNTIME_OUTPUT_DIRECTORY="bin"
@endcode

You can also use CMake GUI. Then open the `MyApplication.sln` project file
generated by CMake in the `build/` directory.

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
(`-DWITH_SDL2APPLICATION=ON` and others) and then you can just press *Configure*
and everything is ready to be built.

@note If you installed Corrade and Magnum separately, the install directory
    containing the DLLs needs to be in @cb{.bat} %PATH% @ce in order to
    properly run the executable. You can also enable `BUILD_STATIC` to compile
    everything as static, see @ref building "the full installation guide" for
    details.

@section getting-started-running Running the application

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

@image html getting-started.png
@image latex getting-started.png

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
@image latex getting-started-blue.png

@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 render your first triangle in a @ref examples-triangle "step-by-step tutorial".
Then you can dig deeper and try other examples, read about
@ref features "fundamental principles" in the documentation and start
experimenting on your own!

@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 custom-buildsystems --- @copybrief custom-buildsystems

*/
}