0026993: Configuration, CMake - use the abstraction level of VTK instead CSF_VTK...
[occt.git] / dox / dev_guides / building / cmake / cmake.md
ba06f8bb 1Building with CMake {#occt_dev_guides__building_cmake}
e5bd0d98 2===================
316d77d9 6This article describes **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 3.0 or later*.
e5bd0d98 7
316d77d9 8**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 9
316d77d9 10**Note**: We discuss the build procedure on example of Windows platform. However, the workflow is almost the same for *nix and Mac operating systems.
e5bd0d98 11
316d77d9 12All the examples in the article will be based on Windows x64 platform and Visual Studio 2010 solution will be the target IDE. The solution will be generated by CMake from the OCCT sources, the one will be built by an user and ready-to-go OCCT binaries will be deployed into a user specified directory by building *INSTALL* project.
e5bd0d98 13
8da8f3d2 14You can get all the required 3-rd party products visiting [the official download page](http://www.opencascade.org/getocc/download/loadocc); see @ref occt_dev_guides__building for more detailed information also.
e5bd0d98 15
316d77d9 16## Get sources
e5bd0d98 17
8da8f3d2 18The sources of OCCT can be obtained from [the official development web-site](http://dev.opencascade.org) by either downloading the universal source package (available at [the official download page](http://www.opencascade.org/getocc/download/loadocc)) or by cloning the Git repository:
e5bd0d98 19
316d77d9 20 git clone ssh://gitolite@git.dev.opencascade.org/occt occt
e5bd0d98 21
8da8f3d2 22As a result, you obtain the following directory structure in your filesystem (d:\ name is used for example):
316d77d9 23
8da8f3d2 24 d:\occt\adm
25 \data
26 \dox
27 \samples
28 \src
29 \tests
30 ...
e5bd0d98 31
8da8f3d2 32The bare sources distribution contains not only the sources of Open CASCADE Technology, but also documentation, samples and non-regression test scripts.
e5bd0d98 33
316d77d9 34## The usage of CMake
e5bd0d98 35
316d77d9 36Now it is time to run a CMake tool which will generate the actual project files for the target IDE (e.g., Visual Studio 2010 solution).
e5bd0d98 37
316d77d9 38It is recommended to use *cmake-gui* - cross-platform GUI tool provided by CMake on Windows, Mac and Linux. As a command-line alternative, *ccmake* also can be used.
e5bd0d98 39
316d77d9 40CMake deals with three directories: source, build or binary and install.
e5bd0d98 41
316d77d9 42* The source directory is where the sources of OCCT are located in your filesystem
8da8f3d2 43* 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.
316d77d9 44* The installation directory is where binaries will be installed after build the *INSTALL* project that is created by CMake generation process, along with header files and resources required for OCCT use in applications.
576f8b11 45
316d77d9 46**Note**: It is possible to choose one installation directory for several configurations of OCCT (differentiated by platform, bitness, compiler and build type).
32856b63 47
8da8f3d2 48**Note**: The good practice is not to mix up different build configurations in a single directory and not to use the source directory as a build one, for example:
316d77d9 49
8da8f3d2 50 d:/occt/ - the source directory
51 d:/tmp/occt-build-vc10-x64 - the build directory with the generated
52 solution and other intermediate files created during a CMake tool working
53 d:/occt-install - the installation directory that is
54 able to contain several OCCT configuratoion
32856b63 55
316d77d9 56## Configuration process
e5bd0d98 57
8da8f3d2 58If 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 59
8da8f3d2 60 cd d:/tmp/occt-build-vc10-x64
61 ccmake d:/occt
e5bd0d98 62
316d77d9 63@figure{/dev_guides/building/cmake/images/cmake_image000.png}
e5bd0d98 64
576f8b11 65Press *c* to configure.
e5bd0d98 66
316d77d9 67All required actions in the configuration process will be described with using the GUI tool below.
576f8b11 68
316d77d9 69If 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 70
316d77d9 71@figure{/dev_guides/building/cmake/images/cmake_image001.png}
576f8b11 72
316d77d9 73**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 74
316d77d9 75Once 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 76
316d77d9 77@figure{/dev_guides/building/cmake/images/cmake_image002.png}
ad211ad3 78
316d77d9 79Once "Finish" button is pressed, the first pass 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.
8da8f3d2 81@figure{/dev_guides/building/cmake/images/cmake_image003.png}
316d77d9 83The 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.
85The change of the state of some variables can lead to a new variable appearance. The new variables appeared after the pass of the configuration process is notified with red color by CMake GUI tool.
87Note: There is "grouped" option which groups variables with a common prefix.
89The following table enumerates the full list of environment variables used at configuration stage:
91| Variable | Type | Purpose |
93| CMAKE_BUILD_TYPE | String | Specifies the build type on single-configuration generators (sush as make). Possible values are Debug, Release and RelWithDebInfo |
94| 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) |
95| USE_GL2PS | Boolean flag | Indicates whether GL2PS product should be used in OCCT visualization module for support of vector image formats (PS, EPS etc) |
96| USE_TBB | Boolean flag | Indicates whether TBB 3-rd 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 |
8da8f3d2 97| USE_VTK | Boolean flag | Indicates whether VTK 3-rd 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 3-rd 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 |
316d77d9 98| 3RDPARTY_DIR | Path | Defines the root directory where all required 3-rd 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|
99| 3RDPARTY_FREETYPE_* | Path | Path to Freetype binaries |
100| 3RDPARTY_TCL_* 3RDPARTY_TK_* | Path | Path to Tcl/Tk binaries |
101| 3RDPARTY_FREEIMAGE* | Path | Path to Freeimage binaries |
102| 3RDPARTY_GL2PS_* | Path | Path to GL2PS binaries |
103| 3RDPARTY_TBB* | Path | Path to TBB binaries |
104| 3RDPARTY_VTK_* | Path | Path to VTK binaries |
4ff92abe 105| 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 106| 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 |
107| 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 |
108| REBUILD_PLATFORM_DEPENDENT_CODE | 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 |
109| BUILD_MODULE_OcctMfcSamples | Boolean flag | Indicates whether MFC samples should be built together with OCCT. This option is only relevant to Windows platforms |
110| BUILD_DOC_OcctOverview | 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 |
111| APPLY_OCCT_PATH_DIR | Boolean flag | 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 |
112| CMAKE_CONFIGURATION_TYPES | String | Semicolon-separated CMake configurations |
113| INSTALL_DIR | Path | Points to the installation directory |
114| INSTALL_FREETYPE | Boolean flag | Indicates whether Freetype binaries should be installed into the installation directory |
115| INSTALL_FREEIMAGE* | Boolean flag | Indicates whether Freeimage binaries should be installed into the installation directory |
116| INSTALL_GL2PS | Boolean flag | Indicates whether GL2PS binaries should be installed into the installation directory |
117| INSTALL_TBB | Boolean flag | Indicates whether TBB binaries should be installed into the installation directory |
118| INSTALL_VTK | Boolean flag | Indicates whether VTK binaries should be installed into the installation directory |
119| INSTALL_TCL | Boolean flag | Indicates whether TCL binaries should be installed into the installation directory |
0e617b05 120| INSTALL_TEST_CASES | Boolean flag | Indicates whether non-regression OCCT test scripts should be installed into the installation directory |
121| INSTALL_SAMPLES | Boolean flag | Indicates whether OCCT samples should be installed into the installation directory |
316d77d9 122| INSTALL_DOC_OcctOverview | Boolean flag | Indicates whether OCCT overview documentation should be installed into the installation directory |
124**Note:** In those CMake options defining paths only the forward slashes ("/") are acceptable.
126### 3rd-party search mechanism (The variables with <i>3RDPARTY_</i> prefix)
128If *3RDPARTY_DIR* directory is defined, required 3rd-party binaries are sought in it, default system folders are ignored.
130The procedure expects to find binary and header files of each 3rd-party product in its own sub-directory: *bin*, *lib* and *include*.
132The result of the search (achived on the next pass of the configuration process) are recorded in the corresponding variables:
e5bd0d98 133
9f33b387 134* *3RDPARTY_\<PRODUCT\>_DIR* - path to the 3rdparty directory (with directory name) (e.g. <i>D:/3rdparty/tcltk-86-32</i>)
135* *3RDPARTY_\<PRODUCT\>_LIBRARY_DIR* - path to directory containing a library (e.g. <i>D:/3rdparty/tcltk-86-32/lib</i>).
136* *3RDPARTY_\<PRODUCT\>_INCLUDE_DIR* - path to the directory containing a header file (e.g., <i>D:/3rdparty/tcltk-86-32/include</i>)
316d77d9 137* *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 138
adc33035 139Note: each library and include directory should be the children of product directory if the last one is defined.
e5bd0d98 140
141The search process is as follows:
576f8b11 1431. Common path: *3RDPARTY_DIR*
1442. Path to a particular 3rd-party library: *3RDPARTY_\<PRODUCT\>_DIR*
5c573e69 1453. Paths to headers and binaries:
9f33b387 146 1. *3RDPARTY_\<PRODUCT\>_INCLUDE_DIR*
e5bd0d98 149
316d77d9 150If 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 search process at level 3 does not find the required files, it seeks in default places.
e5bd0d98 151
316d77d9 152If 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 153
576f8b11 154At this time the search will be performed in the newly identified directory
9f33b387 155and the result will be recorded to corresponding variables (replace old value if it is necessary).
e5bd0d98 156
8da8f3d2 157For example, *3RDPARTY_FREETYPE_DIR* variable
e5bd0d98 158
8da8f3d2 159 d:/3rdparty/freetype-2.4.10
e5bd0d98 160
161can be changed to
8da8f3d2 163 d:/3rdparty/freetype-2.5.3
e5bd0d98 164
316d77d9 165During 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 166
316d77d9 167**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 168
316d77d9 169### OCCT Generation
e5bd0d98 170
316d77d9 171Once the configuration process is done, "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 172
316d77d9 173### OCCT Building
e5bd0d98 174
576f8b11 175Go to the build folder, start the Visual Studio solution *OCCT.sln* and build it by clicking **Build -> Build Solution**.
8da8f3d2 177@figure{/dev_guides/building/cmake/images/cmake_image004.png}
316d77d9 179By default the build solution process skips the building of the INSTALL and Overview project.
e5bd0d98 180
316d77d9 181When the building process is finished build:
182* Overview project to generate OCCT overview documentation (if BUILD_DOC_OcctOverview variable is checked)
8da8f3d2 183* the *INSTALL* project to run **the installation process**
e5bd0d98 184
316d77d9 185For this, right-click on the *Overview/INSTALL* project and select **Project Only -> Build Only** -> *Overview/INSTALL* in the solution explorer.
e5bd0d98 186
316d77d9 187## Installation process
e5bd0d98 188
316d77d9 189Installation 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 190
316d77d9 191Normally you use the installation directory of OCCT to link against your specific application.
576f8b11 192
316d77d9 193the directory structure is follow:
195 data - data files for OCCT (brep, iges, stp)
196 doc - OCCT overview documentation in HTML format
197 inc - header files
198 samples - samples
199 src - all required source files for OCCT
200 tests - OCCT test suite
201 win32\vc10\bind - binary files (installed 3rdparties and occt)
202 \libd - libraries (installed 3rdparties and occt)
576f8b11 203
316d77d9 204**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
576f8b11 206
316d77d9 207 \win32\vc10\bind
208 \libd
209 \bin
210 \lib
576f8b11 211
316d77d9 212If CMake installation flags are enabled for the 3-rd 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 3-rd parties of Open CASCADE Technology (thus, there is no sense to pack them into dedicated directories)
e5bd0d98 213
316d77d9 214The installation folder contains the scripts to run *DRAWEXE* (*draw.bat* or *draw.sh*), samples (if its were installed) and overview.html (short-cut for installed OCCT overview documentation).