0027828: Reference documentation of AIS_Trihedron contains invalid information about...
[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
72c37458 6@section build_cmake_intro General
e5bd0d98 7
8072aba1 8This article describes the **CMake**-based build process which is now suggested as a standard way to produce the binaries of Open CASCADE Technology from sources. *OCCT requires CMake version 2.8.12 or later*.
e5bd0d98 9
72c37458 10@note Comparing to the previous (6.x) releases of Open CASCADE Technology, OCCT 7.0 comes with a complete set of CMake scripts and projects, so that there is no need to use WOK anymore. Moreover, CMake gives you a powerful configuration tool which allows to control many aspects of OCCT deployment. At the same time this tool is quite intuitive which is a significant advantage over the legacy WOK utilities.
e5bd0d98 11
72c37458 12Here we describe the build procedure on example of Windows platform with Visual Studio 2010.
13However, CMake is cross-platform and can be used to build OCCT on Linux and OS X in essentially the same way.
e5bd0d98 14
72c37458 15@note Before you start, make sure to have installed all the 3-rd party products that you are going to use with OCCT; see @ref occt_dev_guides__building.
e5bd0d98 16
72c37458 17@section build_cmake_start Start CMake
e5bd0d98 18
72c37458 19CMake is a tool that generates the actual project files for the selected target build system (e.g. Unix makefiles) or IDE (e.g. Visual Studio 2010).
e5bd0d98 20
72c37458 21For unexpericnced users we recommend to start with *cmake-gui* -- cross-platform GUI tool provided by CMake on Windows, Mac and Linux.
22A command-line alternative, *ccmake* also can be used.
e5bd0d98 23
316d77d9 24CMake deals with three directories: source, build or binary and install.
e5bd0d98 25
316d77d9 26* The source directory is where the sources of OCCT are located in your filesystem
8da8f3d2 27* The build or binary directory is where all the files created during CMake configuration and generation process will be located. The mentioned process will be described below.
8072aba1 28* The installation directory is where binaries will be installed after building the *INSTALL* project that is created by CMake generation process, along with header files and resources required for OCCT use in applications.
576f8b11 29
72c37458 30The good practice is not to use the source directory as a build one.
31Different configurations should be built in different build directories to avoid conflicts.
32It is however possible to choose one installation directory for several configurations of OCCT (differentiated by platform, bitness, compiler and build type), for example:
316d77d9 33
3f812249 34 d:/occt/ -- the source directory
35 d:/tmp/occt-build-vc10-x64 -- the build directory with the generated
36 solution and other intermediate files created during a CMake tool working
37 d:/occt-install -- the installation directory that is
8072aba1 38 able to contain several OCCT configurations
32856b63 39
72c37458 40@section build_cmake_conf Configuration process
e5bd0d98 41
8da8f3d2 42If the command-line tool is used, run the tool from the build directory with a single argument indicating the source (relative or absolute path) directory:
e5bd0d98 43
8da8f3d2 44 cd d:/tmp/occt-build-vc10-x64
45 ccmake d:/occt
e5bd0d98 46
316d77d9 47@figure{/dev_guides/building/cmake/images/cmake_image000.png}
e5bd0d98 48
576f8b11 49Press *c* to configure.
e5bd0d98 50
316d77d9 51All required actions in the configuration process will be described with using the GUI tool below.
576f8b11 52
316d77d9 53If the gui-tool is used, run the tool without additional arguments and after that specify the source directory by clicking **Browse Source** and the build (binary) one by clicking **Browse Build**.
adc33035 54
316d77d9 55@figure{/dev_guides/building/cmake/images/cmake_image001.png}
576f8b11 56
316d77d9 57**Note**: Each 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 and compiler (e.g., <i>d:/occt/build/win32-vc10</i> ).
576f8b11 58
316d77d9 59Once the source and build directories are selected, "Configure" button should be pressed in order to start manual configuration process. It begins with selection of a target configurator. It is "Visual Studio 10 2010 Win64" in our example.
ad211ad3 60
316d77d9 61@figure{/dev_guides/building/cmake/images/cmake_image002.png}
ad211ad3 62
742cc8b0 63To build OCCT with using Universal Windows Platform (UWP) specify path to toolchain file for cross-compiling <i>d:/occt/adm/templates/uwp.toolchain.config.cmake</i>.
64
65**Note**: Universal Windows Platform (UWP) is supported only on "Visual Studio 14 2015". File <i>d:/occt/samples/xaml/ReadMe.md</i> desribes building procedure of XAML (UWP) sample.
66
8072aba1 67Once "Finish" button is pressed, the first pass of the configuration process is executed. At the end of the process, CMake outputs the list of environment variables which have to be properly specified for successful configuration.
316d77d9 68
8da8f3d2 69@figure{/dev_guides/building/cmake/images/cmake_image003.png}
70
316d77d9 71The error message provides an information about these variables. This message will appear after each pass of the process until all required variables are specified correctly.
72
8072aba1 73The change of the state of some variables can lead to the appearance of new variables. The new variables appeared after the pass of the configuration process is notified with red color by CMake GUI tool.
316d77d9 74
75Note: There is "grouped" option which groups variables with a common prefix.
76
77The following table enumerates the full list of environment variables used at configuration stage:
78
79| Variable | Type | Purpose |
80|----------|------|---------|
81| CMAKE_BUILD_TYPE | String | Specifies the build type on single-configuration generators (sush as make). Possible values are Debug, Release and RelWithDebInfo |
82| USE_FREEIMAGE | Boolean flag | Indicates whether Freeimage product should be used in OCCT visualization module for support of popular graphics image formats (PNG, BMP etc) |
83| USE_GL2PS | Boolean flag | Indicates whether GL2PS product should be used in OCCT visualization module for support of vector image formats (PS, EPS etc) |
3f812249 84| USE_TBB | Boolean flag | Indicates whether TBB 3rd party is used or not. TBB stands for Threading Building Blocks, the technology of Intel Corp, which comes with different mechanisms and patterns for injecting parallelism into your application. OCCT remains parallel even without TBB product |
85| USE_VTK | Boolean flag | Indicates whether VTK 3rd party is used or not. VTK stands for Visualization ToolKit, the technology of Kitware Inc intended for general-purpose scientific visualization. OCCT comes with a bridge between CAD data representation and VTK by means of its dedicated VIS component (VTK Integration Services). You may skip this 3rd party unless you are planning to use VTK visualization for OCCT geometry. The official documentation @ref occt_user_guides__vis for the details on VIS |
86| 3RDPARTY_DIR | Path | Defines the root directory where all required 3rd party products will be searched. Once you define this path it is very convenient to click "Configure" button in order to let CMake automatically detect all necessary products|
316d77d9 87| 3RDPARTY_FREETYPE_* | Path | Path to Freetype binaries |
88| 3RDPARTY_TCL_* 3RDPARTY_TK_* | Path | Path to Tcl/Tk binaries |
89| 3RDPARTY_FREEIMAGE* | Path | Path to Freeimage binaries |
90| 3RDPARTY_GL2PS_* | Path | Path to GL2PS binaries |
91| 3RDPARTY_TBB* | Path | Path to TBB binaries |
92| 3RDPARTY_VTK_* | Path | Path to VTK binaries |
4ff92abe 93| BUILD_MODULE_<MODULE>| Boolean flag | Indicates whether the corresponding OCCT module should be built or not. It should be noted that some toolkits of a module can be built even if this module is not checked (this happens if some other modules depend on these toolkits). The main modules and their descriptions can be found in @ref user_guides |
316d77d9 94| BUILD_LIBRARY_TYPE | String | Specifies the type of library to be created. "Shared" libraries are linked dynamically and loaded at runtime. "Static" libraries are archives of object files for use when linking other targets |
95| BUILD_ADDITIONAL_TOOLKITS | String | Semicolon-separated individual toolkits to include into build process. If you want to build some particular libraries (toolkits) only, then you may uncheck all modules in the corresponding *BUILD_MODUE_\<MODULE\>* options and provide the list of necessary libraries here. Of course, all dependencies will be resolved automatically |
109aa56e 96| BUILD_YACCLEX | Boolean flag | Enables Flex/Bison lexical analyzers. OCCT source files relating to STEP reader and ExprIntrp functionality are generated automatically with Flex/Bison. Checking this options leads to automatic search of Flex/Bison binaries and regeneration of the mentioned files |
4b3541c6 97| BUILD_MODULE_MfcSamples | Boolean flag | Indicates whether MFC samples should be built together with OCCT. This option is only relevant to Windows platforms |
98| BUILD_DOC_Overview | Boolean flag | Indicates whether OCCT overview documentation project should be created together with OCCT. It is not built together with OCCT. Checking this options leads to automatic search of Doxygen binaries. Building of it will be call Doxygen command to generate the documentation in HTML format |
109aa56e 99| BUILD_PATCH | Path | Points to the directory recognized as a "patch" for OCCT. If specified, the files from this directory take precedence over the corresponding native OCCT sources. This way you are able to introduce patches to Open CASCADE Technology not affecting the original source distribution |
f1d057b7 100| BUILD_WITH_DEBUG | Boolean flag | Enables extended messages of many OCCT algorithms, usually printed to cout. These include messages on internal errors and special cases encountered, timing etc |
316d77d9 101| CMAKE_CONFIGURATION_TYPES | String | Semicolon-separated CMake configurations |
4b3541c6 102| INSTALL_DIR | Path | Points to the installation directory. INSTALL_DIR is synonym of CMAKE_INSTALL_PREFIX . User can specify both INSTALL_DIR or CMAKE_INSTALL_PREFIX |
103| INSTALL_DIR_BIN | Path | Relative path to the binaries installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_BIN}) |
104| INSTALL_DIR_SCRIPT | Path | Relative path to the scripts installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_SCRIPT}) |
105| INSTALL_DIR_LIB | Path | Relative path to the libraries installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_LIB}) |
106| INSTALL_DIR_INCLUDE | Path | Relative path to the includes installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_INCLUDE}) |
107| INSTALL_DIR_RESOURCE | Path | Relative path to the resources installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_RESOURCE}) |
17d16f78 108| INSTALL_DIR_LAYOUT | String | Defines structure of OCCT files (binaries, resources, headers, etc) for the install directory. Two variants are predefined: for Windows (standard OCCT layout) and for Unix operating systems (standard Linux layout). If needed, layout can be customized with INSTALL_DIR_* variables |
4b3541c6 109| INSTALL_DIR_DATA | Path | Relative path to the data files installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_DATA}) |
110| INSTALL_DIR_SAMPLES | Path | Relative path to the samples installation directory. Note that only "samples/tcl" folder will be installed. (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_SAMPLES}) |
111| INSTALL_DIR_TESTS | Path | Relative path to the tests installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_TESTS}) |
112| INSTALL_DIR_DOC | Path | Relative path to the documentation installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_DOC}) |
316d77d9 113| INSTALL_FREETYPE | Boolean flag | Indicates whether Freetype binaries should be installed into the installation directory |
114| INSTALL_FREEIMAGE* | Boolean flag | Indicates whether Freeimage binaries should be installed into the installation directory |
115| INSTALL_GL2PS | Boolean flag | Indicates whether GL2PS binaries should be installed into the installation directory |
116| INSTALL_TBB | Boolean flag | Indicates whether TBB binaries should be installed into the installation directory |
117| INSTALL_VTK | Boolean flag | Indicates whether VTK binaries should be installed into the installation directory |
118| INSTALL_TCL | Boolean flag | Indicates whether TCL binaries should be installed into the installation directory |
0e617b05 119| INSTALL_TEST_CASES | Boolean flag | Indicates whether non-regression OCCT test scripts should be installed into the installation directory |
4b3541c6 120| INSTALL_DOC_Overview | Boolean flag | Indicates whether OCCT overview documentation should be installed into the installation directory |
316d77d9 121
122**Note:** In those CMake options defining paths only the forward slashes ("/") are acceptable.
123
72c37458 124@section build_cmake_3rdparty 3rd party search mechanism
316d77d9 125
72c37458 126If *3RDPARTY_DIR* directory is defined, then required 3rd party binaries are sought in it, and default system folders are ignored.
316d77d9 127
3f812249 128The procedure expects to find binary and header files of each 3rd party product in its own sub-directory: *bin*, *lib* and *include*.
316d77d9 129
8072aba1 130The results of the search (achived on the next pass of the configuration process) are recorded in the corresponding variables:
e5bd0d98 131
3f812249 132* *3RDPARTY_\<PRODUCT\>_DIR* -- path to the 3rdparty directory (with directory name) (e.g. <i>D:/3rdparty/tcltk-86-32</i>)
133* *3RDPARTY_\<PRODUCT\>_LIBRARY_DIR* -- path to the directory containing a library (e.g. <i>D:/3rdparty/tcltk-86-32/lib</i>).
134* *3RDPARTY_\<PRODUCT\>_INCLUDE_DIR* -- path to the directory containing a header file (e.g., <i>D:/3rdparty/tcltk-86-32/include</i>)
135* *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 only relevant to Windows platforms.
9f33b387 136
8072aba1 137Note: each library and include directory should be children of the product directory if the last one is defined.
e5bd0d98 138
139The search process is as follows:
140
576f8b11 1411. Common path: *3RDPARTY_DIR*
1422. Path to a particular 3rd-party library: *3RDPARTY_\<PRODUCT\>_DIR*
5c573e69 1433. Paths to headers and binaries:
9f33b387 144 1. *3RDPARTY_\<PRODUCT\>_INCLUDE_DIR*
145 2. *3RDPARTY_\<PRODUCT\>_LIBRARY_DIR*
146 3. *3RDPARTY_\<PRODUCT\>_DLL_DIR*
e5bd0d98 147
8072aba1 148If a variable of any level is not defined (empty or <i> \<variable name\>-NOTFOUND </i>) and the upper level variable is defined, the content of the non-defined variable will be sought at the next configuration step. If the search process at level 3 does not find the required files, it seeks in default places.
e5bd0d98 149
316d77d9 150If a search result (include path, or library path, or dll path) does not meet your expectations, you can change *3RDPARTY_\<PRODUCT\>_*_DIR variable*, clear (if they are not empty) *3RDPARTY_\<PRODUCT\>_DLL_DIR, 3RDPARTY_\<PRODUCT\>_INCLUDE_DIR* and 3RDPARTY_\<PRODUCT\>_LIBRARY_DIR variables (or clear one of them) and run the configuration process again.
5c573e69 151
576f8b11 152At this time the search will be performed in the newly identified directory
9f33b387 153and the result will be recorded to corresponding variables (replace old value if it is necessary).
e5bd0d98 154
8da8f3d2 155For example, *3RDPARTY_FREETYPE_DIR* variable
e5bd0d98 156
8da8f3d2 157 d:/3rdparty/freetype-2.4.10
e5bd0d98 158
159can be changed to
160
8da8f3d2 161 d:/3rdparty/freetype-2.5.3
e5bd0d98 162
8072aba1 163During the configuration process the related variables (*3RDPARTY_FREETYPE_DLL_DIR*, *3RDPARTY_FREETYPE_INCLUDE_DIR* and *3RDPARTY_FREETYPE_LIBRARY_DIR*) will be filled with new found values.
e5bd0d98 164
316d77d9 165**Note**: The names of searched libraries and header files are hard-coded. If there is the need to change their names, change 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 166
72c37458 167@section build_cmake_gen Projects generation
e5bd0d98 168
8072aba1 169Once the configuration process is done, the "Generate" button is used to prepare project files for the target IDE. In our exercise the Visual Studio solution will be automatically created in the buid directory.
234e52be 170
72c37458 171@section build_cmake_build Building
e5bd0d98 172
576f8b11 173Go to the build folder, start the Visual Studio solution *OCCT.sln* and build it by clicking **Build -> Build Solution**.
174
8da8f3d2 175@figure{/dev_guides/building/cmake/images/cmake_image004.png}
176
316d77d9 177By default the build solution process skips the building of the INSTALL and Overview project.
e5bd0d98 178
316d77d9 179When the building process is finished build:
4b3541c6 180* Overview project to generate OCCT overview documentation (if BUILD_DOC_Overview variable is checked)
8da8f3d2 181* the *INSTALL* project to run **the installation process**
e5bd0d98 182
316d77d9 183For this, right-click on the *Overview/INSTALL* project and select **Project Only -> Build Only** -> *Overview/INSTALL* in the solution explorer.
e5bd0d98 184
72c37458 185@section build_cmake_install Installation
e5bd0d98 186
8072aba1 187Installation is a process of extracting redistributable resources (binaries, include files etc) from the build directory into the installation one. The installation directory will be free of project files, intermediate object files and any other information related to the build routines.
e5bd0d98 188
316d77d9 189Normally you use the installation directory of OCCT to link against your specific application.
576f8b11 190
8072aba1 191The directory structure is as follows:
316d77d9 192
3f812249 193 data -- data files for OCCT (brep, iges, stp)
194 doc -- OCCT overview documentation in HTML format
195 inc -- header files
196 samples -- samples
197 src -- all required source files for OCCT
198 tests -- OCCT test suite
199 win32\vc10\bind -- binary files (installed 3rdparties and occt)
200 \libd -- libraries (installed 3rdparties and occt)
576f8b11 201
316d77d9 202**Note:** The above example is given for debug configuration. However, it is generally safe to use the same installation directory for the release build. In the latter case the contents of install directory will be enriched with subdirectories and files related to the release configuration. In particular, the binaries directory win64 will be expanded as
203follows:
576f8b11 204
316d77d9 205 \win32\vc10\bind
206 \libd
207 \bin
208 \lib
576f8b11 209
8072aba1 210If CMake installation flags are enabled for the 3rd party products (e.g. INSTALL_FREETYPE), then the corresponding binaries will be copied to the same bin(d) and lib(d) directories together with the native binaries of OCCT. Such organization of libraries can be especially helpful if your OCCT-based software does not use itself the 3rd parties of Open CASCADE Technology (thus, there is no sense to pack them into dedicated directories).
e5bd0d98 211
8072aba1 212The installation folder contains the scripts to run *DRAWEXE* (*draw.bat* or *draw.sh*), samples (if they were installed) and overview.html (short-cut for installed OCCT overview documentation).