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