From 99ffc440b2f26fdbf4b7bbfd3ba8ff250f91744f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Mon, 19 Aug 2013 18:57:34 +0200 Subject: [PATCH] Properly document building on Windows. --- README.md | 15 ++++++------ doc/building.dox | 64 +++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 66 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 54dd68635..221f96fcd 100644 --- a/README.md +++ b/README.md @@ -72,13 +72,14 @@ more comprehensive guide for building, packaging and crosscompiling. Minimal dependencies -------------------- - * C++ compiler with good C++11 support. Currently there are two compilers - which are tested to support everything needed: **GCC** >= 4.6 and **Clang** - >= 3.1. - * **CMake** >= 2.8.8 (needed for `OBJECT` library target) - * **GLEW** - OpenGL extension wrangler (only if targeting desktop OpenGL) - * **Corrade** - Plugin management and utility library. You can get it at - https://github.com/mosra/corrade. +* C++ compiler with good C++11 support. Currently there are two compilers + which are tested to support everything needed: **GCC** >= 4.6 and **Clang** + >= 3.1. On Windows you can use **MinGW**, Visual Studio compiler still + lacks some needed features. +* **CMake** >= 2.8.8 +* **GLEW** - OpenGL extension wrangler (only if targeting desktop OpenGL) +* **Corrade** - Plugin management and utility library. You can get it at + https://github.com/mosra/corrade. Compilation, installation ------------------------- diff --git a/doc/building.dox b/doc/building.dox index 47f17b054..1e6b77cea 100644 --- a/doc/building.dox +++ b/doc/building.dox @@ -38,8 +38,9 @@ Minimal set of tools and libraries required for building is: - C++ compiler with good C++11 support. Currently there are two compilers which are tested to support everything needed: **GCC** >= 4.6 and **Clang** - >= 3.1. -- **CMake** >= 2.8.8 (needed for `OBJECT` library target) + >= 3.1. On Windows you can use **MinGW**, Visual Studio compiler still lacks + some needed features. +- **CMake** >= 2.8.8 - **GLEW** - OpenGL extension wrangler (only if targeting desktop OpenGL) - **Corrade** - Plugin management and utility library. See @ref building-corrade "Corrade download and installation guide" for more @@ -63,9 +64,10 @@ subdirectory. @section building-compilation Compilation, installation -The library (for example with support for GLUT applications) can be built and -installed using these four commands. See below for more information about -optional features. +@subsection building-linux Via command-line (on Linux/Unix) + +On Unix-based OSs, the library (for example with support for GLUT applications) +can be built and installed using these four commands: mkdir -p build && cd build cmake .. \ @@ -74,6 +76,55 @@ optional features. make make install +The library provides a lot of CMake options (described in sections later). They +can be passed to CMake either as `-Dname=value` parameters on command-line +(like above) or set conveniently using `cmake-gui`: + + cd build + cmake-gui . + +@subsection building-windows Using QtCreator and CMake GUI (on Windows) + +On Windows, if you don't want to touch the command-line, the easiest way is to +install QtCreator (just QtCreator, you don't need the full Qt SDK) and +configure it to use MinGW and CMake. + +For most convenient usage it's best to install (or copy/paste) all library +dependencies into directory where MinGW is installed (e.g. `C:/MinGW/`), +following proper filesystem hierarchy, i.e. headers into `include/` and +binaries into `bin/` or `lib/`. CMake will then have no problem finding them +and you won't need to explicitly specify path to each one. + +Then just open project's root `CMakeLists.txt` file within QtCreator. 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 should be ready +to be built. You might need to set some CMake parameters before configuring, +they can be set with `-Dname=value`. See below for more information. + +After the initial import you might want to reconfigure some CMake variables +(more information below). Start CMake GUI, point it to the recently created +build dir, modify the variables and press Generate. QtCreator will detect the +changes and reparse the project accordingly. + +For most convenient usage it's best to set `CMAKE_INSTALL_PREFIX` to directory +where MinGW is installed (e.g. `C:/MinGW/`) and add `C:/MinGW/bin` and +`C:/MinGW/lib` to `PATH`. Installation to given prefix can be then done from +within QtCreator by adding new `make install` build rule. + +@subsubsection building-windows-troubleshooting Windows troubleshooting + +If CMake isn't able to find dependencies (e.g. Corrade is not found) and you +have installed them to MinGW directory, point to `CMAKE_FIND_ROOT_PATH` to +MinGW installation prefix, e.g. specify `-DCMAKE_FIND_ROOT_PATH=C:/MinGW/` +CMake parameter. + +If building fails with GLEW linking errors (`undefined reference to glew...`), +you have to set `GLEW_LIBRARY_DLL` and `GLEW_LIBRARY_LIB` CMake variables +manually. One of them should point to `glew32.dll` and the other to +`glew32.lib`. CMake currently isn't able to distinguish between them and in +most cases points both to the same location. + +See also Corrade's @ref building-corrade-windows-troubleshooting "troubleshooting section". @subsection building-features Enabling or disabling features @@ -149,7 +200,8 @@ in `Test/` subdirectories of build directory) or using ctest --output-on-failure -in build directory. Everything should pass ;-) +in build directory. On Windows the tests require the library to be installed +with DLLs accessible through `PATH`. See above for more information. @subsection building-doc Building documentation