47f7df33b1dde4ec887ff5a0b74c3f6fccc3ed7b
[occt.git] / dox / dev_guides / building / 3rdparty / 3rdparty_windows.md
1 \feff 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 http://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         * gl2ps 1.3.5 -- 1.3.8;
21         * FreeImage 3.14.1 -- 3.16.0;
22         * VTK 6.1.0.
23
24 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*). 
25
26 Further in this document, this folder is referred to as *3rdparty*. 
27
28 @section dev_guides__building_3rdparty_win_2 Building Mandatory Third-party Products
29
30 @subsection dev_guides__building_3rdparty_win_2_1 Tcl/Tk
31
32 Tcl/Tk is required for DRAW test harness.
33
34 @subsubsection dev_guides__building_3rdparty_win_2_1_1 Installation from sources: Tcl
35   
36 Download the necessary archive from http://www.tcl.tk/software/tcltk/download.html and unpack it. 
37   
38 1. In the *win* sub-directory, edit file *buildall.vc.bat*:
39
40    * Edit the line "call ... vcvars32.bat" to have correct path to the version of Visual Studio to be used for building, for instance:
41
42          call "%VS80COMNTOOLS%\vsvars32.bat"
43
44      If you are building 64-bit version, set environment accordingly, e.g.:
45
46          call "%VS80COMNTOOLS%\..\..\VC\vcvarsall.bat" amd64
47      
48    * Define variable *INSTALLDIR* pointing to directory where Tcl/Tk will be installed, e.g.:
49
50          set INSTALLDIR=D:\OCCT\3rdparty\tcltk-86-32
51
52    * Add option *install* to the first command line calling *nmake*:
53
54          nmake -nologo -f makefile.vc release htmlhelp install %1
55
56    * Remove second call to *nmake* (building statically linked executable)
57
58 2. Edit file *rules.vc* replacing line 
59
60        SUFX         = tsgx
61
62    by
63
64        SUFX         = sgx
65
66    This is to avoid extra prefix 't' in the library name, which is not recognized by default by OCCT build tools.
67
68
69 3. By default, Tcl uses dynamic version of run-time library (MSVCRT), which must be installed on the system where Tcl will be used.
70    You may wish to link Tcl library with static version of run-time to avoid this dependency.
71    For that:
72
73    * Edit file *makefile.vc* replacing strings "crt = -MD" by "crt = -MT"
74
75    * Edit source file *tclMain.c* (located in folder *generic*) commenting out forward declaration of function *isatty()*.
76
77
78 4. In the command prompt, run *buildall.vc.bat*
79
80    You might need to run this script twice to have *tclsh* executable installed; check subfolder *bin* of specified installation path to verify this.
81
82 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)
83
84        > cd D:\OCCT\3rdparty\tcltk-86-32\bin
85        > cp tclsh86.exe tclsh.exe
86
87 @subsubsection dev_guides__building_3rdparty_win_2_1_2 Installation from sources: Tk
88   
89 Download the necessary archive from http://www.tcl.tk/software/tcltk/download.html and unpack it. 
90
91 Apply the same steps as described for building Tcl above, with the same INSTALLDIR.
92 Note that Tk produces its own executable, called *wish*. 
93
94 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).
95
96 @subsection dev_guides__building_3rdparty_win_2_2 FreeType
97
98 FreeType is required for text display in a 3D viewer. You can download its sources from http://sourceforge.net/projects/freetype/files/   
99
100 ### The building procedure
101
102 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*. 
103    
104 2. Open the solution file *freetype\\builds\\win32\\vc20xx\\freetype.sln*  in Visual Studio. Here *vc20xx* stands for your version of Visual Studio. 
105
106 3. Select the configuration to build: either Debug or Release. 
107
108 4. Build  the *freetype* project. 
109
110    As a result, you will get a  freetype import library (.lib) in the *freetype\\obj\\win32\\vc20xx*  folder.  
111
112
113 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: 
114
115    @figure{/dev_guides/building/3rdparty/images/3rdparty_image001.png}
116
117    Update the value of the Output File for  x64 configuration: 
118
119    @figure{/dev_guides/building/3rdparty/images/3rdparty_image003.png}
120
121    Build the *freetype* project. 
122
123    As a result, you will obtain a 64 bit import library (.lib) file in the *freetype\\x64\\vc20xx*  folder. 
124
125    To build FreeType as a dynamic library (.dll) follow steps 6, 7 and 8 of this procedure. 
126
127 6. Open menu Project-> Properties-> Configuration  Properties-> General and change option **Configuration Type** to *Dynamic  Library (.dll)*. 
128 7. Edit file *freetype\\include\\freetype\\config\\ftoption.h*:  
129   
130    in line 255, uncomment the definition of macro *FT_EXPORT* and change it as follows: 
131
132        #define FT_EXPORT(x)   __declspec(dllexport) x 
133
134 8. Build  the *freetype* project. 
135
136    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>. 
137    
138    If you build for a 64 bit platform, follow step 5 of the procedure. 
139
140    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: 
141    * **compiler** is *vc8* or *vc9* or *vc10* or *vc11*; 
142    * **bitness**  is *32* or *64*;
143    * **building mode** is *opt* (for Release) or *deb* (for Debug). 
144     
145    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*. 
146
147 @section dev_guides__building_3rdparty_win_3 Building Optional Third-party Products
148
149 @subsection dev_guides__building_3rdparty_win_3_1 TBB
150
151 This third-party product is installed with binaries 
152 from the archive that can be downloaded from http://threadingbuildingblocks.org/. 
153 Go to the **Download** page, find the  release version you need  (e.g. *tbb30_018oss*) and pick the archive for Windows  platform. 
154
155 Unpack the downloaded  archive of TBB product into the *3rdparty* folder. 
156
157 Further in this document,  this folder is referred to as *tbb*. 
158
159 @subsection dev_guides__building_3rdparty_win_3_2  gl2ps
160
161 This third-party product should be built as a dynamically loadable library (dll file). 
162 You can download its sources from  http://geuz.org/gl2ps/src/. 
163
164 ### The building procedure
165
166 1. Unpack the downloaded  archive of gl2ps product (e.g. *gl2ps-1.3.5.tgz*) into the *3rdparty*  folder. 
167
168    As a result, you will get a folder named, for example, *3rdparty\\gl2ps-1.3.5-source*. 
169
170    Rename it into <i>gl2ps-platform-compiler-building mode</i>, where 
171    * **platform** -- *win32*  or *win64*; 
172    * **compiler** -- *vc8*, *vc9* or *vc10*; 
173    * **building mode** -- *opt*  (for release) or *deb* (for debug). 
174    
175    For example, <i>gl2ps-win64-vc10-deb</i>
176
177    Further in this document,  this folder is referred to as *gl2ps*. 
178
179 2. Download (from http://www.cmake.org/cmake/resources/software.html) 
180    and install the *CMake* build system.  
181
182 3. Edit the file *gl2ps\\CMakeLists.txt*. 
183
184    After line 113 in *CMakeLists.txt*: 
185
186        set_target_properties(shared PROPERTIES  COMPILE_FLAGS \"-DGL2PSDLL -DGL2PSDLL_EXPORTS\")
187     
188    add the following line:   
189     
190        add_definitions(-D_USE_MATH_DEFINES)  
191
192    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. 
193
194 4. Launch CMake <i>(cmake-gui.exe)</i> using  the Program menu. 
195
196    In CMake: 
197   
198    * Define where the source code is. 
199      This path must point to *gl2ps*  folder. 
200
201    * Define where to build the  binaries. 
202      This path must point to the folder where generated gl2ps project binaries will be placed 
203      (for example, *gl2ps\\bin*). 
204      Further in this document, this folder is referred to as *gl2ps_bin*.
205
206    * Press  **Configure** button. 
207    
208      @figure{/dev_guides/building/3rdparty/images/3rdparty_image004.png}
209
210    * Select the generator (the compiler  and the target platform -- 32 or 64 bit) in the pop-up window. 
211    
212      @figure{/dev_guides/building/3rdparty/images/3rdparty_image005.png}
213
214    * Press **Finish** button to  return to the main CMake window. 
215      Expand the ENABLE group and uncheck  ENABLE_PNG and ENABLE_ZLIB check boxes. 
216          
217      @figure{/dev_guides/building/3rdparty/images/3rdparty_image006.png}
218
219    * 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*. 
220    
221      @figure{/dev_guides/building/3rdparty/images/3rdparty_image007.png}
222
223    * Press **Configure** button again, then press **Generate** button to generate Visual Studio projects. After completion, close CMake application. 
224
225 5. Open the solution file *gl2ps_bin\\gl2ps.sln* in Visual Studio. 
226
227    * Select a configuration to build 
228      * Choose **Release** to build Release binaries. 
229      * Choose **Debug** to build Debug binaries. 
230    * Select a platform to build. 
231      * Choose **Win32** to build for a 32 bit platform. 
232      * Choose **x64** to build for a 64 bit platform. 
233    * Build the solution. 
234    * Build the *INSTALL* project. 
235     
236 As a  result, you should have the installed gl2ps product in the *CMAKE_INSTALL_PREFIX* path. 
237
238 @subsection dev_guides__building_3rdparty_win_3_3 FreeImage
239
240 This third-party product should be built as a dynamically loadable library (.dll file). 
241 You can download its sources from 
242 http://sourceforge.net/projects/freeimage/files/Source%20Distribution/
243
244 ### The building procedure: 
245
246 1. Unpack the  downloaded archive of FreeImage product into *3rdparty* folder. 
247   
248    As a result, you should have a folder named *3rdparty\\FreeImage*. 
249   
250    Rename it according to the rule: *freeimage-platform-compiler-building  mode*, where 
251    
252    * **platform**  is *win32* or *win64*; 
253    * **compiler**  is *vc8* or *vc9* or *vc10* or *vc11*; 
254    * **building  mode** is *opt* (for release) or *deb* (for debug) 
255
256    Further in this  document, this folder is referred to as *freeimage*. 
257
258 2. Open the solution file *freeimage\\FreeImage.*.sln* in your Visual Studio. 
259   
260    If you use a Visual Studio version higher than VC++ 2008, apply conversion of the workspace. 
261    Such conversion should be suggested automatically by Visual  Studio. 
262     
263 3. Select a  configuration to build. 
264
265    - Choose **Release**  if you are building Release binaries. 
266    - Choose **Debug** if you are building  Debug binaries. 
267
268    *Note:* 
269
270    If you want to  build a debug version of FreeImage binaries then you need to rename the following files in FreeImage and FreeimagePlus projects:
271    
272    Project -> Properties -> Configuration Properties -> Linker -> General -> Output File
273
274        FreeImage*d*.dll  to FreeImage.dll 
275        FreeImagePlus*d*.dll to FreeImagePlus.dll 
276
277    Project -> Properties -> Configuration Properties -> Linker -> Debugging-> Generate Program Database File
278
279        FreeImage*d*.pdb  to FreeImage.pdb 
280        FreeImagePlus*d*.pdb to FreeImagePlus.pdb 
281
282    Project -> Properties -> Configuration Properties -> Linker -> Advanced-Import Library
283
284        FreeImage*d*.lib  to FreeImage.lib 
285        FreeImagePlus*d*.lib  to FreeImagePlus.lib 
286
287    Project -> Properties -> Configuration Properties -> Build Events -> Post -> Build Event -> Command Line 
288
289        FreeImage*d*.dll     to FreeImage.dll 
290        FreeImage*d*.lib     to FreeImage.lib 
291        FreeImagePlus*d*.dll to FreeImagePlus.dll 
292        FreeImagePlus*d*.lib to FreeImagePlus.lib 
293
294    Additionally, rename in project FreeImagePlus 
295    
296    Project -> Properties -> Configuration  Properties -> Linker -> Input -> Additional Dependencies 
297
298        from FreeImage*d*.lib to FreeImage.lib 
299
300 4. Select a platform to build. 
301
302    - Choose *Win32* if you are building for a 32 bit platform. 
303    - Choose *x64* if you are building for a 64 bit platform. 
304
305 5. Start the building process. 
306
307    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*).
308
309 @subsection dev_guides__building_3rdparty_win_3_4 VTK
310
311 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.
312
313 ### The building procedure:
314
315 1. Download the necessary archive from http://www.vtk.org/VTK/resources/software.html and unpack it into *3rdparty* folder.
316
317    As a result, you will get a folder named, for example, <i>3rdparty\VTK-6.1.0.</i>
318
319    Further in this document, this folder is referred to as *VTK*.
320
321 2. Use CMake to generate VS projects for building the library:
322    - Start CMake-GUI and select VTK folder as source path, and the folder of your choice for VS project and intermediate build data.
323    - Click **Configure**.
324    - 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).
325    - Generate VS projects with default CMake options. The open solution *VTK.sln* will be generated in the build folder.
326
327 3. Build project VTK in Release mode.