ba06f8bb |
1 | Building with CMake {#occt_dev_guides__building_cmake} |
e5bd0d98 |
2 | =================== |
3 | |
4 | @tableofcontents |
5 | |
6 | This file describes steps to build OCCT libraries from complete source package |
7 | with CMake. CMake is free software that can create GNU Makefiles, KDevelop, |
8 | XCode, and Visual Studio project files. Version 2.6 or above of CMake is |
9 | required. |
10 | |
11 | If you are building OCCT from bare sources (as in Git repository), or do some |
12 | changes affecting CDL files, you need to use WOK to re-generate header files |
ba06f8bb |
13 | and build scripts / projects. See \ref occt_dev_guides__building_wok for instructions. |
e5bd0d98 |
14 | |
ad211ad3 |
15 | Before building OCCT, you need to install required third-party libraries; see |
ba06f8bb |
16 | instructions for your platform in @ref occt_dev_guides__building. |
e5bd0d98 |
17 | |
18 | ## Decide on location of build and install directories. |
19 | |
20 | The build directory is the one where intermediate files will be created (projects / makefiles, objects, binaries). |
32856b63 |
21 | Each configuration to be built should have its own build directory. |
e5bd0d98 |
22 | |
32856b63 |
23 | The install directory is the one where binaries will be installed after build, along with header files and resources required for OCCT use in applications. |
24 | It is possible to install several configurations of OCCT (differentiated by platform, bitness, compiler, and build type) into the same directory. |
e5bd0d98 |
25 | |
26 | It is recommended to separate build and install directories from OCCT source directory, for example: |
27 | |
32856b63 |
28 | /user/home/occt/ - sources |
29 | /user/home/tmp/occt-build-vc10-x64-release - intermediate files |
30 | /user/home/occt-install - installed binaries |
e5bd0d98 |
31 | |
32 | ## CMake usage |
33 | |
32856b63 |
34 | Run CMake indicating path to OCCT sources ($CASROOT) and selected build directory. |
e5bd0d98 |
35 | |
32856b63 |
36 | It is recommended to use GUI tools provided by CMake: cmake-gui on Windows and Mac, ccmake or cmake-gui on Linux. |
e5bd0d98 |
37 | |
38 | ### Windows: |
39 | |
32856b63 |
40 | Specify the root folder of OCCT ($CASROOT, it contains CMakelists.txt file) by clicking Browse Source. |
e5bd0d98 |
41 | |
32856b63 |
42 | @figure{/dev_guides/building/cmake/images/cmake_image001.png} |
e5bd0d98 |
43 | |
32856b63 |
44 | Specify location (build folder) for Cmake generated project files by clicking Browse Build. |
45 | Each configuration of the project should be built in its own directory. |
46 | When building multiple configurations it is recommended to compose name of build directories including system, bitness, compiler, and build type (e.g., d:/occt/build/win32-vc9-debug). |
e5bd0d98 |
47 | |
32856b63 |
48 | 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. |
49 | |
50 | @figure{/dev_guides/building/cmake/images/cmake_image002.png} |
51 | |
52 | ### Linux (ccmake variant): |
e5bd0d98 |
53 | |
54 | In the console, change to the build directory and call ccmake with the path to the source directory of the project: |
55 | |
56 | > cd ~/occt/build/debug |
79d580f2 |
57 | > ccmake ~/occt |
e5bd0d98 |
58 | |
32856b63 |
59 | @figure{/dev_guides/building/cmake/images/cmake_image003.png} |
e5bd0d98 |
60 | |
61 | Press "c" to configure. |
62 | |
32856b63 |
63 | Use of *cmake-gui* is the same as described above for Windows. |
64 | |
e5bd0d98 |
65 | ### Mac OS: |
66 | |
67 | Use cmake-gui (Applications -> CMake 2.8-10.app) to generate project files for the chosen build environment (e.g., XCode). |
68 | |
32856b63 |
69 | @figure{/dev_guides/building/cmake/images/cmake_image004.png} |
e5bd0d98 |
70 | |
71 | ## OCCT Configuration |
72 | |
73 | The error message which appears at the end of configuration process, informs you about the required variables |
74 | which need to be defined. This error will appear until all required variables are defined correctly. |
75 | Note: In cmake-gui there is "grouped" option, which groups variables with a common prefix. |
76 | |
5c573e69 |
77 | ### Selection of components to be built |
e5bd0d98 |
78 | |
5c573e69 |
79 | The variables with "BUILD_" prefix allow specifying OCCT components and |
80 | configuration to be built: |
234e52be |
81 | |
5c573e69 |
82 | * BUILD_CONFIGURATION - defines configuration to be built (Release by default). |
32856b63 |
83 | * BUILD_<MODULE> - specify whether corresponding OCCT module should be |
84 | built (all toolkits). Note that even if whole module is not |
85 | selected for build, its toolkits used by other toolkits |
86 | selected for build will be included automatically. |
87 | * BUILD_TOOLKITS - allows including additional toolkits from non-selected |
88 | modules (should be list of toolkit names separated by a |
89 | space or a semicolon). |
90 | * BUILD_SAMPLES - specify whether OCCT MFC samples should be built. |
91 | * BUILD_PATCH_DIR - optionally specify additional folder containing patched OCCT source files. |
92 | The patch may contain arbitrary subset of OCCT source files (including CMake scripts, templates, etc.), organized in the same structure of folders as OCCT. |
93 | The projects generated by CMake will use files found in the patch folder instead of corresponding files of OCCT. |
e5bd0d98 |
94 | |
5c573e69 |
95 | Check variables with "USE_" prefix (USE_FREEIMAGE, USE_GL2PS, USE_TBB, and |
96 | USE_OPENCL) if you want to enable use of the corresponding optional 3rd-party |
97 | library. |
98 | |
234e52be |
99 | ### 3rd-party configuration (The variables with 3RDPARTY_ prefix) |
e5bd0d98 |
100 | |
101 | If you have 3rd-party libraries in a non-default location |
102 | (e.g., on Windows, binaries downloaded from "http://www.opencascade.org/getocc/download/3rdparty/"), |
32856b63 |
103 | specify 3RDPARTY_DIR variable that points to the folders of 3rdparty libraries (some or all). |
104 | At the next configuration step the 3rd-party libraries will be searched for in 3RDPARTY_DIR directory, and stored in 3RDPARTY_\<LIBRARY\>_DIR variables. |
105 | The procedure expects to find binary and header files of each 3rd-party library in its own sub-directory, separated by sub-directories *bin*, *lib*, and *include*. |
ad211ad3 |
106 | |
5c573e69 |
107 | Press "Configure" ("c" key for ccmake). |
ad211ad3 |
108 | |
e5bd0d98 |
109 | The result of the 3rdparty product search will be recorded in the corresponding variables: |
110 | |
111 | * 3RDPARTY_\<PRODUCT\>_DIR - path to the product directory (with directory name) (e.g., D:/3rdparty/Tcl-8.5.12.0-32) |
32856b63 |
112 | * 3RDPARTY_\<PRODUCT\>_LIBRARY - path to the .lib libraries (with the library name) (e.g., D:/3rdparty/Tcl-8.5.12.0-32/lib/tcl85.lib). |
113 | In non-windows case, this variable is the same as 3RDPARTY_\<PRODUCT\>_DLL. |
e5bd0d98 |
114 | * 3RDPARTY_\<PRODUCT\>_INCLUDE - path to the include directory that contains the required header file (with "include" name) (e.g., D:/3rdparty/Tcl-8.5.12.0-32/include including tcl.h) |
115 | * 3RDPARTY_\<PRODUCT\>_DLL - path to the .dll/.so/.dylib library (with the library name) (e.g., D:/3rdparty/Tcl-8.5.12.0-32/bin/tcl85.dll) |
116 | |
117 | The search process is as follows: |
118 | |
5c573e69 |
119 | 1. Common path: 3RDPARTY_DIR |
120 | 2. Path to particular 3rd-party library: 3RDPARTY_\<PRODUCT\>_DIR |
121 | 3. Paths to headers and binaries: |
122 | 1. 3RDPARTY_\<PRODUCT\>_INCLUDE |
123 | 2. 3RDPARTY_\<PRODUCT\>_LIBRARY |
124 | 3. 3RDPARTY_\<PRODUCT\>_DLL |
e5bd0d98 |
125 | |
126 | If a variable of any level is not defined (empty or \<variable name\>-NOTFOUND) |
127 | and the upper level variable is defined, the content of the non-defined variable |
128 | will be searched for at the next configuration step. If search process in level 3 |
234e52be |
129 | does not find the required files, it searches in default places also. |
e5bd0d98 |
130 | |
5c573e69 |
131 | **Note**: the names of searched libraries and header files are hardcoded. |
132 | Freetype search process tries to find ft2build.h file in 3RDPARTY_FREETYPE INCLUDE dir |
e5bd0d98 |
133 | and after that adds "3RDPARTY_FREETYPE_INCLUDE /freetype2" path to common includes if it exists. |
5c573e69 |
134 | |
135 | Important: If BUILD_CONFIGURATION variable is changed - at the next configuration |
e5bd0d98 |
136 | 3RDPARTY_ variables will be replaced by the search process result, except for the 3RDPARTY_DIR variable. |
137 | |
138 | *Note*: CMake will produce an error after the configuration step until all required variables are defined correctly. |
139 | If the search result (include path, or library path, or dll path) does not meet your expectations - |
140 | you can change 3RDPARTY_\<PRODUCT\>_DIR variable, clear (if they are not empty) |
141 | 3RDPARTY_\<PRODUCT\>_DLL, 3RDPARTY_\<PRODUCT\>_INCLUDE_DIR and 3RDPARTY_\<PRODUCT\>_LIBRARY variables |
142 | (or clear one of them) and run the configuration process again. |
5c573e69 |
143 | |
e5bd0d98 |
144 | At this time the search will be performed in the new identified directory |
145 | and the result will be recorded to empty variables (non-empty variables will not be replaced). |
146 | |
147 | For example, (Linux case) 3RDPARTY_FREETYPE_DIR variable |
148 | |
234e52be |
149 | /PRODUCTS/maintenance/Mandriva2010/freetype-2.3.7 |
e5bd0d98 |
150 | |
151 | can be changed to |
152 | |
234e52be |
153 | /PRODUCTS/maintenance/Mandriva2010/freetype-2.4.10 |
e5bd0d98 |
154 | |
155 | and the related variables: 3RDPARTY_FREETYPE_DLL, 3RDPARTY_FREETYPE_INCLUDE_DIR and 3RDPARTY_FREETYPE_LIBRARY will be cleared. |
156 | |
32856b63 |
157 | @figure{/dev_guides/building/cmake/images/cmake_image005.png} |
e5bd0d98 |
158 | |
159 | During configuration process the cleaned variables will be filled with new found values. |
160 | |
234e52be |
161 | ###The variables with INSTALL_ prefix: |
e5bd0d98 |
162 | |
234e52be |
163 | Define in INSTALL_DIR variable the path where will be placed built OCCT files (libraries, executables and headers). |
e5bd0d98 |
164 | If INSTALL_\<PRODUCT\> variable is checked - 3rd-party products will be copied to the install directory. |
234e52be |
165 | |
166 | #### At the end of the configuration process "configuring done" message will be shown and the generation process can be started. |
e5bd0d98 |
167 | |
168 | ## OCCT Generation |
169 | |
170 | This will create makefiles or project files for your build system. |
171 | |
172 | ### Windows |
173 | |
174 | Click Generate button and wait until the generation process is finished. |
175 | Then the project files will appear in the build folder (e.g., d:/occt/build/win32-vc9-release). |
176 | |
177 | ### Linux |
178 | |
179 | When the configuration is complete, start the generation process by pressing "g". |
180 | |
32856b63 |
181 | @figure{/dev_guides/building/cmake/images/cmake_image006.png} |
e5bd0d98 |
182 | |
183 | ### Mac OS X |
184 | |
185 | Click Generate button and wait until the generation process is finished. |
186 | Then the project files will appear in the build folder (e.g., /Developer/occt/build/XCode). |
187 | |
188 | ## OCCT Building |
189 | |
190 | The install folder contains bin, inc, lib and res folders and a script to run DRAWEXE (draw.bat or draw.sh). |
191 | "bin" contains executables, DLL (Windows) style shared libraries and pdb-files in OCCT debug version,. |
192 | "lib" contains the import parts of DLL libraries. |
193 | "inc" contains header files. |
194 | "res" contains all required source files for OCCT. |
195 | |
196 | ### Windows (Visual studio) |
197 | |
198 | Go to the build folder, start the Visual Studio solution (OCCT.sln) and build it by clicking Build - Build Solution. |
199 | When the building process finished, build the INSTALL project |
200 | (by default the build solution process skips the building of the INSTALL project) to move the above files to INSTALL_DIR. |
201 | For this in the solution explorer right click on the INSTALL project and select Project Only - Build Only INSTALL. |
202 | |
203 | ### Linux (make) |
204 | Change directory to binary dir and run make command |
205 | |
206 | > make |
207 | |
208 | To copy all libraries, executables and chosen 3rd-party libraries run "make" command with "install" argument |
209 | |
210 | > make install |
211 | |
212 | This command will move the above files to INSTALL_DIR. |
213 | |
214 | ### Mac OS X (XCode) |
215 | |
216 | Go to the build folder, start the XCode solution (OCCT.xcodeproj) |
217 | and build it by clicking Build -> Build. |
218 | Please notice that XCode may have worst responsibility to user actions |
219 | due to sources processing at first start. |
220 | |
221 | When the building process finished, build the INSTALL project |
222 | (by default the build solution process skips the building of the INSTALL project) |
223 | to move the above files to INSTALL_DIR. |
224 | Notice that env.sh (configure PATH and DYLD_LIBRARY_PATH environment variables |
225 | as well as Draw Harness extra variables) and draw.sh (to launch DRAWEXE) will be created in target directory. |