0032147: Documentation - drop mentioning of WOK from build_3rdparty
[occt.git] / dox / build / build_occt / building_occt.md
CommitLineData
06ce029f 1Build OCCT {#build_upgrade__building_occt}
e5bd0d98 2===================
3
4@tableofcontents
5
06ce029f
VS
6@note Before building OCCT, make sure to have all required third-party libraries installed.
7The list of required libraries depends on what OCCT modules will be used, and your preferences.
8The typical minimum is **Freetype** (necessary for Visualization) and **Tcl/Tk** (for DRAW).
0a6d9742 9See @ref intro_req "requirements on 3rdparty libraries" for a full list.
06ce029f
VS
10On OS X we recommend to use native libraries.
11
12@section build_occt_windows Windows
13
14@subsection build_occt_win_cmake Building with CMake tool
e5bd0d98 15
80223385 16This article describes the **CMake**-based build process, which is now suggested as a standard way to produce the binaries of Open CASCADE Technology from sources. *OCCT requires CMake version 2.8.12 or later*.
e5bd0d98 17
80223385 18Here we describe the build procedure on the example of Windows platform with Visual Studio 2010.
72c37458 19However, CMake is cross-platform and can be used to build OCCT on Linux and OS X in essentially the same way.
e5bd0d98 20
06ce029f 21@note Before you start, make sure to have installed all 3-rd party products that you are going to use with OCCT; see @ref build_upgrade.
e5bd0d98 22
06ce029f 23@subsubsection build_cmake_start Start CMake
e5bd0d98 24
72c37458 25CMake is a tool that generates the actual project files for the selected target build system (e.g. Unix makefiles) or IDE (e.g. Visual Studio 2010).
e5bd0d98 26
80223385 27For unexperienced users we recommend to start with *cmake-gui* -- a cross-platform GUI tool provided by CMake on Windows, Mac and Linux.
28A command-line alternative, *ccmake* can also be used.
e5bd0d98 29
80223385 30CMake deals with three directories: source, build or binary and installation.
e5bd0d98 31
80223385 32* The source directory is where the sources of OCCT are located in your file system;
33* The build or binary directory is where all files created during CMake configuration and generation process will be located. The mentioned process will be described below.
8072aba1 34* The installation directory is where binaries will be installed after building the *INSTALL* project that is created by CMake generation process, along with header files and resources required for OCCT use in applications.
576f8b11 35
72c37458 36The good practice is not to use the source directory as a build one.
37Different configurations should be built in different build directories to avoid conflicts.
38It is however possible to choose one installation directory for several configurations of OCCT (differentiated by platform, bitness, compiler and build type), for example:
316d77d9 39
3f812249 40 d:/occt/ -- the source directory
41 d:/tmp/occt-build-vc10-x64 -- the build directory with the generated
42 solution and other intermediate files created during a CMake tool working
43 d:/occt-install -- the installation directory that is
8072aba1 44 able to contain several OCCT configurations
32856b63 45
06ce029f 46@subsubsection build_cmake_conf Configuration process
e5bd0d98 47
8da8f3d2 48If the command-line tool is used, run the tool from the build directory with a single argument indicating the source (relative or absolute path) directory:
e5bd0d98 49
8da8f3d2 50 cd d:/tmp/occt-build-vc10-x64
51 ccmake d:/occt
e5bd0d98 52
06ce029f 53@figure{/build/build_occt/images/cmake_image000.png}
e5bd0d98 54
576f8b11 55Press *c* to configure.
e5bd0d98 56
80223385 57All actions required in the configuration process with the GUI tool will be described below.
576f8b11 58
80223385 59If the GUI tool is used, run this tool without additional arguments and after that specify the source directory by clicking **Browse Source** and the build (binary) one by clicking **Browse Build**.
adc33035 60
06ce029f 61@figure{/build/build_occt/images/cmake_image001.png}
576f8b11 62
316d77d9 63**Note**: Each configuration of the project should be built in its own directory. When building multiple configurations it is recommended to indicate in the name of build directories the system, bitness and compiler (e.g., <i>d:/occt/build/win32-vc10</i> ).
576f8b11 64
316d77d9 65Once the source and build directories are selected, "Configure" button should be pressed in order to start manual configuration process. It begins with selection of a target configurator. It is "Visual Studio 10 2010 Win64" in our example.
ad211ad3 66
06ce029f 67@figure{/build/build_occt/images/cmake_image002.png}
ad211ad3 68
a20cce39 69To build OCCT for **Universal Windows Platform (UWP)** specify the path to toolchain file for cross-compiling <i>d:/occt/adm/templates/uwp.toolchain.config.cmake</i>.
70
71Alternatively, if you are using CMake from the command line add options -DCMAKE_SYSTEM_NAME=WindowsStore -DCMAKE_SYSTEM_VERSION=10.0 .
742cc8b0 72
80223385 73**Note**: Universal Windows Platform (UWP) is supported only on "Visual Studio 14 2015". File <i>d:/occt/samples/xaml/ReadMe.md</i> describes the building procedure of XAML (UWP) sample.
742cc8b0 74
80223385 75Once "Finish" button is pressed, the first pass of the configuration process is executed. At the end of the process, CMake outputs the list of environment variables, which have to be properly specified for successful configuration.
316d77d9 76
06ce029f 77@figure{/build/build_occt/images/cmake_image003.png}
8da8f3d2 78
80223385 79The error message provides some information about these variables. This message will appear after each pass of the process until all required variables are specified correctly.
316d77d9 80
80223385 81The change of the state of some variables can lead to the appearance of new variables. The new variables appeared after the pass of the configuration process are highlighted with red color by CMake GUI tool.
316d77d9 82
80223385 83Note: There is "grouped" option, which groups variables with a common prefix.
316d77d9 84
80223385 85The following table gives the full list of environment variables used at the configuration stage:
316d77d9 86
87| Variable | Type | Purpose |
88|----------|------|---------|
80223385 89| CMAKE_BUILD_TYPE | String | Specifies the build type on single-configuration generators (such as make). Possible values are Debug, Release and RelWithDebInfo |
90| USE_FREEIMAGE | Boolean flag | Indicates whether FreeImage product should be used in OCCT visualization module for support of popular graphics image formats (PNG, BMP, etc.) |
7863dabb 91| USE_RAPIDJSON | Boolean flag | Indicates whether RapidJSON product should be used in OCCT Data Exchange module for support of glTF mesh file format |
3f812249 92| USE_TBB | Boolean flag | Indicates whether TBB 3rd party is used or not. TBB stands for Threading Building Blocks, the technology of Intel Corp, which comes with different mechanisms and patterns for injecting parallelism into your application. OCCT remains parallel even without TBB product |
80223385 93| USE_VTK | Boolean flag | Indicates whether VTK 3rd party is used or not. VTK stands for Visualization ToolKit, the technology of Kitware Inc intended for general-purpose scientific visualization. OCCT comes with a bridge between CAD data representation and VTK by means of its dedicated VIS component (VTK Integration Services). You may skip this 3rd party unless you are planning to use VTK visualization for OCCT geometry. See the official documentation @ref occt_user_guides__vis for the details on VIS |
3f812249 94| 3RDPARTY_DIR | Path | Defines the root directory where all required 3rd party products will be searched. Once you define this path it is very convenient to click "Configure" button in order to let CMake automatically detect all necessary products|
316d77d9 95| 3RDPARTY_FREETYPE_* | Path | Path to Freetype binaries |
96| 3RDPARTY_TCL_* 3RDPARTY_TK_* | Path | Path to Tcl/Tk binaries |
97| 3RDPARTY_FREEIMAGE* | Path | Path to Freeimage binaries |
316d77d9 98| 3RDPARTY_TBB* | Path | Path to TBB binaries |
99| 3RDPARTY_VTK_* | Path | Path to VTK binaries |
4ff92abe 100| BUILD_MODULE_<MODULE>| Boolean flag | Indicates whether the corresponding OCCT module should be built or not. It should be noted that some toolkits of a module can be built even if this module is not checked (this happens if some other modules depend on these toolkits). The main modules and their descriptions can be found in @ref user_guides |
68df8478 101| BUILD_LIBRARY_TYPE | String | Specifies the type of library to be created. "Shared" libraries are linked dynamically and loaded at runtime. "Static" libraries are archives of object files used when linking other targets. Note that Draw Harness plugin system is incompatible with "Static" builds, and therefore it is disabled for these builds.|
316d77d9 102| BUILD_ADDITIONAL_TOOLKITS | String | Semicolon-separated individual toolkits to include into build process. If you want to build some particular libraries (toolkits) only, then you may uncheck all modules in the corresponding *BUILD_MODUE_\<MODULE\>* options and provide the list of necessary libraries here. Of course, all dependencies will be resolved automatically |
80223385 103| BUILD_YACCLEX | Boolean flag | Enables Flex/Bison lexical analyzers. OCCT source files relating to STEP reader and ExprIntrp functionality are generated automatically with Flex/Bison. Checking this option leads to automatic search of Flex/Bison binaries and regeneration of the mentioned files |
510d9690 104| BUILD_SAMPLES_MFC | Boolean flag | Indicates whether MFC samples should be built together with OCCT. This option is only relevant to Windows platforms |
105| BUILD_SAMPLES_QT | Boolean flag | Indicates whether QT samples should be built together with OCCT. |
d2c90917 106| BUILD_Inspector | Boolean flag | Indicates whether Inspector should be built together with OCCT. |
80223385 107| BUILD_DOC_Overview | Boolean flag | Indicates whether OCCT overview documentation project should be created together with OCCT. It is not built together with OCCT. Checking this option leads to automatic search of Doxygen binaries. Its building calls Doxygen command to generate the documentation in HTML format |
109aa56e 108| BUILD_PATCH | Path | Points to the directory recognized as a "patch" for OCCT. If specified, the files from this directory take precedence over the corresponding native OCCT sources. This way you are able to introduce patches to Open CASCADE Technology not affecting the original source distribution |
80223385 109| BUILD_WITH_DEBUG | Boolean flag | Enables extended messages of many OCCT algorithms, usually printed to cout. These include messages on internal errors and special cases encountered, timing, etc. |
7a59f4ce 110| BUILD_ENABLE_FPE_SIGNAL_HANDLER | Boolean flag | Enable/Disable the floating point exceptions (FPE) during DRAW execution only. Corresponding environment variable (CSF_FPE) can be changed manually in custom.bat/sh scripts without regeneration by CMake. |
316d77d9 111| CMAKE_CONFIGURATION_TYPES | String | Semicolon-separated CMake configurations |
80223385 112| INSTALL_DIR | Path | Points to the installation directory. *INSTALL_DIR* is a synonym of *CMAKE_INSTALL_PREFIX*. The user can specify both *INSTALL_DIR* or *CMAKE_INSTALL_PREFIX* |
4b3541c6 113| INSTALL_DIR_BIN | Path | Relative path to the binaries installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_BIN}) |
114| INSTALL_DIR_SCRIPT | Path | Relative path to the scripts installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_SCRIPT}) |
115| INSTALL_DIR_LIB | Path | Relative path to the libraries installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_LIB}) |
116| INSTALL_DIR_INCLUDE | Path | Relative path to the includes installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_INCLUDE}) |
117| INSTALL_DIR_RESOURCE | Path | Relative path to the resources installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_RESOURCE}) |
80223385 118| INSTALL_DIR_LAYOUT | String | Defines the structure of OCCT files (binaries, resources, headers, etc.) for the install directory. Two variants are predefined: for Windows (standard OCCT layout) and for Unix operating systems (standard Linux layout). If needed, the layout can be customized with INSTALL_DIR_* variables |
4b3541c6 119| INSTALL_DIR_DATA | Path | Relative path to the data files installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_DATA}) |
120| INSTALL_DIR_SAMPLES | Path | Relative path to the samples installation directory. Note that only "samples/tcl" folder will be installed. (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_SAMPLES}) |
121| INSTALL_DIR_TESTS | Path | Relative path to the tests installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_TESTS}) |
122| INSTALL_DIR_DOC | Path | Relative path to the documentation installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_DOC}) |
316d77d9 123| INSTALL_FREETYPE | Boolean flag | Indicates whether Freetype binaries should be installed into the installation directory |
124| INSTALL_FREEIMAGE* | Boolean flag | Indicates whether Freeimage binaries should be installed into the installation directory |
316d77d9 125| INSTALL_TBB | Boolean flag | Indicates whether TBB binaries should be installed into the installation directory |
126| INSTALL_VTK | Boolean flag | Indicates whether VTK binaries should be installed into the installation directory |
127| INSTALL_TCL | Boolean flag | Indicates whether TCL binaries should be installed into the installation directory |
0e617b05 128| INSTALL_TEST_CASES | Boolean flag | Indicates whether non-regression OCCT test scripts should be installed into the installation directory |
4b3541c6 129| INSTALL_DOC_Overview | Boolean flag | Indicates whether OCCT overview documentation should be installed into the installation directory |
316d77d9 130
80223385 131**Note:** Only the forward slashes ("/") are acceptable in the CMake options defining paths.
316d77d9 132
06ce029f 133@subsubsection build_cmake_3rdparty 3rd party search mechanism
316d77d9 134
72c37458 135If *3RDPARTY_DIR* directory is defined, then required 3rd party binaries are sought in it, and default system folders are ignored.
316d77d9 136
3f812249 137The procedure expects to find binary and header files of each 3rd party product in its own sub-directory: *bin*, *lib* and *include*.
316d77d9 138
80223385 139The results of the search (achieved on the next pass of the configuration process) are recorded in the corresponding variables:
e5bd0d98 140
3f812249 141* *3RDPARTY_\<PRODUCT\>_DIR* -- path to the 3rdparty directory (with directory name) (e.g. <i>D:/3rdparty/tcltk-86-32</i>)
142* *3RDPARTY_\<PRODUCT\>_LIBRARY_DIR* -- path to the directory containing a library (e.g. <i>D:/3rdparty/tcltk-86-32/lib</i>).
143* *3RDPARTY_\<PRODUCT\>_INCLUDE_DIR* -- path to the directory containing a header file (e.g., <i>D:/3rdparty/tcltk-86-32/include</i>)
144* *3RDPARTY_\<PRODUCT\>_DLL_DIR* -- path to the directory containing a shared library (e.g., <i>D:/3rdparty/tcltk-86-32/bin</i>) This variable is only relevant to Windows platforms.
9f33b387 145
8072aba1 146Note: each library and include directory should be children of the product directory if the last one is defined.
e5bd0d98 147
148The search process is as follows:
149
576f8b11 1501. Common path: *3RDPARTY_DIR*
1512. Path to a particular 3rd-party library: *3RDPARTY_\<PRODUCT\>_DIR*
5c573e69 1523. Paths to headers and binaries:
9f33b387 153 1. *3RDPARTY_\<PRODUCT\>_INCLUDE_DIR*
154 2. *3RDPARTY_\<PRODUCT\>_LIBRARY_DIR*
155 3. *3RDPARTY_\<PRODUCT\>_DLL_DIR*
e5bd0d98 156
8072aba1 157If a variable of any level is not defined (empty or <i> \<variable name\>-NOTFOUND </i>) and the upper level variable is defined, the content of the non-defined variable will be sought at the next configuration step. If the search process at level 3 does not find the required files, it seeks in default places.
e5bd0d98 158
316d77d9 159If a search result (include path, or library path, or dll path) does not meet your expectations, you can change *3RDPARTY_\<PRODUCT\>_*_DIR variable*, clear (if they are not empty) *3RDPARTY_\<PRODUCT\>_DLL_DIR, 3RDPARTY_\<PRODUCT\>_INCLUDE_DIR* and 3RDPARTY_\<PRODUCT\>_LIBRARY_DIR variables (or clear one of them) and run the configuration process again.
5c573e69 160
576f8b11 161At this time the search will be performed in the newly identified directory
9f33b387 162and the result will be recorded to corresponding variables (replace old value if it is necessary).
e5bd0d98 163
8da8f3d2 164For example, *3RDPARTY_FREETYPE_DIR* variable
e5bd0d98 165
8da8f3d2 166 d:/3rdparty/freetype-2.4.10
e5bd0d98 167
168can be changed to
169
8da8f3d2 170 d:/3rdparty/freetype-2.5.3
e5bd0d98 171
8072aba1 172During the configuration process the related variables (*3RDPARTY_FREETYPE_DLL_DIR*, *3RDPARTY_FREETYPE_INCLUDE_DIR* and *3RDPARTY_FREETYPE_LIBRARY_DIR*) will be filled with new found values.
e5bd0d98 173
316d77d9 174**Note**: The names of searched libraries and header files are hard-coded. If there is the need to change their names, change appropriate cmake variables (edit CMakeCache.txt file or edit in cmake-gui in advance mode) without reconfiguration: *3RDPARTY_\<PRODUCT\>_INCLUDE* for include, *3RDPARTY_\<PRODUCT\>_LIB* for library and *3RDPARTY_\<PRODUCT\>_DLL* for shared library.
e5bd0d98 175
06ce029f 176@subsubsection build_cmake_gen Projects generation
e5bd0d98 177
a25d5aaa 178Once the configuration process is done, the "Generate" button is used to prepare project files for the target IDE.
179In our exercise the Visual Studio solution will be automatically created in the build directory.
234e52be 180
06ce029f 181@subsubsection build_cmake_build Building
e5bd0d98 182
576f8b11 183Go to the build folder, start the Visual Studio solution *OCCT.sln* and build it by clicking **Build -> Build Solution**.
184
06ce029f 185@figure{/build/build_occt/images/cmake_image004.png}
8da8f3d2 186
316d77d9 187By default the build solution process skips the building of the INSTALL and Overview project.
e5bd0d98 188
316d77d9 189When the building process is finished build:
4b3541c6 190* Overview project to generate OCCT overview documentation (if BUILD_DOC_Overview variable is checked)
8da8f3d2 191* the *INSTALL* project to run **the installation process**
e5bd0d98 192
316d77d9 193For this, right-click on the *Overview/INSTALL* project and select **Project Only -> Build Only** -> *Overview/INSTALL* in the solution explorer.
e5bd0d98 194
06ce029f 195@subsubsection build_cmake_install Installation
e5bd0d98 196
8072aba1 197Installation is a process of extracting redistributable resources (binaries, include files etc) from the build directory into the installation one. The installation directory will be free of project files, intermediate object files and any other information related to the build routines.
e5bd0d98 198
316d77d9 199Normally you use the installation directory of OCCT to link against your specific application.
576f8b11 200
8072aba1 201The directory structure is as follows:
316d77d9 202
3f812249 203 data -- data files for OCCT (brep, iges, stp)
204 doc -- OCCT overview documentation in HTML format
205 inc -- header files
206 samples -- samples
207 src -- all required source files for OCCT
208 tests -- OCCT test suite
209 win32\vc10\bind -- binary files (installed 3rdparties and occt)
210 \libd -- libraries (installed 3rdparties and occt)
576f8b11 211
316d77d9 212**Note:** The above example is given for debug configuration. However, it is generally safe to use the same installation directory for the release build. In the latter case the contents of install directory will be enriched with subdirectories and files related to the release configuration. In particular, the binaries directory win64 will be expanded as
213follows:
576f8b11 214
316d77d9 215 \win32\vc10\bind
216 \libd
217 \bin
218 \lib
576f8b11 219
8072aba1 220If CMake installation flags are enabled for the 3rd party products (e.g. INSTALL_FREETYPE), then the corresponding binaries will be copied to the same bin(d) and lib(d) directories together with the native binaries of OCCT. Such organization of libraries can be especially helpful if your OCCT-based software does not use itself the 3rd parties of Open CASCADE Technology (thus, there is no sense to pack them into dedicated directories).
e5bd0d98 221
8072aba1 222The installation folder contains the scripts to run *DRAWEXE* (*draw.bat* or *draw.sh*), samples (if they were installed) and overview.html (short-cut for installed OCCT overview documentation).
06ce029f
VS
223
224@subsection build_occt_win_codeblocks Building with Code::Blocks
225
226This file describes steps to build OCCT libraries from sources using **Code::Blocks**, a cross-platform IDE, using project files generated by OCCT legacy tool **genproj**.
227It can be used as an alternative to CMake build system (see @ref build_occt_win_cmake) for all supported platforms.
228
229@subsubsection build_codeblocks_3rdparty Third-party libraries
230
231Before building OCCT, make sure to have all the needed third-party libraries installed, see @ref build_upgrade.
232
233@subsubsection build_codeblocks_conf Configuration
234
235Before building it is necessary to set up build environment.
236
237The environment is defined in the file *custom.sh* (on Linux and OS X) or *custom.bat* (on Windows) which can be edited directly:
238
239* Add paths to includes of used third-party libraries in variable *CSF_OPT_INC*.
240* Add paths to their binary libraries in variable *CSF_OPT_LIB64*.
241* Set variable *SHORTCUT_HEADERS* to specify a method for population of folder *inc* by header files. Supported methods are:
242 * *Copy* - headers will be copied from *src*;
243 * *ShortCut* - short-cut header files will be created, redirecting to same-named header located in *src*;
244 * "HardLink* - hard links to headers located in *src* will be created.
245* For optional third-party libraries, set corresponding environment variable <i>HAVE_<LIBRARY_NAME></i> to either *false*, e.g.:
246~~~~~
247 export HAVE_FREEIMAGE=false
248~~~~~
249
250Alternatively, or when *custom.sh* or *custom.bat* does not exist, you can launch **genconf** tool to configure environment interactively:
251
252@figure{/build/build_occt/images/genconf_linux.png}
253
254Click "Save" to store the specified configuration in *custom.sh* or *custom.bat* file.
255
256@subsubsection build_codeblocks_gen Projects generation
257
258Launch **genproj** tool with option *cbp* to update content of *inc* folder and generate project files after changes in OCCT code affecting layout or composition of source files:
259
260~~~~~
261 $ cd /dev/OCCT/opencascade-7.0.0
262 $ ./genproj cbp
263~~~~~
264
265The generated Code::Blocks project are placed into subfolder *adm/&lt;OS&gt;/cbp*.
266
267@note To use **genproj** and **genconf** tools you need to have Tcl installed and accessible by PATH.
268
269@subsubsection build_codeblocks_build Building
270
271To start **Code::Blocks**, launch script *codeblocks.sh*.
272
273To build all toolkits, click **Build->Build workspace** in the menu bar.
274
275To start *DRAWEXE*, which has been built with **Code::Blocks** on Mac OS X, run the script
276~~~~~
277 ./draw.sh cbp [d]
278~~~~~
279Option *d* is used if OCCT has been built in **Debug** mode.
280
281@subsection build_occt_genproj Building with Genproj tool
282
283This page describes steps to build OCCT libraries from a complete source archive on Windows with <b>MS Visual C++</b> using projects generated by **genproj** tool.
284It is an alternative to use of CMake build system (see @ref build_occt_win_cmake).
285
286**genproj** is a legacy tool (originated from command "wgenproj" in WOK) for generation of Visual Studio, Code.Blocks, and XCode project files used for building Open CASCADE Technology.
287These project files are placed inside OCCT directory (in *adm* subfolder) and use relative paths, thus can be moved together with sources.
288
289The project files included in official distribution of OCCT are generated by this tool.
290If you have official distribution with project files included, you can use them directly without a need to call **genproj**.
291
292@subsubsection build_msvc_3rdparty Third-party libraries
293
294Before building OCCT, make sure to have all the required third-party libraries installed.
295
296The easiest way to install third-party libraries is to download archive with pre-built binaries, corresponding to version of Visual Studio you are using, from https://opencascade.com/content/3rd-party-components.
297
298You can also build third-party libraries from their sources, see @ref build_upgrade_building_3rdparty for instructions.
299
300@subsubsection build_msvc_conf Configuration
301
302If you have Visual Studio projects already available (pre-installed or generated), you can edit file *custom.bat* manually to adjust the environment:
303
304* *VCVER* -- specification of format of project files, defining also version of Visual Studio to be used, and default name of the sub-folder for binaries:
305
306| VCVER | Visual Studio version | Windows Platform | Binaries folder name |
307|-----------|-----------------------|----------------------------------|----------------------|
308| vc10 | 2010 (10) | Desktop (Windows API) | vc10 |
309| vc11 | 2012 (11) | Desktop (Windows API) | vc11 |
310| vc12 | 2013 (12) | Desktop (Windows API) | vc12 |
311| vc14 | 2015 (14) | Desktop (Windows API) | vc14 |
312| vc14-uwp | 2015 (14) | UWP (Universal Windows Platform) | vc14-uwp |
313| vc141 | 2017 (15) | Desktop (Windows API) | vc14 |
314| vc141-uwp | 2017 (15) | UWP (Universal Windows Platform) | vc14-uwp |
315| vc142 | 2019 (16) | Desktop (Windows API) | vc14 |
316| vc142-uwp | 2019 (16) | UWP (Universal Windows Platform) | vc14-uwp |
317
318* *ARCH* -- architecture (32 or 64), affects only *PATH* variable for execution
319* <i>HAVE_*</i> -- flags to enable or disable use of optional third-party products
320* <i>CSF_OPT_*</i> -- paths to search for includes and binaries of all used third-party products
321* *SHORTCUT_HEADERS* -- defines method for population of folder *inc* by header files. Supported methods are:
322 * *Copy* - headers will be copied from *src*;
323 * *ShortCut* - short-cut header files will be created, redirecting to same-named header located in *src*;
324 * "HardLink* - hard links to headers located in *src* will be created.
325
326Alternatively, you can launch **genconf**, a GUI tool allowing to configure build options interactively.
327That tool will analyze your environment and propose you to choose available options:
328
329* Version of Visual Studio to be used (from the list of installed ones, detected by presence of environment variables like *VS100COMNTOOLS*).
330* Method to populate folder *inc* (short-cuts by default).
331* Location of third-party libraries (usually downloaded from OCCT web site, see above).
332* Path to common directory where third-party libraries are located (optional).
333* Paths to headers and binaries of the third-party libraries (found automatically basing on previous options; click button "Reset" to update).
334* Generation of PDB files within Release build ("Release with Debug info", false by default).
335
336@figure{/build/build_occt/images/genconf_windows.png}
337
338Click "Save" to store the specified configuration in *custom.bat* file.
339
340@subsubsection build_msvc_generate Projects generation
341
342Launch **genproj** to update content of *inc* folder and generate project files after changes in OCCT code affecting layout or composition of source files.
343
344@note To use **genproj** and **genconf** tools you need to have Tcl installed and accessible by PATH.
345If Tcl is not found, the tool may prompt you to enter the path to directory where Tcl can be found.
346
347~~~~~
348 $ genproj.bat
349~~~~~
350
351Note that if *custom.bat* is not present, **genproj** will start **genconf** to configure environment.
352
353@subsubsection build_msvc_build Building
354
355Launch *msvc.bat* to start Visual Studio with all necessary environment variables defined, and build the whole solution or required toolkits.
356
357Note: the MSVC project files are located in folders <i>adm\\msvc\\vc...</i>.
358Binaries are produced in *win32* or *win64* folders.
359
360To start DRAW, launch *draw.bat*.
361
362@section build_occt_linux Linux
363
364You may choose one of the following ways to generate, configure and build OCCT sources on Linux just keeping in mind
365this platform specific:
366
367* @ref build_occt_win_cmake "Configuration, generation and building OCCT on Windows using CMake tool"
368* @ref build_occt_code_blocks "Building on Mac OS X with Code::Blocks IDE"
369
370@section build_occt_crossplatform_cmake Android (cross-compiling)
371
372This article describes the steps to build OCCT libraries for Android from a complete source package
373with GNU make (makefiles). The steps on Windows 7 and Ubuntu 15.10 are similar. There is the only one difference:
374 makefiles are built with mingw32-make
375on Windows and native GNU make on Ubuntu.
376
377Required tools (download and install if it is required):
378 - CMake v3.0+ http://www.cmake.org/cmake/resources/software.html
379 - Cross-compilation toolchain for CMake https://github.com/taka-no-me/android-cmake
380 - Android NDK rev.10+ https://developer.android.com/tools/sdk/ndk/index.html
381 - GNU Make: MinGW v4.82+ for Windows (http://sourceforge.net/projects/mingw/files/), GNU Make 4.0 for Ubuntu.
382
383Run GUI tool provided by CMake.
384
385@subsection build_occt_crossplatform_cmake_config Configuration
386
387**Configure Tools**
388 - Specify the root folder of OCCT (<i>$CASROOT</i>, which contains *CMakelists.txt* file) by clicking **Browse Source**.
389 - Specify the location (build folder) for Cmake generated project files by clicking **Browse Build**.
390
391@figure{/build/build_occt/images/android_image001.png}
392
393Click **Configure** button. It opens the window with a drop-down list of generators supported by CMake project.
394
395Select "MinGW MakeFiles" item from the list
396 - Choose "Specify toolchain file for cross-compiling"
397 - Click "Next"
398@figure{/build/build_occt/images/android_image002.png}
399
400 - Specify a toolchain file at the next dialog by android.toolchain.cmake . It is contained by cross-compilation
401toolchain for CMake
402 - Click "Finish"
403@figure{/build/build_occt/images/android_image003.png}
404
405If ANDROID_NDK environment variable is not defined in current OS, add cache entry ANDROID_NDK (entry type is PATH) --
406path to the NDK folder ("Add Entry" button)
407@figure{/build/build_occt/images/android_image004.png}
408
409If on Windows the message is appeared: "CMake Error: CMake was unable to find a build program corresponding
410to "MinGW Makefiles"
411CMAKE_MAKE_PROGRAM is not set. You probably need to select a different build tool.",
412specify **CMAKE_MAKE_PROGRAM** to mingw32-make executable.
413@figure{/build/build_occt/images/android_image005.png}
414
415**Configure OCCT**
416
417How to configure OCCT, see "OCCT Configuration" section of @ref build_occt_win_cmake
418"Configure, Generate, Build using CMake tool" taking into account the specific configuration variables for android:
419 - ANDROID_ABI = armeabi-v7a
420 - ANDROID_NATIVE_API_LEVEL = 15
421 - ANDROID_NDK_LAYOUT is equal to CMAKE_BUILD_TYPE variable
422 - **BUILD_MODULE_Draw = OFF**
423
424@figure{/build/build_occt/images/android_image006.png}
425
426@subsection build_occt_crossplatform_cmake_generation Generate Makefiles
427
428Click **Generate** button and wait until the generation process is finished.
429Then makefiles will appear in the build folder (e.g. <i> D:/tmp/occt-android </i>).
430
431@subsection build_occt_crossplatform_cmake_building Build Makefiles
432
433Open console and go to the build folder. Type "mingw32-make" (Windows) or "make" (Ubuntu) to start build process.
434
435> mingw32-make
436or
437> make
438
439Parallel building can be started with using **"-jN"** argument of "mingw32-make/make", where N is the number of
440 building threads.
441
442> mingw32-make -j4
443or
444> make -j4
445
446@subsection build_occt_crossplatform_cmake_install Install OCCT Libraries
447
448Type "mingw32-make/make" with argument "install" to place the libraries to the install folder
449
450> mingw32-make install
451or
452> make install
453
454@section build_occt_macos Mac OS X
455
456@subsection build_occt_macos_xcode Building with Xcode
457
458This file describes steps to build OCCT libraries from sources on Mac OS X with **Xcode** projects, generated by OCCT legacy tool **genproj**.
459
460<h2>Configuration</h2>
461
462Before building it is necessary to set up build environment.
463
464The environment is defined in the file *custom.sh* which can be edited directly:
465
466* Add paths to includes of used third-party libraries in variable *CSF_OPT_INC* (use colon ":" as path separator).
467* Add paths to their binary libraries in variable *CSF_OPT_LIB64*.
468* Set variable *SHORTCUT_HEADERS* to specify a method for population of folder *inc* by header files. Supported methods are:
469 * *Copy* - headers will be copied from *src*;
470 * *ShortCut* - short-cut header files will be created, redirecting to same-named header located in *src*;
471 * "HardLink* - hard links to headers located in *src* will be created.
472* For optional third-party libraries, set corresponding environment variable <i>HAVE_<LIBRARY_NAME></i> to either *false*, e.g.:
473~~~~~
474 export HAVE_GL2PS=false
475~~~~~
476
477Alternatively, or when *custom.sh* does not exist, you can launch *genconf.sh* to configure environment interactively:
478
479@figure{/build/build_occt/images/genconf_osx.png}
480
481Click "Save" to store the specified configuration in *custom.sh* file.
482
483<h2>Projects generation</h2>
484
485Launch **genproj** tool to update content of *inc* folder and generate project files after changes in OCCT code affecting layout or composition of source files.
486
487@note To use **genproj** and **genconf** tools you need to have Tcl installed and accessible by PATH.
488
489For instance, in Terminal application:
490
491~~~~~
492 $ cd /dev/OCCT/opencascade-7.0.0
493 $ ./genproj
494~~~~~
495
496<h2>Building</h2>
497
498To start **Xcode**, launch script *xcode.sh*.
499
500To build a certain toolkit, select it in **Scheme** drop-down list in Xcode toolbar, press **Product** in the menu and click **Build** button.
501
502To build the entire OCCT:
503* Create a new empty project (select **File -> New -> Project -> Empty project** in the menu; input the project name, e.g. *OCCT*; then click **Next** and **Create**).
504* Drag and drop the *OCCT* folder in the created *OCCT* project in the Project navigator.
505* Select **File -> New -> Target -> Aggregate** in the menu.
506* Enter the project name (e.g. *OCCT*) and click **Finish**. The **Build Phases** tab will open.
507* Click "+" button to add the necessary toolkits to the target project. It is possible to select all toolkits by pressing **Command+A** combination.
508
509<h2>Launching DRAW</h2>
510
511To start *DRAWEXE*, which has been built with Xcode on Mac OS X, perform the following steps:
512
5131.Open Terminal application
514
5152.Enter <i>\<OCCT_ROOT_DIR\></i>:
516~~~~~
517 cd \<OCCT_ROOT_DIR\>
518~~~~~
519
5203.Run the script
521~~~~~
522 ./draw_cbp.sh xcd [d]
523~~~~~
524
525Option *d* is used if OCCT has been built in **Debug** mode.
526
527@subsection build_occt_code_blocks Building with Code::Blocks
528
529This file describes steps to build OCCT libraries from sources using **Code::Blocks**, a cross-platform IDE, using
530project files generated by OCCT legacy tool **genproj**.
531
532<h2>Configure</h2>
533
534Before building it is necessary to set up build environment.
535
536The environment is defined in the file *custom.sh* (on Linux and OS X) or *custom.bat* (on Windows) which can be edited
537directly:
538
539* Add paths to includes of used third-party libraries in variable *CSF_OPT_INC*.
540* Add paths to their binary libraries in variable *CSF_OPT_LIB64*.
541* Set variable *SHORTCUT_HEADERS* to specify a method for population of folder *inc* by header files. Supported methods are:
542 * *Copy* - headers will be copied from *src*;
543 * *ShortCut* - short-cut header files will be created, redirecting to same-named header located in *src*;
544 * "HardLink* - hard links to headers located in *src* will be created.
545* For optional third-party libraries, set corresponding environment variable <i>HAVE_<LIBRARY_NAME></i> to either *false*, e.g.:
546~~~~~
547 export HAVE_GL2PS=false
548~~~~~
549
550Alternatively, or when *custom.sh* or *custom.bat* does not exist, you can launch **genconf** tool to configure
551 environment interactively:
552
553@figure{/build/build_occt/images/genconf_linux.png}
554
555Click "Save" to store the specified configuration in *custom.sh* or *custom.bat* file.
556
557<h2>Generate Projects</h2>
558
559Launch **genproj** tool with option *cbp* to update content of *inc* folder and generate project files after changes in
560OCCT code affecting layout or composition of source files:
561
562~~~~~
563 $ cd /dev/OCCT/opencascade-7.0.0
564 $ ./genproj cbp
565~~~~~
566
567The generated Code::Blocks project are placed into subfolder *adm/&lt;OS&gt;/cbp*.
568
569@note To use **genproj** and **genconf** tools you need to have Tcl installed and accessible by PATH.
570
571<h2>Build</h2>
572
573To start **Code::Blocks**, launch script *codeblocks.sh*.
574
575To build all toolkits, click **Build->Build workspace** in the menu bar.
576
577To start *DRAWEXE*, which has been built with **Code::Blocks** on Mac OS X, run the script
578~~~~~
579 ./draw_cbp.sh cbp [d]
580~~~~~
a25d5aaa 581Option *d* is used if OCCT has been built in **Debug** mode.