dox/dev_guides/building/cmake/cmake.md

   1 Building with CMake {#occt_dev_guides__building_cmake}
   2 ===================
   3
   4 @tableofcontents
   5
   6 This file describes steps to build OCCT libraries from complete source package
   7 with CMake. CMake is free software that can create GNU Makefiles, KDevelop,
   8 XCode, and Visual Studio project files. Version 2.6 or above of CMake is
   9 required.
  10
  11 If you are building OCCT from bare sources (as in Git repository), or do some
  12 changes affecting CDL files, you need to use WOK to re-generate header files
  13 and build scripts / projects. See \ref occt_dev_guides__building_wok for instructions.
  14
  15 Before building OCCT, you need to install required third-party libraries; see
  16 instructions for your platform in @ref occt_dev_guides__building.
  17
  18 ## Decide on location of build and install directories.
  19
  20 The build directory is the one where intermediate files will be created (projects / makefiles, objects, binaries).
  21 The install directory is the one where binaries will be installed after build,
  22 along with header files and resources required for OCCT use in applications.
  23
  24 OCCT CMake scripts assume use of separate build and one install directories
  25 for each configuration (Debug or Release).
  26
  27 It is recommended to separate build and install directories from OCCT source directory, for example:
  28
  29        /user/home/occt/ - sources
  30        /user/home/tmp/occt-build-release - intermediate files (release)
  31        /user/home/occt-install-release - installed binaries (release)
  32
  33 ## CMake usage
  34
  35 Run CMake indicating path to OCCT sources ($CASROOT; in previous example
  36 CASROOT equal to /user/home/occt in lin case, and d:/occt in windows case)
  37 and selected build directory (in prev example build directory is
  38 /user/home/tmp/occt-build-release).
  39
  40 It is recommended to use GUI tools provided by CMake: cmake-gui on Windows
  41 and Mac, ccmake on Linux.
  42
  43 ### Windows:
  44
  45 @image html /dev_guides/building/cmake/images/cmake_image001.png
  46 @image latex /dev_guides/building/cmake/images/cmake_image001.png
  47
  48 * Specify "main" CMakelists.txt meta-project location by clicking Browse Source (e.g., $CASROOT)
  49 * Specify location (build folder) for Cmake generated project files by clicking Browse Build (e.g., d:/occt/build/win32-vc9-debug) (each cmake configuration of the project uses a specific build directory and a specific directory for installed files. It is recommended to compose names of the binary and install directory from system, bitness, compiler and build type.)
  50 * 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)
  51
  52 @image html /dev_guides/building/cmake/images/cmake_image002.png
  53 @image latex /dev_guides/building/cmake/images/cmake_image002.png
  54
  55 ### Linux:
  56
  57 In the console, change to the build directory and call ccmake with the path to the source directory of the project:
  58
  59        > cd ~/occt/build/debug
  60        > ccmake ~/occt
  61
  62 @image html /dev_guides/building/cmake/images/cmake_image003.png
  63 @image latex /dev_guides/building/cmake/images/cmake_image003.png
  64
  65 Press "c" to configure.
  66
  67 ### Mac OS:
  68
  69 Use cmake-gui (Applications -> CMake 2.8-10.app) to generate project files for the chosen build environment (e.g., XCode).
  70
  71 @image html /dev_guides/building/cmake/images/cmake_image004.png
  72 @image latex /dev_guides/building/cmake/images/cmake_image004.png
  73
  74 ## OCCT Configuration
  75
  76 The error message which appears at the end of configuration process, informs you about the required variables
  77 which need to be defined. This error will appear until all required variables are defined correctly.
  78 Note: In cmake-gui there is "grouped" option, which groups variables with a common prefix.
  79
  80 ### Selection of components to be built
  81
  82 The variables with "BUILD_" prefix allow specifying OCCT components and
  83 configuration to be built:
  84
  85 * BUILD_CONFIGURATION - defines configuration to be built (Release by default).
  86 * BUILD_<MODULE> - specify whether corresponding OCCT module should be
  87                    built (all toolkits). Note that even if 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_SAMPLES - specify whether OCCT MFC samples should be built.
  94
  95 Check variables with "USE_" prefix (USE_FREEIMAGE, USE_GL2PS, USE_TBB, and
  96 USE_OPENCL) if you want to enable use of the corresponding optional 3rd-party
  97 library.
  98
  99 ### 3rd-party configuration
 100
 101 ### 3rd-party configuration (The variables with 3RDPARTY_ prefix)
 102
 103 If you have 3rd-party libraries in a non-default location
 104 (e.g., on Windows, binaries downloaded from "http://www.opencascade.org/getocc/download/3rdparty/"),
 105 specify 3RDPARTY_DIR variable that points to the folders of 3rdparty products (some or all).
 106 At the next configuration 3rd-party product paths stored in 3RDPARTY_\<PRODUCT\>_DIR variable
 107 will be searched for in 3RDPARTY_DIR directory. If the structure of 3RDPARTY_DIR directory
 108 is the same as adopted in the OCCT, the directory will contain product dir, lib and header files.
 109
 110 Press "Configure" ("c" key for ccmake).
 111
 112 The result of the 3rdparty product search will be recorded in the corresponding variables:
 113
 114 * 3RDPARTY_\<PRODUCT\>_DIR - path to the product directory (with directory name) (e.g., D:/3rdparty/Tcl-8.5.12.0-32)
 115 * 3RDPARTY_\<PRODUCT\>_LIBRARY - path to the .lib libraries (with the library name) (e.g., D:/3rdparty/Tcl-8.5.12.0-32/lib/tcl85.lib). In non-windows case, this variable is the same as 3RDPARTY_\<PRODUCT\>_DLL.
 116 * 3RDPARTY_\<PRODUCT\>_INCLUDE - path to the include directory that contains the required header file (with "include" name) (e.g., D:/3rdparty/Tcl-8.5.12.0-32/include including tcl.h)
 117 * 3RDPARTY_\<PRODUCT\>_DLL - path to the .dll/.so/.dylib library  (with the library name) (e.g., D:/3rdparty/Tcl-8.5.12.0-32/bin/tcl85.dll)
 118
 119 The search process is as follows:
 120
 121 1. Common path: 3RDPARTY_DIR
 122 2. Path to particular 3rd-party library: 3RDPARTY_\<PRODUCT\>_DIR
 123 3. Paths to headers and binaries:
 124    1. 3RDPARTY_\<PRODUCT\>_INCLUDE
 125    2. 3RDPARTY_\<PRODUCT\>_LIBRARY
 126    3. 3RDPARTY_\<PRODUCT\>_DLL
 127
 128 If a variable of any level is not defined (empty or \<variable name\>-NOTFOUND)
 129 and the upper level variable is defined, the content of the non-defined variable
 130 will be searched for at the next configuration step. If search process in level 3
 131 does not find the required files, it searches in default places also.
 132
 133 **Note**: the names of searched libraries and header files are hardcoded.
 134 Freetype search process tries to find ft2build.h file in 3RDPARTY_FREETYPE INCLUDE dir
 135 and after that adds "3RDPARTY_FREETYPE_INCLUDE /freetype2" path to common includes if it exists.
 136
 137 Important: 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.
 139
 140 *Note*: CMake will produce an error after the configuration step until all required variables are defined correctly.
 141 If the search result (include path, or library path, or dll path) does not meet your expectations -
 142 you can  change 3RDPARTY_\<PRODUCT\>_DIR variable, clear (if they are not empty)
 143 3RDPARTY_\<PRODUCT\>_DLL, 3RDPARTY_\<PRODUCT\>_INCLUDE_DIR and 3RDPARTY_\<PRODUCT\>_LIBRARY variables
 144 (or clear one of them) and run the configuration process again.
 145
 146 At this time the search will be performed in the new identified directory
 147 and the result will be recorded to empty variables (non-empty variables will not be replaced).
 148
 149 For example, (Linux case) 3RDPARTY_FREETYPE_DIR variable
 150
 151     /PRODUCTS/maintenance/Mandriva2010/freetype-2.3.7
 152
 153 can be changed to
 154
 155     /PRODUCTS/maintenance/Mandriva2010/freetype-2.4.10
 156
 157 and the related variables: 3RDPARTY_FREETYPE_DLL, 3RDPARTY_FREETYPE_INCLUDE_DIR and  3RDPARTY_FREETYPE_LIBRARY will be cleared.
 158
 159 @image html /dev_guides/building/cmake/images/cmake_image005.png
 160 @image latex /dev_guides/building/cmake/images/cmake_image005.png
 161
 162 During configuration process the cleaned variables will be filled with new found values.
 163
 164 ###The variables with INSTALL_ prefix:
 165
 166 Define in INSTALL_DIR variable the path where will be placed built OCCT files (libraries, executables and headers).
 167 If INSTALL_\<PRODUCT\> variable is checked - 3rd-party products will be copied to the install directory.
 168
 169 #### At the end of the configuration process "configuring done" message will be shown and the generation process can be started.
 170
 171 ## OCCT Generation
 172
 173 This will create makefiles or project files for your build system.
 174
 175 ### Windows
 176
 177 Click Generate button and wait until the generation process is finished.
 178 Then the project files will appear in the build folder (e.g., d:/occt/build/win32-vc9-release).
 179
 180 ### Linux
 181
 182 When the configuration is complete, start the generation process by pressing "g".
 183
 184 @image html /dev_guides/building/cmake/images/cmake_image006.png
 185 @image latex /dev_guides/building/cmake/images/cmake_image006.png
 186
 187 ### Mac OS X
 188
 189 Click Generate button and wait until the generation process is finished.
 190 Then the project files will appear in the build folder (e.g., /Developer/occt/build/XCode).
 191
 192 ## OCCT Building
 193
 194 The install folder contains bin, inc, lib and res folders and a script to run DRAWEXE (draw.bat or draw.sh).
 195 "bin" contains executables, DLL (Windows) style shared libraries and pdb-files in OCCT debug version,.
 196 "lib" contains the import parts of DLL libraries.
 197 "inc" contains header files.
 198 "res" contains all required source files for OCCT.
 199
 200 ### Windows (Visual studio)
 201
 202 Go to the build folder, start the Visual Studio solution (OCCT.sln) and build it by clicking Build - Build Solution.
 203 When the building process finished, build the INSTALL project
 204 (by default the build solution process skips the building of the INSTALL project) to move the above files to INSTALL_DIR.
 205 For this in the solution explorer right click on the INSTALL project and select Project Only - Build Only INSTALL.
 206
 207 ### Linux (make)
 208 Change directory to binary dir and run make command
 209
 210        > make
 211
 212 To copy all libraries, executables and chosen 3rd-party libraries run "make" command with "install" argument
 213
 214        > make install
 215
 216 This command will move the above files to INSTALL_DIR.
 217
 218 ### Mac OS X (XCode)
 219
 220 Go to the build folder, start the XCode solution (OCCT.xcodeproj)
 221 and build it by clicking Build -> Build.
 222 Please notice that XCode may have worst responsibility to user actions
 223 due to sources processing at first start.
 224
 225 When the building process finished, build the INSTALL project
 226 (by default the build solution process skips the building of the INSTALL project)
 227 to move the above files to INSTALL_DIR.
 228 Notice that env.sh (configure PATH and DYLD_LIBRARY_PATH environment variables
 229 as well as Draw Harness extra variables) and draw.sh (to launch DRAWEXE) will be created in target directory.
 230
 231 ## OCCT project debugging for Visual Studio
 232 Run OCCT.bat from the build directory to start Visual Studio with required environment for debugging.