6a68c2ac356ecb15cdcde45ab9d7b84f7406d186
[occt.git] / dox / dev_guides / building / 3rdparty / 3rdparty_windows.md
1 \feff Building 3rd-party libraries on Windows {#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 
8 used by Open CASCADE Technology (OCCT) and samples on Windows platform. 
9
10 This guide assumfamiliar with MS Visual Studio / Visual C++. 
11
12 You need to use the same version of MS Visual Studio for building 
13 all third-party products and OCCT itself, in order to receive a consistent set of run-time binaries. 
14
15 The links for downloading the third-party products are available on the web site 
16 of OPEN CASCADE SAS at http://www.opencascade.org/getocc/require/. 
17 There are two types of third-party products which are used  by OCCT: 
18
19 * Mandatory  products: Tcl/Tk 8.5 - 8.6 and  FreeType 2.4.10 - 2.4.11
20 * Optional  products: TBB 3.x - 4.x, gl2ps 1.3.5 - 1.3.8, FreeImage 3.14.1 -3.15.4
21
22 It is recommended to create a separate new folder on your workstation where 
23 you will unpack the downloaded archives of the third-party  products, 
24 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.We recommend installing a binary distribution that could 
33 be downloaded from http://www.activestate.com/activetcl.
34
35 Go to \"Free Downloads\" and pick the version of the Install Wizard 
36 that matches your target platform – 32 bit (x86) or 64 bit (x64). 
37 The version of Visual Studio you use is irrelevant when choosing the Install Wizard. 
38
39 Run the Install Wizard you  downloaded, and install Tcl/Tk products 
40
41 * to 3rdparty\\tcltk-win32 folder (for 32-bit platform) or 
42 * to 3rdparty\\tcltk-win64 folder (for 64-bit platform). 
43
44 Further in this document,  this folder is referred to as *tcltk*. 
45
46 @subsection dev_guides__building_3rdparty_win_2_2 FreeType
47
48 FreeType is required for display of text in 3D viewer. 
49 You can download its sources from http://sourceforge.net/projects/freetype/files/   
50
51 The building process is the following:
52
53 1. Unpack the  downloaded archive of FreeType product into the *3rdparty*  folder. 
54
55    As a result, you should have a folder named for example, *3rdparty\\freetype-2.4.10*.  Further in this document, this folder is referred to as *freetype*. 
56
57 2. Open the  solution file *freetype\\builds\\win32\\vc20xx\\freetype.sln*  in Visual Studio, where vc20xx stands for the version of Visual Studio you are  using. 
58 3. Select a  configuration to build: either Debug or Release. 
59 4. Build  the *freetype* project. 
60
61    As a result, you will get a  freetype import library (.lib) in the *freetype\\obj\\win32\\vc20xx*  folder. 
62
63 5. If you are  building for 64 bit platform, start the Configuration Manager (Build - Configuration Manager), 
64    and add *x64* platform to the solution configuration by copying the  settings from Win32 platform: 
65
66    @image html /dev_guides/building/3rdparty/images/3rdparty_image001.png 
67    @image latex /dev_guides/building/3rdparty/images/3rdparty_image001.png 
68
69    Update the value of the Output File for  x64 configuration: 
70
71    @image html /dev_guides/building/3rdparty/images/3rdparty_image003.png 
72    @image latex /dev_guides/building/3rdparty/images/3rdparty_image003.png 
73
74    Build the *freetype* project. 
75
76    As a result, you should obtain a 64  bit import library (.lib) file in the *freetype\\x64\\vc20xx*  folder. 
77
78    If you want to build freetype as a dynamic library (.dll) follow items 6, 7 and 8 of this list. 
79
80 6. Open Project-Properties-Configuration  Properties-General and change option 'Configuration Type' to \"*Dynamic  Library (.dll)*\". 
81 7. Edit file *freetype\\include\\freetype\\config\\ftoption.h*:  
82   
83    in line 255, uncomment the definition of macro FT_EXPORT and change it as follows: 
84
85        #define FT_EXPORT(x)   __declspec(dllexport) x 
86
87 8. Build  the *freetype* project. 
88
89    As a result, you should obtain import  library (.lib) and dynamic library (.dll) 
90    files in *freetype  \\objs\\release or \\objs\\debug folders.* 
91    If you are building for a 64 bit  platform, follow item 5 of this list. 
92
93    In order to facilitate use of the  FreeType libraries in OCCT with minimal adjustment of its build procedures, 
94    it is recommended to copy the include files and libraries of FreeType to a separate folder, named according to the pattern: 
95    *freetype-compiler-bitness-building  mode*  
96    where 
97     
98    * compiler  is vc8 or vc9 or vc10 or vc11; 
99    * bitness  is 32 or 64; 
100    * building  mode is opt (for Release) or deb (for Debug) 
101     
102    The include subfolder should be copied as is, while libraries should be renamed to 
103    *freetype.lib* and *freetype.dll* (suffixes removed) and placed to subdirectories 
104    *lib *and  *bin*, respectively. If Debug configuration is built, 
105    the Debug libraries should be put in subdirectories *libd* and *bind*. 
106
107 @section dev_guides__building_3rdparty_win_3 Building Optional Third-party Products
108
109 @subsection dev_guides__building_3rdparty_win_3_1 TBB
110
111 This third-party product is  installed with binaries 
112 from the archive that can be downloaded from http://threadingbuildingblocks.org/. 
113 Go to \"Downloads page\", find the  release version you need  (e.g. tbb30_018oss) and pick the archive for Windows  platform. 
114 Unpack the downloaded  archive of TBB product into the *3rdparty* folder. 
115 Further in this document,  this folder is referred to as *tbb*. 
116
117 @subsection dev_guides__building_3rdparty_win_3_2  gl2ps
118
119 This third-party product should be built as a dynamically loadable library (dll file). 
120 You can download its sources from  http://geuz.org/gl2ps/src/ 
121
122 The building process is the following: 
123
124 1. Unpack the downloaded  archive of gl2ps product (e.g. *gl2ps-1.3.5.tgz*) into the *3rdparty*  folder. 
125
126    As a result, you should  have a folder named for example, *3rdparty\\gl2ps-1.3.5-source*. 
127
128    Rename it according to the  rule: gl2ps-platform-compiler-building mode, where 
129
130    * platform is win32  or win64; 
131    * compiler is vc8 or  vc9 or vc10; 
132    * building mode - opt  (for release) or deb (for debug) 
133
134    Further in this document,  this folder is referred to as *gl2ps*. 
135
136 2. Download (from http://www.cmake.org/cmake/resources/software.html) 
137    and install the *CMake* build system.  
138
139 3. Edit the file *gl2ps\\CMakeLists.txt*. 
140
141    After line 113 in CMakeLists.txt: 
142
143        set_target_properties(shared PROPERTIES  COMPILE_FLAGS \"-DGL2PSDLL -DGL2PSDLL_EXPORTS\")
144     
145    add the following line:   
146     
147        add_definitions(-D_USE_MATH_DEFINES)  
148
149    Attention: If cygwin was installed on  your computer make sure that there is no path 
150    to the latter in the PATH variable in order to avoid possible conflicts during  the configuration. 
151
152 4. Launch CMake (cmake-gui.exe) using  the Program menu. 
153
154    In CMake: 
155   
156    * Define where the source code is. 
157      This path must point to *gl2ps*  folder. 
158
159    * Define where to build the  binaries. 
160      This path must point to the folder where generated gl2ps project binaries will be placed 
161      (for example, *gl2ps\\bin*). 
162      Further in this document, this folder is referred to as *gl2ps_bin*.
163
164    * Press the \"Configure\" button. 
165      @image html /dev_guides/building/3rdparty/images/3rdparty_image004.png 
166      @image latex /dev_guides/building/3rdparty/images/3rdparty_image004.png 
167
168    * Select the generator (the compiler  and the target platform - 32 or 64 bit) in the pop-up window. 
169      @image html /dev_guides/building/3rdparty/images/3rdparty_image005.png 
170      @image latex /dev_guides/building/3rdparty/images/3rdparty_image005.png 
171
172    * Then press the \"Finish\" button to  return to the main CMake window. 
173      Expand the ENABLE group and uncheck  ENABLE_PNG and ENABLE_ZLIB check boxes. 
174      @image html /dev_guides/building/3rdparty/images/3rdparty_image006.png 
175      @image latex /dev_guides/building/3rdparty/images/3rdparty_image006.png 
176
177    * Expand the CMAKE group and define CMAKE_INSTALL_PREFIX 
178      (path where you want to install the build results, for example, *c:\\occ3rdparty\\gl2ps-1.3.5*). 
179      @image html /dev_guides/building/3rdparty/images/3rdparty_image007.png 
180      @image latex /dev_guides/building/3rdparty/images/3rdparty_image007.png 
181
182    * Press the  \"Configure\" button again, and then the \"Generate\" button in order to generate 
183        Visual Studio projects. After completion, close CMake application. 
184
185 5. Open the solution file *gl2ps_bin\\gl2ps.sln* in Visual Studio. 
186
187    * Select a  configuration to build 
188      * Choose \"*Release*\" if you are building Release binaries. 
189      * Choose \"*Debug*\" if you are building Debug binaries. 
190    * Select  a platform to build. 
191      * Choose \"*Win32*\" if you are building for a 32 bit  platform. 
192      * Choose \"*x64*\" if you are building for a 64 bit  platform. 
193    * Build the solution. 
194    * Build the *INSTALL* project. 
195     
196 As a  result, you should have the installed gl2ps product in the *CMAKE_INSTALL_PREFIX*  path. 
197
198 @subsection dev_guides__building_3rdparty_win_3_3 FreeImage
199
200 This third-party product should be built as a dynamically loadable library (.dll file). 
201 You can download its sources from 
202 http://sourceforge.net/projects/freeimage/files/Source%20Distribution/
203
204 The building process is the following: 
205
206 1. Unpack the  downloaded archive of FreeImage product into *3rdparty* folder. 
207   
208    As a result,  you should have a folder named *3rdparty\\FreeImage*. 
209   
210    Rename it  according to the rule: freeimage-platform-compiler-building  mode, where 
211    
212    * platform  is win32 or win64; 
213    * compiler  is vc8 or vc9 or vc10 or vc11; 
214    * building  mode is opt (for release) or deb (for debug) 
215
216    Further in this  document, this folder is referred to as *freeimage*. 
217
218 2. Open the  solution file *freeimage\\FreeImage.*.sln* in Visual Studio  that corresponds to the version of Visual Studio you use. 
219   
220    Since the  version of Visual Studio you use is higher than VC++ 2008, apply conversion of the workspace. 
221    Such conversion should be suggested automatically by Visual  Studio. 
222     
223 3. Select a  configuration to build. 
224
225    - Choose \" *Release* \"  if you are building Release binaries. 
226    - Choose \" *Debug* \" if you are building  Debug binaries. 
227
228    *Note:* 
229
230    If you want to  build a debug version of FreeImage binaries then you must rename 
231    the following  files for projects FreeImage and FreeimagePlus:
232
233    Project-Properties-Configuration Properties-Linker-General-Output File
234
235        from FreeImage*d*.dll  to FreeImage.dll 
236        from  FreeImagePlus*d*.dll to FreeImagePlus.dll 
237
238    Project-Properties-Configuration Properties-Linker-Debugging-Generate Program Database File
239
240        from FreeImage*d*.pdb  to FreeImage.pdb 
241        from  FreeImagePlus*d*.pdb to FreeImagePlus.pdb 
242
243    Project-Properties-Configuration Properties-Linker-Advanced-Import Library
244
245        from FreeImage*d*.lib  to FreeImage.lib 
246        from FreeImagePlus*d*.lib  to FreeImagePlus.lib 
247
248    Project-Properties-Configuration Properties-Build Events-Post-Build Event-Comand Line 
249
250        from FreeImage*d*.dll     to FreeImage.dll 
251        from FreeImage*d*.lib     to FreeImage.lib 
252        from FreeImagePlus*d*.dll to FreeImagePlus.dll 
253        from FreeImagePlus*d*.lib to FreeImagePlus.lib 
254
255    Additionally, for project FreeImagePlus rename: 
256    Project-Properties-Configuration  Properties-Linker-Input-Additional Dependencies 
257
258        from FreeImage*d*.lib to FreeImage.lib 
259
260 4. Select a platform to build. 
261
262    - Choose \" *Win32* \" if you are building for a 32 bit platform. 
263    - Choose \" *x64* \" if you are building for a 64 bit platform. 
264
265 5. Start the building process. 
266
267    As a result, you should have the  library files of FreeImage product in the 
268    *freeimage\\Dist* folder (FreeImage.dll and FreeImage.lib files) and in the 
269    *freeimage\\Wrapper\\FreeImagePlus\\dist* folder (FreeImagePlus.dll and 
270    FreeImagePlus.lib files).
271
272 @subsection dev_guides__building_3rdparty_win_opencl OpenCL ICD Loader
273
274 If you have OpenCL SDK (one provided by Apple, AMD, NVIDIA, Intel, or other 
275 vendor) installed on your system, you should find OpenCL headers and
276 libraries required for building OCCT inside that SDK.
277
278 Alternatively, you can use OpenCL ICD (Installable Client Driver) Loader 
279 provided by Khronos group. The following describes steps used to build OpenCL 
280 ICD Loader version 1.2.11.0.
281
282 1. Download OpenCL ICD Loader sources archive and OpenCL header files from 
283    Khronos OpenCL Registry
284    http://www.khronos.org/registry/cl/
285
286 2. Unpack the archive and put headers in **inc/CL** sub-folder
287
288 3. Use CMake to generate VS projects for building the library:
289    - Start CMake-GUI and select OpenCL ICD Loader folder as source path,
290      and the folder of your choice for VS project and intermediate build data
291    - Click Generate
292    - Select VS version to be used (among the one you have installed; we
293      recommend using VS 2010), and architecture (32- or 64-bit)
294
295 4. Open solution **OPENCL_ICD_LOADER.sln** generated in the build folder.
296    Though not strictly necessary, we recommend making two changes in generated 
297    projects:
298    - Add file **OpenCL.rc** to project OpenCL, to have version and Khronos 
299      copyright correctly embedded in DLL
300    - In properties of OpenCL project, on "C/C++ / Code Generation" page,
301      for Release configuration, change "Runtime library" to "Multi-threaded 
302      (/MT)", to avoid dependency on run-time DLL. 
303   
304 5. Build project OpenCL in Release mode
305
306 6. Create installation folder for OpenCL IDL Loader package and put there:
307    - OpenCL header files in **include/CL** subfolder
308    - OpenCL.dll (generated in **bin/Release** subfolder of source package)
309      in **bin** subfolder
310    - OpenCL.lib (generated in **Release** subfolder of build directory)
311      in **lib** subfolder