0022859: Developers guide with code samples
[occt.git] / dox / dev_guides / building / cmake / cmake.md
ba06f8bb 1Building with CMake {#occt_dev_guides__building_cmake}
e5bd0d98 2===================
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.
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
576f8b11 20The build directory is where intermediate files (projects / makefiles, objects, binaries) will be created. Each built configuration should have its own build directory.
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:
32856b63 27 /user/home/occt/ - sources
28 /user/home/tmp/occt-build-vc10-x64-release - intermediate files
29 /user/home/occt-install - installed binaries
e5bd0d98 30
31## CMake usage
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:
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
576f8b11 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-debug</i> ).
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
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
55 > cd ~/occt/build/debug
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:
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
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.
77### Selection of the components to be built
e5bd0d98 78
576f8b11 79The variables with <i>BUILD_</i> prefix allow specifying OCCT components and
5c573e69 80configuration to be built:
234e52be 81
576f8b11 82* *BUILD_CONFIGURATION* - defines configuration to be built (Release by default).
83* <i>BUILD_<MODULE></i> - specifies whether the corresponding OCCT module should be
84 built (all toolkits). Note that even if the whole module is not
32856b63 85 selected for build, its toolkits used by other toolkits
86 selected for build will be included automatically.
576f8b11 87* *BUILD_TOOLKITS* - allows including additional toolkits from non-selected
32856b63 88 modules (should be list of toolkit names separated by a
89 space or a semicolon).
576f8b11 90* *BUILD_SAMPLES* - specifies whether OCCT MFC samples should be built.
91* *BUILD_PATCH_DIR* - optionally specifies additional folder containing patched OCCT source files.
32856b63 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.
576f8b11 93 The projects generated by CMake will use files found in the patch folder instead of the corresponding files of OCCT.
e5bd0d98 94
576f8b11 95Check variables with <i>USE_</i> prefix (<i>USE_FREEIMAGE, USE_GL2PS, USE_TBB,</i> and
96<i>USE_OPENCL</i>) if you want to enable use of the corresponding optional 3rd-party
5c573e69 97library.
576f8b11 99### 3rd-party configuration (The variables with <i>3RDPARTY_</i> prefix)
e5bd0d98 100
101If you have 3rd-party libraries in a non-default location
576f8b11 102(e.g., on Windows, binaries downloaded from http://www.opencascade.org/getocc/download/3rdparty/")
9f33b387 103*3RDPARTY_DIR* variable should be specified with the path to the folders where required 3rd-party libraries will be sought
576f8b11 104
9f33b387 105The 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 106
9f33b387 107The procedure expects to find binary and header files of each 3rd-party library in its own sub-directory: *bin*, *lib* and *include*.
ad211ad3 108
576f8b11 109Press **Configure** (**c** key for ccmake).
ad211ad3 110
9f33b387 111The result of the search are recorded in the corresponding variables:
e5bd0d98 112
9f33b387 113* *3RDPARTY_\<PRODUCT\>_DIR* - path to the 3rdparty directory (with directory name) (e.g. <i>D:/3rdparty/tcltk-86-32</i>)
114* *3RDPARTY_\<PRODUCT\>_LIBRARY_DIR* - path to directory containing a library (e.g. <i>D:/3rdparty/tcltk-86-32/lib</i>).
115* *3RDPARTY_\<PRODUCT\>_INCLUDE_DIR* - path to the directory containing a header file (e.g., <i>D:/3rdparty/tcltk-86-32/include</i>)
116* *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
119Note: a libraries and include directories should be the children of product directory if the last one is defined.
e5bd0d98 120
121The search process is as follows:
576f8b11 1231. Common path: *3RDPARTY_DIR*
1242. Path to a particular 3rd-party library: *3RDPARTY_\<PRODUCT\>_DIR*
5c573e69 1253. Paths to headers and binaries:
9f33b387 126 1. *3RDPARTY_\<PRODUCT\>_INCLUDE_DIR*
e5bd0d98 129
576f8b11 130If a variable of any level is not defined (empty or <i> \<variable name\>-NOTFOUND </i>)
e5bd0d98 131and the upper level variable is defined, the content of the non-defined variable
9f33b387 132will 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 133
576f8b11 134Important: If *BUILD_CONFIGURATION* variable is changed, at the next configuration
135*3RDPARTY_ variables* will be replaced by the search process result, except for the *3RDPARTY_DIR* variable.
e5bd0d98 136
9f33b387 137**Note** : CMake will produce an error after the configuration step until all required variables are defined correctly.
576f8b11 138If the search result (include path, or library path, or dll path) does not meet your expectations,
9f33b387 139you can change *3RDPARTY_\<PRODUCT\>_*_DIR variable*, clear (if they are not empty)
e5bd0d98 141(or clear one of them) and run the configuration process again.
5c573e69 142
576f8b11 143At this time the search will be performed in the newly identified directory
9f33b387 144and the result will be recorded to corresponding variables (replace old value if it is necessary).
e5bd0d98 145
576f8b11 146For example, (Linux case) *3RDPARTY_FREETYPE_DIR* variable
e5bd0d98 147
9f33b387 148 /PRODUCTS/maintenance/Mandriva2010/freetype-2.4.10
e5bd0d98 149
150can be changed to
9f33b387 152 /PRODUCTS/maintenance/Mandriva2010/freetype-2.5.3
e5bd0d98 153
9f33b387 154During 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 155
9f33b387 156**Note**: The names of searched libraries and header files are hard-coded. If there is the need to change their names,
157change 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 158
234e52be 159###The variables with INSTALL_ prefix:
e5bd0d98 160
9f33b387 161Define *INSTALL_DIR* variable as the path will be contain the built OCCT files (libraries, executables and headers)
576f8b11 162If <i>INSTALL_\<PRODUCT\></i> variable is checked, 3rd-party products will be copied to the install directory.
234e52be 163
576f8b11 164At the end of the configuration process "configuring done" message will be shown and the generation process can be started.
e5bd0d98 165
166## OCCT Generation
576f8b11 168This procedure will create makefiles or project files for your build system.
e5bd0d98 169
170### Windows
576f8b11 172Click **Generate** button and wait until the generation process is finished.
173Then the project files will appear in the build folder (e.g. <i> d:/occt/build/win32-vc9-release </i>).
e5bd0d98 174
175### Linux
9f33b387 177Click **Generate** button (if you use cmake-gui) or press **g** (for ccmake) to start the generation process.
e5bd0d98 178
179### Mac OS X
576f8b11 181Click **Generate** button and wait until the generation process is finished.
182Then the project files will appear in the build folder (e.g. <i> /Developer/occt/build/XCode </i>).
e5bd0d98 183
184## OCCT Building
9f33b387 186The 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:
187* **data** - data files for OCCT (brep, iges, stp)
188* **inc** - header files
189* **samples** - tcl sample files
190* **src** - all required source files for OCCT
191* **tests** - OCCT test suite
beb18c1f 192* **win32/vc10/bind**> - example relative directory tree of binary files (3rdparty and occt)
193* **win32/vc9/lib**> - example relative directory tree of libraries (3rdparty and occt)
e5bd0d98 194
195### Windows (Visual studio)
576f8b11 197Go to the build folder, start the Visual Studio solution *OCCT.sln* and build it by clicking **Build -> Build Solution**.
199When 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*.
201For this, right-click on the *INSTALL* project and select **Project Only -> Build Only** -> *INSTALL* in the solution explorer.
e5bd0d98 202
203### Linux (make)
576f8b11 204
205Change directory to the directory with binaries and run *make* command
e5bd0d98 206
207 > make
576f8b11 209To copy all libraries, executables and chosen 3rd-party libraries run *make* command with *install* argument
e5bd0d98 210
211 > make install
576f8b11 213This command will move the above files to *INSTALL_DIR*.
e5bd0d98 214
215### Mac OS X (XCode)
576f8b11 217Go to the build folder, start XCode solution *OCCT.xcodeproj* and build it by clicking **Build -> Build**.
218Please notice that XCode may lag because it processes sources at the first start.
220When 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*.
221Notice that *env.sh* (which configures *PATH* and *DYLD_LIBRARY_PATH* environment variables
222as well as Draw Harness extra variables) and *draw.sh* (to launch *DRAWEXE* ) will be created in the target directory.
224### MFC samples
226On Windows you can also build binaries of MFC samples together with OCCT. For this, activate **BUILD_Samples** check-box in CMake configuration dialog.
e5bd0d98 229
576f8b11 230Please take into account that MFC sample binaries will be installed in the same folder as OCCT binaries during building of *INSTALL* project.
beb18c1f 231To run an MFC sample use *sample.bat* launcher. The command format is: <i>sample.bat *SampleName*</i> (e.g. <i>sample.bat ImportExport</i>).