From 441e6dd736be2ce67d87bb5773ea4466f2fd6a4d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Sat, 31 Mar 2012 21:39:05 +0200 Subject: [PATCH] Added documentation about building, improved README. --- README.md | 74 ++++++++++++++++++++++++++++++++-------- doc/Building.dox | 87 ++++++++++++++++++++++++++++++++++++++++++++++++ doc/MainPage.dox | 8 +++-- 3 files changed, 154 insertions(+), 15 deletions(-) create mode 100644 doc/Building.dox diff --git a/README.md b/README.md index 95b31e246..f40fbd133 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,78 @@ -Magnum is currently an simple OpenGL 3 graphics engine, not using any deprecated -functionality. It's currently used in Kompas 3D map view plugin. +Magnum is 3D graphics engine written in C++11 and OpenGL 3 Core Profile. +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 - * OpenGL headers (on Linux most probably shipped with Mesa) - * GLEW - OpenGL extension wrangler - * GLUT - optionally, for examples - * Qt - optionally, for unit tests + * 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 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 -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. +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 ;-) + +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 ======= diff --git a/doc/Building.dox b/doc/Building.dox new file mode 100644 index 000000000..0f5e70f03 --- /dev/null +++ b/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. +*/ diff --git a/doc/MainPage.dox b/doc/MainPage.dox index d40d41d3b..d4d77d924 100644 --- a/doc/MainPage.dox +++ b/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.