Added documentation about building, improved README.

README.md

@@ -1,30 +1,78 @@
-Magnum is currently an simple OpenGL 3 graphics engine, not using any deprecated
+Magnum is 3D graphics engine written in C++11 and OpenGL 3 Core Profile.
-functionality. It's currently used in Kompas 3D map view plugin.
+Features:
+
+ * Easy-to-use templated mathematical library for matrix/vector calculations.
+ * Comprehensive use of C++11 features for safety, performance and ease of
+   development.
+ * Hierarchical scene graph which supports transformation caching for better
+   performance, classes for convenient usage of shaders, buffers and textures.
+ * Mesh tools for cleaning, optimizing and generating meshes. Collection of
+   pre-made graphic primitives and shaders for testing purposes.
 
 INSTALLATION
 ============
 
-Dependencies
+You can either use packaging scripts, which are stored in package/
-------------
+subdirectory, or compile and install everything manually. Note that Doxygen
+documentation contains more comprehensive guide for building, packaging and
+crosscompiling.
+
+Minimal dependencies
+--------------------
 
- * CMake    - for building
+ * C++ compiler with good C++11 support. Currently the only compiler which
- * OpenGL headers (on Linux most probably shipped with Mesa)
+   supports everything needed is **GCC** >= 4.6. **Clang** >= 3.1 (from SVN)
- * GLEW     - OpenGL extension wrangler
+   will probably work too.
- * GLUT     - optionally, for examples
+ * **CMake** >= 2.6
- * Qt       - optionally, for unit tests
+ * **OpenGL headers**, on Linux most probably shipped with Mesa
+ * **GLEW** - OpenGL extension wrangler
+ * **Corrade** - Plugin management and utility library. You can get it at
+   http://mosra.cz/blog/corrade.php
 
 Compilation, installation
 -------------------------
 
+The library can be built and installed using these four commands:
+
     mkdir -p build
     cd build
     cmake -DCMAKE_INSTALL_PREFIX=/usr .. && make
     make install
 
-Some examples of engine usage are stored in examples/ directory, if you want to
+Building and running unit tests
-build them, pass -DBUILD_EXAMPLES=True to CMake. Examples use the GLUT library.
+-------------------------------
-If you want to build also unit tests (which are not built by default),
+
-pass -DBUILD_TESTS=True to CMake. Unit tests use QtTest framework.
+If you want to build also unit tests (which are not built by default), pass
+`-DBUILD_TESTS=True` to CMake. Unit tests use QtTest framework (you need at
+least **Qt 4.6**) and can be run using
+
+    ctest -V
+
+in build directory. Everything should pass ;-)
+
+Building documentation
+----------------------
+
+The documentation (which you are currently reading) is written in **Doxygen**
+(preferrably 1.8 with Markdown support, but older versions should do good job
+too) and additionally uses **Graphviz** for class diagrams. The documentation
+can be build by running
+
+    doxygen
+
+in root directory (i.e. where `Doxyfile` is). Resulting HTML documentation
+will be in `build/doc/` directory.
+
+PLUGINS AND EXAMPLES
+====================
+
+Various importer plugins for image and 3D model formats are maintained in
+separate repository, which can be found at
+http://github.com/mosra/magnum-plugins .
+
+There are also examples of engine usage, varying from simple *Hello
+World*-like example to more advanced applications, such as viewer for complex
+3D models. Example repository is at http://github.com/mosra/magnum-examples .
 
 CONTACT
 =======

doc/Building.dox

@@ -0,0 +1,87 @@
+/** @page Building Building %Magnum
+
+%Magnum can be built either @ref BuildingCompilation "manually" or using
+already prepared packaging files, currently only
+@ref BuildingArch "ArchLinux PKGBUILDs". Guide how to @ref BuildingWin
+"crosscompile for Windows" is also available.
+
+@tableofcontents
+
+Minimal set of tools and libraries required for building is:
+
+- C++ compiler with good C++11 support. Currently the only compiler which
+  supports everything needed is **GCC** >= 4.6. **Clang** >= 3.1 (from SVN)
+  will probably work too.
+- **CMake** >= 2.6
+- **OpenGL** headers, on Linux most probably shipped with Mesa
+- **GLEW** - OpenGL extension wrangler
+- **Corrade** - Plugin management and utility library. You can get it at
+  http://mosra.cz/blog/corrade.php
+
+@section BuildingCompilation Compilation, installation
+The library can be built and installed using these four commands:
+
+    mkdir -p build
+    cd build
+    cmake -DCMAKE_INSTALL_PREFIX=/usr .. && make
+    make install
+
+@subsection BuildingTests Building and running unit tests
+If you want to build also unit tests (which are not built by default), pass
+`-DBUILD_TESTS=True` to CMake. Unit tests use QtTest framework (you need at
+least **Qt 4.6**) and can be run using
+
+    ctest -V
+
+in build directory. Everything should pass ;-)
+
+@subsection BuildingDoc Building documentation
+The documentation (which you are currently reading) is written in **Doxygen**
+(preferrably 1.8 with Markdown support, but older versions should do good job
+too) and additionally uses **Graphviz** for class diagrams. The documentation
+can be build by running
+
+    doxygen
+
+in root directory (i.e. where `Doxyfile` is). Resulting HTML documentation
+will be in `build/doc/` directory.
+
+@section BuildingArch Building ArchLinux packages
+In `package/archlinux` directory is currently one PKGBUILD for Git development
+build. The package is also in AUR under the same name.
+
+There is also development PKGBUILD and MinGW development PKGBUILD in root,
+which allows you to build and install the package directly from source tree
+without downloading anything. The PKGBUILD also contains `check()` function
+which will run all unit tests before packaging. Note that the unit tests
+require Qt, as said above.
+
+@section BuildingWin Crosscompiling for Windows using MinGW
+@note This guide is tailored mainly for crosscompiling from ArchLinux. For
+this system there is also prepared `mingw32-magnum` development package in
+root, named `PKGBUILD-mingw32`.
+
+You will need MinGW32 versions of the compiler and all libraries (OpenGL
+headers, GLEW, Corrade), i.e. these ArchLinux packages:
+
+- `mingw32-gcc`, which depends on `mingw32-w32api` containing OpenGL headers
+- `mingw32-runtime`
+- `mingw32-glew`
+- `mingw32-corrade`
+
+Make sure you have `toolchains` Git submodule updated, or, if you build from
+source, download the files from https://github.com/mosra/toolchains and put
+them in toolchains/ subdirectory. Then create build directory and run cmake
+and make:
+
+    mkdir build-win
+    cd build-win
+    cmake .. \
+        -DCMAKE_TOOLCHAIN_FILE=../toolchains/archlinux/basic-mingw32.cmake \
+        -DCMAKE_INSTALL_PREFIX=/usr/i486-mingw32
+    make
+
+You may need to modify the `basic-mingw32.cmake` file and
+`CMAKE_INSTALL_PREFIX` to suit your distribution filesystem hierarchy. If
+everything goes well, in `build-win/` subdirectories will be the DLLs.
+*/

doc/MainPage.dox

@@ -1,12 +1,12 @@
 namespace Magnum {
 /** @mainpage
 
-%Magnum is simple graphical engine written in C++11 and OpenGL 3 Core Profile.
+%Magnum is 3D graphics engine written in C++11 and OpenGL 3 Core Profile.
 Features:
 
 - Easy-to-use templated @ref Math "mathematical library" for matrix/vector
   calculations.
-- Comprehensive use of C++11 features for security, performance and ease of
+- Comprehensive use of C++11 features for safety, performance and ease of
   development.
 - Hierarchical @ref Scene "scene graph" which supports transformation caching
   for better performance, classes for convenient usage of
@@ -16,6 +16,10 @@ Features:
   Collection of pre-made @ref Primitives "graphic primitives" and
   @ref Shaders "shaders" for testing purposes.
 
+@section BuildingLink Building Magnum
+
+Guide @ref Building "how to build Magnum" on different platforms.
+
 @section BasicUsage Basic usage
 
 %Scene in %Magnum is composed of hierarchically connected object instances.