magnum/doc/getting-started.dox

/*
    This file is part of Magnum.

    Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019
              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-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 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 3.1)
project(MyApplication)

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

# Add Corrade and Magnum as subprojects, enable Sdl2Application
set(WITH_SDL2APPLICATION ON CACHE BOOL "" FORCE)
add_subdirectory(corrade)
add_subdirectory(magnum)

add_subdirectory(src)
@endcode

@m_class{m-block m-warning}

@par What the heck is ON CACHE BOOL? FORCE?!
    CMake is a buildsystem with a long history and even though some design
    decisions were not good in retrospect, preserving the behavior is crucial
    for its reliability. The above is needed due to an unfortunate behavior of
    the @cmake option() @ce command that got
    [fixed in CMake 3.13](https://cmake.org/cmake/help/latest/policy/CMP0077.html).
    If you can afford requiring CMake 3.13 for your project, you can change the
    above to just the following:
@par
    @code{.cmake}
    cmake_minimum_required(VERSION 3.13) # important

    ...

    set(WITH_SDL2APPLICATION ON)
    add_subdirectory(corrade)
    add_subdirectory(magnum)
    @endcode

<b></b>

@m_class{m-block m-success}

@par Building Magnum separately
    Even though using Magnum as a CMake subproject is a fully supported use
    case, in the long run it might be better to build & 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 correctly find and use it. There are also
    ready-to-use packages for various OSes and distributions, as listed above.
@par
    If you have a separate installation (or a package), 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

Because the bootstrap project is based on SDL2, make sure you have SDL2
installed. It's usually in your system's package manager, on macOS you can get
it from Homebrew using @cb{.sh} brew install sdl2 @ce. 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 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 ..
cmake --build .
./src/MyApplication
@endcode

@m_class{m-note m-success}

@par Generating an Xcode project
    On macOS it's possible to generate an Xcode project by running CMake as
    `cmake -G Xcode ..`. After that's done, you can open the generated project
    from the `build` directory.

@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. Depending 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 Developer
Command Prompt, alternatively execute the correct `vcvarsall.bat` in order to
populate the necessary environment variables.

@code{.bat}
mkdir build && cd build
cmake .. ^
    -DCMAKE_PREFIX_PATH="C:/Users/you/where/you/extracted/SDL" ^
    -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
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 singles --- @copybrief singles
-   @subpage custom-buildsystems --- @copybrief custom-buildsystems

*/
}