dox/dev_guides/building/cmake/cmake.md

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