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