1 Build 3rd-parties {#build_upgrade_building_3rdparty}
2 ==============================================
5 On Windows, the easiest way to install third-party libraries is to download archive with pre-built binaries from https://opencascade.com/content/3rd-party-components.
6 On Linux and OS X, it is recommended to use the version installed in the system natively.
8 @section dev_guides__building_3rdparty_win_1 Windows
10 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++.
12 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.
14 The links for downloading the third-party products are available at https://opencascade.com/content/3rd-party-components.
16 There are two types of third-party products used by OCCT:
20 * FreeType 2.4.10 -- 2.5.3.
23 * FreeImage 3.14.1 -- 3.16.0;
26 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*).
28 Further in this document, this folder is referred to as *3rdparty*.
30 @subsection dev_guides__building_3rdparty_win_2 Tcl/Tk
32 Tcl/Tk is required for DRAW test harness.
34 **Installation from sources: Tcl**
36 Download the necessary archive from https://www.tcl.tk/software/tcltk/download.html and unpack it.
38 1. In the *win* sub-directory, edit file *buildall.vc.bat*:
40 * Edit the line "call ... vcvars32.bat" to have correct path to the version of Visual Studio to be used for building, for instance:
42 call "%VS80COMNTOOLS%\vsvars32.bat"
44 If you are building 64-bit version, set environment accordingly, e.g.:
46 call "%VS80COMNTOOLS%\..\..\VC\vcvarsall.bat" amd64
48 * Define variable *INSTALLDIR* pointing to directory where Tcl/Tk will be installed, e.g.:
50 set INSTALLDIR=D:\OCCT\3rdparty\tcltk-86-32
52 * Add option *install* to the first command line calling *nmake*:
54 nmake -nologo -f makefile.vc release htmlhelp install %1
56 * Remove second call to *nmake* (building statically linked executable)
58 2. Edit file *rules.vc* replacing line
66 This is to avoid extra prefix 't' in the library name, which is not recognized by default by OCCT build tools.
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.
73 * Edit file *makefile.vc* replacing strings "crt = -MD" by "crt = -MT"
75 * Edit source file *tclMain.c* (located in folder *generic*) commenting out forward declaration of function *isatty()*.
78 4. In the command prompt, run *buildall.vc.bat*
80 You might need to run this script twice to have *tclsh* executable installed; check subfolder *bin* of specified installation path to verify this.
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)
84 > cd D:\OCCT\3rdparty\tcltk-86-32\bin
85 > cp tclsh86.exe tclsh.exe
87 **Installation from sources: Tk**
89 Download the necessary archive from https://www.tcl.tk/software/tcltk/download.html and unpack it.
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*.
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).
96 @subsection dev_guides__building_3rdparty_win_2_2 FreeType
98 FreeType is required for text display in a 3D viewer. You can download its sources from https://sourceforge.net/projects/freetype/files/
100 ### The building procedure
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*.
104 2. Open the solution file *freetype\\builds\\win32\\vc20xx\\freetype.sln* in Visual Studio. Here *vc20xx* stands for your version of Visual Studio.
106 3. Select the configuration to build: either Debug or Release.
108 4. Build the *freetype* project.
110 As a result, you will get a freetype import library (.lib) in the *freetype\\obj\\win32\\vc20xx* folder.
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:
115 @figure{/build/build_3rdparty/images/3rdparty_image001.png}
117 Update the value of the Output File for x64 configuration:
119 @figure{/build/build_3rdparty/images/3rdparty_image003.png}
121 Build the *freetype* project.
123 As a result, you will obtain a 64 bit import library (.lib) file in the *freetype\\x64\\vc20xx* folder.
125 To build FreeType as a dynamic library (.dll) follow steps 6, 7 and 8 of this procedure.
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*:
130 in line 255, uncomment the definition of macro *FT_EXPORT* and change it as follows:
132 #define FT_EXPORT(x) __declspec(dllexport) x
134 8. Build the *freetype* project.
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>.
138 If you build for a 64 bit platform, follow step 5 of the procedure.
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).
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*.
148 @subsection dev_guides__building_3rdparty_win_3_1 TBB
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.
154 Unpack the downloaded archive of TBB product into the *3rdparty* folder.
156 Further in this document, this folder is referred to as *tbb*.
158 @subsection dev_guides__building_3rdparty_win_3_3 FreeImage
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/
164 ### The building procedure:
166 1. Unpack the downloaded archive of FreeImage product into *3rdparty* folder.
168 As a result, you should have a folder named *3rdparty\\FreeImage*.
170 Rename it according to the rule: *freeimage-platform-compiler-building mode*, where
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)
176 Further in this document, this folder is referred to as *freeimage*.
178 2. Open the solution file *freeimage\\FreeImage.*.sln* in your Visual Studio.
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.
183 3. Select a configuration to build.
185 - Choose **Release** if you are building Release binaries.
186 - Choose **Debug** if you are building Debug binaries.
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:
192 Project -> Properties -> Configuration Properties -> Linker -> General -> Output File
194 FreeImage*d*.dll to FreeImage.dll
195 FreeImagePlus*d*.dll to FreeImagePlus.dll
197 Project -> Properties -> Configuration Properties -> Linker -> Debugging-> Generate Program Database File
199 FreeImage*d*.pdb to FreeImage.pdb
200 FreeImagePlus*d*.pdb to FreeImagePlus.pdb
202 Project -> Properties -> Configuration Properties -> Linker -> Advanced-Import Library
204 FreeImage*d*.lib to FreeImage.lib
205 FreeImagePlus*d*.lib to FreeImagePlus.lib
207 Project -> Properties -> Configuration Properties -> Build Events -> Post -> Build Event -> Command Line
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
214 Additionally, rename in project FreeImagePlus
216 Project -> Properties -> Configuration Properties -> Linker -> Input -> Additional Dependencies
218 from FreeImage*d*.lib to FreeImage.lib
220 4. Select a platform to build.
222 - Choose *Win32* if you are building for a 32 bit platform.
223 - Choose *x64* if you are building for a 64 bit platform.
225 5. Start the building process.
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*).
229 @subsection dev_guides__building_3rdparty_win_3_4 VTK
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.
233 ### The building procedure:
235 1. Download the necessary archive from https://www.vtk.org/VTK/resources/software.html and unpack it into *3rdparty* folder.
237 As a result, you will get a folder named, for example, <i>3rdparty\VTK-6.1.0.</i>
239 Further in this document, this folder is referred to as *VTK*.
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.
247 3. Build project VTK in Release mode.
250 @section build_3rdparty_linux Linux
252 This document presents additional guidelines for building third-party
253 products used by Open CASCADE Technology and samples on Linux platform.
255 The links for downloading the third-party products are available on the web site at
256 https://opencascade.com/content/3rd-party-components.
258 There are two types of third-party products, which are necessary to build OCCT:
260 * Mandatory products:
262 * FreeType 2.4.10 - 2.5.3;
265 * FreeImage 3.14.1 - 3.16.0;
269 @subsection dev_guides__building_3rdparty_linux_2_1 Tcl/Tk
271 Tcl/Tk is required for DRAW test harness.
273 **Installation from sources: Tcl**
275 Download the necessary archive from https://www.tcl.tk/software/tcltk/download.html and unpack it.
277 1. Enter the unix sub-directory of the directory where the Tcl source files are located <i>(TCL_SRC_DIR)</i>.
281 2. Run the *configure* command:
283 configure --enable-gcc --enable-shared --enable-threads --prefix=TCL_INSTALL_DIR
285 For a 64 bit platform also add <i>--enable-64bit</i> option to the command line.
287 3. If the configure command has finished successfully, start the building process:
291 4. If building is finished successfully, start the installation of Tcl.
292 All binary and service files of the product will be copied to the directory defined by *TCL_INSTALL_DIR*
296 **Installation from sources: Tk**
298 Download the necessary archive from https://www.tcl.tk/software/tcltk/download.html and unpack it.
300 1. Enter the unix sub-directory of the directory where the Tk source files are located <i>(TK_SRC_DIR)</i>
304 2. Run the configure command, where <i>TCL_LIB_DIR</i> is *TCL_INSTALL_DIR/lib*.
306 configure --enable-gcc --enable-shared --enable-threads --with-tcl=TCL_LIB_DIR --prefix=TK_INSTALL_DIR
308 For a 64 bit platform also add <i>--enable-64bit</i> option to the command line.
310 3. If the configure command has finished successfully, start the building process:
314 4. If the building has finished successfully, start the installation of Tk.
315 All binary and service files of the product will be copied
316 to the directory defined by *TK_INSTALL_DIR* (usually it is *TCL_INSTALL_DIR*)
320 @subsection dev_guides__building_3rdparty_linux_2_2 FreeType
322 FreeType is required for text display in the 3D viewer.
323 Download the necessary archive from https://sourceforge.net/projects/freetype/files/ and unpack it.
325 1. Enter the directory where the source files of FreeType are located <i>(FREETYPE_SRC_DIR)</i>.
329 2. Run the *configure* command:
331 configure --prefix=FREETYPE_INSTALL_DIR
333 For a 64 bit platform also add <i>CFLAGS='-m64 -fPIC' CPPFLAGS='-m64 -fPIC'</i> option to the command line.
335 3. If the *configure* command has finished successfully, start the building process:
339 4. If the building has finished successfully, start the installation of FreeType.
340 All binary and service files of the product will be copied to the directory defined by *FREETYPE_INSTALL_DIR*
345 @subsection dev_guides__building_3rdparty_linux_3_1 TBB
347 This third-party product is installed with binaries from the archive that can be downloaded from https://github.com/intel/tbb.
348 Go to the **Download** page, find the release version you need and pick the archive for Linux platform.
349 To install, unpack the downloaded archive of TBB product.
351 @subsection dev_guides__building_3rdparty_linux_3_3 FreeImage
353 Download the necessary archive from https://sourceforge.net/projects/freeimage/files/Source%20Distribution/
354 and unpack it. The directory with unpacked sources is further referred to as *FREEIMAGE_SRC_DIR*.
356 1. Modify *FREEIMAGE_SRC_DIR/Source/OpenEXR/Imath/ImathMatrix.h*:
357 In line 60 insert the following:
361 2. Enter the directory where the source files of FreeImage are located <i>(FREEIMAGE_SRC_DIR)</i>.
365 3. Run the building process
369 4. Run the installation process
371 a. If you have the permission to write into directories <i>/usr/include</i> and <i>/usr/lib</i>, run the following command:
374 b. If you do not have this permission, you need to modify file *FREEIMAGE_SRC_DIR/Makefile.gnu*:
376 Change lines 7-9 from:
379 INCDIR ?= $(DESTDIR)/usr/include
380 INSTALLDIR ?= $(DESTDIR)/usr/lib
384 DESTDIR ?= $(DESTDIR)
385 INCDIR ?= $(DESTDIR)/include
386 INSTALLDIR ?= $(DESTDIR)/lib
388 Change lines 65-67 from:
390 install -m 644 -o root -g root $(HEADER) $(INCDIR)
391 install -m 644 -o root -g root $(STATICLIB) $(INSTALLDIR)
392 install -m 755 -o root -g root $(SHAREDLIB) $(INSTALLDIR)
396 install -m 755 $(HEADER) $(INCDIR)
397 install -m 755 $(STATICLIB) $(INSTALLDIR)
398 install -m 755 $(SHAREDLIB) $(INSTALLDIR)
408 Then run the installation process by the following command:
410 make DESTDIR=FREEIMAGE_INSTALL_DIR install
412 5. Clean temporary files
416 @subsection dev_guides__building_3rdparty_linux_3_4 VTK
418 You can download VTK sources from https://www.vtk.org/VTK/resources/software.html
420 ### The building procedure:
422 Download the necessary archive from https://www.vtk.org/VTK/resources/software.html and unpack it.
424 1. Install or build *cmake* product from the source file.
425 2. Start *cmake* in GUI mode with the directory where the source files of *VTK* are located:
429 * Press <i>[c]</i> to make the initial configuration
430 * Define the necessary options in *VTK_INSTALL_PREFIX*
431 * Press <i>[c]</i> to make the final configuration
432 * Press <i>[g]</i> to generate Makefile and exit
434 3. Start the building of VTK:
438 4. Start the installation of VTK. Binaries will be installed according to the *VTK_INSTALL_PREFIX* option.
442 @subsection dev_guides__building_3rdparty_linux_4 Installation From Official Repositories
444 **Debian-based distributives**
446 All 3rd-party products required for building of OCCT could be installed
447 from official repositories. You may install them from console using apt-get utility:
449 sudo apt-get install tcllib tklib tcl-dev tk-dev libfreetype-dev libxt-dev libxmu-dev libxi-dev libgl1-mesa-dev libfreeimage-dev
451 Building is possible with C++ compliant compiler:
453 sudo apt-get install g++
455 @section build_3rdparty_macos Mac OS X
457 This document presents additional guidelines for building third-party products
458 used by Open CASCADE Technology and samples on Mac OS X platform (10.6.4 and later).
460 The links for downloading the third-party products are available at https://opencascade.com/content/3rd-party-components.
462 There are two types of third-party products, which are necessary to build OCCT:
464 * Mandatory products:
466 * FreeType 2.4.10 - 2.5.3.
469 * FreeImage 3.14.1 - 3.16.0
472 @subsection dev_guides__building_3rdparty_osx_2_1 Tcl/Tk 8.5
474 Tcl/Tk is required for DRAW test harness. Version 8.5 or 8.6 can be used with OCCT.
476 **Installation from sources: Tcl 8.5**
478 Download the necessary archive from https://www.tcl.tk/software/tcltk/download.html and unpack it.
480 1. Enter the *macosx* sub-directory of the directory where the Tcl source files are located <i>(TCL_SRC_DIR)</i>.
482 cd TCL_SRC_DIR/macosx
484 2. Run the *configure* command
486 configure --enable-gcc --enable-shared --enable-threads --prefix=TCL_INSTALL_DIR
488 For a 64 bit platform also add <i>--enable-64bit</i> option to the command line.
490 3. If the *configure* command has finished successfully, start the building process
494 4. If building is finished successfully, start the installation of Tcl.
495 All binary and service files of the product will be copied to the directory defined by *TCL_INSTALL_DIR*.
499 **Installation from sources: Tk 8.5**
501 Download the necessary archive from https://www.tcl.tk/software/tcltk/download.html and unpack it.
503 1. Enter the *macosx* sub-directory of the directory where the source files of Tk are located <i>(TK_SRC_DIR)</i>.
507 2. Run the *configure* command, where TCL_LIB_DIR is TCL_INSTALL_DIR/lib
509 configure --enable-gcc --enable-shared --enable-threads --with-tcl=TCL_LIB_DIR --prefix=TK_INSTALL_DIR
511 For a 64 bit platform also add <i>--enable-64bit</i> option to the command line.
513 3. If the *configure* command has finished successfully, start the building process:
517 4. If the building has finished successfully, start the installation of Tk. All binary and service files of the product will be copied to the directory defined by *TK_INSTALL_DIR* (usually it is TCL_INSTALL_DIR)
521 @subsection dev_guides__building_3rdparty_osx_2_2 FreeType 2.4.10
523 FreeType is required for text display in the 3D viewer.
525 Download the necessary archive from https://sourceforge.net/projects/freetype/files/ and unpack it.
527 1. Enter the directory where the source files of FreeType are located <i>(FREETYPE_SRC_DIR)</i>.
531 2. Run the *configure* command
533 configure --prefix=FREETYPE_INSTALL_DIR
535 For a 64 bit platform also add <i>CFLAGS='-m64 -fPIC' CPPFLAGS='-m64 -fPIC'</i> option to the command line.
537 3. If the *configure* command has finished successfully, start the building process
541 4. If building has finished successfully, start the installation of FreeType.
542 All binary and service files of the product will be copied to the directory defined by *FREETYPE_INSTALL_DIR*.
546 @subsection dev_guides__building_3rdparty_osx_3_1 TBB 3.x or 4.x
548 This third-party product is installed with binaries from the archive
549 that can be downloaded from https://github.com/intel/tbb.
550 Go to the **Download** page, find the release version you need (e.g. *tbb30_018oss*)
551 and pick the archive for Mac OS X platform.
552 To install, unpack the downloaded archive of TBB 3.0 product (*tbb30_018oss_osx.tgz*).
554 @subsection dev_guides__building_3rdparty_osx_3_3 FreeImage 3.14.1 or 3.15.x
556 Download the necessary archive from
557 https://sourceforge.net/projects/freeimage/files/Source%20Distribution/
558 and unpack it. The directory with unpacked sources is further referred to as *FREEIMAGE_SRC_DIR*.
560 Note that for building FreeImage on Mac OS X 10.7 you should replace *Makefile.osx*
561 in *FREEIMAGE_SRC_DIR* by the corrected file, which you can find in attachment to issue #22811 in OCCT Mantis bug tracker
562 (https://tracker.dev.opencascade.org/file_download.php?file_id=6937&type=bug).
564 1. If you build FreeImage 3.15.x you can skip this step.
565 Modify <i>FREEIMAGE_SRC_DIR/Source/OpenEXR/Imath/ImathMatrix.h:</i>
567 In line 60 insert the following:
571 Modify <i>FREEIMAGE_SRC_DIR/Source/FreeImage/PluginTARGA.cpp:</i>
581 2. Enter the directory where the source files of FreeImage are located <i>(FREEIMAGE_SRC_DIR)</i>.
585 3. Run the building process
589 4. Run the installation process
591 1. If you have the permission to write into <i>/usr/local/include</i> and <i>/usr/local/lib</i> directories, run the following command:
595 2. If you do not have this permission, you need to modify file *FREEIMAGE_SRC_DIR/Makefile.osx*:
605 Change lines 65-69 from:
607 install -d -m 755 -o root -g wheel $(INCDIR) $(INSTALLDIR)
608 install -m 644 -o root -g wheel $(HEADER) $(INCDIR)
609 install -m 644 -o root -g wheel $(SHAREDLIB) $(STATICLIB) $(INSTALLDIR)
610 ranlib -sf $(INSTALLDIR)/$(STATICLIB)
611 ln -sf $(SHAREDLIB) $(INSTALLDIR)/$(LIBNAME)
615 install -d $(INCDIR) $(INSTALLDIR)
616 install -m 755 $(HEADER) $(INCDIR)
617 install -m 755 $(STATICLIB) $(INSTALLDIR)
618 install -m 755 $(SHAREDLIB) $(INSTALLDIR)
619 ln -sf $(SHAREDLIB) $(INSTALLDIR)/$(VERLIBNAME)
620 ln -sf $(VERLIBNAME) $(INSTALLDIR)/$(LIBNAME)
622 Then run the installation process by the following command:
624 make PREFIX=FREEIMAGE_INSTALL_DIR install
626 5. Clean temporary files