0024916: Use custom-built Tcl instead of ActiveTcl distribution

[occt.git] / dox / dev_guides / building / 3rdparty / 3rdparty_windows.md

 Building 3rd-party libraries on Windows {#occt_dev_guides__building_3rdparty_windows}
==============================================
@tableofcontents

@section dev_guides__building_3rdparty_win_1 Introduction

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++. 

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. 

The links for downloading the third-party products are available on the web site of OPEN CASCADE SAS at http://www.opencascade.org/getocc/require/. There are two types of third-party products used  by OCCT: 

* Mandatory  products: 
	* Tcl/Tk 8.5 - 8.6;
	* FreeType 2.4.10 - 2.4.11.
* Optional  products:
	* TBB 3.x - 4.x;
	* gl2ps 1.3.5 - 1.3.8;
	* FreeImage 3.14.1 -3.15.4.

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*). 

Further in this document, this folder is referred to as *3rdparty*. 

@section dev_guides__building_3rdparty_win_2 Building Mandatory Third-party Products

@subsection dev_guides__building_3rdparty_win_2_1 Tcl/Tk

Tcl/Tk is required for DRAW test harness.

@subsubsection dev_guides__building_3rdparty_win_2_1_1 Installation from sources: Tcl
  
Download the necessary archive from http://www.tcl.tk/software/tcltk/download.html and unpack it. 
  
1. In the *win* sub-directory, edit file *buildall.vc.bat*:

   * Edit the line "call ... vcvars32.bat" to have correct path to the version of Visual Studio to be used for building, for instance:

         call "%VS80COMNTOOLS%\vsvars32.bat"

     If you are building 64-bit version, set environment accordingly, e.g.:

         call "%VS80COMNTOOLS%\..\..\VC\vcvarsall.bat" amd64
     
   * Define variable *INSTALLDIR* pointing to directory where Tcl/Tk will be installed, e.g.:

         set INSTALLDIR=D:\OCCT\3rdparty\tcltk-86-32

   * Add option *install* to the first command line calling *nmake*:

         nmake -nologo -f makefile.vc release htmlhelp install %1

   * Remove second call to *nmake* (building statically linked executable)

2. Edit file *rules.vc* replacing line 

       SUFX	    = tsgx

   by

       SUFX	    = sgx

   This is to avoid extra prefix 't' in the library name, which is not recognized by default by OCCT build tools.

3. In the command prompt, run *buildall.vc.bat*

   You might need to run this script twice to have *tclsh* executable installed; check subfolder *bin* of specified installation path to verify this.

4. 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)

       > cd D:\OCCT\3rdparty\tcltk-86-32\bin
       > cp tclsh86.exe tclsh.exe

@subsubsection dev_guides__building_3rdparty_win_2_1_2 Installation from sources: Tk
  
Download the necessary archive from http://www.tcl.tk/software/tcltk/download.html and unpack it. 

Apply the same steps as described for building Tcl above, with the same INSTALLDIR.
Note that Tk produces its own executable, called *wish*. 

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).

@subsection dev_guides__building_3rdparty_win_2_2 FreeType

FreeType is required for text display in a 3D viewer. You can download its sources from http://sourceforge.net/projects/freetype/files/   

### The building procedure

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*. 
   
2. Open the solution file *freetype\\builds\\win32\\vc20xx\\freetype.sln*  in Visual Studio. Here *vc20xx* stands for your version of Visual Studio. 

3. Select the configuration to build: either Debug or Release. 

4. Build  the *freetype* project. 

   As a result, you will get a  freetype import library (.lib) in the *freetype\\obj\\win32\\vc20xx*  folder.  


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: 

   @image html /dev_guides/building/3rdparty/images/3rdparty_image001.png 
   @image latex /dev_guides/building/3rdparty/images/3rdparty_image001.png 

   Update the value of the Output File for  x64 configuration: 

   @image html /dev_guides/building/3rdparty/images/3rdparty_image003.png 
   @image latex /dev_guides/building/3rdparty/images/3rdparty_image003.png 

   Build the *freetype* project. 

   As a result, you will obtain a 64 bit import library (.lib) file in the *freetype\\x64\\vc20xx*  folder. 

   To build FreeType as a dynamic library (.dll) follow steps 6, 7 and 8 of this procedure. 

6. Open menu Project-> Properties-> Configuration  Properties-> General and change option **Configuration Type** to *Dynamic  Library (.dll)*. 
7. Edit file *freetype\\include\\freetype\\config\\ftoption.h*:  
  
   in line 255, uncomment the definition of macro *FT_EXPORT* and change it as follows: 

       #define FT_EXPORT(x)   __declspec(dllexport) x 

8. Build  the *freetype* project. 

   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>. 
   
   If you build for a 64 bit platform, follow step 5 of the procedure. 

   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: 
   * **compiler** is *vc8* or *vc9* or *vc10* or *vc11*; 
   * **bitness**  is *32* or *64*;
   * **building mode** is *opt* (for Release) or *deb* (for Debug). 
    
   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*. 

@section dev_guides__building_3rdparty_win_3 Building Optional Third-party Products

@subsection dev_guides__building_3rdparty_win_3_1 TBB

This third-party product is installed with binaries 
from the archive that can be downloaded from http://threadingbuildingblocks.org/. 
Go to the **Download** page, find the  release version you need  (e.g. *tbb30_018oss*) and pick the archive for Windows  platform. 

Unpack the downloaded  archive of TBB product into the *3rdparty* folder. 

Further in this document,  this folder is referred to as *tbb*. 

@subsection dev_guides__building_3rdparty_win_3_2  gl2ps

This third-party product should be built as a dynamically loadable library (dll file). 
You can download its sources from  http://geuz.org/gl2ps/src/. 

### The building procedure

1. Unpack the downloaded  archive of gl2ps product (e.g. *gl2ps-1.3.5.tgz*) into the *3rdparty*  folder. 

   As a result, you will get a folder named, for example, *3rdparty\\gl2ps-1.3.5-source*. 

   Rename it into <i>gl2ps-platform-compiler-building mode</i>, where 
   * **platform** is *win32*  or *win64*; 
   * **compiler** is *vc8*, *vc9* or *vc10*; 
   * **building mode** - *opt*  (for release) or *deb* (for debug). 
   
   For example, <i>gl2ps-win64-vc10-deb</i>

   Further in this document,  this folder is referred to as *gl2ps*. 

2. Download (from http://www.cmake.org/cmake/resources/software.html) 
   and install the *CMake* build system.  

3. Edit the file *gl2ps\\CMakeLists.txt*. 

   After line 113 in *CMakeLists.txt*: 

       set_target_properties(shared PROPERTIES  COMPILE_FLAGS \"-DGL2PSDLL -DGL2PSDLL_EXPORTS\")
    
   add the following line:   
    
       add_definitions(-D_USE_MATH_DEFINES)  

   Attention: If Cygwin was installed on  your computer, make sure that there is no path to it in the *PATH* variable to avoid possible conflicts during the configuration. 

4. Launch CMake <i>(cmake-gui.exe)</i> using  the Program menu. 

   In CMake: 
  
   * Define where the source code is. 
     This path must point to *gl2ps*  folder. 

   * Define where to build the  binaries. 
     This path must point to the folder where generated gl2ps project binaries will be placed 
     (for example, *gl2ps\\bin*). 
     Further in this document, this folder is referred to as *gl2ps_bin*.

   * Press  **Configure** button. 
   
     @image html /dev_guides/building/3rdparty/images/3rdparty_image004.png 
     @image latex /dev_guides/building/3rdparty/images/3rdparty_image004.png 

   * Select the generator (the compiler  and the target platform - 32 or 64 bit) in the pop-up window. 
   
     @image html /dev_guides/building/3rdparty/images/3rdparty_image005.png 
     @image latex /dev_guides/building/3rdparty/images/3rdparty_image005.png 

   * Press **Finish** button to  return to the main CMake window. 
     Expand the ENABLE group and uncheck  ENABLE_PNG and ENABLE_ZLIB check boxes. 
	 
     @image html /dev_guides/building/3rdparty/images/3rdparty_image006.png 
     @image latex /dev_guides/building/3rdparty/images/3rdparty_image006.png 

   * Expand the CMAKE group and define *CMAKE_INSTALL_PREFIX* which is the path where you want to install the build results, for example, *c:\\occ3rdparty\\gl2ps-1.3.5*. 
   
     @image html /dev_guides/building/3rdparty/images/3rdparty_image007.png 
     @image latex /dev_guides/building/3rdparty/images/3rdparty_image007.png 

   * Press **Configure** button again, then press **Generate** button to generate Visual Studio projects. After completion, close CMake application. 

5. Open the solution file *gl2ps_bin\\gl2ps.sln* in Visual Studio. 

   * Select a configuration to build 
     * Choose **Release** to build Release binaries. 
     * Choose **Debug** to build Debug binaries. 
   * Select a platform to build. 
     * Choose **Win32** to build for a 32 bit platform. 
     * Choose **x64** to build for a 64 bit platform. 
   * Build the solution. 
   * Build the *INSTALL* project. 
    
As a  result, you should have the installed gl2ps product in the *CMAKE_INSTALL_PREFIX* path. 

@subsection dev_guides__building_3rdparty_win_3_3 FreeImage

This third-party product should be built as a dynamically loadable library (.dll file). 
You can download its sources from 
http://sourceforge.net/projects/freeimage/files/Source%20Distribution/

### The building procedure: 

1. Unpack the  downloaded archive of FreeImage product into *3rdparty* folder. 
  
   As a result, you should have a folder named *3rdparty\\FreeImage*. 
  
   Rename it according to the rule: *freeimage-platform-compiler-building  mode*, where 
   
   * **platform**  is *win32* or *win64*; 
   * **compiler**  is *vc8* or *vc9* or *vc10* or *vc11*; 
   * **building  mode** is *opt* (for release) or *deb* (for debug) 

   Further in this  document, this folder is referred to as *freeimage*. 

2. Open the solution file *freeimage\\FreeImage.*.sln* in your Visual Studio. 
  
   If you use a Visual Studio version higher than VC++ 2008, apply conversion of the workspace. 
   Such conversion should be suggested automatically by Visual  Studio. 
    
3. Select a  configuration to build. 

   - Choose **Release**  if you are building Release binaries. 
   - Choose **Debug** if you are building  Debug binaries. 

   *Note:* 

   If you want to  build a debug version of FreeImage binaries then you need to rename the following files in FreeImage and FreeimagePlus projects:
   
   Project -> Properties -> Configuration Properties -> Linker -> General -> Output File

       FreeImage*d*.dll  to FreeImage.dll 
       FreeImagePlus*d*.dll to FreeImagePlus.dll 

   Project -> Properties -> Configuration Properties -> Linker -> Debugging-> Generate Program Database File

       FreeImage*d*.pdb  to FreeImage.pdb 
       FreeImagePlus*d*.pdb to FreeImagePlus.pdb 

   Project -> Properties -> Configuration Properties -> Linker -> Advanced-Import Library

       FreeImage*d*.lib  to FreeImage.lib 
       FreeImagePlus*d*.lib  to FreeImagePlus.lib 

   Project -> Properties -> Configuration Properties -> Build Events -> Post -> Build Event -> Command Line 

       FreeImage*d*.dll     to FreeImage.dll 
       FreeImage*d*.lib     to FreeImage.lib 
       FreeImagePlus*d*.dll to FreeImagePlus.dll 
       FreeImagePlus*d*.lib to FreeImagePlus.lib 

   Additionally, rename in project FreeImagePlus 
   
   Project -> Properties -> Configuration  Properties -> Linker -> Input -> Additional Dependencies 

       from FreeImage*d*.lib to FreeImage.lib 

4. Select a platform to build. 

   - Choose *Win32* if you are building for a 32 bit platform. 
   - Choose *x64* if you are building for a 64 bit platform. 

5. Start the building process. 

   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*).

@subsection dev_guides__building_3rdparty_win_opencl OpenCL ICD Loader

If you have OpenCL SDK (one provided by Apple, AMD, NVIDIA, Intel, or other 
vendor) installed on your system, you should find OpenCL headers and
libraries required for building OCCT inside that SDK.

Alternatively, you can use OpenCL ICD (Installable Client Driver) Loader 
provided by Khronos group. The following describes steps used to build OpenCL 
ICD Loader version 1.2.11.0.

1. Download OpenCL ICD Loader sources archive and OpenCL header files from 
   Khronos OpenCL Registry
   http://www.khronos.org/registry/cl/

2. Unpack the archive and put headers in *inc/CL* sub-folder

3. Use CMake to generate VS projects for building the library:
   - Start CMake-GUI and select OpenCL ICD Loader folder as source path, and the folder of your choice for VS project and intermediate build data;
   - Click **Generate**;
   - 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).

4. Open solution *OPENCL_ICD_LOADER.sln* generated in the build folder.
   Though not strictly necessary, we recommend making two changes in the generated projects:
   - Add file *OpenCL.rc* to project OpenCL, to have version and Khronos copyright correctly embedded in DLL;
   - Change **Runtime library** to **Multi-threaded(/MT)** in the properties of OpenCL project, on **C/C++ / Code Generation** page for Release configuration, to avoid dependency on run-time DLL. 
  
5. Build project OpenCL in Release mode

6. Create the installation folder for OpenCL IDL Loader package and put there:
   - OpenCL header files in *include/CL* subfolder;
   - *OpenCL.dll* (generated in *bin/Release* subfolder of the source package) in *bin* subfolder;
   - *OpenCL.lib* (generated in *Release* subfolder of the build directory) in *lib* subfolder.