building.docu 9.18 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
Jan Möbius's avatar
Jan Möbius committed
7
at least version 5.9 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.11 <= Qt <= 5.13  ( http://www.qt.io/download/ ) Use the OpenGL version. If you install Qt, please make sure that QtScript is also installed.</li>
Jan Möbius's avatar
Jan Möbius committed
13
14
</ul>

Jan Möbius's avatar
Jan Möbius committed
15
\section optlibs Optional libraries ( Without these libraries some functionality might not be available) 
Jan Möbius's avatar
Jan Möbius committed
16
17
<ul>
<li> QWT (>=6.0)  ( optional, used for histogram plottings, http://qwt.sourceforge.net/)</li>
18
19
</ul> 

20
21
22
On Debian, you can install the prerequisites this way (tested on Debian buster):

<code>
23
apt install cmake make g++ libeigen3-dev python3-dev qt5-default libqt5script5 libqt5scripttools5 libqt5svg5-dev libqt5quick5 libqt5x11extras5-dev libqt5help5 qtscript5-dev libqt5xmlpatterns5-dev libqwt-qt5-dev qttools5-dev qtdeclarative5-dev libqt5opengl5-dev libglew-dev
24
25
26
</code>


27
28
29
30
31
\section bs Build System
The build system uses cmake to generate all makefiles.

\section build_cmake Building OpenFlipper using Cmake

Jan Möbius's avatar
Jan Möbius committed
32
For the following section CMake >= 3.12 has to be installed.
33
In the toplevel directory of OpenFlipper is a CMakeLists.txt
Jan Möbius's avatar
Jan Möbius committed
34
35
file that specifies the build configuration and targets. 
See the following subsections for information on how to build OpenFlipper
36
37
38
39
40
for your specific operating system.

\subsection cmake_blinux Building OpenFlipper under Linux

<ul>
Jan Möbius's avatar
Jan Möbius committed
41
<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 />
42
<li> Extract the source code or get it via git:<br />
Jan Möbius's avatar
Jan Möbius committed
43
44
45
<code><b> git clone --recursive https://graphics.rwth-aachen.de:9000/OpenFlipper-Free/OpenFlipper-Free.git OpenFlipper-Free</b></code></li>
<li> Create a build directory (e.g. <b>build</b>) next to the OpenFlipper source 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 ../OpenFlipper-Free</b></code></li>
46
47
48
49
<li> Now call  <b>make</b> to build OpenFlipper </li>
</ul>

To switch between debug and release build, use <br />
Jan Möbius's avatar
Jan Möbius committed
50
<b>cmake -DCMAKE_BUILD_TYPE=Release ../OpenFlipper-Free</b><br />
51
52
53
54
55
56
57
58
59
60
<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>
61
<li>Get Visual Studio 2015 or higher (We recommend 2017) </li>
62
<li> Get cmake for windows from http://www.cmake.org/cmake/resources/software.html </li>
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
<li>Get and Install Qt ( >= 5.9) , Visual Studio Version matching your installation ) </li>
<li>Download and install git (https://git-scm.com/downloads)</li>
<li>Start git gui</li>
<li>Choose "Clone Existing Repository"</li> 
\image html 01_clone_1.png
<li>Enter the source location: "https://www.graphics.rwth-aachen.de:9000/OpenFlipper-Free/OpenFlipper-Free" and a target directory (We assume "C:\Development\OpenFlipper" as the target directory).</li> 
\image html 02_clone_2.png
<li>Git Gui will now download the source code</li> 
\image html 03_clone_3.png
<li>After download you can close the following window</li> 
\image html 04_clone_finished.png
<li>Now start cmake-gui and enter the location of the source code ("C:\Development\OpenFlipper" in our case).</li> 
\image html 05_cmake_gui_1.png
<li>Enter the target build directory ("C:\Development\Build" in our case).</li> 
\image html 05_cmake_gui_2.png
<li>Click configure.</li> \image html 05_cmake_gui_3.png
<li>CMake now asks what generator we want to use.</li> 
\image html 06_choose_generator_a.png
<li>We will use Visual Studio 2017 64-bit mode.</li> 
\image html 06_choose_generator_b.png
Jan Möbius's avatar
Jan Möbius committed
83
<li>After selection, the window should look like this.</li> 
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
\image html 06_choose_generator_c.png
<li>Afterwards, cmake will ask if we want to create the build directory, if it did not exist before. Choose yes here.</li> 
\image html 06_create_folder.png
<li>Now cmake will configure the project. Depending on install locations, it might not find your Qt installation automatically. Then you will get the error shown in the image.</li> 
\image html 07_cmake_error_b.png 
<li>To fix this, search for QT5 in the search box. If nothing shows up, you have to enable the checkbox called "Advanced". You should find a variable called QT5_INSTALL_PATH. Click on the three dots on the right of the input box.</li> 
\image html 08_set_qt5_install_path.png
<li>Navigate to your Qt installation directory. Choose the qt version folder matching your generator (In our case, Visual Studio 2017 64-bit and therefore msvc2017_64) and click "Select folder".</li> 
\image html 09_set_qt5_install_path_2.png
<li>The path should now be set correctly.</li>
\image html 10_set_qt5_install_path_3.png
<li>Run configure again.</li> 
\image html 11_configure_again.png
<li>After configuring, you should see "Configuring done" in the output. Now click on "Generate".</li> 
\image html 11_configure_done.png
<li>If everything went fine, you should also have a "Generating done" in the log.</li> 
\image html 12_generation_done.png
Jan Möbius's avatar
Jan Möbius committed
101
<li>Now you can open the generated Visual Studio project. Either by pressing the "Open Project" Button"</li>
102
\image html 13_open_project.png 
Jan Möbius's avatar
Jan Möbius committed
103
<li>Or by navigating with the explorer to the build folder and opening the "OpenFlipper.sln" file.</li> 
104
105
106
107
108
109
110
111
112
113
\image html 13_navigate_to_solution_file.png
<li>Make sure that OpenFlipper is the startup project.</li> 
\image html 14_set_as_startup_project.png
<li>At the top, you can choose the build type for your project.</li> 
\image html 15_choose_build_type.png
<li>Now you can build the solution. This will compile OpenFlipper and all plugins. </li> 
\image html 16_build_solution.png
<li>If everything has been compiled, you can start OpenFlipper by clicking on the run button at the top. </li>
\image html 17_local_windows_debugger.png
</ul>
114

Jan Möbius's avatar
Jan Möbius committed
115
\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. Console outputs are only available in Visual Studio, when the "Debug" configuration is selected, or the -c option is passed as command line option.
116

117
118
119
120
121
122
123
\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
124
     qt4-mac +debug<br />
125
126
127
128
     cmake<br />
br />
     As additional ports we recommend the following<br />
     fftw-3<br />
Jan Möbius's avatar
Jan Möbius committed
129
     qwt-60 +debug +qt4<br />
130
131
132
     subversion<br />
     doxygen<br />
<li> Extract the source code or get it via svn:<br />
Jan Möbius's avatar
Jan Möbius committed
133
134
135
<code><b> git clone --recursive https://graphics.rwth-aachen.de:9000/OpenFlipper-Free/OpenFlipper-Free.git OpenFlipper-Free</b></code></li>
<li> Create a build directory (e.g. <b>build</b>) next to the OpenFlipper-Free 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 ../OpenFlipper-Free</b></code> or if you want to build in release mode type <code><b> cmake -DCMAKE_BUILD_TYPE=Release ../OpenFlipper-Free</b></code>
136
<br />
Jan Möbius's avatar
Jan Möbius committed
137
 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>
138
139
140
<li> Now call <b>make</b> to build OpenFlipper </li>
</ul>

Jan Möbius's avatar
Jan Möbius committed
141
142
143
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>
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168

\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.

 */