-Building with CMake {#dev_guides__building__cmake}
+Building with CMake {#occt_dev_guides__building_cmake}
===================
@tableofcontents
If you are building OCCT from bare sources (as in Git repository), or do some
changes affecting CDL files, you need to use WOK to re-generate header files
-and build scripts / projects. See \ref dev_guides__building__wok for instructions.
+and build scripts / projects. See \ref occt_dev_guides__building_wok for instructions.
-Before building OCCT, you need to install required third-party libraries; see paragraph 1 of
-\ref dev_guides__building for instructions.
+Before building OCCT, you need to install required third-party libraries; see
+instructions for your platform in @ref occt_dev_guides__building.
## Decide on location of build and install directories.
The build directory is the one where intermediate files will be created (projects / makefiles, objects, binaries).
-The install directory is the one where binaries will be installed after build, along with header files and resources required for OCCT use in applications.
+The install directory is the one where binaries will be installed after build,
+along with header files and resources required for OCCT use in applications.
-OCCT CMake scripts assume use of separate build and one install directories for each configuration (Debug or Release).
+OCCT CMake scripts assume use of separate build and one install directories
+for each configuration (Debug or Release).
It is recommended to separate build and install directories from OCCT source directory, for example:
## CMake usage
-Run CMake indicating path to OCCT sources ($CASROOT; in previous example CASROOT equal to /user/home/occt in lin case, and d:/occt in win case) and selected build directory (in prev example build directory is /user/home/tmp/occt-build-release).
+Run CMake indicating path to OCCT sources ($CASROOT; in previous example
+CASROOT equal to /user/home/occt in lin case, and d:/occt in windows case)
+and selected build directory (in prev example build directory is
+/user/home/tmp/occt-build-release).
-It is recommended to use GUI tools provided by CMake: cmake-gui on Windows and Mac, ccmake on Linux.
+It is recommended to use GUI tools provided by CMake: cmake-gui on Windows
+and Mac, ccmake on Linux.
### Windows:
which need to be defined. This error will appear until all required variables are defined correctly.
Note: In cmake-gui there is "grouped" option, which groups variables with a common prefix.
-###The variables with BUILD_ prefix:
+### Selection of components to be built
-* BUILD_TYPE - defines build configuration of the future project (Release by default)
-* BUILD_<MODULE> - allows including the toolkit set of the specified module to the future project or excluding it from the project.
-* BUILD_TOOLKITS - allows including additional specified toolkits (list of items separated by a space or a semicolon) to the common set of the future project.
+The variables with "BUILD_" prefix allow specifying OCCT components and
+configuration to be built:
-Check USE_\<PRODUCT\> variable (USE_FREEIMAGE, USE_GL2PS, USE_TBB and USE_OPENCL) if you want to use this 3rd-party product in the future project.
+* BUILD_CONFIGURATION - defines configuration to be built (Release by default).
+* BUILD_<MODULE> - specify whether corresponding OCCT module should be
+ built (all toolkits). Note that even if whole module is not
+ selected for build, its toolkits used by other toolkits
+ selected for build will be included automatically.
+* BUILD_TOOLKITS - allows including additional toolkits from non-selected
+ modules (should be list of toolkit names separated by a
+ space or a semicolon).
+* BUILD_SAMPLES - specify whether OCCT MFC samples should be built.
+
+Check variables with "USE_" prefix (USE_FREEIMAGE, USE_GL2PS, USE_TBB, and
+USE_OPENCL) if you want to enable use of the corresponding optional 3rd-party
+library.
### 3rd-party configuration
+### 3rd-party configuration (The variables with 3RDPARTY_ prefix)
+
If you have 3rd-party libraries in a non-default location
(e.g., on Windows, binaries downloaded from "http://www.opencascade.org/getocc/download/3rdparty/"),
specify 3RDPARTY_DIR variable that points to the folders of 3rdparty products (some or all).
At the next configuration 3rd-party product paths stored in 3RDPARTY_\<PRODUCT\>_DIR variable
will be searched for in 3RDPARTY_DIR directory. If the structure of 3RDPARTY_DIR directory
is the same as adopted in the OCCT, the directory will contain product dir, lib and header files.
-Press "Configure" ("c" key for ccmake)
-Important: The names of searched libraries and header files are hardcoded.
+
+Press "Configure" ("c" key for ccmake).
+
The result of the 3rdparty product search will be recorded in the corresponding variables:
* 3RDPARTY_\<PRODUCT\>_DIR - path to the product directory (with directory name) (e.g., D:/3rdparty/Tcl-8.5.12.0-32)
The search process is as follows:
-1 level:. 3RDPARTY_DIR
- 2 level: 3RDPARTY_\<PRODUCT\>_DIR\
- 3 level: 3RDPARTY_\<PRODUCT\>_LIBRARY
- 3 level: 3RDPARTY_\<PRODUCT\>_INCLUDE
- 3 level: 3RDPARTY_\<PRODUCT\>_DLL
+1. Common path: 3RDPARTY_DIR
+2. Path to particular 3rd-party library: 3RDPARTY_\<PRODUCT\>_DIR
+3. Paths to headers and binaries:
+ 1. 3RDPARTY_\<PRODUCT\>_INCLUDE
+ 2. 3RDPARTY_\<PRODUCT\>_LIBRARY
+ 3. 3RDPARTY_\<PRODUCT\>_DLL
If a variable of any level is not defined (empty or \<variable name\>-NOTFOUND)
and the upper level variable is defined, the content of the non-defined variable
will be searched for at the next configuration step. If search process in level 3
-doesn't find the required files, it searches in default places also.
+does not find the required files, it searches in default places also.
-*Note*: Freetype search process tries to find ft2build.h file in 3RDPARTY_FREETYPE INCLUDE dir
+**Note**: the names of searched libraries and header files are hardcoded.
+Freetype search process tries to find ft2build.h file in 3RDPARTY_FREETYPE INCLUDE dir
and after that adds "3RDPARTY_FREETYPE_INCLUDE /freetype2" path to common includes if it exists.
-Important: If BUILD_TYPE or BITNESS variable is changed - at the next configuration
+
+Important: If BUILD_CONFIGURATION variable is changed - at the next configuration
3RDPARTY_ variables will be replaced by the search process result, except for the 3RDPARTY_DIR variable.
*Note*: CMake will produce an error after the configuration step until all required variables are defined correctly.
you can change 3RDPARTY_\<PRODUCT\>_DIR variable, clear (if they are not empty)
3RDPARTY_\<PRODUCT\>_DLL, 3RDPARTY_\<PRODUCT\>_INCLUDE_DIR and 3RDPARTY_\<PRODUCT\>_LIBRARY variables
(or clear one of them) and run the configuration process again.
+
At this time the search will be performed in the new identified directory
and the result will be recorded to empty variables (non-empty variables will not be replaced).
For example, (Linux case) 3RDPARTY_FREETYPE_DIR variable
-/PRODUCTS/maintenance/Mandriva2010/freetype-2.3.7
+ /PRODUCTS/maintenance/Mandriva2010/freetype-2.3.7
can be changed to
-/PRODUCTS/maintenance/Mandriva2010/freetype-2.4.10
+ /PRODUCTS/maintenance/Mandriva2010/freetype-2.4.10
and the related variables: 3RDPARTY_FREETYPE_DLL, 3RDPARTY_FREETYPE_INCLUDE_DIR and 3RDPARTY_FREETYPE_LIBRARY will be cleared.
During configuration process the cleaned variables will be filled with new found values.
-### Install path configuration
+###The variables with INSTALL_ prefix:
-Define in INSTALL_DIR variable the path to the installed OCCT files (libraries, executables and headers).
+Define in INSTALL_DIR variable the path where will be placed built OCCT files (libraries, executables and headers).
If INSTALL_\<PRODUCT\> variable is checked - 3rd-party products will be copied to the install directory.
-At the end of the configuration process "configuring done" message will be shown and the generation process can be started.
+
+#### At the end of the configuration process "configuring done" message will be shown and the generation process can be started.
## OCCT Generation