0024816: Tool for upgrading OCCT and dependent code
[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
576f8b11 6This file describes the steps to build OCCT libraries from a complete source package
7with **CMake**. CMake is free software that can create GNU Makefiles, KDevelop,
9f33b387 8XCode, Eclipse and Visual Studio project files. **CMake** version 3.0 or above is
e5bd0d98 9required.
10
576f8b11 11If you build OCCT from bare sources (as in Git repository) or make some
e5bd0d98 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
576f8b11 15Before building OCCT, you need to install the required third-party libraries; see the
ba06f8bb 16instructions for your platform in @ref occt_dev_guides__building.
e5bd0d98 17
576f8b11 18## Define the location of build and install directories.
e5bd0d98 19
adc33035 20The build directory is where intermediate files (projects / makefiles, objects, binaries) will be created.
e5bd0d98 21
576f8b11 22The install directory is where binaries will be installed after build, along with header files and resources required for OCCT use in applications.
32856b63 23It is possible to install several configurations of OCCT (differentiated by platform, bitness, compiler, and build type) into the same directory.
e5bd0d98 24
25It is recommended to separate build and install directories from OCCT source directory, for example:
26
adc33035 27 /user/home/occt/ - sources
28 /user/home/tmp/occt-build-vc10-x64 - intermediate files
29 /user/home/occt-install - installed binaries
e5bd0d98 30
31## CMake usage
32
576f8b11 33Run CMake indicating the path to OCCT sources <i>($CASROOT)</i> and selected build directory.
e5bd0d98 34
9f33b387 35It is recommended to use GUI tools provided by CMake: *cmake-gui* on Windows, Mac and Linux (*ccmake* also can be used on Linux).
e5bd0d98 36
37### Windows:
38
576f8b11 39Specify the root folder of OCCT (<i>$CASROOT</i>, which contains *CMakelists.txt* file) by clicking **Browse Source**.
e5bd0d98 40
32856b63 41@figure{/dev_guides/building/cmake/images/cmake_image001.png}
e5bd0d98 42
576f8b11 43Specify the location (build folder) for Cmake generated project files by clicking **Browse Build**.
e5bd0d98 44
adc33035 45Each 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> ).
576f8b11 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**.
32856b63 48
49@figure{/dev_guides/building/cmake/images/cmake_image002.png}
50
51### Linux (ccmake variant):
e5bd0d98 52
576f8b11 53In the console, change to the build directory and call *ccmake* with the path to the source directory of the project:
e5bd0d98 54
adc33035 55 > cd ~/occt/build
79d580f2 56 > ccmake ~/occt
e5bd0d98 57
32856b63 58@figure{/dev_guides/building/cmake/images/cmake_image003.png}
e5bd0d98 59
576f8b11 60Press *c* to configure.
e5bd0d98 61
576f8b11 62*cmake-gui* is used in the same way as described above for Windows.
32856b63 63
e5bd0d98 64### Mac OS:
65
576f8b11 66Use *cmake-gui* **Applications -> CMake 2.8-10.app** to generate project files for the chosen build environment (e.g., XCode).
e5bd0d98 67
32856b63 68@figure{/dev_guides/building/cmake/images/cmake_image004.png}
e5bd0d98 69
70## OCCT Configuration
71
576f8b11 72The error message, which appears at the end of configuration process, informs you about the required variables,
e5bd0d98 73which need to be defined. This error will appear until all required variables are defined correctly.
e5bd0d98 74
576f8b11 75Note: In *cmake-gui* there is "grouped" option, which groups variables with a common prefix.
76
adc33035 77**Note**: If a single-configuration generator is chosen (such as make), there is the need to specify *CMAKE_BUILD_TYPE* variable
78with the value of further build type: Debug, Release or RelWithDebInfo.
79
576f8b11 80### Selection of the components to be built
e5bd0d98 81
576f8b11 82The variables with <i>BUILD_</i> prefix allow specifying OCCT components and
5c573e69 83configuration to be built:
234e52be 84
adc33035 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
99Check 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
5c573e69 100library.
101
576f8b11 102### 3rd-party configuration (The variables with <i>3RDPARTY_</i> prefix)
e5bd0d98 103
104If you have 3rd-party libraries in a non-default location
576f8b11 105(e.g., on Windows, binaries downloaded from http://www.opencascade.org/getocc/download/3rdparty/")
9f33b387 106*3RDPARTY_DIR* variable should be specified with the path to the folders where required 3rd-party libraries will be sought
576f8b11 107
9f33b387 108The 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.
576f8b11 109
9f33b387 110The procedure expects to find binary and header files of each 3rd-party library in its own sub-directory: *bin*, *lib* and *include*.
ad211ad3 111
576f8b11 112Press **Configure** (**c** key for ccmake).
ad211ad3 113
9f33b387 114The result of the search are recorded in the corresponding variables:
e5bd0d98 115
9f33b387 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
adc33035 122Note: each library and include directory should be the children of product directory if the last one is defined.
e5bd0d98 123
124The search process is as follows:
125
576f8b11 1261. Common path: *3RDPARTY_DIR*
1272. Path to a particular 3rd-party library: *3RDPARTY_\<PRODUCT\>_DIR*
5c573e69 1283. Paths to headers and binaries:
9f33b387 129 1. *3RDPARTY_\<PRODUCT\>_INCLUDE_DIR*
130 2. *3RDPARTY_\<PRODUCT\>_LIBRARY_DIR*
131 3. *3RDPARTY_\<PRODUCT\>_DLL_DIR*
e5bd0d98 132
576f8b11 133If a variable of any level is not defined (empty or <i> \<variable name\>-NOTFOUND </i>)
e5bd0d98 134and the upper level variable is defined, the content of the non-defined variable
9f33b387 135will be sought at the next configuration step. If search process at level 3 does not find the required files, it seeks in default places.
5c573e69 136
576f8b11 137Important: 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.
e5bd0d98 139
9f33b387 140**Note** : CMake will produce an error after the configuration step until all required variables are defined correctly.
576f8b11 141If the search result (include path, or library path, or dll path) does not meet your expectations,
9f33b387 142you 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
e5bd0d98 144(or clear one of them) and run the configuration process again.
5c573e69 145
576f8b11 146At this time the search will be performed in the newly identified directory
9f33b387 147and the result will be recorded to corresponding variables (replace old value if it is necessary).
e5bd0d98 148
576f8b11 149For example, (Linux case) *3RDPARTY_FREETYPE_DIR* variable
e5bd0d98 150
9f33b387 151 /PRODUCTS/maintenance/Mandriva2010/freetype-2.4.10
e5bd0d98 152
153can be changed to
154
9f33b387 155 /PRODUCTS/maintenance/Mandriva2010/freetype-2.5.3
e5bd0d98 156
9f33b387 157During 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
e5bd0d98 158
9f33b387 159**Note**: The names of searched libraries and header files are hard-coded. If there is the need to change their names,
160change 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.
e5bd0d98 161
234e52be 162###The variables with INSTALL_ prefix:
e5bd0d98 163
9f33b387 164Define *INSTALL_DIR* variable as the path will be contain the built OCCT files (libraries, executables and headers)
576f8b11 165If <i>INSTALL_\<PRODUCT\></i> variable is checked, 3rd-party products will be copied to the install directory.
234e52be 166
adc33035 167Additional 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
576f8b11 172At the end of the configuration process "configuring done" message will be shown and the generation process can be started.
e5bd0d98 173
174## OCCT Generation
175
576f8b11 176This procedure will create makefiles or project files for your build system.
e5bd0d98 177
178### Windows
179
576f8b11 180Click **Generate** button and wait until the generation process is finished.
181Then the project files will appear in the build folder (e.g. <i> d:/occt/build/win32-vc9-release </i>).
e5bd0d98 182
183### Linux
184
9f33b387 185Click **Generate** button (if you use cmake-gui) or press **g** (for ccmake) to start the generation process.
e5bd0d98 186
187### Mac OS X
188
576f8b11 189Click **Generate** button and wait until the generation process is finished.
190Then the project files will appear in the build folder (e.g. <i> /Developer/occt/build/XCode </i>).
e5bd0d98 191
192## OCCT Building
193
9f33b387 194The 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
beb18c1f 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)
e5bd0d98 202
203### Windows (Visual studio)
204
576f8b11 205Go to the build folder, start the Visual Studio solution *OCCT.sln* and build it by clicking **Build -> Build Solution**.
206
207When 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
209For this, right-click on the *INSTALL* project and select **Project Only -> Build Only** -> *INSTALL* in the solution explorer.
e5bd0d98 210
211### Linux (make)
576f8b11 212
213Change directory to the directory with binaries and run *make* command
e5bd0d98 214
215 > make
216
576f8b11 217To copy all libraries, executables and chosen 3rd-party libraries run *make* command with *install* argument
e5bd0d98 218
219 > make install
220
576f8b11 221This command will move the above files to *INSTALL_DIR*.
e5bd0d98 222
223### Mac OS X (XCode)
224
576f8b11 225Go to the build folder, start XCode solution *OCCT.xcodeproj* and build it by clicking **Build -> Build**.
226Please notice that XCode may lag because it processes sources at the first start.
227
228When 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*.
229Notice that *env.sh* (which configures *PATH* and *DYLD_LIBRARY_PATH* environment variables
230as well as Draw Harness extra variables) and *draw.sh* (to launch *DRAWEXE* ) will be created in the target directory.
231
232### MFC samples
233
234On 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}
e5bd0d98 237
576f8b11 238Please take into account that MFC sample binaries will be installed in the same folder as OCCT binaries during building of *INSTALL* project.
beb18c1f 239To run an MFC sample use *sample.bat* launcher. The command format is: <i>sample.bat *SampleName*</i> (e.g. <i>sample.bat ImportExport</i>).