dox/dev_guides/building/3rdparty/3rdparty_windows.md

   1  Building 3rd-party libraries on Windows {#occt_dev_guides__building_3rdparty_windows}
   2 ==============================================
   3 @tableofcontents
   4
   5 @section dev_guides__building_3rdparty_win_1 Introduction
   6
   7 This document presents guidelines for building third-party products used by Open CASCADE Technology (OCCT) and samples on Windows platform. It is assumed that you are already familiar with MS Visual Studio / Visual C++.
   8
   9 You need to use the same version of MS Visual Studio for building all third-party products and OCCT itself, in order to receive a consistent set of run-time binaries.
  10
  11 The links for downloading the third-party products are available on the web site of OPEN CASCADE SAS at https://www.opencascade.com/content/3rd-party-components.
  12
  13 There are two types of third-party products used  by OCCT:
  14
  15 * Mandatory  products:
  16         * Tcl/Tk 8.5 -- 8.6;
  17         * FreeType 2.4.10 -- 2.5.3.
  18 * Optional  products:
  19         * TBB 3.x -- 4.x;
  20         * FreeImage 3.14.1 -- 3.16.0;
  21         * VTK 6.1.0.
  22
  23 It is recommended to create a separate new folder on your workstation, where you will unpack the downloaded archives of the third-party  products, and where you will build these products (for example, *c:\\occ3rdparty*).
  24
  25 Further in this document, this folder is referred to as *3rdparty*.
  26
  27 @section dev_guides__building_3rdparty_win_2 Building Mandatory Third-party Products
  28
  29 @subsection dev_guides__building_3rdparty_win_2_1 Tcl/Tk
  30
  31 Tcl/Tk is required for DRAW test harness.
  32
  33 @subsubsection dev_guides__building_3rdparty_win_2_1_1 Installation from sources: Tcl
  34
  35 Download the necessary archive from https://www.tcl.tk/software/tcltk/download.html and unpack it.
  36
  37 1. In the *win* sub-directory, edit file *buildall.vc.bat*:
  38
  39    * Edit the line "call ... vcvars32.bat" to have correct path to the version of Visual Studio to be used for building, for instance:
  40
  41          call "%VS80COMNTOOLS%\vsvars32.bat"
  42
  43      If you are building 64-bit version, set environment accordingly, e.g.:
  44
  45          call "%VS80COMNTOOLS%\..\..\VC\vcvarsall.bat" amd64
  46
  47    * Define variable *INSTALLDIR* pointing to directory where Tcl/Tk will be installed, e.g.:
  48
  49          set INSTALLDIR=D:\OCCT\3rdparty\tcltk-86-32
  50
  51    * Add option *install* to the first command line calling *nmake*:
  52
  53          nmake -nologo -f makefile.vc release htmlhelp install %1
  54
  55    * Remove second call to *nmake* (building statically linked executable)
  56
  57 2. Edit file *rules.vc* replacing line
  58
  59        SUFX         = tsgx
  60
  61    by
  62
  63        SUFX         = sgx
  64
  65    This is to avoid extra prefix 't' in the library name, which is not recognized by default by OCCT build tools.
  66
  67
  68 3. By default, Tcl uses dynamic version of run-time library (MSVCRT), which must be installed on the system where Tcl will be used.
  69    You may wish to link Tcl library with static version of run-time to avoid this dependency.
  70    For that:
  71
  72    * Edit file *makefile.vc* replacing strings "crt = -MD" by "crt = -MT"
  73
  74    * Edit source file *tclMain.c* (located in folder *generic*) commenting out forward declaration of function *isatty()*.
  75
  76
  77 4. In the command prompt, run *buildall.vc.bat*
  78
  79    You might need to run this script twice to have *tclsh* executable installed; check subfolder *bin* of specified installation path to verify this.
  80
  81 5. For convenience of use, we recommend making a copy of *tclsh* executable created in subfolder *bin* of *INSTALLDIR* and named with Tcl version number suffix, as *tclsh.exe* (with no suffix)
  82
  83        > cd D:\OCCT\3rdparty\tcltk-86-32\bin
  84        > cp tclsh86.exe tclsh.exe
  85
  86 @subsubsection dev_guides__building_3rdparty_win_2_1_2 Installation from sources: Tk
  87
  88 Download the necessary archive from https://www.tcl.tk/software/tcltk/download.html and unpack it.
  89
  90 Apply the same steps as described for building Tcl above, with the same INSTALLDIR.
  91 Note that Tk produces its own executable, called *wish*.
  92
  93 You might need to edit default value of *TCLDIR* variable defined in *buildall.vc.bat* (should be not necessary if you unpack both Tcl and Tk sources in the same folder).
  94
  95 @subsection dev_guides__building_3rdparty_win_2_2 FreeType
  96
  97 FreeType is required for text display in a 3D viewer. You can download its sources from https://sourceforge.net/projects/freetype/files/
  98
  99 ### The building procedure
 100
 101 1. Unpack the downloaded archive of FreeType product into the *3rdparty*  folder. As a result, you will get a folder named, for example, *3rdparty\\freetype-2.4.10*.  Further in this document, this folder is referred to as *freetype*.
 102
 103 2. Open the solution file *freetype\\builds\\win32\\vc20xx\\freetype.sln*  in Visual Studio. Here *vc20xx* stands for your version of Visual Studio.
 104
 105 3. Select the configuration to build: either Debug or Release.
 106
 107 4. Build  the *freetype* project.
 108
 109    As a result, you will get a  freetype import library (.lib) in the *freetype\\obj\\win32\\vc20xx*  folder.
 110
 111
 112 5. If you build FreeType for a 64 bit platform, select in the main menu **Build - Configuration Manager**  and add *x64* platform to the solution configuration by copying the settings from Win32 platform:
 113
 114    @figure{/dev_guides/building/3rdparty/images/3rdparty_image001.png}
 115
 116    Update the value of the Output File for  x64 configuration:
 117
 118    @figure{/dev_guides/building/3rdparty/images/3rdparty_image003.png}
 119
 120    Build the *freetype* project.
 121
 122    As a result, you will obtain a 64 bit import library (.lib) file in the *freetype\\x64\\vc20xx*  folder.
 123
 124    To build FreeType as a dynamic library (.dll) follow steps 6, 7 and 8 of this procedure.
 125
 126 6. Open menu Project-> Properties-> Configuration  Properties-> General and change option **Configuration Type** to *Dynamic  Library (.dll)*.
 127 7. Edit file *freetype\\include\\freetype\\config\\ftoption.h*:
 128
 129    in line 255, uncomment the definition of macro *FT_EXPORT* and change it as follows:
 130
 131        #define FT_EXPORT(x)   __declspec(dllexport) x
 132
 133 8. Build  the *freetype* project.
 134
 135    As a result, you will obtain the files of the import  library (.lib) and the dynamic library (.dll)   in folders <i>freetype  \\objs\\release</i> or <i>\\objs\\debug </i>.
 136
 137    If you build for a 64 bit platform, follow step 5 of the procedure.
 138
 139    To facilitate the use of FreeType libraries in OCCT with minimal adjustment of build procedures, it is recommended to copy the include files and libraries of FreeType into a separate folder, named according to the pattern: *freetype-compiler-bitness-building mode*, where:
 140    * **compiler** is *vc8* or *vc9* or *vc10* or *vc11*;
 141    * **bitness**  is *32* or *64*;
 142    * **building mode** is *opt* (for Release) or *deb* (for Debug).
 143
 144    The *include* subfolder should be copied as is, while libraries should be renamed to *freetype.lib* and *freetype.dll* (suffixes removed) and placed to subdirectories *lib *and  *bin*, respectively. If the Debug configuration is built, the Debug libraries should be put into subdirectories *libd* and *bind*.
 145
 146 @section dev_guides__building_3rdparty_win_3 Building Optional Third-party Products
 147
 148 @subsection dev_guides__building_3rdparty_win_3_1 TBB
 149
 150 This third-party product is installed with binaries
 151 from the archive that can be downloaded from https://github.com/intel/tbb.
 152 Go to the **Download** page, find the  release version you need  (e.g. *tbb30_018oss*) and pick the archive for Windows  platform.
 153
 154 Unpack the downloaded  archive of TBB product into the *3rdparty* folder.
 155
 156 Further in this document,  this folder is referred to as *tbb*.
 157
 158 @subsection dev_guides__building_3rdparty_win_3_3 FreeImage
 159
 160 This third-party product should be built as a dynamically loadable library (.dll file).
 161 You can download its sources from
 162 https://sourceforge.net/projects/freeimage/files/Source%20Distribution/
 163
 164 ### The building procedure:
 165
 166 1. Unpack the  downloaded archive of FreeImage product into *3rdparty* folder.
 167
 168    As a result, you should have a folder named *3rdparty\\FreeImage*.
 169
 170    Rename it according to the rule: *freeimage-platform-compiler-building  mode*, where
 171
 172    * **platform**  is *win32* or *win64*;
 173    * **compiler**  is *vc8* or *vc9* or *vc10* or *vc11*;
 174    * **building  mode** is *opt* (for release) or *deb* (for debug)
 175
 176    Further in this  document, this folder is referred to as *freeimage*.
 177
 178 2. Open the solution file *freeimage\\FreeImage.*.sln* in your Visual Studio.
 179
 180    If you use a Visual Studio version higher than VC++ 2008, apply conversion of the workspace.
 181    Such conversion should be suggested automatically by Visual  Studio.
 182
 183 3. Select a  configuration to build.
 184
 185    - Choose **Release**  if you are building Release binaries.
 186    - Choose **Debug** if you are building  Debug binaries.
 187
 188    *Note:*
 189
 190    If you want to  build a debug version of FreeImage binaries then you need to rename the following files in FreeImage and FreeimagePlus projects:
 191
 192    Project -> Properties -> Configuration Properties -> Linker -> General -> Output File
 193
 194        FreeImage*d*.dll  to FreeImage.dll
 195        FreeImagePlus*d*.dll to FreeImagePlus.dll
 196
 197    Project -> Properties -> Configuration Properties -> Linker -> Debugging-> Generate Program Database File
 198
 199        FreeImage*d*.pdb  to FreeImage.pdb
 200        FreeImagePlus*d*.pdb to FreeImagePlus.pdb
 201
 202    Project -> Properties -> Configuration Properties -> Linker -> Advanced-Import Library
 203
 204        FreeImage*d*.lib  to FreeImage.lib
 205        FreeImagePlus*d*.lib  to FreeImagePlus.lib
 206
 207    Project -> Properties -> Configuration Properties -> Build Events -> Post -> Build Event -> Command Line
 208
 209        FreeImage*d*.dll     to FreeImage.dll
 210        FreeImage*d*.lib     to FreeImage.lib
 211        FreeImagePlus*d*.dll to FreeImagePlus.dll
 212        FreeImagePlus*d*.lib to FreeImagePlus.lib
 213
 214    Additionally, rename in project FreeImagePlus
 215
 216    Project -> Properties -> Configuration  Properties -> Linker -> Input -> Additional Dependencies
 217
 218        from FreeImage*d*.lib to FreeImage.lib
 219
 220 4. Select a platform to build.
 221
 222    - Choose *Win32* if you are building for a 32 bit platform.
 223    - Choose *x64* if you are building for a 64 bit platform.
 224
 225 5. Start the building process.
 226
 227    As a result, you should have the  library files of FreeImage product  in *freeimage\\Dist* folder (*FreeImage.dll* and *FreeImage.lib*) and in *freeimage\\Wrapper\\FreeImagePlus\\dist* folder (*FreeImagePlus.dll* and *FreeImagePlus.lib*).
 228
 229 @subsection dev_guides__building_3rdparty_win_3_4 VTK
 230
 231 VTK is an open-source, freely available software system for 3D computer graphics, image processing and visualization. VTK Integration Services component provides adaptation functionality for visualization of OCCT topological shapes by means of VTK library.
 232
 233 ### The building procedure:
 234
 235 1. Download the necessary archive from https://www.vtk.org/VTK/resources/software.html and unpack it into *3rdparty* folder.
 236
 237    As a result, you will get a folder named, for example, <i>3rdparty\VTK-6.1.0.</i>
 238
 239    Further in this document, this folder is referred to as *VTK*.
 240
 241 2. Use CMake to generate VS projects for building the library:
 242    - Start CMake-GUI and select VTK folder as source path, and the folder of your choice for VS project and intermediate build data.
 243    - Click **Configure**.
 244    - Select the VS version to be used from the ones you have installed (we recommend using VS 2010) and the architecture (32 or 64-bit).
 245    - Generate VS projects with default CMake options. The open solution *VTK.sln* will be generated in the build folder.
 246
 247 3. Build project VTK in Release mode.