0022827: Make non-CPP source files (CDLs, headers) to appear in MS VS project files...
[occt.git] / dox / dev_guides / building / cmake / cmake.md
1 Building with CMake {#occt_dev_guides__building_cmake}
2 ===================
3
4 @tableofcontents
5
6 This file describes the steps to build OCCT libraries from a complete source package
7 with **CMake**. CMake is free software that can create GNU Makefiles, KDevelop, 
8 XCode, Eclipse and Visual Studio project files. **CMake** version 3.0 or above is 
9 required.
10
11 If you build OCCT from bare sources (as in Git repository) or make some 
12 changes affecting CDL files, you need to use WOK to re-generate header files
13 and build scripts / projects. See \ref occt_dev_guides__building_wok for instructions.
14
15 Before building OCCT, you need to install the required third-party libraries; see the
16 instructions for your platform in @ref occt_dev_guides__building.
17
18 ## Define the location of build and install directories.
19
20 The build directory is where intermediate files (projects / makefiles, objects, binaries) will be created.
21
22 The install directory is where binaries will be installed after build, along with header files and resources required for OCCT use in applications. 
23 It is possible to install several configurations of OCCT (differentiated by platform, bitness, compiler, and build type) into the same directory.
24
25 It is recommended to separate build and install directories from OCCT source directory, for example:
26
27        /user/home/occt/                   - sources
28        /user/home/tmp/occt-build-vc10-x64 - intermediate files
29        /user/home/occt-install            - installed binaries
30
31 ## CMake usage
32
33 Run CMake indicating the path to OCCT sources <i>($CASROOT)</i> and selected build directory.
34
35 It is recommended to use GUI tools provided by CMake: *cmake-gui* on Windows, Mac and Linux (*ccmake* also can be used on Linux).
36
37 ### Windows:
38
39 Specify the root folder of OCCT (<i>$CASROOT</i>, which contains *CMakelists.txt* file) by clicking **Browse Source**.
40
41 @figure{/dev_guides/building/cmake/images/cmake_image001.png}
42
43 Specify the location (build folder) for Cmake generated project files by clicking **Browse Build**.
44
45 Each configuration of the project should be built in its own directory. When building multiple configurations it is recommended to indicate in the name of build directories the system, bitness, compiler, and build type (e.g., <i>d:/occt/build/win32-vc9</i> ).
46
47 **Configure** opens the window with a drop-down list of generators supported by CMake project. Select the required generator (e.g., Visual Studio 2008) and click **Finish**.
48
49 @figure{/dev_guides/building/cmake/images/cmake_image002.png}
50
51 ### Linux (ccmake variant):
52
53 In the console, change to the build directory and call *ccmake* with the path to the source directory of the project:
54
55        > cd ~/occt/build
56        > ccmake ~/occt
57
58 @figure{/dev_guides/building/cmake/images/cmake_image003.png}
59
60 Press *c* to configure.
61
62 *cmake-gui* is used in the same way as described above for Windows.
63
64 ### Mac OS:
65
66 Use *cmake-gui* **Applications -> CMake 2.8-10.app** to generate project files for the chosen build environment (e.g., XCode).
67
68 @figure{/dev_guides/building/cmake/images/cmake_image004.png}
69
70 ## OCCT Configuration
71
72 The error message, which appears at the end of configuration process, informs you about the required variables, 
73 which need to be defined. This error will appear until all required variables are defined correctly.
74
75 Note: In *cmake-gui* there is "grouped" option, which groups variables with a common prefix.
76
77 **Note**: If a single-configuration generator is chosen (such as make), there is the need to specify *CMAKE_BUILD_TYPE* variable
78 with the value of further build type: Debug, Release or RelWithDebInfo.
79
80 ### Selection of the components to be built
81
82 The variables with <i>BUILD_</i> prefix allow specifying OCCT components and
83 configuration to be built:
84
85 * *BUILD_LIBRARY_TYPE*     - specifies whether static or shared libraries should be built.
86 * <i>BUILD_<MODULE></i>    - specifies whether the corresponding OCCT module should be 
87                              built (all toolkits). Note that even if the whole module is not 
88                              selected for build, its toolkits used by other toolkits 
89                              selected for build will be included automatically.
90 * *BUILD_TOOLKITS*         - allows including additional toolkits from non-selected 
91                              modules (should be list of toolkit names separated by a 
92                              space or a semicolon).
93 * *BUILD_MFC_SAMPLES*      - specifies whether OCCT MFC samples should be built.
94 * *BUILD_OCCT_OVERVIEW*    - specifies whether OCCT overview documentation should be generated.
95 * *BUILD_PATCH_DIR*        - optionally specifies additional folder containing patched OCCT source files.
96                              The patch may contain arbitrary subset of OCCT source files (including CMake scripts, templates, etc.), organized in the same structure of folders as OCCT.
97                              The projects generated by CMake will use files found in the patch folder instead of the corresponding files of OCCT.
98
99 Check variables with <i>USE_</i> prefix (<i>USE_FREEIMAGE, USE_GL2PS, USE_TBB,</i>) if there is the need to enable use of the corresponding optional 3rd-party 
100 library.
101
102 ### 3rd-party configuration (The variables with <i>3RDPARTY_</i> prefix)
103
104 If you have 3rd-party libraries in a non-default location 
105 (e.g., on Windows, binaries downloaded from http://www.opencascade.org/getocc/download/3rdparty/") 
106 *3RDPARTY_DIR* variable should be specified with the path to the folders where required 3rd-party libraries will be sought
107
108 The results of search for 3rd-party directories will be stored in *3RDPARTY_\<LIBRARY\>_DIR* variables. If *3RDPARTY_DIR* directory is defined, required libraries are sought in *3RDPARTY_DIR* location.
109
110 The procedure expects to find binary and header files of each 3rd-party library in its own sub-directory: *bin*, *lib* and *include*.
111
112 Press **Configure** (**c** key for ccmake).
113
114 The result of the search are recorded in the corresponding variables:
115
116 * *3RDPARTY_\<PRODUCT\>_DIR* - path to the 3rdparty directory (with directory name) (e.g. <i>D:/3rdparty/tcltk-86-32</i>)
117 * *3RDPARTY_\<PRODUCT\>_LIBRARY_DIR* - path to directory containing a library (e.g. <i>D:/3rdparty/tcltk-86-32/lib</i>). 
118 * *3RDPARTY_\<PRODUCT\>_INCLUDE_DIR* - path to the directory containing a header file (e.g., <i>D:/3rdparty/tcltk-86-32/include</i>)
119 * *3RDPARTY_\<PRODUCT\>_DLL_DIR* - path to the directory containing a shared library (e.g., <i>D:/3rdparty/tcltk-86-32/bin</i>) This variable is able just in windows case
120
121
122 Note: each library and include directory should be the children of product directory if the last one is defined.
123
124 The search process is as follows:
125
126 1. Common path: *3RDPARTY_DIR*
127 2. Path to a particular 3rd-party library: *3RDPARTY_\<PRODUCT\>_DIR*
128 3. Paths to headers and binaries:
129    1. *3RDPARTY_\<PRODUCT\>_INCLUDE_DIR*
130    2. *3RDPARTY_\<PRODUCT\>_LIBRARY_DIR*
131    3. *3RDPARTY_\<PRODUCT\>_DLL_DIR*
132
133 If a variable of any level is not defined (empty or <i> \<variable name\>-NOTFOUND </i>) 
134 and the upper level variable is defined, the content of the non-defined variable 
135 will be sought at the next configuration step. If search process at level 3 does not find the required files, it seeks in default places.
136
137 Important: If *BUILD_CONFIGURATION* variable is changed, at the next configuration 
138 *3RDPARTY_ variables* will be replaced by the search process result, except for the *3RDPARTY_DIR* variable.
139
140 **Note** : CMake will produce an error after the configuration step until all required variables are defined correctly.
141 If the search result (include path, or library path, or dll path) does not meet your expectations, 
142 you can  change *3RDPARTY_\<PRODUCT\>_*_DIR variable*, clear (if they are not empty) 
143 *3RDPARTY_\<PRODUCT\>_DLL_DIR, 3RDPARTY_\<PRODUCT\>_INCLUDE_DIR* and 3RDPARTY_\<PRODUCT\>_LIBRARY_DIR variables 
144 (or clear one of them) and run the configuration process again. 
145
146 At this time the search will be performed in the newly identified directory 
147 and the result will be recorded to corresponding variables (replace old value if it is necessary).
148
149 For example, (Linux case) *3RDPARTY_FREETYPE_DIR* variable 
150
151     /PRODUCTS/maintenance/Mandriva2010/freetype-2.4.10
152
153 can be changed to 
154
155     /PRODUCTS/maintenance/Mandriva2010/freetype-2.5.3
156
157 During the configuration process and the related variables (*3RDPARTY_FREETYPE_DLL_DIR*, *3RDPARTY_FREETYPE_INCLUDE_DIR* and *3RDPARTY_FREETYPE_LIBRARY_DIR*) will be filled with new found values
158
159 **Note**: The names of searched libraries and header files are hard-coded. If there is the need to change their names,
160 change appropriate cmake variables (edit CMakeCache.txt file or edit in cmake-gui in advance mode) without reconfiguration: *3RDPARTY_\<PRODUCT\>_INCLUDE* for include, *3RDPARTY_\<PRODUCT\>_LIB* for library and *3RDPARTY_\<PRODUCT\>_DLL* for shared library.
161
162 ###The variables with INSTALL_ prefix:
163
164 Define *INSTALL_DIR* variable as the path will be contain the built OCCT files (libraries, executables and headers)
165 If <i>INSTALL_\<PRODUCT\></i> variable is checked, 3rd-party products will be copied to the install directory.
166
167 Additional INSTALL_ variables:
168
169 * INSTALL_SAMPLES       - copy all OCCT samples into the install folder
170 * INSTALL_OCCT_OVERVIEW - copy generated OCCT overview documentation into the install folder
171
172 At the end of the configuration process "configuring done" message will be shown and the generation process can be started.
173
174 ## OCCT Generation
175
176 This procedure will create makefiles or project files for your build system.
177
178 ### Windows
179
180 Click **Generate** button and wait until the generation process is finished. 
181 Then the project files will appear in the build folder (e.g. <i> d:/occt/build/win32-vc9-release </i>). 
182
183 ### Linux
184
185 Click **Generate** button (if you use cmake-gui) or press **g** (for ccmake) to start the generation process.
186
187 ### Mac OS X
188
189 Click **Generate** button and wait until the generation process is finished. 
190 Then the project files will appear in the build folder (e.g. <i> /Developer/occt/build/XCode </i>).
191
192 ## OCCT Building
193
194 The install folder contains the scripts to run *DRAWEXE* (*draw.bat* or *draw.sh*) and samples (if its were built; (see below **MFC samples**)); the directory structure is follow:
195 * **data**    - data files for OCCT (brep, iges, stp)
196 * **inc**     - header files
197 * **samples** - tcl sample files
198 * **src**     - all required source files for OCCT
199 * **tests**   - OCCT test suite
200 * **win32/vc10/bind**> - example relative directory tree of binary files (3rdparty and occt)
201 * **win32/vc9/lib**>   - example relative directory tree of libraries (3rdparty and occt)
202
203 ### Windows (Visual studio)
204
205 Go to the build folder, start the Visual Studio solution *OCCT.sln* and build it by clicking **Build -> Build Solution**.
206
207 When the building process is finished, build the *INSTALL* project (by default the build solution process skips the building of the INSTALL project) to move the above files to *INSTALL_DIR*. 
208
209 For this, right-click on the *INSTALL* project and select **Project Only -> Build Only** -> *INSTALL* in the solution explorer. 
210
211 ### Linux (make)
212
213 Change directory to the directory with binaries and run *make* command
214
215        > make 
216
217 To copy all libraries, executables and chosen 3rd-party libraries run *make* command with *install* argument
218
219        > make install
220
221 This command will move the above files to *INSTALL_DIR*.
222
223 ### Mac OS X (XCode)
224
225 Go to the build folder, start XCode solution *OCCT.xcodeproj* and build it by clicking **Build -> Build**. 
226 Please notice that XCode may lag because it processes sources at the first start.
227
228 When the building process has finished, build the *INSTALL* project (by default the build solution process skips the building of *INSTALL* project) to move the above files to *INSTALL_DIR*. 
229 Notice that *env.sh* (which configures *PATH* and *DYLD_LIBRARY_PATH* environment variables 
230 as well as Draw Harness extra variables) and *draw.sh* (to launch *DRAWEXE* ) will be created in the target directory. 
231
232 ### MFC samples
233
234 On Windows you can also build binaries of MFC samples together with OCCT. For this, activate **BUILD_Samples** check-box in CMake configuration dialog.
235
236 @figure{/dev_guides/building/cmake/images/cmake_image007.png}
237
238 Please take into account that MFC sample binaries will be installed  in the same folder as OCCT binaries during building of *INSTALL* project.
239 To run an MFC sample use *sample.bat* launcher. The command format is: <i>sample.bat *SampleName*</i> (e.g. <i>sample.bat ImportExport</i>).