0024810: "Patch" feature should be introduced in OCC CMake building procedure
[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).
ad211ad3 21The install directory is the one where binaries will be installed after build,
22along with header files and resources required for OCCT use in applications.
e5bd0d98 23
ad211ad3 24OCCT CMake scripts assume use of separate build and one install directories
25for each configuration (Debug or Release).
e5bd0d98 26
27It 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 35Run CMake indicating path to OCCT sources ($CASROOT; in previous example
36CASROOT equal to /user/home/occt in lin case, and d:/occt in windows case)
37and selected build directory (in prev example build directory is
38/user/home/tmp/occt-build-release).
e5bd0d98 39
ad211ad3 40It is recommended to use GUI tools provided by CMake: cmake-gui on Windows
41and 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
57In 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
65Press "c" to configure.
66
67### Mac OS:
68
69Use 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
76The error message which appears at the end of configuration process, informs you about the required variables
77which need to be defined. This error will appear until all required variables are defined correctly.
78Note: In cmake-gui there is "grouped" option, which groups variables with a common prefix.
79
5c573e69 80### Selection of components to be built
e5bd0d98 81
5c573e69 82The variables with "BUILD_" prefix allow specifying OCCT components and
83configuration to be built:
234e52be 84
5c573e69 85* BUILD_CONFIGURATION - defines configuration to be built (Release by default).
86* BUILD_<MODULE> - specify whether corresponding OCCT module should be
87 built (all toolkits). Note that even if 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_SAMPLES - specify whether OCCT MFC samples should be built.
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
99### 3rd-party configuration
e5bd0d98 100
234e52be 101### 3rd-party configuration (The variables with 3RDPARTY_ prefix)
e5bd0d98 102
103If you have 3rd-party libraries in a non-default location
104(e.g., on Windows, binaries downloaded from "http://www.opencascade.org/getocc/download/3rdparty/"),
105specify 3RDPARTY_DIR variable that points to the folders of 3rdparty products (some or all).
106At the next configuration 3rd-party product paths stored in 3RDPARTY_\<PRODUCT\>_DIR variable
107will be searched for in 3RDPARTY_DIR directory. If the structure of 3RDPARTY_DIR directory
108is the same as adopted in the OCCT, the directory will contain product dir, lib and header files.
ad211ad3 109
5c573e69 110Press "Configure" ("c" key for ccmake).
ad211ad3 111
e5bd0d98 112The result of the 3rdparty product search will be recorded in the corresponding variables:
113
114* 3RDPARTY_\<PRODUCT\>_DIR - path to the product directory (with directory name) (e.g., D:/3rdparty/Tcl-8.5.12.0-32)
115* 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.
116* 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)
117* 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)
118
119The search process is as follows:
120
5c573e69 1211. Common path: 3RDPARTY_DIR
1222. Path to particular 3rd-party library: 3RDPARTY_\<PRODUCT\>_DIR
1233. Paths to headers and binaries:
124 1. 3RDPARTY_\<PRODUCT\>_INCLUDE
125 2. 3RDPARTY_\<PRODUCT\>_LIBRARY
126 3. 3RDPARTY_\<PRODUCT\>_DLL
e5bd0d98 127
128If a variable of any level is not defined (empty or \<variable name\>-NOTFOUND)
129and the upper level variable is defined, the content of the non-defined variable
130will be searched for at the next configuration step. If search process in level 3
234e52be 131does not find the required files, it searches in default places also.
e5bd0d98 132
5c573e69 133**Note**: the names of searched libraries and header files are hardcoded.
134Freetype search process tries to find ft2build.h file in 3RDPARTY_FREETYPE INCLUDE dir
e5bd0d98 135and after that adds "3RDPARTY_FREETYPE_INCLUDE /freetype2" path to common includes if it exists.
5c573e69 136
137Important: If BUILD_CONFIGURATION variable is changed - at the next configuration
e5bd0d98 1383RDPARTY_ 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.
141If the search result (include path, or library path, or dll path) does not meet your expectations -
142you can change 3RDPARTY_\<PRODUCT\>_DIR variable, clear (if they are not empty)
1433RDPARTY_\<PRODUCT\>_DLL, 3RDPARTY_\<PRODUCT\>_INCLUDE_DIR and 3RDPARTY_\<PRODUCT\>_LIBRARY variables
144(or clear one of them) and run the configuration process again.
5c573e69 145
e5bd0d98 146At this time the search will be performed in the new identified directory
147and the result will be recorded to empty variables (non-empty variables will not be replaced).
148
149For example, (Linux case) 3RDPARTY_FREETYPE_DIR variable
150
234e52be 151 /PRODUCTS/maintenance/Mandriva2010/freetype-2.3.7
e5bd0d98 152
153can be changed to
154
234e52be 155 /PRODUCTS/maintenance/Mandriva2010/freetype-2.4.10
e5bd0d98 156
157and the related variables: 3RDPARTY_FREETYPE_DLL, 3RDPARTY_FREETYPE_INCLUDE_DIR and 3RDPARTY_FREETYPE_LIBRARY will be cleared.
158
159@image html /dev_guides/building/cmake/images/cmake_image005.png
160@image latex /dev_guides/building/cmake/images/cmake_image005.png
161
162During configuration process the cleaned variables will be filled with new found values.
163
234e52be 164###The variables with INSTALL_ prefix:
e5bd0d98 165
234e52be 166Define in INSTALL_DIR variable the path where will be placed built OCCT files (libraries, executables and headers).
e5bd0d98 167If INSTALL_\<PRODUCT\> variable is checked - 3rd-party products will be copied to the install directory.
234e52be 168
169#### At the end of the configuration process "configuring done" message will be shown and the generation process can be started.
e5bd0d98 170
171## OCCT Generation
172
173This will create makefiles or project files for your build system.
174
175### Windows
176
177Click Generate button and wait until the generation process is finished.
178Then the project files will appear in the build folder (e.g., d:/occt/build/win32-vc9-release).
179
180### Linux
181
182When the configuration is complete, start the generation process by pressing "g".
183
184@image html /dev_guides/building/cmake/images/cmake_image006.png
185@image latex /dev_guides/building/cmake/images/cmake_image006.png
186
187### Mac OS X
188
189Click Generate button and wait until the generation process is finished.
190Then the project files will appear in the build folder (e.g., /Developer/occt/build/XCode).
191
192## OCCT Building
193
194The install folder contains bin, inc, lib and res folders and a script to run DRAWEXE (draw.bat or draw.sh).
195"bin" contains executables, DLL (Windows) style shared libraries and pdb-files in OCCT debug version,.
196"lib" contains the import parts of DLL libraries.
197"inc" contains header files.
198"res" contains all required source files for OCCT.
199
200### Windows (Visual studio)
201
202Go to the build folder, start the Visual Studio solution (OCCT.sln) and build it by clicking Build - Build Solution.
203When the building process finished, build the INSTALL project
204(by default the build solution process skips the building of the INSTALL project) to move the above files to INSTALL_DIR.
205For this in the solution explorer right click on the INSTALL project and select Project Only - Build Only INSTALL.
206
207### Linux (make)
208Change directory to binary dir and run make command
209
210 > make
211
212To copy all libraries, executables and chosen 3rd-party libraries run "make" command with "install" argument
213
214 > make install
215
216This command will move the above files to INSTALL_DIR.
217
218### Mac OS X (XCode)
219
220Go to the build folder, start the XCode solution (OCCT.xcodeproj)
221and build it by clicking Build -> Build.
222Please notice that XCode may have worst responsibility to user actions
223due to sources processing at first start.
224
225When the building process finished, build the INSTALL project
226(by default the build solution process skips the building of the INSTALL project)
227to move the above files to INSTALL_DIR.
228Notice that env.sh (configure PATH and DYLD_LIBRARY_PATH environment variables
229as well as Draw Harness extra variables) and draw.sh (to launch DRAWEXE) will be created in target directory.
230
231## OCCT project debugging for Visual Studio
232Run OCCT.bat from the build directory to start Visual Studio with required environment for debugging.