building.docu 8.71 KB
Newer Older
1 2 3 4 5 6
/*! \page buildingOpenFlipper Building OpenFlipper

\section dependencies Dependencies

OpenFlipper is developed on top of the Qt framework. This framework provides
easy cross platform development. Therefore an installed version of QT with
7
at least version 4.8.6 is required. We use the cmake MakeFile generator to build 
8 9
OpenFlipper.

Jan Möbius's avatar
Jan Möbius committed
10
\section reqlibs Required libraries
11
<ul>
12
<li> 5.5 >= Qt >= 4.8.6  ( http://www.qt.io/download/ ) Use the OpenGL version for Qt >= 5.0</li>
13
<li> GLUT         ( http://www.opengl.org/resources/libraries/glut/ )</li>
Jan's avatar
Jan committed
14
<li> GLEW (>=1.6) ( http://glew.sourceforge.net )</li>
Jan Möbius's avatar
Jan Möbius committed
15 16
</ul>

Jan Möbius's avatar
Jan Möbius committed
17
\section optlibs Optional libraries ( Without these libraries some functionality might not be available) 
Jan Möbius's avatar
Jan Möbius committed
18 19
<ul>
<li> QWT (>=6.0)  ( optional, used for histogram plottings, http://qwt.sourceforge.net/)</li>
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
</ul> 

\section bs Build System
The build system uses cmake to generate all makefiles.

\section build_cmake Building OpenFlipper using Cmake

For the following section CMake >= 2.8.4 has to be installed.
In the toplevel directory of OpenFlipper is a CMakeLists.txt
file that specifies the build configuration and targets. In most cases
this file should be left untouched. Additional functions and environment
settings are to be found in the cmake directory in the toplevel folder.
See following subsections for information on how to build OpenFlipper
for your specific operating system.

\subsection cmake_blinux Building OpenFlipper under Linux

<ul>
Jan Möbius's avatar
Jan Möbius committed
38
<li> First install the required libraries via your linux distributions package management e.g. apt or rpm (for the list of packages see above)<br />
39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57
<li> Extract the source code or get it via svn:<br />
<code><b> svn co http://www.openflipper.org/svnrepo/OpenFlipper/branches/Free OpenFlipper</b></code></li>
<li> Create a build directory (e.g. <b>build</b>) in the toplevel directory: <code><b>mkdir build</b></code></li>
<li> Change to the newly created directory <code><b>cd build</b></code> and type <code><b>cmake ..</b></code></li>
<li> Now call  <b>make</b> to build OpenFlipper </li>
</ul>

To switch between debug and release build, use <br />
<b>cmake -DCMAKE_BUILD_TYPE=Release ..</b><br />
<br />
To change the install path use<br />
<b>-DCMAKE_INSTALL_PREFIX=[path]</b><br />

The created application (binaries, libs and shared files) are located in the <b>Build</b>
directory.

\subsection cmake_bwin Building OpenFlipper under Windows

<ul>
58
<li> Get Visual Studio 2008/2010 </li>
59
<li> Get and Install Qt ( >= 4.8.6 , Visual Studio Version matching your installation ) </li>
60
<li> Set the QTDIR Variable to your Qt Installation directory:<br />
61 62
<li> For Qt5, you need to add the value "%QTDIR%/bin" to the "Path" variable. Keep in mind: The "QTDIR" variable is the path which includes the "bin", "include", "lib", ... directories.

63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87
<br />
     <b>Windows Vista/7:</b> <br />
     Open the Control Panel<br />
     Select System and Security -> System -> Advanced System settings<br />
     Click on "Advanced" tab<br />
     At the bottom click on "Environment Variables"<br />
     In the bottom window,check if there is already a QTDIR entry and modify it or use "Add" to create it<br />
     Set the path to your QT installation directory<br />
<br />
     <b>Windows XP:</b> <br />
     Open the Control Panel<br />
     Select System<br />
     Click on "Advanced" tab<br />
     At the bottom click on "Environment Variables"<br />
     In the bottom window,check if there is already a QTDIR entry and modify it or use "Add" to create it<br />
     Set the path to your QT installation directory<br />
<br />
</li>
<li> Extract OpenFlipper source code. ( If you want to use svn  you can get a free svn client from http://tortoisesvn.net/downloads ) </li>
<li> Download the glew library and install it (The best way is to install it to c:\\libs\\glew directory ).)<br />
     The c:\\libs\\glew\\lib subdirectory should contain the dll and the *.lib files)<br />
     The headers should be located in the c:\\libs\\glew\\include\\gl subdirectory</li>
<li> Rearrange the files in the glut-3.7 directory such that)<br />
     all *.lib and *.dll files are in a c:\\libs\\glut-3.7\\lib subdirectory)<br />
     and the glut.h file is moved to the subdirectory c:\\libs\\glut-3.7\\include\\gl\\glut.h</li>
88
<li> Get cmake for windows from http://www.cmake.org/cmake/resources/software.html </li>
89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106
<li> Start the cmake gui and select the OpenFlipper toplevel directory as source directory </li>
\image html cmake-source.png
<li> Choose a build directory (e.g. a subdirectory called \c build-release in OpenFlipper's root dir)</li>
\image html cmake-builddir.png
<li> Click on configure </li>
\image html cmake-configuregenerate.png
<li>Choose a generator for Visual Studio (according to your Visual Studio version)....</li>
\image html cmake-generator.png
<li>
If the configuration fails because of libraries and/or headers which have not been found, an error message will be printed in the bottom window.
You can adjust the paths in cmake-gui manually in the large window. Note that some build variables are only visible in Advanced Mode.
You can change view modes of cmake-gui via the select box on the top. </li>
<li>Rerun configure until everything is configured correctly and no more red rows or errors are shown.</li>
<li> Click generate to create the visual studio project files </li>
<li> You can now find a Visual Studio solution file (OpenFlipper.sln) in the <b>build directory</b> directory you chose in cmake.</li>
<li> Now you can build OpenFlipper from within Visual Studio using the newly created project file by starting Build Solution. </li>
</ul> 

107 108 109 110 111
\note If you want to build OpenFlipper as release on windows, you don't have to set the CMAKE_BUILD_TYPE variable to "Release" before configuring
 generating the Visual Studio solution file. Instead, choose the build type "Release" in Visual Studio and build the solution.

Don't forget setting up the "OpenFlipper" target as startup project as shown in the image below to run the debugger with OpenFlipper right out of Visual Studio.
\image html windows_build_set_as_startup.png
112 113 114 115 116 117 118 119

\subsection cmake_bmacos Building OpenFlipper under MacOS X

<ul>
<li> First install the required libraries<br />
     To get all required libraries you should use the macports project: http://www.macports.org/ <br />
     <br />
     Install at least the following ports: <br />
Jan Möbius's avatar
Jan Möbius committed
120
     qt4-mac +debug<br />
121 122 123 124 125 126
     glew<br />
     glut<br />
     cmake<br />
br />
     As additional ports we recommend the following<br />
     fftw-3<br />
Jan Möbius's avatar
Jan Möbius committed
127
     qwt-60 +debug +qt4<br />
128 129 130 131 132
     subversion<br />
     doxygen<br />
<li> Extract the source code or get it via svn:<br />
<code><b> svn co http://www-i8.informatik.rwth-aachen.de/svnrepo/OpenFlipper/branches/Free OpenFlipper</b></code></li>
<li> Create a build directory (e.g. <b>build</b>) in the toplevel directory: <code><b>mkdir build</b></code></li>
133 134
<li> Change to the newly created directory ( <code><b>cd build</b></code> ) and type <code><b>cmake ..</b></code> or if you want to build in release mode type <code><b> cmake -DCMAKE_BUILD_TYPE=Release ..</b></code>
<br />
Jan Möbius's avatar
Jan Möbius committed
135
 You can also enable bundle creation by adding <code><b>-DOPENFLIPPER_CALL_FIX_BUNDLE=true</b></code> to the cmake command line (If you want a bundle containing all required libraries. Otherwise, the libraries will be used at their original locations.) </li>
136 137 138
<li> Now call <b>make</b> to build OpenFlipper </li>
</ul>

Jan Möbius's avatar
Jan Möbius committed
139 140 141
The created application bundle can be found in the <b>Build</b> directory. If you build with <code><b>-DOPENFLIPPER_CALL_FIX_BUNDLE=true</b></code>, the bundle will contain all required libraries. 

You can also create a drag and drop installer for mac by calling <code><b>make OpenFlipper_package</b></code>. This will also call fixbundle on your Bundle. <b>Note: When fixbundle has been called, the rpaths will be switched to local libraries. Concurrent builds, will still reference the global ones, which will cause inconsistencies and crashes! You have to call fixbundle after each build if it has been called once.</b>
142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166

\section cmake_plugin Building OpenFlipper Plugins with CMake

Building plugins with CMake is very simple. The OpenFlipper CMake build system
expects a CMakeLists.txt file in each of the plugin's directories.
So when developing a plugin, just make sure there is a CMakeLists.txt in
your plugin's directory. In this file include the global file plugin.cmake
which specifies the openflipper_plugin() function:

<code>include(plugin)</code>

You then have to add the following line which configures the build parameters
of your plugin:

<code>openflipper_plugin()</code>

Note: There are several parameters that one can pass to this function.
Usage:

\include example/cmake_plugin_usage.txt

For a detailed description of the parameters see the CMake documentation.
For an example of how to build a simple plugin see \ref ex1.

 */