0025105: Remove TColgp_DataMapOfIntegerCirc2d
[occt.git] / dox / dev_guides / building / cmake / cmake.md
CommitLineData
ba06f8bb 1Building with CMake {#occt_dev_guides__building_cmake}
e5bd0d98 2===================
3
4@tableofcontents
5
6This file describes steps to build OCCT libraries from complete source package
7with CMake. CMake is free software that can create GNU Makefiles, KDevelop,
8XCode, and Visual Studio project files. Version 2.6 or above of CMake is
9required.
10
11If you are building OCCT from bare sources (as in Git repository), or do some
12changes affecting CDL files, you need to use WOK to re-generate header files
ba06f8bb 13and build scripts / projects. See \ref occt_dev_guides__building_wok for instructions.
e5bd0d98 14
ad211ad3 15Before building OCCT, you need to install required third-party libraries; see
ba06f8bb 16instructions for your platform in @ref occt_dev_guides__building.
e5bd0d98 17
18## Decide on location of build and install directories.
19
20The build directory is the one where intermediate files will be created (projects / makefiles, objects, binaries).
32856b63 21Each configuration to be built should have its own build directory.
e5bd0d98 22
32856b63 23The install directory is the one where binaries will be installed after build, along with header files and resources required for OCCT use in applications.
24It is possible to install several configurations of OCCT (differentiated by platform, bitness, compiler, and build type) into the same directory.
e5bd0d98 25
26It 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 34Run CMake indicating path to OCCT sources ($CASROOT) and selected build directory.
e5bd0d98 35
32856b63 36It 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 40Specify 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 44Specify location (build folder) for Cmake generated project files by clicking Browse Build.
45Each configuration of the project should be built in its own directory.
46When 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 48Configure 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
54In 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
61Press "c" to configure.
62
32856b63 63Use of *cmake-gui* is the same as described above for Windows.
64
e5bd0d98 65### Mac OS:
66
67Use 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
73The error message which appears at the end of configuration process, informs you about the required variables
74which need to be defined. This error will appear until all required variables are defined correctly.
75Note: 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 79The variables with "BUILD_" prefix allow specifying OCCT components and
80configuration 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 95Check variables with "USE_" prefix (USE_FREEIMAGE, USE_GL2PS, USE_TBB, and
96USE_OPENCL) if you want to enable use of the corresponding optional 3rd-party
97library.
98
234e52be 99### 3rd-party configuration (The variables with 3RDPARTY_ prefix)
e5bd0d98 100
101If 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 103specify 3RDPARTY_DIR variable that points to the folders of 3rdparty libraries (some or all).
104At the next configuration step the 3rd-party libraries will be searched for in 3RDPARTY_DIR directory, and stored in 3RDPARTY_\<LIBRARY\>_DIR variables.
105The 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 107Press "Configure" ("c" key for ccmake).
ad211ad3 108
e5bd0d98 109The 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
117The search process is as follows:
118
5c573e69 1191. Common path: 3RDPARTY_DIR
1202. Path to particular 3rd-party library: 3RDPARTY_\<PRODUCT\>_DIR
1213. Paths to headers and binaries:
122 1. 3RDPARTY_\<PRODUCT\>_INCLUDE
123 2. 3RDPARTY_\<PRODUCT\>_LIBRARY
124 3. 3RDPARTY_\<PRODUCT\>_DLL
e5bd0d98 125
126If a variable of any level is not defined (empty or \<variable name\>-NOTFOUND)
127and the upper level variable is defined, the content of the non-defined variable
128will be searched for at the next configuration step. If search process in level 3
234e52be 129does 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.
132Freetype search process tries to find ft2build.h file in 3RDPARTY_FREETYPE INCLUDE dir
e5bd0d98 133and after that adds "3RDPARTY_FREETYPE_INCLUDE /freetype2" path to common includes if it exists.
5c573e69 134
135Important: If BUILD_CONFIGURATION variable is changed - at the next configuration
e5bd0d98 1363RDPARTY_ 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.
139If the search result (include path, or library path, or dll path) does not meet your expectations -
140you can change 3RDPARTY_\<PRODUCT\>_DIR variable, clear (if they are not empty)
1413RDPARTY_\<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 144At this time the search will be performed in the new identified directory
145and the result will be recorded to empty variables (non-empty variables will not be replaced).
146
147For example, (Linux case) 3RDPARTY_FREETYPE_DIR variable
148
234e52be 149 /PRODUCTS/maintenance/Mandriva2010/freetype-2.3.7
e5bd0d98 150
151can be changed to
152
234e52be 153 /PRODUCTS/maintenance/Mandriva2010/freetype-2.4.10
e5bd0d98 154
155and 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
159During configuration process the cleaned variables will be filled with new found values.
160
234e52be 161###The variables with INSTALL_ prefix:
e5bd0d98 162
234e52be 163Define in INSTALL_DIR variable the path where will be placed built OCCT files (libraries, executables and headers).
e5bd0d98 164If 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
170This will create makefiles or project files for your build system.
171
172### Windows
173
174Click Generate button and wait until the generation process is finished.
175Then the project files will appear in the build folder (e.g., d:/occt/build/win32-vc9-release).
176
177### Linux
178
179When 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
185Click Generate button and wait until the generation process is finished.
186Then the project files will appear in the build folder (e.g., /Developer/occt/build/XCode).
187
188## OCCT Building
189
190The 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
198Go to the build folder, start the Visual Studio solution (OCCT.sln) and build it by clicking Build - Build Solution.
199When 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.
201For this in the solution explorer right click on the INSTALL project and select Project Only - Build Only INSTALL.
202
203### Linux (make)
204Change directory to binary dir and run make command
205
206 > make
207
208To copy all libraries, executables and chosen 3rd-party libraries run "make" command with "install" argument
209
210 > make install
211
212This command will move the above files to INSTALL_DIR.
213
214### Mac OS X (XCode)
215
216Go to the build folder, start the XCode solution (OCCT.xcodeproj)
217and build it by clicking Build -> Build.
218Please notice that XCode may have worst responsibility to user actions
219due to sources processing at first start.
220
221When the building process finished, build the INSTALL project
222(by default the build solution process skips the building of the INSTALL project)
223to move the above files to INSTALL_DIR.
224Notice that env.sh (configure PATH and DYLD_LIBRARY_PATH environment variables
225as well as Draw Harness extra variables) and draw.sh (to launch DRAWEXE) will be created in target directory.