diff --git a/dox/FILES.txt b/dox/FILES.txt index 0dbc6e01f0..b816e36647 100644 --- a/dox/FILES.txt +++ b/dox/FILES.txt @@ -14,14 +14,15 @@ user_guides/ocaf/ocaf.md user_guides/tobj/tobj.md user_guides/shape_healing/shape_healing.md user_guides/draw_test_harness/draw_test_harness.md -user_guides/wok/wok.md dev_guides/dev_guides.md -dev_guides/wok/wok.md dev_guides/cdl/cdl.md dev_guides/tests/tests.md dev_guides/documentation/documentation.md +dev_guides/wok/wok.md +dev_guides/building/building.md +dev_guides/building/wok/wok.md dev_guides/building/automake.md dev_guides/building/cmake.md dev_guides/building/code_blocks.md diff --git a/dox/Overview/LICENSE.md b/dox/Overview/LICENSE.md index afb9b4b517..135828613d 100644 --- a/dox/Overview/LICENSE.md +++ b/dox/Overview/LICENSE.md @@ -88,7 +88,7 @@ This License does not grant any rights to use the trademarks, trade names and do ### 11. Copyright -The Initial Developer retains all rights, title and interest in and to the Original Code. You may not remove the copyright © notice which appears when You download the Software. +The Initial Developer retains all rights, title and interest in and to the Original Code. You may not remove the copyright (c) notice which appears when You download the Software. ### 12. Term @@ -133,7 +133,7 @@ Open CASCADE S.A.S. is a French société par actions simplifiée having its mai The content of this file is subject to the Open CASCADE Technology Public License Version 6.5 (the "License"). You may not use the content of this file except in compliance with the License. -Please obtain a copy of the License at http://www.opencascade.org and read it completely before using this file. The Initial Developer of the Original Code is Open CASCADE S.A.S., with main offices at 1, place des Frères Montgolfier, 78280 Guyancourt, France. The Original Code is copyright © Open CASCADE S.A.S., 2001. All rights reserved. +Please obtain a copy of the License at http://www.opencascade.org and read it completely before using this file. The Initial Developer of the Original Code is Open CASCADE S.A.S., with main offices at 1, place des Frères Montgolfier, 78280 Guyancourt, France. The Original Code is copyright (c) Open CASCADE S.A.S., 2001. All rights reserved. "The Original Code and all software distributed under the License are distributed on an "AS IS" basis, without warranty of any kind, and the Initial Developer hereby disclaims all such warranties, including without limitation, any warranties of merchantability, fitness for a particular purpose or non-infringement. @@ -146,9 +146,9 @@ Please see the License for the specific terms and conditions governing rights an #### Schedule "B" -"The content of this file is subject to the Open CASCADE Technology Public License Version 6.5 (the "License"). You may not use the content of this file except in compliance with the License. Please obtain a copy of the License at http://www.opencascade.org and read it completely before using this file. The Initial Developer of the Original Code is Open CASCADE S.A.S., with main offices at 1, place des Frères Montgolfier, 78280 Guyancourt, France. The Original Code is copyright © Open CASCADE S.A.S., 2001. All rights reserved. +"The content of this file is subject to the Open CASCADE Technology Public License Version 6.5 (the "License"). You may not use the content of this file except in compliance with the License. Please obtain a copy of the License at http://www.opencascade.org and read it completely before using this file. The Initial Developer of the Original Code is Open CASCADE S.A.S., with main offices at 1, place des Frères Montgolfier, 78280 Guyancourt, France. The Original Code is copyright (c) Open CASCADE S.A.S., 2001. All rights reserved. -Modifications to the Original Code have been made by ________________________. Modifications are copyright © [Year to be included]. All rights reserved. +Modifications to the Original Code have been made by ________________________. Modifications are copyright (c) [Year to be included]. All rights reserved. The software Open CASCADE Technology and all software distributed under the License are distributed on an "AS IS" basis, without warranty of any kind, and the Initial Developer hereby disclaims all such warranties, including without limitation, any warranties of merchantability, fitness for a particular purpose or non-infringement. Please see the License for the specific terms and conditions governing rights and limitations under the License". diff --git a/dox/Overview/Overview.md b/dox/Overview/Overview.md index eb119f0966..7e34d0afcf 100644 --- a/dox/Overview/Overview.md +++ b/dox/Overview/Overview.md @@ -3,29 +3,31 @@ Overview {#mainpage} @section OCCT_OVW_SECTION_1 Welcome -Welcome to Open CASCADE Technology version 6.6.0, a minor release, +Welcome to Open CASCADE Technology version 6.7.0, a minor release, which introduces a number of new features and improved traditional -functionality along with some changes over the previous maintenance release 6.5.5. +functionality along with some changes over the previous release 6.6.0. This release makes Open CASCADE Technology even a more powerful and stable development platform for 3D modeling and numerical simulation applications. -Open CASCADE Technology 6.6.0 is a full-featured package that allows developing +Open CASCADE Technology 6.7.0 is a full-featured package that allows developing applications on Windows and Linux platforms. @htmlonly
@endhtmlonly http://www.opencascade.org -![](/overview/images/overview_occttransparent.png) +@image html /overview/images/overview_occttransparent.png +@image latex /overview/images/overview_occttransparent.png -Copyright © 2001-2013 OPEN CASCADE S.A.S. +Copyright (c) 2001-2013 OPEN CASCADE S.A.S. -![](/resources/occt_logo.png) +@image html /resources/occt_logo.png +@image latex /resources/occt_logo.png @htmlonly
@endhtmlonly @section OCCT_OVW_SECTION_2 Copyrights -Copyright© 2001-2013 by OPEN CASCADE S.A.S. All rights reserved. +Copyright(c) 2001-2013 by OPEN CASCADE S.A.S. All rights reserved. Trademark information ---------------------- @@ -77,7 +79,7 @@ text image generation tools, and many other products. FreeType 2 is released under two open-source licenses: BSD-like FreeType License and the GPL. -**Intel® Threading Building Blocks (TBB)** offers a rich and complete approach to expressing parallelism in a C++ program. +**Intel(R) Threading Building Blocks (TBB)** offers a rich and complete approach to expressing parallelism in a C++ program. It is a library that helps you to take advantage of multi-core processor performance without having to be a threading expert. Threading Building Blocks is not just a threads-replacement library. It represents a higher-level, task-based parallelism that abstracts platform details and threading mechanisms for scalability and performance. @@ -85,7 +87,7 @@ TBB is available under GPLv2 license with the runtime exception. Open CASCADE Technology WOK module on Windows also makes use of LGPL-licensed C routines * regexp and getopt, taken from GNU C library. -**Doxygen** (Copyright © 1997-2010 by Dimitri van Heesch) is open source documentation system for +**Doxygen** (Copyright (c) 1997-2010 by Dimitri van Heesch) is open source documentation system for C++, C, Java, Objective-C, Python, IDL, PHP and C#. This product is used in Open CASCADE Technology for automatic creation of Technical Documentation from C++ header files. If you need further information on Doxygen, please refer to http://www.stack.nl/~dimitri/doxygen/index.html. @@ -169,6 +171,74 @@ then run **wgendoc** command with required arguments e.g., wgendoc –output=d:/occt/doc {–m=Draw Visualization} -chm +@section OCCT_OVW_SECTION_5 Requirements + +@subsection OCCT_OVW_SECTION_5_1 Linux Intel + + + + + + + + + + + + + + + +
Operating System 64-bit: Mandriva 2010, CentOS 5. 5, CentOS 6.3, Fedora 17, Fedora 18, Ubuntu-1304, Debian 6.0 *
Minimum memory 512 Mb, 1 Gb recommended
Free disk space (complete installation) For full installation Open CASCADE Technology requires 600 Mb of disk space.
Minimum swap space 500 Mb
Video card **GeForce** The following versions of GeForce drivers are recommended: 64-bit Version: 100.14.19 or later http://www.nvidia.com/object/linux_display_amd64_100.14.19.html 32-bit Version: 100.14.19 or later http://www.nvidia.com/object/linux_display_ia32_100.14.19.html
Graphic library OpenGL 1.1+ (OpenGL 1.5+ is recommended)
C++ GNU gcc 4.0. - 4.7.3.
TCL (for testing tools) Tcltk 8.5 or 8.6 http://www.tcl.tk/software/tcltk/8.6.html
Qt (for demonstration tools) Qt 4.6.2 http://qt.nokia.com/downloads
Freetype (OCCT Text rendering) freetype-2.4.11 http://sourceforge.net/projects/freetype/files/
FreeImage (Support of common graphic formats) FreeImage 3.15.4 http://sourceforge.net/projects/freeimage/files/Source%20Distribution/
gl2ps (Export contents of OCCT viewer to vector graphic file) gl2ps-1.3.8 http://geuz.org/gl2ps/
TBB (optional tool for parallelized version of BRepMesh component) TBB 3.x or 4.x http://www.threadingbuildingblocks.org/
OpenCL (optional for providing ray tracing visualization core http://developer.amd.com/tools-and-sdks/heterogeneous-computing/amd-accelerated-parallel-processing-app-sdk/downloads/
+\* Debian 60 64 bit is a permanently tested platform. + +@subsection OCCT_OVW_SECTION_5_2 Windows Intel + + + + + + + + + + + + + + + + +
Operating System 32/64-bit: 8/ 7 SP1 / VISTA SP2 /XP SP3
Minimum memory 512 Mb, 1 Gb recommended
Free disk space (complete installation) For full installation Open CASCADE Technology requires 650 Mb of disk space but during the process of installation you will need 1,2 Gb of free disk space.
Minimum swap space 500 Mb
Video card **GeForce** Version 266.58 WHQL or later is recommended: http://www.nvidia.com/Download/index.aspx +
Graphic library OpenGL 1.1+ (OpenGL 1.5+ is recommended)
C++ Microsoft Visual Studio .NET 2005 SP1 with all security updates +Microsoft Visual Studio .NET 2008 SP1* +Microsoft Visual Studio .NET 2010 +Microsoft Visual Studio .NET 2012 +Microsoft Visual Studio .NET 2013 +
TCL (for testing tools) TActiveTcl 8.5 or 8.6 +http://www.activestate.com/activetcl/downloads
Qt (for demonstration tools) Qt 4.6.2 http://qt.digia.com/downloads
Freetype (OCCT Text rendering) freetype-2.4.11 http://sourceforge.net/projects/freetype/files/
FreeImage (Support of common graphic formats ) FreeImage 3.15.4 http://sourceforge.net/projects/freeimage/files/Source%20Distribution/
gl2ps (Export contents of OCCT viewer to vector graphic file) gl2ps-1.3.8 http://geuz.org/gl2ps/
TBB (optional tool for parallelized version of BRepMesh component) TBB 3.x or 4.x http://www.threadingbuildingblocks.org/
OpenCL (optional for providing ray tracing visualization core http://developer.amd.com/tools-and-sdks/heterogeneous-computing/amd-accelerated-parallel-processing-app-sdk/downloads/
+ +* The official release of OCCT for Windows contains libraries built with VC++ 2008. + + +@subsection OCCT_OVW_SECTION_5_3 MAC OS X + + + + + + + + + + + + + + + +
Operating System Mac OS X 10.6.8 Snow Leopard / 10.7 Lion
Minimum memory 512 Mb, 1 Gb recommended
Free disk space (complete installation) For full installation Open CASCADE Technology requires 600 Mb of disk space.
Minimum swap space 500 Mb
Video card **GeForce** Version 266.58 WHQL or later is recommended: http://www.nvidia.com/Download/index.aspx +
Graphic library OpenGL 1.1+ (OpenGL 1.5+ is recommended)
C++ XCode 3.2 or newer (4.x is recommended)
Qt (for demonstration tools) Qt 4.6.2 http://qt.digia.com/downloads
Freetype (OCCT Text rendering) freetype-2.4.11 http://sourceforge.net/projects/freetype/files/
FreeImage (Support of common graphic formats ) FreeImage 3.15.4 http://sourceforge.net/projects/freeimage/files/Source%20Distribution/
gl2ps (Export contents of OCCT viewer to vector graphic file) gl2ps-1.3.8 http://geuz.org/gl2ps/
TBB (optional tool for parallelized version of BRepMesh component) TBB 3.x or 4.x http://www.threadingbuildingblocks.org/
OpenCL (optional for providing ray tracing visualization core OpenCL 1.2.8 native
@section OCCT_OVW_SECTION_4 Installation @@ -209,26 +279,32 @@ and build it using the relevant tools. For additional convenience of the users, OPEN CASCADE also provides the documents with recommendations on building third-party products from source files. + + When the installation is complete, you will find the following directories (some might be absent in case of custom installation): -![](/overview/images/overview_installation.png) - -### Description of directory tree +@image html /overview/images/overview_installation.png "The directory tree" +@image latex /overview/images/overview_installation.png "The directory tree" - * **3rdparty** * This folder contains third-party products necessary to compile and use OCCT as well as start sample applications with Visual C++ 2008; - * **ros/adm** * This folder contains administration files, which allow rebuilding OCCT; - * **ros/adm/cmake** * This folder contains files of CMake building procedure; - * **ros/adm/msvc** * This folder contains Visual Studio projects for Visual C++ 2005, 2008 and 2010, which allow rebuilding OCCT under Windows platform in 32 and 64-bit mode; - * **ros/data** * This folder contains CAD files in different formats, which can be used to test the OCCT functionalities; - * **ros/doc** * This folder contains OCCT Overview documentation; - * **ros/drv** * This folder contains source files generated by WOK (private header files and instantiations of generic classes); - * **ros/inc** * This folder contains all OCCT header files; - * **ros/samples** * This folder contains sample applications. - * **ros/src** * This folder contains OCCT source files. They are organized in folders, one per development unit; - * **ros/tests** * This folder contains scripts for OCCT testing. - * **ros/win32/vc9** * This folder contains executable and library files built in optimize mode for Windows platform by Visual C++ 2008; + + * **adm** This folder contains administration files, which allow rebuilding OCCT; + * **adm/cmake** This folder contains files of CMake building procedure; + * **adm/msvc** This folder contains Visual Studio projects for Visual C++ 2005, 2008 and 2010, which allow rebuilding OCCT under Windows platform in 32 and 64-bit mode; + * **data** This folder contains CAD files in different formats, which can be used to test the OCCT functionalities; + * **doc** This folder contains OCCT Overview documentation; + * **drv** This folder contains source files generated by WOK (private header files and instantiations of generic classes); + * **inc** This folder contains all OCCT header files; + * **samples** This folder contains sample applications. + * **src** This folder contains OCCT source files. They are organized in folders, one per development unit; + * **tests** This folder contains scripts for OCCT testing. + * **win32/vc9** This folder contains executable and library files built in optimize mode for Windows platform by Visual C++ 2008; + +3rd party products have been moved to the root of Open CASCADE installation. + +@image html /overview/images/overview_3rdparty.png "The third-party products" +@image latex /overview/images/overview_3rdparty.png "The third-party products" @subsection OCCT_OVW_SECTION_4_2 System Environment Variables @@ -266,7 +342,7 @@ The scripts are located in the OpenCACADE/ros folder of the sour * **PATH** is required to define the path to OCCT binaries and 3rdparty folder; * **LD_LIBRARY_PATH** is required to define the path to OCCT libraries (on UNIX platforms only); * **MMGT_OPT** if set to 1, the memory manager performs optimizations as described below; if set to 2, - Intel ® TBB optimized memory manager is used; if 0 (default), every memory block is allocated + Intel (R) TBB optimized memory manager is used; if 0 (default), every memory block is allocated in C memory heap directly (via malloc() and free() functions). In the latter case, all other options except MMGT_CLEAR and MMGT_REENTRANT are ignored; * **MMGT_CLEAR** if set to 1 (default), every allocated memory block is cleared by zeros; @@ -312,89 +388,12 @@ in XML validators or editors, together with persistent XmlOcaf documents; * **CSF_MIGRATION_TYPES** is required in order to read documents that contain old data types, such as *TDataStd_Shape*; * **TCLLIBPATH**, **TCL_LIBRARY**, **TK_LIBRARY** and **TIX_LIBRARY** are required to allow work with **DRAW** and **WOK**. - -@section OCCT_OVW_SECTION_5 Requirements - -@subsection OCCT_OVW_SECTION_5_1 Linux Intel - -| Operating System | 32/64-bit: Debian: 4.0, Mandriva: 2010* | -| :--------------------------------------------- | :------------------------------------------------------------------------------------------------- | -| Minimum memory | 512 Mb, 1 Gb recommended | -| Free disk space (complete installation) | For full installation Open CASCADE Technology requires 600 Mb of disk space. | -| Minimum swap space | 500 Mb | -| Video card | GeForce, | -| | The following versions of GeForce drivers are recommended: | -| | 64-bit Version: 100.14.19 or later http://www.nvidia.com/object/linux_display_amd64_100.14.19.html | -| | 32-bit Version: 100.14.19 or later http://www.nvidia.com/object/linux_display_ia32_100.14.19.html | -| Graphic library | OpenGL 1.1+ (OpenGL 1.5+ is recommended) | -| C++ | GNU gcc 4.0. * 4.3.2. | -| TCL (for testing tools) | Tcltk 8.5 or 8.6 | -| | http://www.tcl.tk/software/tcltk/8.6.html | -| Qt (for demonstration tools) | Qt 4.6.2 http://qt.digia.com/downloads | -| Freetype (OCCT Text rendering) | freetype-2.4.10 | -| | http://sourceforge.net/projects/freetype/files/ | -| FreeImage (Support of common graphic formats ) | FreeImage 3.14.1 | -| | http://sourceforge.net/projects/freeimage/files/Source%20Distribution/ | -| gl2ps (Export contents of OCCT | gl2ps-1.3.5 | -| viewer to vector graphic file) | http://geuz.org/gl2ps/ | -| TBB (optional tool for parallelized | TBB 3.x or 4.x | -| version of BRepMesh component) | http://www.threadingbuildingblocks.org/ | - -@subsection OCCT_OVW_SECTION_5_2 Windows Intel - -| Operating System | 32/64-bit: 8/ 7 SP1 / VISTA SP2 /XP SP3 | -| :--------------------------------------------- | :----------------------------------------------------------------------------------------------- | -| Minimum memory | 512 Mb, 1 Gb recommended | -| Free disk space | For full installation Open CASCADE Technology requires 650 Mb of disk space. | -| (complete installation) | but during the process of installation you will need 1,2 Gb of free disk space. | -| Minimum swap space | 500 Mb | -| Video card | GeForce, | -| | Version 266.58 WHQL or later is recommended:http://www.nvidia.com/Download/index.aspx | -| Graphic library | OpenGL 1.1+ (OpenGL 1.5+ is recommended) | -| C++ | Microsoft Visual Studio .NET 2005 SP1 with all security updates | -| | Microsoft Visual Studio .NET 2008 SP1* | -| | Microsoft Visual Studio .NET 2010 | -| | Microsoft Visual Studio .NET 2012 | -| TCL (for testing tools) | ActiveTcl 8.5 or 8.6 | -| | http://www.activestate.com/activetcl/downloads | -| Qt (for demonstration tools) | Qt 4.6.2 http://qt.digia.com/downloads | -| Freetype (OCCT Text rendering) | freetype-2.4.10 | -| | http://sourceforge.net/projects/freetype/files/ | -| FreeImage (Support of common graphic formats ) | FreeImage 3.14.1 | -| | http://sourceforge.net/projects/freeimage/files/Source%20Distribution/ | -| gl2ps (Export contents of OCCT | gl2ps-1.3.5 | -| viewer to vector graphic file) | http://geuz.org/gl2ps/ | -| TBB (optional tool for parallelized | TBB 3.x or 4.x | -| version of BRepMesh component) | http://www.threadingbuildingblocks.org/ | - -@subsection OCCT_OVW_SECTION_5_3 MAC OS X - -| Operating System | Requires Mac OS X 10.6.8 Snow Leopard / 10.7 Lion | -| :--------------------------------------------- | :----------------------------------------------------------------------------------------------- | -| Minimum memory | 512 Mb, 1 Gb recommended | -| Free disk space (complete installation) | For full installation Open CASCADE Technology requires 600 Mb of disk space. | -| Minimum swap space | 500 Mb | -| Graphic library | OpenGL 1.1+ (OpenGL 1.5+ is recommended) | -| C++ | XCode 3.2 or newer (4.x is recommended) | -| TCL (for testing tools) | Tcltk 8.5 or 8.6 | -| | http://www.tcl.tk/software/tcltk/8.6.html | -| Qt (for demonstration tools) | Qt 4.6.2 http://qt.digia.com/downloads | -| Freetype (OCCT Text rendering) | freetype-2.4.10 | -| | http://sourceforge.net/projects/freetype/files/ | -| FreeImage (Support of common graphic formats ) | FreeImage 3.14.1 | -| | http://sourceforge.net/projects/freeimage/files/Source%20Distribution/ | -| gl2ps (Export contents of OCCT | gl2ps-1.3.5 | -| viewer to vector graphic file) | http://geuz.org/gl2ps/ | -| TBB (optional tool for parallelized | TBB 3.x or 4.x | -| version of BRepMesh component) | http://www.threadingbuildingblocks.org/ | - - @section OCCT_OVW_SECTION_6 Release Notes Open CASCADE Technology latest version @htmlonly -Release Notes +Release Notes @endhtmlonly (PDF) @@ -407,7 +406,8 @@ Draw is a command interpreter based on TCL and a graphical system used for testi Draw can be used interactively to create, display and modify objects such as curves, surfaces and topological shapes. -![](/overview/images/overview_draw.png "") +@image html /overview/images/overview_draw.png +@image latex /overview/images/overview_draw.png Scripts can be written to customize Draw and perform tests. New types of objects and new commands can be added using C++ programming language. @@ -528,7 +528,8 @@ The list of MFC samples: * Animation * Convert -![](/overview/images/overview_mvc.png "") +@image html /overview/images/overview_mvc.png +@image latex /overview/images/overview_mvc.png **Remarks:** @@ -545,7 +546,8 @@ OCCT contains three samples based on Qt application framework Import Export programming sample contains 3D Viewer and Import // Export functionality. -![](/overview/images/overview_qt.png "") +@image html /overview/images/overview_qt.png +@image latex /overview/images/overview_qt.png Tutorial --------- @@ -582,7 +584,8 @@ for testing this functionality (accessible only through TEST pre-processor defin C# sample containing 3D Viewer and Import // Export functionality. -![](/overview/images/overview_c__ie.png "") +@image html /overview/images/overview_c__ie.png +@image latex /overview/images/overview_c__ie.png Import: @@ -602,3 +605,7 @@ Export: * C# sample is available only on Windows platform; * It is delivered in source code only and must be built with Microsoft Visual C++ 2005. + + + + diff --git a/dox/dev_guides/building/building.md b/dox/dev_guides/building/building.md new file mode 100644 index 0000000000..25ef343e6d --- /dev/null +++ b/dox/dev_guides/building/building.md @@ -0,0 +1,32 @@ +Building OCCT Libraries {#dev_guides__building} +========= + +The source package of the Open CASCADE Technology including the source files of samples +and tools and the set of building procedures is available for self-dependent preparation +binary files on UNIX and Windows platforms. + +In order to build OCCT libraries from these sources for use in your program, +you need to: + +1. Install the required third-party libraries. + + Follow the instructions provided in the documents titled "Building 3rd party + products for OCCT" on http://dev.opencascade.org/?q=home/resources for + choice of the needed libraries, their installation and building. + +2. If you use OCCT sources from Git repository or do come changes affecting + CDL files or dependencies of OCCT toolkit, update header files generated + from CDL, and regenerate build scripts for your environment using WOK. + See \subpage dev_guides__building__wok "WOK" for details. + + Skip to step 3 if you use complete source package (e.g. official OCCT + release) without changes in CDL. + +3. Build using your preferred build tool. + - \subpage dev_guides__building__automake "Building on Linux with Autotools" + - \subpage dev_guides__building__cmake "Building with CMake (cross-platform)" + - \subpage dev_guides__building__code_blocks "Building on Mac OS X with Code::Blocks" + - \subpage dev_guides__building__msvc "Building on Windows with MS Visual Studio 2005-2012" + - \subpage dev_guides__building__xcode "Building on Mac OS X with Xcode" + +The current version of OCCT can be consulted in the file src/Standard/Standard_Version.hxx \ No newline at end of file diff --git a/dox/dev_guides/building/wok/images/wok_image001.jpg b/dox/dev_guides/building/wok/images/wok_image001.jpg new file mode 100644 index 0000000000..37fd7350d4 Binary files /dev/null and b/dox/dev_guides/building/wok/images/wok_image001.jpg differ diff --git a/dox/dev_guides/building/wok/images/wok_image002.jpg b/dox/dev_guides/building/wok/images/wok_image002.jpg new file mode 100644 index 0000000000..b805c9b218 Binary files /dev/null and b/dox/dev_guides/building/wok/images/wok_image002.jpg differ diff --git a/dox/dev_guides/wok/images/wok_image003.jpg b/dox/dev_guides/building/wok/images/wok_image003.jpg similarity index 100% rename from dox/dev_guides/wok/images/wok_image003.jpg rename to dox/dev_guides/building/wok/images/wok_image003.jpg diff --git a/dox/dev_guides/wok/images/wok_image004.jpg b/dox/dev_guides/building/wok/images/wok_image004.jpg similarity index 100% rename from dox/dev_guides/wok/images/wok_image004.jpg rename to dox/dev_guides/building/wok/images/wok_image004.jpg diff --git a/dox/dev_guides/building/wok/wok.md b/dox/dev_guides/building/wok/wok.md new file mode 100644 index 0000000000..784936f7d3 --- /dev/null +++ b/dox/dev_guides/building/wok/wok.md @@ -0,0 +1,157 @@ +WOK {#dev_guides__building__wok} +========= + +WOK is a legacy build environment for Open CASCADE Technology. It is required +for generation of header files for classes defined with @ref ug_cdl "CDL" +("Cascade Definition Language"). Also tools for generation of project files +for other build systems, and OCCT documentation, are integrated to WOK. + +WOK thus is needed in the following situations: +- Building from OCCT sources from Git repository (do not contain generated files) +- Building after some changes made in CDL files + +Before installing and using WOK, make sure that you have installed a compiler (it is assumed that it is Visual Studio on Windows or gcc on Linux and MacOS) and third-party components required for building OCCT. + +@section wok1 Installing WOK + + Download the latest version of binary distribution WOK from http://dev.opencascade.org/index.php?q=home/resources + +@subsection wok11 Windows + + Run the installer. You will be prompted to read and accept the OCCT Public License to proceed: + + @image html /dev_guides/building/wok/images/wok_image001.jpg + @image latex /dev_guides/building/wok/images/wok_image001.jpg + + Click Next and proceed with the installation. + At the end of the installation you will be prompted to specify the version and the location of Visual Studio to be used, and the location of third-party libraries: + + @image html /dev_guides/building/wok/images/wok_image002.jpg + @image latex /dev_guides/building/wok/images/wok_image002.jpg + + You can change these settings at any time later. For this click on the item "Customize environment (GUI tool)" in the WOK group in the Windows Start menu. + + The shortcuts from this group provide two ways to run WOK: + * In command prompt window ("WOK TCL shell"). + * In Emacs editor ("WOK Emacs"). Using Emacs is convenient if you need to work within WOK environment. + + By default WOK installer creates a WOK factory with name "LOC" within workshop "dev" (WOK path :LOC:dev). + +@subsection wok12 Linux + + * Unpack the .tgz archive containing WOK distributive into an installation directory . + + * Perform the following commands assuming that you have unpacked WOK distributive archive into : + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl} + cd /site + wok_confgui.sh + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Define all necessary paths to third-party products in the dialog window: + + @image html /dev_guides/building/wok/images/wok_image003.jpg + @image latex /dev_guides/building/wok/images/wok_image003.jpg + + * Run the following commands to create WOK LOC factory: + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl} + cd /site + wok_init.sh + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + * Your installation procedure is over. To run WOK use one the following commands: + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl} + cd /site + wok_emacs.sh + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + or + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl} + cd /site + wok_tclsh.sh + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +@subsection wok13 Mac OS X + + * In the Finder double click on wokSetup.dmg file. This will open a new window. Drag and drop "wokSetup" folder from this window at the location in the Finder where you want to install WOK, i.e. . + + * Browse in the Finder to the folder /site and double click on WokConfig. This will open a window with additional search path settings. Define all necessary paths to third-party products in the dialog window: + + @image html /dev_guides/building/wok/images/wok_image004.jpg + @image latex /dev_guides/building/wok/images/wok_image004.jpg + + * Run the following commands to create WOK LOC factory: + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl} + cd /site + wok_init.sh + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + * Your installation procedure is over. To run WOK in Emacs navigate in the Finder to the folder /site and double click on WokEmacs. + + +@section wok2 Initialization of Workbench + + To start working with OCCT, clone the OCCT Git repository from the server (see http://dev.opencascade.org/index.php?q=home/resources for details) or unpack the source archive. + + Then create a WOK workbench (command wcreate) setting its Home to the directory, where the repository is created ($CASROOT variable). The workbench should have the same name as that directory. + + For example, assuming that OCCT repository has been cloned into D:/occt folder: + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl} + LOC:dev> wcreate occt -DHome=D:/occt + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Note: $CASROOT is equal to D:/occt now + + Then you can work with this workbench using normal WOK functionality (wprocess, umake, etc.; see WOK Users Guide for details) or use it only for generation of derived sources and project files, and build OCCT with Visual Studio on Windows or make command on Linux, as described below. + +@section wok3 Generation of building projects + + Use command wgenproj in WOK to generate derived headers, source and building projects files: + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl} + LOC:dev> wokcd occt + LOC:dev:occt> wgenproj [ -target= ] [ -no_wprocess ] + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +TARGET: + * vc8 - Visual Studio 2005 + * vc9 - Visual Studio 2008 + * vc10 - Visual Studio 2010 + * vc11 - Visual Studio 2012 + * cbp - CodeBlocks + * cmake - CMake + * amk - AutoMake + * xcd - Xcode +-no_wprocess - skip generation of derived headers and source files + +Note that this command takes several minutes to complete at the first call. + +Re-execute this step to generate derived headers, source and building projects files if some CDL files in OCCT have been modified (either by you directly, or due to updates in the repository). Note that in some cases WOK may fail to update correctly; in such case remove sub-directories drv and .adm and repeat the command. + +To regenerate derived headers and source files without regeneration of projects use command: + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl} + LOC:dev> wokcd occt + LOC:dev:occt> wprocess -DGroups=Src,Xcpp + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The generated building project has been placed into $CASROOT/adm folder: + * for vc8 - $CASROOT/adm/msvc/vc8 + * for vc9 - $CASROOT/adm/msvc/vc9 + * for vc10 - $CASROOT/adm/msvc/vc10 + * for vc11 - $CASROOT/adm/msvc/vc11 + * for cbp - $CASROOT/adm/ /cbp + * for cmake - $CASROOT/adm/cmake + * for amk - $CASROOT/adm/lin/amk + * xcd - $CASROOT/adm//xcd + +@section wok4 Generation of documentation + + Use command wgendoc in WOK to generate reference documentation: + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl} + :LOC:dev> wokcd occt + :LOC:dev:occt> wgendoc + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The following options can be used: + * -wb=< workbench name > the name of OCCT workbench (the current one by default); + * -m=< list of modules > the list of modules that will be contained in the documentation; + * -outdir=< path > the output directory for the documentation; + * -chm the option to generate CHM file; + * -hhc=< path > the path to HTML Help Compiler (hhc.exe) or equivalent; + * -qthelp=< path > the option to generate Qt Help file, it is necessary to specify the path to qthelpgenerator executable; + * -doxygen=< path > the path to Doxygen executable + * -dot=< path > the path to GraphViz dot executable \ No newline at end of file diff --git a/dox/dev_guides/cdl/cdl.md b/dox/dev_guides/cdl/cdl.md index bde49759c6..279e2db3a9 100644 --- a/dox/dev_guides/cdl/cdl.md +++ b/dox/dev_guides/cdl/cdl.md @@ -18,21 +18,10 @@ Using the services described in the **packages**, you can construct an **execut To save data in a file, you need to define persistent classes. Then, you group these classes in a schema, which provides the necessary read/write tools. - - - - - - - - -
- -
- - - ![](/devs_guide/cdl/images/cdl_image003.jpg) -
+ + @image html /dev_guides/cdl/images/cdl_image003.jpg + @image latex /dev_guides/cdl/images/cdl_image003.jpg + Figure 1. Building an Open CASCADE Technology application @section occt_1819379591_986437237 2. Introduction to CDL @subsection occt_1819379591_98643723721 Purposes of the Language @@ -40,21 +29,8 @@ You can use CDL to **define data **in the Open CASCADE Technology environment. You use CDL in the **design phase **of a development process to define a set of software components which best model the concepts stated in the application specification. - - - - - - - - -
- -
- - - ![](/devs_guide/cdl/images/cdl_image004.jpg) -
+ @image html /dev_guides/cdl/images/cdl_image004.jpg + @image latex /dev_guides/cdl/images/cdl_image004.jpg Figure 2. The Development Process @@ -120,21 +96,9 @@ You declare the variables of a **data manipulation language **as being of certa * Data types manipulated by handle (or reference) * Data types manipulated by value - - - - - - - - -
- -
- - - ![](/devs_guide/cdl/images/cdl_image005.jpg) -
+ + @image html /dev_guides/cdl/images/cdl_image005.jpg + @image latex /dev_guides/cdl/images/cdl_image005.jpg Figure 3. Manipulation of data types @@ -333,16 +297,16 @@ Capital and small letters are not equivalent (i.e. AB, Ab, aB, ab are four diff The following is a list of keywords. -alias                      any                   as                     asynchronous -class                     client                deferred            end -enumeration           exception          executable        external -fields                     friends              from                 generic -immutable              imported           inherits              instantiates -is                          library               like                   me -mutable                 myclass            out                   package -pointer                   primitive            private              protected -raises                    redefined          returns              schema -static                     to                     uses                 virtual +alias any as asynchronous +class client deferred end +enumeration exception executable external +fields friends from generic +immutable imported inherits instantiates +is library like me +mutable myclass out package +pointer primitive private protected +raises redefined returns schema +static to uses virtual In a CDL file, the following characters are used as punctuation: ; : , = ( ) [ ] ‘ “ @@ -361,12 +325,12 @@ There are two types of numeric constants: integer and real. An **integer **constant consists of a string of digits, which may or may not be preceded by a sign. Integer constants express whole numbers. **Examples** -1995         0           -273         +78 +1995 0 -273 +78 A **real **constant may or may not be preceded by a sign, and consists of an integral part followed by a decimal point and a fractional part (either one or both parts may be null, but both parts must always be present). It may also be followed by the letter E to indicate that the following figures represent the exponent (also optionally signed). **Examples** -5.0        0.0          -0.8E+3          5.67E-12 +5.0 0.0 -0.8E+3 5.67E-12 ***Literal Constants*** @@ -375,12 +339,12 @@ Literal constants include individual characters and strings of characters. An **individual character **constant is a single printable character enclosed by two apostrophes. (See the definition of the class Character in the Standard Package). **Examples** - ‘B’      ‘y’      ‘&’      ‘*’      ‘’’ ‘‘ + ‘B’ ‘y’ ‘&’ ‘*’ ‘’’ ‘‘ A **string **constant is composed of printable characters enclosed by quotation marks. **Examples** -’’G’’     ’’jjjj’’     ’’This is a character string, isn’t it?’’ +’’G’’ ’’jjjj’’ ’’This is a character string, isn’t it?’’ The **quotation mark **can itself appear within a character string as long as it is preceded by a backslash. **Examples** @@ -408,20 +372,20 @@ Four of these primitives are known to the schema of the database because they i The primitives inheriting from Storable are the following: -**Boolean                **Is used to represent logical data. It has only two values: +**Boolean **Is used to represent logical data. It has only two values: *True *and *False*. -**Byte                      **8-bit number. -**Character              **Designates any ASCII character. -**ExtCharacter         **Is an extended character. -**Integer                  **Is an integer number. -**Real                                  **Denotes a real number (i.e. one with a whole and a fractional part, either of which may be null). -**ShortReal              **Real with a smaller choice of values and memory size. +**Byte **8-bit number. +**Character **Designates any ASCII character. +**ExtCharacter **Is an extended character. +**Integer **Is an integer number. +**Real **Denotes a real number (i.e. one with a whole and a fractional part, either of which may be null). +**ShortReal **Real with a smaller choice of values and memory size. There are also non-storable primitives. They are: -**CString                 **Is used for literal constants. -**ExtString              **Is an extended string. -**Address                **Represents a byte address of undetermined size. +**CString **Is used for literal constants. +**ExtString **Is an extended string. +**Address **Represents a byte address of undetermined size. The services offered by each of these types are described in the Standard Package. @@ -435,7 +399,8 @@ Two types are manipulated by handle: * Types defined using classes inheriting from the **Transient **class. These types are not storable as such in a file. -![](/devs_guide/cdl/images/cdl_image006.jpg) +@image html /dev_guides/cdl/images/cdl_image006.jpg +@image latex /dev_guides/cdl/images/cdl_image006.jpg Figure 4. Manipulation of a data type by reference @@ -446,22 +411,9 @@ Types, which are manipulated by value, behave in a more direct fashion than tho You can store types known to the schema (i.e. either primitives or inheriting from Storable) and manipulated by value inside a persistent object as part of the representation. This is the only way for you to store objects “manipulated by value” in a file. - - - - - - - - - -
- -
- - - ![](/devs_guide/cdl/images/cdl_image007.jpg) -
+ @image html /dev_guides/cdl/images/cdl_image007.jpg + @image latex /dev_guides/cdl/images/cdl_image007.jpg + Figure 5. Manipulation of a data type by value Three types are manipulated by value: @@ -522,21 +474,10 @@ The elements, which make up the definition of a class, are divided into four pa * the invariants * the internal representation * the friend methods and friend classes. - - - - - - - - -
- -
- - - ![](/devs_guide/cdl/images/cdl_image009.jpg) -
+ + @image html /dev_guides/cdl/images/cdl_image009.jpg + @image latex /dev_guides/cdl/images/cdl_image009.jpg + **Figure 7. Contents of a class** *** a deferred class does not have to contain a constructor** @@ -588,7 +529,7 @@ data-type}’)’] @subsubsection occt_1819379591_1718435309331 Package declaration - **Packages** are used to group   classes, which have some logical coherence. For example, the Standard Package groups together all the predefined resources of the language. In its simplest form, a package contains the declaration of all data types, which it introduces. You may also use a package to offer public methods and hide its internal classes by declaring them private. + **Packages** are used to group classes, which have some logical coherence. For example, the Standard Package groups together all the predefined resources of the language. In its simplest form, a package contains the declaration of all data types, which it introduces. You may also use a package to offer public methods and hide its internal classes by declaring them private. ** ** **Example** @@ -629,7 +570,8 @@ Grouped behind the keyword **uses **are the names of all the packages containin The methods you declare in a package do not belong to any particular class. **Package methods ***must *carry a name different from the data types contained in the package. Like any other method, they can be overloaded. With the exception of the keyword **me **and the visibility (a package method can *only *be either public or private) package methods are described in the same way as **instance methods**. -![](/devs_guide/cdl/images/cdl_image010.jpg) +@image html /dev_guides/cdl/images/cdl_image010.jpg +@image latex /dev_guides/cdl/images/cdl_image010.jpg Figure 8. Contents of a package The example of the package below includes some of the basic data structures: @@ -716,7 +658,7 @@ is end SingleList; -- Third compilation unit, the class “Set” : generic class Set from Collection (Item as Storable) -  inherits + inherits Persistent from Standard; raises NoSuchObject from Collection, @@ -724,7 +666,7 @@ NoMoreObject from Collection private class Node instantiates SingleList from Collection (Item); -- etc.... - end Set; + end Set; NOTE @@ -828,7 +770,7 @@ const Handle(Standard_Type)& TYPE (MyPack_MyImport) static Handle(Standard_Type) _aType = new Standard_Type (“MyPack_MyImport”,sizeof (MyPack_MyImport)) - return _aType; + return _aType; } Then, add the names of these two files (MyPack_MyImport.hxx, MyPack_MyImport.cxx) to a file called FILES in the src subdirectory of the package. If the file does not exist you must create it. @@ -938,11 +880,11 @@ end; The behavior of an object class is defined by a list of **methods, **which are either **functions **or **procedures**. Functions return an object, whereas procedures only communicate by passing arguments. In both cases, when the transmitted object is an instance manipulated by a handle, its identifier is passed. There are three categories of methods: -**Object constructor            **Creates an instance of the described class. A class will have one or more object constructors with various arguments or none. +**Object constructor **Creates an instance of the described class. A class will have one or more object constructors with various arguments or none. -**Instance method               **Operates on the instance which owns it. +**Instance method **Operates on the instance which owns it. -**Class method                    **Does not work on individual instances, only on the class                                                     itself. +**Class method **Does not work on individual instances, only on the class itself. @subsubsection occt_1819379591_1972310108411 Object Constructors @@ -965,7 +907,7 @@ numeric-constant | literal-constant | named-constant declaration-of-constructed-type ::= **returns **[ **mutable **] class-name -The name of the constructors is fixed: “Create”. The object returned by a constructor  is always of the type of the described class. If that type is manipulated by a handle, you *must *declare it as **mutable**, in which case the content of the instance it references is accessible for further modification. +The name of the constructors is fixed: “Create”. The object returned by a constructor is always of the type of the described class. If that type is manipulated by a handle, you *must *declare it as **mutable**, in which case the content of the instance it references is accessible for further modification. For example, the constructor of the class “Point” **Example** @@ -1004,7 +946,7 @@ identifier formal-part-of-instance-method [ declaration-of-returned-type ] [ exception-declaration ] formal-part-of-instance-method ::= - ’(’ me [’:’ passing-mode parameter-access ] {’;’ + ’(’ me [’:’ passing-mode parameter-access ] {’;’ parameter}’)’ parameter ::= identifier {’,’ identifier} ’:’ passing-mode @@ -1124,8 +1066,8 @@ coord: Real[3]; Depending on their type, Object fields have one of the two forms. When the field is of the “manipulated by handle” type, it corresponds to an identifier. In this case, the contents of the object can be shared by other objects or by a handle in a program. When the field is of a “manipulated by value” type, it contains the value of the object. In this case you say the object is **embedded**. @subsection occt_1819379591_197231010843 Exceptions -  -Exceptions describe exceptional situations, which can arise during the execution of a method. With the raising of an exception, the normal course of program execution is interrupted. The actions carried out in response to this situation are called  treatment of exception. + +Exceptions describe exceptional situations, which can arise during the execution of a method. With the raising of an exception, the normal course of program execution is interrupted. The actions carried out in response to this situation are called treatment of exception. exception-treatment ::= **raises **exception-name {’,’ exception-name} @@ -1146,11 +1088,11 @@ raises OutOfRange; Instance methods are likely to raise certain exceptions called **systematic exceptions **which do not have to appear. They are: -**NullObject                         **Raised when the principal object does not exist. +**NullObject **Raised when the principal object does not exist. -**ImmutableObject                          **Raised when a method tries to modify an immutable principal object. +**ImmutableObject **Raised when a method tries to modify an immutable principal object. -**TypeMismatch                              **Raised if an argument typed by association is of an unsuitable type. +**TypeMismatch **Raised if an argument typed by association is of an unsuitable type. These exceptions are described in the Standard Package (System Toolkits). @@ -1176,7 +1118,7 @@ declaration-of-a-sub-class ::= A class cannot inherit one of its descendent classes; nor can it inherit a native type. All the classes of a system can be described in a non-cyclic diagram called the **inheritance graph**. -The definition of a sub-class is identical to that of a simple class. Note that a super-class *must not *appear in the **uses **clause of the sub-class, even if it appears in the definition of the sub-class. The behavior of a sub-class includes as a minimum all  instance methods and protected methods of its super-classes. +The definition of a sub-class is identical to that of a simple class. Note that a super-class *must not *appear in the **uses **clause of the sub-class, even if it appears in the definition of the sub-class. The behavior of a sub-class includes as a minimum all instance methods and protected methods of its super-classes. NOTE Note that constructors and class methods are never inherited. @@ -1191,7 +1133,7 @@ declaration-of-a-redefined-method ::= identifier formal-part-of-instance-method [returnedtype- declaration] [declaration-of-exceptions] -**  is redefined **[visibility]’;’ +** is redefined **[visibility]’;’ A redefined method must conform to the syntax described in the super-class where it appears. The exceptions contained in the super-class can be renewed, and others may be added as long as they inherit from an ancestor class. @@ -1212,7 +1154,7 @@ declaration-of-a-non-redefinable-method ::= identifier formal-part-of-instance-method [returnedtype- declaration] [declaration-of-exceptions] -** is virtual **[visibility]’;’ +** is virtual **[visibility]’;’ All methods are static by default. To enable redefinition in all the child classes, add “**is virtual;**“ when declaring the method. @@ -1228,7 +1170,7 @@ The CDL language allows you to describe a class, which introduces methods witho declaration-of-a-deferred-class ::= **deferred class **class-name - [**inherits **class-name + [**inherits **class-name [**uses **data-type {’,’ data-type}] [**raises **exception-name {’,’ exception-name}] **is **class-definition @@ -1376,29 +1318,29 @@ inherits Persistent raises NoSuchObject is Create returns mutable SingleList; -    ---Purpose: Creates an empty list + ---Purpose: Creates an empty list IsEmpty (me) returns Boolean; -    ---Purpose: Returns true if the list me is empty + ---Purpose: Returns true if the list me is empty SwapTail (me : mutable; S : in out mutable SingleList) -    ---Purpose: Exchanges the tail of list me with S + ---Purpose: Exchanges the tail of list me with S -- Exception NoSuchObject raised when me is empty raises NoSuchObject; -   Value (me) returns Item -   ---Purpose: Returns first element of the list me + Value (me) returns Item + ---Purpose: Returns first element of the list me -- Exception NoSuchObject raised when me is empty raises NoSuchObject; -   Tail (me) returns mutable SingleList + Tail (me) returns mutable SingleList ---Purpose: Returns the tail of the list me -- Exception NoSuchObject raised when me is empty raises NoSuchObject; -   fields + fields Data : Item; -   Next : SingleList; -   end SingleList; + Next : SingleList; + end SingleList; Even though no object of the type “SingleList” IS created, the class contains a constructor. This class constitutes a model, which will be recopied at instantiation time to create a new class which will generate objects. The constructor will then be required. **Example** @@ -1423,7 +1365,7 @@ The syntax is as follows: instantiation-of-a-generic-class ::= [**deferred**] **class **class-name -**     instantiates **class-name ’(’data-type {’,’ +** instantiates **class-name ’(’data-type {’,’ data-type}’);’ Instantiation is said to be **static**. In other words, it must take place before any use can be made of the type of the instantiated class. Each data type is associated term by term with those declared at the definition of the generic class. These latter ones, when they are not of the type **any**, restrict instantiation to those classes, which have a behavior at least equal to that of the class specified in the type constraint, including constructors. Note that this is not guaranteed by inheritance itself. @@ -1443,18 +1385,18 @@ It often happens that many classes are linked by a common generic type. This is **Example** declaration-of-a-generic-class ::= -   [**deferred**] **generic class **class-name ’(’generic- + [**deferred**] **generic class **class-name ’(’generic- type{’,’generic-type}’)’ -   [**inherits **class-name {’,’ class-name}] -   [**uses **data-type {’,’ data-type}] -   [**raises **exception-name {’,’ exception-name}] -   [{[visibility] class-declaration}] -**   is **class-definition + [**inherits **class-name {’,’ class-name}] + [**uses **data-type {’,’ data-type}] + [**raises **exception-name {’,’ exception-name}] + [{[visibility] class-declaration}] +** is **class-definition **end **[class-name]’;’ -   class-declaration ::= -   incomplete-declaration-of-a-class | -   declaration-of-a-non-generic-class | -  instantiation-of-a-generic-class + class-declaration ::= + incomplete-declaration-of-a-class | + declaration-of-a-non-generic-class | + instantiation-of-a-generic-class **Nested classes**, even though they are described as non-generic classes, are generic by construction, being inside the class of which they are a part. As a consequence, the generic types introduced by the **encompassing class **can be used in the definition of the nested class. This is true even if the generic type is only used in a nested class. The generic types still* must *appear as an argument of the encompassing class. All other types used by a nested class *must *appear in its **uses **or **raises **clauses, just as if it were an independent class. @@ -1467,34 +1409,34 @@ generic class Set (Item as Storable) inherits Persistent private class Node instantiates SingleList (Item); class Iterator -   uses Set, Node -   raises NoSuchObject, NoMoreObject -   is -   Create (S : Set) returns mutable Iterator; + uses Set, Node + raises NoSuchObject, NoMoreObject + is + Create (S : Set) returns mutable Iterator; ---Purpose: Creates an iterator on the group S -   More (me) returns Boolean; + More (me) returns Boolean; ---Purpose: Returns true if there are still elements -   -- to explore -   Next (me) raises NoMoreObject; + -- to explore + Next (me) raises NoMoreObject; ---Purpose: Passes to the following element -   Value (me) returns any Item raises NoSuchObject; + Value (me) returns any Item raises NoSuchObject; ---Purpose: Returns the current element -   fields -   Current : Node; + fields + Current : Node; end Iterator; is -   Create returns mutable Set; + Create returns mutable Set; ---Purpose: Creates an empty group -   IsEmpty (me) returns Boolean; + IsEmpty (me) returns Boolean; ---Purpose: Returns true if the group is empty -   Add (me : mutable; T : Item); + Add (me : mutable; T : Item); ---Purpose: Adds an item to the group me -   Remove (me : mutable; T : item) raises + Remove (me : mutable; T : item) raises NoSuchObject; ---Purpose: Removes an item from the group me -   etc. -   fields -   Head : Node; + etc. + fields + Head : Node; end Set; Note that in their fields, both “Set” and “Iterator” are clients of another class, “Node”. This last can be effectively declared **private **for it only appears in fields which are themselves private. @@ -1543,19 +1485,19 @@ identifier {’,’ identifier} ’:’ data-type Example fields -   Phi, Delta, Gamma : AngularMomenta [3] -   is protected ; + Phi, Delta, Gamma : AngularMomenta [3] + is protected ; @subsubsection occt_1819379591_1972310108463 Visibility of Methods Methods act on fields. Only methods belonging to a class can act on the fields of the class; this stems from the principle of object encapsulation. Methods can be characterized in three ways: by default, methods are **public**. Methods can be declared **private **or **protected **to restrict their usage. -**Public methods                            **Are the default and are generally the most common. They describe the behavior of a class or a package, and they are callable by any part of a program. +**Public methods **Are the default and are generally the most common. They describe the behavior of a class or a package, and they are callable by any part of a program. -**Private methods                            **Exist only for the internal structuring of their class or their package. Private class methods can only be called by methods belonging to the same class. Private package methods can only be called by all methods belonging to the same package and its classes. +**Private methods **Exist only for the internal structuring of their class or their package. Private class methods can only be called by methods belonging to the same class. Private package methods can only be called by all methods belonging to the same package and its classes. -**Protected methods            **Are private methods, which are also callable from the interior of descendent classes. +**Protected methods **Are private methods, which are also callable from the interior of descendent classes. If you want to restrict the usage of a method, you associate with it a visibility as follows : @@ -1588,15 +1530,15 @@ Friend classes or methods are declared inside the class, which reveals its priv declaration-of-friends ::= **friends **friend {’,’friend} -   friend ::= -   identifier **from **[**class**] class-name [formal-part] | + friend ::= + identifier **from **[**class**] class-name [formal-part] | **Defining the Software Components 67** identifier **from **[**package**] package-name [formal-part] | -**   class**] class-name -   formal-part ::= -   simple-formal-part | -   formal-part-of-instance-method | -   formal-part-of-class-method +** class**] class-name + formal-part ::= + simple-formal-part | + formal-part-of-instance-method | + formal-part-of-class-method The formal part *must *be presented if the method contains one; thus this can be overloaded without necessarily propagating the friend relationship among its homonyms. The keyword **class **allows you to avoid certain ambiguities. For example, it removes any confusion between “method M from class C” and “method M from package P”. @@ -1606,23 +1548,11 @@ As an example, take a method, which calculates the perpendicular distance betwe friends Distance from Line (me; P : Point) A method can be a friend to many classes. The class to which the method belongs does *not *need to appear in the **uses **clause of other classes of which it is a friend. - - - - - - - - -
- -
- - - ![](/devs_guide/cdl/images/cdl_image011.jpg) -
When the methods of a class are all friends of another class, you can establish the friendship at the level of the class. + @image html /dev_guides/cdl/images/cdl_image011.jpg + @image latex /dev_guides/cdl/images/cdl_image011.jpg +When the methods of a class are all friends of another class, you can establish the friendship at the level of the class. Figure 9. Visibility of various components @section occt_1819379591_858765726 Appendix A. Syntax Summary @@ -1754,7 +1684,7 @@ redefinition |** ****redefined**** **[redefinition] **raises**** **exception-name {’,’ exception-name} (35) declaration-of-visibility ::= -**is****  **visibility +**is**** **visibility (36) declaration-of-attributes-of-instance-method ::= **is**** **visibility | **is **definition-of-level @@ -1844,7 +1774,7 @@ package-name] [**inherits**** **class-name [**uses**** **data-type {’,’ data-type}] [**raises**** **exception-name {’,’ exception-name}] -**   is **definition-of-a-class +** is **definition-of-a-class **end **[class-name]’;’ (55) type-constraint ::= @@ -1858,19 +1788,6 @@ identifier **as**** **type-constraint @subsection occt_1819379591_213955286151 Comparison of CDL & C++ Syntax for Data Types manipulated by Handle and by Value - - - - - - - - -
- -
- - - ![](/devs_guide/cdl/images/cdl_image012.jpg) -
- + @image html /dev_guides/cdl/images/cdl_image012.jpg + @image latex /dev_guides/cdl/images/cdl_image012.jpg + \ No newline at end of file diff --git a/dox/dev_guides/dev_guides.md b/dox/dev_guides/dev_guides.md index e72a1dc8b9..5e88b4f532 100644 --- a/dox/dev_guides/dev_guides.md +++ b/dox/dev_guides/dev_guides.md @@ -1,7 +1,7 @@ Developer Guides {#dev_guides} ================ -@section OCCT_OVW_SECTION1 Source Repository +## Source Repository This directory contains sources of Open CASCADE Technology (OCCT), a collection of C++ libraries providing services for 3D surface and solid modeling, CAD data @@ -15,39 +15,7 @@ compliance with the License. Please see the LICENSE file or obtain a copy of the License at http://www.opencascade.org and read it completely before using this software. -@section OCCT_OVW_SECTION11 Building OCCT Libraries - -The source package of the Open CASCADE Technology including the source files of samples -and tools and the set of building procedures is available for self-dependent preparation -binary files on UNIX and Windows platforms. - -In order to build OCCT libraries from these sources for use in your program, -you need to: - -1. Install the required third-party libraries. - - Follow the instructions provided in the documents titled "Building 3rd party - products for OCCT" on http://dev.opencascade.org/?q=home/resources for - choice of the needed libraries, their installation and building. - -2. If you use OCCT sources from Git repository or do come changes affecting - CDL files or dependencies of OCCT toolkit, update header files generated - from CDL, and regenerate build scripts for your environment using WOK. - See \subpage dev_guides__wok "WOK" for details. - - Skip to step 3 if you use complete source package (e.g. official OCCT - release) without changes in CDL. - -3. Build using your preferred build tool. - - \subpage dev_guides__building__automake "Building on Linux with Autotools" - - \subpage dev_guides__building__cmake "Building with CMake (cross-platform)" - - \subpage dev_guides__building__code_blocks "Building on Mac OS X with Code::Blocks" - - \subpage dev_guides__building__msvc "Building on Windows with MS Visual Studio 2005-2012" - - \subpage dev_guides__building__xcode "Building on Mac OS X with Xcode" - -The current version of OCCT can be consulted in the file src/Standard/Standard_Version.hxx - -@section OCCT_OVW_SECTION111 Automatic tests +## Automatic tests OCCT automatic testing system is integrated with @ref draw "DRAW Test Harness", a console application based on Tcl (a scripting language). @@ -88,15 +56,24 @@ To see intermediate commands and their output during the test execution, add one more argument '-echo' at the end of the command line, or type 'dlog get' after test completion. -For more information consult \subpage dev_guides__tests "Automatic Testing System" +For more information consult \subpage dev_guides__tests -@section OCCT_OVW_SECTION1112 CDL Overview +## docs +**short description** -CDL is the component definition language of the Open CASCADE Technology (OCCT) programming platform. -Some components, which CDL allows you to create, are specific to OCCT application architecture. +\subpage dev_guides__documentation -For more information consult \subpage dev_guides__cdl "Component Definition Language Developer's Guide" +## wok +**short description** -@section OCCT_OVW_SECTION1113 Documentation Overview +\subpage dev_guides__wok -\subpage dev_guides__documentation "Documentation Developer's Guide" +## building +**short description** + +\subpage dev_guides__building + +## cdl +**short description** + +\subpage dev_guides__cdl \ No newline at end of file diff --git a/dox/dev_guides/documentation/documentation.md b/dox/dev_guides/documentation/documentation.md index d8965dd884..69cf2e6cd7 100644 --- a/dox/dev_guides/documentation/documentation.md +++ b/dox/dev_guides/documentation/documentation.md @@ -20,6 +20,9 @@ The latest version: http://www.mathjax.org/download/ MiKTeX or equivalent tool (used for PDF document creation) Latest version: http://miktex.org/download +**Note**: to generate pdf documentation with MiKTeX you should execute gen.bat with MiKTeX environment +(e.g. into MiKTeX command promt) + @section OCCT_DM_SECTION_2_1 Documentation Generation Run gendoc.bat from OCCT directory to generate all articles are defined in FILES.txt: @@ -80,7 +83,8 @@ The MarkDown files have a "*.md" extension and are based on rules desribed in @subsection OCCT_DM_SECTION_3_2 Directory Structure -![](/devs_guide/documentation/images/documentation_image001.png) +@image html /dev_guides/documentation/images/documentation_image001.png +@image latex /dev_guides/documentation/images/documentation_image001.png Every separate article has own folder if images are used in it. These images are stored into "images" subfolder. @@ -90,7 +94,7 @@ If you want to use the same image for several articles, you can place the one in **Note**: Every article can use any image that is used by others articles. To avoid incorrect image displaying, use relative path to the image (starting from dox folder). For instance @verbatim -![](/devs_guide/snv/images/snv_image001.svg) +@image html /dev_guides/snv/images/snv_image001.svg @endverbatim Result of generation of the documentation is: @@ -103,14 +107,14 @@ Result of generation of the documentation is: - Place a new article into folder that is chosen taking into account the place of the article at the hierarchy of the documentation. For instance the article about "using SVN working with OCCT -source code" (svn.md - the file of the article) might be placed into /dox/devs_guide/ . If the article has images then you may create +source code" (svn.md - the file of the article) might be placed into /dox/dev_guides/ . If the article has images then you may create the own folder of the article and subfolder in it for images. For instance -*/dox/devs_guide/svn/ - for svn.md file -*/dox/devs_guide/svn/images/ - for images +*/dox/dev_guides/svn/ - for svn.md file +*/dox/dev_guides/svn/images/ - for images - Update dox/FILES.txt to add relative path to svn.md. For instance @verbatim -devs_guide/snv/svn.md +dev_guides/snv/svn.md @endverbatim **Note**: the place of the relative path to an article is connected with the place @@ -129,403 +133,3 @@ http://en.wikipedia.org/wiki/Help:Displaying_a_formula More information on MarkDown and Doxygen syntax can be found at: http://www.stack.nl/~dimitri/doxygen/manual - - -@section OCCT_DM_SECTION_A Appendix 1: Document Syntax - -Each OCCT document file in *.md format has a simple structure. -It can contain: - -| Content type | Obligation | -| :---------------- | :-------------------: | -| Header | M | -| Footer | M | -| Plain text | O | -| List | O | -| Table | O | -| Code | O | -| Formula | O | -| Image | O | -| Page numbers | M (auto generation) | -| Table of contents | M (auto generation) | - -The legend: - - * M is for Mandatory - * O is for Optional - -@subsection OCCT_DM_SECTION_A_1 Text Caption (a header) - -headings of different levels can be specified with the following code: - -@verbatim -Header 1 {#header1} -======= -@endverbatim - - to get - - Header 1 -========= - - and with the following code: - -@verbatim -Header 2 {#header2} --------- -@endverbatim - -to get - -Header 2 ---------- - -Where a word in curly braces is a MarkDown-style reference, which can be used in table of contents. -If you would like to have the table of contents, it is recommended to use \@section, -\@subsection and \@subsubsection pages instead of MarkDown headers as follows: - -@verbatim - @section Section_Name Section Header - @subsection SubSection_Name SubSection Header - @subsubsection SubSubSection_Name SubSubSection Header -@endverbatim - -@subsection OCCT_DM_SECTION_A_2 Plain Text - -Plain text is a text in a notepad-like format. To insert special symbols, -like \< , \> or \\, prepend them with \\ character: \\\<, \\\>, \\\\ -To emphasize some words, write one pair of asterisks ( * ) or underscores ( _ ) across the word -to make it *italic* and two pairs of these symbols to make a word **Bold**. - -@subsection OCCT_DM_SECTION_A_3 Lists - -To create a bulleted list, start each line with a hyphen or an asterisk, -followed by a space. List items can be nested. This code: - -@verbatim - * Bullet 1 - * Bullet 2 - * Bullet 2a - * Bullet 2b - * Bullet 3 -@endverbatim - - produces this list: - - * Bullet 1 - * Bullet 2 - * Bullet 2a - * Bullet 2b - * Bullet 3 - -To create a numbered list, start each line with number and a period, then a space. Thus this code - -@verbatim - 1. ListItem_1 - 2. ListItem_2 - 3. ListItem_3 -@endverbatim - - produces this list: - - 1. ListItem_1 - 2. ListItem_2 - 3. ListItem_3 - -It is recommended to indent lists with 2 spaces. - -@subsection OCCT_DM_SECTION_A_4 Tables - -A table consists of a header line, a separator line, and at least one row line. -Table columns are separated by the pipe (|) character. The following example: - -@verbatim -First Header | Second Header -------------- | ------------- -Content Cell | Content Cell -Content Cell | Content Cell -@endverbatim - - will produce the following table: - -First Header | Second Header ------------- | ------------- -Content Cell | Content Cell -Content Cell | Content Cell - -Column alignment can be controlled via one or two colons at the header separator line: - -@verbatim -| Right | Center | Left | -| ----: | :----: | :---- | -| 10 | 10 | 10 | -| 1000 | 1000 | 1000 | -@endverbatim - -which will looks as follows: - -| Right | Center | Left | -| ----: | :----: | :---- | -| 10 | 10 | 10 | -| 1000 | 1000 | 1000 | - -@subsection OCCT_DM_SECTION_A_5 Code Blocks - -It is recommended to indent a code lines with 4 spaces. -A fenced code block does not require indentation, and is defined by a pair of "fence lines". -Such line consists of 3 or more tilde (~) characters on a line. -The end of the block should have the same number of tildes. Here is an example: - -~~~~~~~~~~~~~~~~~~~~~~~ - a one-line code block -~~~~~~~~~~~~~~~~~~~~~~~ - -By default the output is the same as for a normal code block. -To highlight the code, the developer has to indicate the typical file extension, -which corresponds to the programming language, after the opening fence. -For highlighting according to the C++ language, for instance, write the following code (the curly braces and dot are optional): - -@verbatim -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} - int func(int a,int b) { return a*b; } -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -@endverbatim - -which will produce: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} - int func(int a,int b) { return a*b; } -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Verbatim content can be written by using framing \@verbatim \@endverbatim . For instance - -@verbatim - verbatim text -@endverbatim - -@subsection OCCT_DM_SECTION_A_6 References - -To insert a reference to a website, it is proposed to write a URL. For example: http://en.wikipedia.org -To insert a reference to another part of the same document, the developer can write: - -@verbatim - @htmlonly - Doxygen Configuration file - @endhtmlonly -@endverbatim - -to get a link to paragraph : @htmlonly Doxygen configuration @endhtmlonly - -@subsection OCCT_DM_SECTION_A_7 Images - -To insert image into document the developer can write the following code(in Doxygen-style): -@verbatim -![alt-caption](relative/path/to/image/image001.svg "Image Caption") -@endverbatim - -This code tells Doxygen to insert a picture right in the place this code was written. Like this: -@verbatim -![](/resources/occt_logo.png "OCCT logo") -@endverbatim - -![](/resources/occt_logo.png "OCCT logo") - -@subsection OCCT_DM_SECTION_A_8 Table Of Contents - -To get the table of contents at the beginning of the document, write \@tableofcontents tag. -But it is not needed now because TreeView option for HTML is used. -The TOC in the PDF document will be generated automatically. - -@subsection OCCT_DM_SECTION_A_9 Formulas - -Formulas within documents will be generated using MathJax tool. - -A developer has to specify these parameters in Doxyfile to enable support of MathJax in Doxygen: - - USE_MATHJAX = YES - MATHJAX_FORMAT = HTML-CSS - MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest - MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols - -To use MathJax tool with the HTML page, it's \ block has to contain - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.html} - - - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -First script configures MathJax to understand separator types and to left allign formulas. -The second script inserts reference to MathJax tool. -This tool will always be used when the HTML output will be shown. - -Equations can be written by several ways: - -1.Unnumbered displayed formulas that are centered on a separate line. -These formulas should be put between \@f\[ and \@f\] tags. An example: - -@verbatim -@f$[ - |I_2|=\left| \int_{0}^T \psi(t) - \left\{ - u(a,t)- - \int_{\gamma(t)}^a - \frac{d\theta}{k(\theta,t)} - \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi - \right\} dt - \right| -@f$] -@endverbatim - -gives the following result: - - @f$ - |I_2|=\left| \int_{0}^T \psi(t) - \left\{ - u(a,t)- - \int_{\gamma(t)}^a - \frac{d\theta}{k(\theta,t)} - \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi - \right\} dt - \right| - @f$ - -2.Formulas can also be put between @verbatim \begin{align} @endverbatim and @verbatim \end{align} @endverbatim tags. An example: - -@verbatim - \begin{align} - \dot{x} & = \sigma(y-x) \\ - \dot{y} & = \rho x - y - xz \\ - \dot{z} & = -\beta z + xy - \end{align} -@endverbatim - - gives the following result: -@latexonly - \begin{align} - \dot{x} & = \sigma(y-x) \\ - \dot{y} & = \rho x - y - xz \\ - \dot{z} & = -\beta z + xy - \end{align} -@endlatexonly - -@htmlonly - \begin{align} - \dot{x} & = \sigma(y-x) \\ - \dot{y} & = \rho x - y - xz \\ - \dot{z} & = -\beta z + xy - \end{align} -@endhtmlonly - -3.Inline formulas can be specified using this syntax: - -@verbatim - @f$ \sqrt{3x-1}+(1+x)^2 @f$ -@endverbatim - - that leads to the following result: @f$ \sqrt{3x-1}+(1+x)^2 @f$ - -@section OCCT_DM_SECTION_B Appendix 2: Doxygen Configuration - -@subsection OCCT_DM_SECTION_B_1 Doxygen Configuration File - -To generate documentation from "source" *.md files a developer can use file OCCT.doxyfile, -which is located in /docs directory of OCCT (more information can be found at @htmlonly -Directory Structure @endhtmlonly paragraph) -or create his own configuration file, called "Doxyfile". The configuration file may look as follows: - -@verbatim - DOXYFILE_ENCODING = UTF-8 - PROJECT_NAME = "OCCT User's Guides" - PROJECT_NUMBER = 1.0.1 - PROJECT_LOGO = "D:/OS/OCCT/docs/OCCT_logo.png" - OUTPUT_LANGUAGE = English - TAB_SIZE = 4 - MARKDOWN_SUPPORT = YES - AUTOLINK_SUPPORT = NO - SHOW_FILES = NO - WARNINGS = YES - WARN_IF_UNDOCUMENTED = YES - WARN_IF_DOC_ERROR = YES - WARN_NO_PARAMDOC = NO - WARN_FORMAT = "$file:$line: $text" - INPUT = "D:/OS/OCCT/docs/" - INPUT_ENCODING = UTF-8 - FILE_PATTERNS = *.md - RECURSIVE = YES - IMAGE_PATH = tmp - GENERATE_HTML = YES - SEARCHENGINE = NO - HTML_OUTPUT = html - HTML_FILE_EXTENSION = .html - HTML_HEADER = "static/header.html" - HTML_FOOTER = "static/footer.html" - HTML_STYLESHEET = "static/general.css" - HTML_EXTRA_STYLESHEET = "static/styles.css" - HTML_COLORSTYLE_HUE = 220 - HTML_COLORSTYLE_SAT = 100 - HTML_COLORSTYLE_GAMMA = 80 - HTML_TIMESTAMP = YES - HTML_DYNAMIC_SECTIONS = NO - HTML_INDEX_NUM_ENTRIES = 100 - GENERATE_LATEX = YES - GENERATE_RTF = YES -@endverbatim - -@subsection OCCT_DM_SECTION_B_2 Doxygen Output Customization - -The customization of the output files, produced by Doxygen, can be made by using different Doxyfile parameters, -like HTML_COLORSTYLE_SAT, which specifies one of HSV color component of HTML page header, and also by using DoxygenLayout xml file. -A developer can use default file from /docs directory or generate his own with doxygen -l command. It may looks as follows: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.xml} - - - - - - - - - - - - - - - - - - - - - - - - ... - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The tag \ specifies tabs which appear at the head of each html page. For the OCCT user documentation - "mainpage" and "pages" tabs are usually needed and their visible parameter should always be "yes". -The visibility of other tabs should be set to "no". - -Developers can find more information about Doxygen configuration in the help file -or at http://www.stack.nl/~dimitri/doxygen/manual/ - -@subsection OCCT_DM_SECTION_B_3 Doxywizard Usage - -The easiest way of applying and modification of Doxyfile is to use a Doxywizard application, -which is usually a part of the Doxygen tool. To apply a configuration file, the developer should -select "Open..." item of the File menu or press Ctrl + O. Modification of Doxyfile can be made -using "Wizard" or "Expert" tabs of Doxywizard application. - -Developers can find more information about Doxywizard usage in the help file or at -http://www.stack.nl/~dimitri/doxygen/manual/doxywizard_usage.html. diff --git a/dox/dev_guides/tests/tests.md b/dox/dev_guides/tests/tests.md index 731e2a64cb..2282f23312 100644 --- a/dox/dev_guides/tests/tests.md +++ b/dox/dev_guides/tests/tests.md @@ -173,7 +173,8 @@ By convention, names of test groups, grids, and cases should contain no spaces a Names begin, end, data, parse.rules, grids.list, cases.list are reserved. General layout of test scripts is shown on Figure 1. -![](/devs_guide/tests/images/tests_image001.png "") +@image html /dev_guides/tests/images/tests_image001.png +@image latex /dev_guides/tests/images/tests_image001.png Figure 1. Layout of tests folder diff --git a/dox/dev_guides/wok/images/wok_image001.jpg b/dox/dev_guides/wok/images/wok_image001.jpg index 37fd7350d4..0e782cab77 100644 Binary files a/dox/dev_guides/wok/images/wok_image001.jpg and b/dox/dev_guides/wok/images/wok_image001.jpg differ diff --git a/dox/dev_guides/wok/images/wok_image002.jpg b/dox/dev_guides/wok/images/wok_image002.jpg index b805c9b218..5f87a335b2 100644 Binary files a/dox/dev_guides/wok/images/wok_image002.jpg and b/dox/dev_guides/wok/images/wok_image002.jpg differ diff --git a/dox/user_guides/wok/images/wok_image005.jpg b/dox/dev_guides/wok/images/wok_image005.jpg similarity index 100% rename from dox/user_guides/wok/images/wok_image005.jpg rename to dox/dev_guides/wok/images/wok_image005.jpg diff --git a/dox/user_guides/wok/images/wok_image005.png b/dox/dev_guides/wok/images/wok_image005.png similarity index 100% rename from dox/user_guides/wok/images/wok_image005.png rename to dox/dev_guides/wok/images/wok_image005.png diff --git a/dox/user_guides/wok/images/wok_image006.png b/dox/dev_guides/wok/images/wok_image006.png similarity index 100% rename from dox/user_guides/wok/images/wok_image006.png rename to dox/dev_guides/wok/images/wok_image006.png diff --git a/dox/user_guides/wok/images/wok_image007.png b/dox/dev_guides/wok/images/wok_image007.png similarity index 100% rename from dox/user_guides/wok/images/wok_image007.png rename to dox/dev_guides/wok/images/wok_image007.png diff --git a/dox/user_guides/wok/images/wok_image008.png b/dox/dev_guides/wok/images/wok_image008.png similarity index 100% rename from dox/user_guides/wok/images/wok_image008.png rename to dox/dev_guides/wok/images/wok_image008.png diff --git a/dox/user_guides/wok/images/wok_image009.png b/dox/dev_guides/wok/images/wok_image009.png similarity index 100% rename from dox/user_guides/wok/images/wok_image009.png rename to dox/dev_guides/wok/images/wok_image009.png diff --git a/dox/user_guides/wok/images/wok_image010.png b/dox/dev_guides/wok/images/wok_image010.png similarity index 100% rename from dox/user_guides/wok/images/wok_image010.png rename to dox/dev_guides/wok/images/wok_image010.png diff --git a/dox/user_guides/wok/images/wok_image011.png b/dox/dev_guides/wok/images/wok_image011.png similarity index 100% rename from dox/user_guides/wok/images/wok_image011.png rename to dox/dev_guides/wok/images/wok_image011.png diff --git a/dox/user_guides/wok/images/wok_image012.png b/dox/dev_guides/wok/images/wok_image012.png similarity index 100% rename from dox/user_guides/wok/images/wok_image012.png rename to dox/dev_guides/wok/images/wok_image012.png diff --git a/dox/user_guides/wok/images/wok_image013.jpg b/dox/dev_guides/wok/images/wok_image013.jpg similarity index 100% rename from dox/user_guides/wok/images/wok_image013.jpg rename to dox/dev_guides/wok/images/wok_image013.jpg diff --git a/dox/user_guides/wok/images/wok_image014.jpg b/dox/dev_guides/wok/images/wok_image014.jpg similarity index 100% rename from dox/user_guides/wok/images/wok_image014.jpg rename to dox/dev_guides/wok/images/wok_image014.jpg diff --git a/dox/user_guides/wok/images/wok_image015.png b/dox/dev_guides/wok/images/wok_image015.png similarity index 100% rename from dox/user_guides/wok/images/wok_image015.png rename to dox/dev_guides/wok/images/wok_image015.png diff --git a/dox/user_guides/wok/images/wok_image016.png b/dox/dev_guides/wok/images/wok_image016.png similarity index 100% rename from dox/user_guides/wok/images/wok_image016.png rename to dox/dev_guides/wok/images/wok_image016.png diff --git a/dox/user_guides/wok/images/wok_image017.png b/dox/dev_guides/wok/images/wok_image017.png similarity index 100% rename from dox/user_guides/wok/images/wok_image017.png rename to dox/dev_guides/wok/images/wok_image017.png diff --git a/dox/user_guides/wok/images/wok_image018.png b/dox/dev_guides/wok/images/wok_image018.png similarity index 100% rename from dox/user_guides/wok/images/wok_image018.png rename to dox/dev_guides/wok/images/wok_image018.png diff --git a/dox/user_guides/wok/images/wok_image019.png b/dox/dev_guides/wok/images/wok_image019.png similarity index 100% rename from dox/user_guides/wok/images/wok_image019.png rename to dox/dev_guides/wok/images/wok_image019.png diff --git a/dox/user_guides/wok/images/wok_image020.png b/dox/dev_guides/wok/images/wok_image020.png similarity index 100% rename from dox/user_guides/wok/images/wok_image020.png rename to dox/dev_guides/wok/images/wok_image020.png diff --git a/dox/user_guides/wok/images/wok_image021.png b/dox/dev_guides/wok/images/wok_image021.png similarity index 100% rename from dox/user_guides/wok/images/wok_image021.png rename to dox/dev_guides/wok/images/wok_image021.png diff --git a/dox/user_guides/wok/images/wok_image022.png b/dox/dev_guides/wok/images/wok_image022.png similarity index 100% rename from dox/user_guides/wok/images/wok_image022.png rename to dox/dev_guides/wok/images/wok_image022.png diff --git a/dox/dev_guides/wok/wok.md b/dox/dev_guides/wok/wok.md index 808868d930..4d9b9eef4a 100644 --- a/dox/dev_guides/wok/wok.md +++ b/dox/dev_guides/wok/wok.md @@ -1,153 +1,3252 @@ -WOK {#dev_guides__wok} -========= +Workshop Organisation Toolkit {#dev_guides__wok} +============================== -WOK is a legacy build environment for Open CASCADE Technology. It is required -for generation of header files for classes defined with @ref ug_cdl "CDL" -("Cascade Definition Language"). Also tools for generation of project files -for other build systems, and OCCT documentation, are integrated to WOK. +@section occt_wok_1_ Introduction Glossary -WOK thus is needed in the following situations: -- Building from OCCT sources from Git repository (do not contain generated files) -- Building after some changes made in CDL files +@subsection occt_wok_1_1 About the Development Environment -Before installing and using WOK, make sure that you have installed a compiler (it is assumed that it is Visual Studio on Windows or gcc on Linux and MacOS) and third-party components required for building OCCT. +Open CASCADE Technology (**OCCT**) development environment is able to accommodate large numbers of developers working on a variety of products. Within this environment developers can produce multiple versions of products for various hardware and software platforms, including versions corresponding to particular marketing requirements. At the same time, OCCT development environment enables the maximum possible reuse of software components. In other words, OCCT development environment is designed to facilitate industrial scale development. +@subsection occt_wok_1_2 Brief Overview of Open CASCADE Technology Development Environment +The following diagram shows OPEN CASCADE tools and resources, the development method, and the architecture of applications that you can develop with Open CASCADE Technology. -@section wok1 Installing WOK +@image html /dev_guides/wok/images/wok_image005.png "Schematic View of OCCT Development Platform" +@image latex /dev_guides/wok/images/wok_image005.png "Schematic View of OCCT Development Platform" - Download the latest version of binary distribution WOK from http://dev.opencascade.org/index.php?q=home/resources +The application developer goes about creating his application by editing his source code and producing the final application using a set of intelligent construction tools. These tools are available within a structured development environment called the **software factory**. -@subsection wok11 Windows +The developer defines new software components in CDL, Component Description Language, and uses a CDL compiler to derive their C++ implementations. These components are then compiled into packages. +@subsection occt_wok_1_3 WOK Components +@subsubsection occt_wok_1_3_1 Entities +The WOK environment is made up of entities, for example software factories and development units. A full list of WOK entities is provided in the Glossary section. +@subsubsection occt_wok_1_3_2 Files +WOK manages two different types of files: user source files and WOK administration files. To support this, each entity has a home directory, which contains its administration directory. This is called *adm* and stores the administration files that WOK needs. In addition development units have a source directory called *src*, which contains both .cdl and .cxx source files, and a header file directory called *inc*, which contains .hxx files. - Run the installer. You will be prompted to read and accept the OCCT Public License to proceed: - - ![](/devs_guide/wok/images/wok_image001.jpg "") +@subsection occt_wok_1_4 Glossary +@subsubsection occt_wok_1_4_1 Development Units +A **development unit** is the smallest unit that can be subject to basic development operations such as modifying, compiling, linking and building. +The following list contains all types of development units. The letter in parentheses indicates the letter key by commands such as *ucreate* and *umake*. In the rest of the manual, this letter key is referred to as the *short key*. +* package (p) A set of related classes and methods along with their CDL definitions. +* schema (s) A set of persistent data types. +* executable (x) An executable is used for unit and integration test purposes. It is based on one or more packages. +* nocdlpack (n) A package without a CDL definition. Used for low-level programming or for incorporating foreign resources. +* interface (i) A specific set of services available for wrapping (an interface contains packages, classes, and methods). +* jni (j) A development unit used to wrap C++ classes to Java. It is based on one or more interfaces. +* toolkit (t) A set of packages. Useful in grouping packages together when there is a large number of packages based around a particular subject. +* delivery (d) A development unit for publishing development units. +* resource (r) A development unit containing miscellaneous files. + +@subsubsection occt_wok_1_4_2 Workbenches +A workbench is a specialized directory structure where the user creates, modifies, and uses development units. A workbench is likely to be the personal property of one user or at most a small team of developers. +@image html /dev_guides/wok/images/wok_image006.png "Schema of a Workbench Containing three Development Units" +@image latex /dev_guides/wok/images/wok_image006.png "Schema of a Workbench Containing three Development Units" + +@subsubsection occt_wok_1_4_3 Workshops +A workshop is a tree of workbenches. It provides the development team with an independent workspace inside which the complete cycle of software production can be carried out. +The root workbench is in a valid state and contains the working versions of the development units. +Development units in a root workbench are visible in its child workbenches. + +For example, the schema below shows a workshop containing three workbenches. Workbenches B and C are the children of workbench A. Development units in A are visible in both B and C +@image html /dev_guides/wok/images/wok_image007.png "Workbenches" +@image latex /dev_guides/wok/images/wok_image007.png "Workbenches" + +Workshops are fully independent of each other. They are organized in such a way that development units can be grouped into a delivery and placed in a warehouse. Communication between workshops is carried out by means of these deliveries. A warehouse belongs to a factory and is visible from all workshops in that factory. In this way, development units can be shared between a group of development teams. + +@image html /dev_guides/wok/images/wok_image008.png "Two Workshops Delivering and Borrowing Parcels" +@image latex /dev_guides/wok/images/wok_image008.png "Two Workshops Delivering and Borrowing Parcels" + +@subsubsection occt_wok_1_4_4 Factories +A factory is a set of workshops and their corresponding warehouse. There is a single warehouse in any factory. The continuous upgrading and improvement of a product is carried out in a specific factory. +To create a new version of an application within the factory, you establish a new workshop dedicated to creation and support of the new version. + +@image html /dev_guides/wok/images/wok_image009.png "Factory Contains Workshops and Warehouse" +@image latex /dev_guides/wok/images/wok_image009.png "Factory Contains Workshops and Warehouse" + +@section occt_wok_2_ Elements of the Platform +@subsection occt_wok_2_1 Development Units +A **development unit** is the basic element of WOK development. It includes the following three entities: + * A directory structure (a minor component) + * Source files, also called primary files + * The result of the build process (compilation, etc.), also called derived files. + +@subsubsection occt_wok_2_1_1 Directory Structure of a Development Unit +The directory structure of a development unit consists of a tree of directories, which are created when the development unit is initialized. Refer to the Workbenches section for further details on the workbench structure. +@subsubsection occt_wok_2_1_2 Files in a Development Unit + +#### Source Files - Click Next and proceed with the installation. - At the end of the installation you will be prompted to specify the version and the location of Visual Studio to be used, and the location of third-party libraries: +Source files are written by the developer in the source section (the *src* directory) of the development unit. +Each development unit maintains the description of its own source files, and this description is stored in one or more files within the *src* directory. The details of how the description is stored vary according to development unit type as shown below: +* package (p) The names of all source files are worked out from the CDL description, following the conventions described in the *C++ Programming Guide*. This list of files can be supplemented by additional files listed in the file called FILES. This file must be stored in the unit’s src directory. Whenever header files are included in the *src* directory of a development unit, they must be specified in FILES so that the C++ preprocessor will take them into account. This reduces compilation time by 10 to 40 percent. +* schema (s) No description of the source files is needed. There is a single source file: *schema.cdl*. +* executable (x) The names of all source files are worked out from the CDL description. The format of this file is described in the Building an Executable section. +* nocdlpack (n) The list of source files is contained in the FILES file stored in the unit’s src directory. +interface (i). No description of the source files is needed. There is a single source file: *interface.cdl*. +* jni (j). No description of the source files is needed. There is a single source file: *jni.cdl*. +* toolkit (t) The description is given by the file called PACKAGES which is stored in the unit’s src directory. FILES must also exist in this directory, and must include PACKAGES in its list of files. +* delivery (d) The description is given by two files stored in the unit’s src directory: FILES and a file called COMPONENTS. FILES must include COMPONENTS in its list of files. +* resource (r) A resource unit is used in a delivery. FILES contains a list of the unit’s files, one per line in the following format: *atype:::afilename* Here, *filename* is the name of a file, which the compiler will look for in the src directory of the unit, and *atype* is a WOK type. To display a list of all available WOK types, use the command: *wokinfo -T*. + +#### Derived files + +Derived files created by compilation are automatically placed in the derived section of the development unit. These may be executable files or archives of compilation results. + +@subsubsection occt_wok_2_1_3 Package +A package is a development unit that defines a set of classes, which share a number of common features such as similar data structure or a set of complementary algorithmic services. Packages help to manage creation and the use of large hierarchies of software components. +To create a package, you write a .cdl file describing it in the src directory of the package development unit. The description includes classes and global methods, which comprise it. Each class is also described in a separate .cdl file. The package .cdl file also lists the packages used in the specification of its classes and methods. +C++ implementation files are also stored in the src subdirectory of the package development unit. These implementation files are: + * .cxx for an ordinary class + * .lxx for any inline methods + * .pxx for any private declarations + * .gxx for a generic class - ![](/devs_guide/wok/images/wok_image002.jpg "") +To create the Development Unit structure for a package use the following syntax: +~~~~~ +ucreate –p MyPackage +~~~~~ + +The package description has the following CDL syntax: +~~~~~ +package PackageName +[uses AnotherPackage {‘,’ YetAnotherPackage}] +is +[{type-declaration}] +[{package-method}] +end [PackageName]’:’ +~~~~~ + +For example: +~~~~~ +package CycleModel +uses +Pcollection +Tcollection +BREpPrimAPI +TopExp +Geom +Pgeom +is +deferred class Element; +class Wheel; +class Frame; +class LocalReference; +Adjust(awheel: wheel from CycleModel; +  aframe: Frame from CycleModel); +end CycleModel; +~~~~~ +For full details on the CDL syntax, refer to the *CDL User’s Guide*. + +@subsubsection occt_wok_2_1_4 Schema + +A schema is a development unit that defines the set of all data types, which your application is likely to need in order to read and write files. Such data types are **persistent**. + +To create a schema, write a .cdl file that lists all the packages, which contain all persistent data types used by the application. Note that only persistent classes are taken into account during compilation; transient classes are ignored. + +Note that you don’t have to put dependencies in all packages and classes. You only have to write the highest level dependencies. In other words, the *uses* keyword in the schema file allows you to list packages. Any package similarly listed in the package files for these packages are also incorporated into the schema. + +To create the Development Unit structure for a schema use the syntax below: +~~~~~ +ucreate –s MySchema +~~~~~ + +The schema description has the following CDL syntax : + +~~~~~ +schema SchemaName +is +ListOfPackagesContainingPersistentClasses; +ListOfPersistentClasses; +end; +~~~~~ + +For example: +~~~~~ +schema MyCycleSchema +is +class Wheel from package CycleModel; +class Frame from package CycleModel; +.. +class Spanner from package CycleTools; +end; +~~~~~ +For full details on the CDL syntax, refer to the *CDL User’s Guide*. + +@subsubsection occt_wok_2_1_5 Executable +The purpose of an executable is to make executable programs. The executable can use services from one or more packages and is described in a .cdl file as a set of packages. + +To create an executable, you write one or more MyExe.cxx files in the src subdirectory of the unit. This file will contain the main function. Then it is possible to compile the executable. + +To create the Development Unit structure for an executable, use the syntax below: +~~~~~ +ucreate –x MyExec +~~~~~ + +The executable description has the following CDL syntax: +~~~~~ +executable ExecName +is +executable BinaryFile +uses +LibFile as external +is +C++File; +end; +end; +~~~~~ + +For example: +~~~~~ +executable MyExecUnit’ +is +executable myexec +uses +Tcl_Lib as external +is +myexec; +end; +executable myex2 +is +myex2; +end; +end; +~~~~~ +For full details on the CDL syntax, refer to the *CDL Reference Manual*. + +@subsubsection occt_wok_2_1_6 Toolkit +A toolkit is a development unit that groups a set of packages to create a shareable library. An example of a toolkit is the ModelingData module. Toolkits serve for the following purposes: + * Linking of large numbers of packages + * Faster loading of executable files that use toolkits such as test files. + +A toolkit has no CDL definition. Creating a toolkit involves writing a PACKAGES file in the src subdirectory of its development unit. This file lists all the packages needed in the toolkit. You then create a definition of this file to the FILES. + +You then compile the toolkit to create a shareable library. + +@subsubsection occt_wok_2_1_7 Nocdlpack +A nocdlpack is a development unit that has no CDL definition. It is compiled directly from source files written in C, C++, Fortran, or in sources to be treated by the lex or yacc tools. A nocdlpack is useful when you write a low-level interface with another product, for example, a network application. + +To define a nocdlpack, you create a file called FILES in the src subdirectory of the nocdlpack development unit. In this file, you list the Fortran, C, C++, lex, and yacc files that compose the pack. You list the files one per line. + +On compilation, the result is a shareable library. + +@subsubsection occt_wok_2_1_8 Interface +An interface is a development unit that defines a set of services available for wrapping into Java. +An interface is defined in a .cdl file as a list of packages, package methods, classes, and methods. It makes these available to a jni unit. + +To create the Development Unit structure for an interface, use the syntax below: +~~~~~ +ucreate -i MyInterface +~~~~~ + +The interface description has the following CDL syntax: + +~~~~~ +interface InterfaceName +is +ListOfPackages +ListOfClasses +ListOfMethods +end; +~~~~~ + +For example: +~~~~~ +interface MyInterface +is +        package TopoDS; +        class Shape from ShapeFix; +end ; +~~~~~ + +@subsubsection occt_wok_2_1_9 Jni +A jni is a development unit that wraps declared services into Java using JNI (Java Native Interface). + +A jni creates Java classes that are used as C++ counterparts when developing in Java. + +To create the Development Unit structure for an Jni, use the syntax below: +ucreate -j MyJni + +The interface description has the following CDL syntax: +~~~~~ +client JniName +is +{interface InterfaceName;} +end; +~~~~~ + +For example : +~~~~~ +client MyJni +is +        interface MyInterface; +        interface MyAnotherInterface; +end ; +~~~~~ + +@subsubsection occt_wok_2_1_10 Delivering Parcels +The delivery process allows creating parcels. These parcels group together the development work done within a given workshop. You can ship these parcels to other workshops called client workshops. + +A delivery is autonomous. Once the delivery development unit is compiled, a parcel is stored in the factory warehouse and has no more connection with the workshop where it was created. A parcel has its own directory structure. + +All Open CASCADE Technology resources are seen as parcels. + +@image html /dev_guides/wok/images/wok_image010.png "Parcels" +@image latex /dev_guides/wok/images/wok_image010.png "Parcels" + +You create a delivery unit under a specified workbench. + +You are **strongly advised** to create delivery units under the *root* workbench of the workshop. Child workbenches could be deleted in the future, whereas the root workbench is likely to remain untouched. In other words, you safeguard the delivery by creating it in the root workbench. + +**Note** If you do not specify a workbench when you make a delivery, it is created under the current workbench. - You can change these settings at any time later. For this click on the item "Customize environment (GUI tool)" in the WOK group in the Windows Start menu. - - The shortcuts from this group provide two ways to run WOK: - * In command prompt window ("WOK TCL shell"). - * In Emacs editor ("WOK Emacs"). Using Emacs is convenient if you need to work within WOK environment. +@subsection occt_wok_2_2 Workbenches +A workbench is generally the place where one particular developer or a team of developers works on a particular development. A workbench is composed of a public part and a private part. - By default WOK installer creates a WOK factory with name "LOC" within workshop "dev" (WOK path :LOC:dev). +@subsubsection occt_wok_2_2_1 Roots +The following roots are used in the structure of a workbench: +* **Home** Workbench root containing various administration files of the workbench. +* **Src** Root of the workbench sources, which facilitates the integration into WOK of version management software such as CVS. +* **DBMS** Root of the derived files dependent on the extraction profile (.hxx, _0.cxx files, etc.). +* **DBMS_Station** Roots of the derived files dependent on the extraction profile and on the platform (.o, .so files, etc.). -@subsection wok12 Linux +Roots are defined for each profile and platform supported by the workbench. For example, a workbench supporting the DFLT profile on Sun and SGI platforms has the following roots: +* **Home** Workbench root, +* **Src** Root of the source files, +* **DFLT** Root of the derived files, +* **DFLT_sun** Root of the files built on Sun platforms, +* **DFLT_sil** Root of the files built on SGI platforms, - * Unpack the .tgz archive containing WOK distributive into an installation directory . - - * Perform the following commands assuming that you have unpacked WOK distributive archive into : - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl} - cd /site - wok_confgui.sh - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - Define all necessary paths to third-party products in the dialog window: - - ![](/devs_guide/wok/images/wok_image003.jpg "") +For a workbench additionally supporting *ObjectStore*, the following additional roots are also found: *OBJS, OBJS_sun, OBJS_sil*. - * Run the following commands to create WOK LOC factory: - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl} - cd /site - wok_init.sh - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - * Your installation procedure is over. To run WOK use one the following commands: - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl} - cd /site - wok_emacs.sh - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - or - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl} - cd /site - wok_tclsh.sh - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +These roots are defined in the workbench definition file *MyWorkbench.edl* as the parameter \%MyWorkbench_RootName. -@subsection wok13 Mac OS X - - * In the Finder double click on wokSetup.dmg file. This will open a new window. Drag and drop "wokSetup" folder from this window at the location in the Finder where you want to install WOK, i.e. . - - * Browse in the Finder to the folder /site and double click on WokConfig. This will open a window with additional search path settings. Define all necessary paths to third-party products in the dialog window: - - ![](/devs_guide/wok/images/wok_image004.jpg "") +**Note** that default values help to define various roots. - * Run the following commands to create WOK LOC factory: - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl} - cd /site - wok_init.sh - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +@subsubsection occt_wok_2_2_2 Directories +Under each root, a hierarchy of directories allows to store various files. +* Under the Home root are found: + * *work*, the private workbench directory reserved for the developer + * *Adm*, the directory reserved for administration files. +* Src contains: + * *src/MyUD*, the directory containing the source files of the development unit MyUD. +* DBMS contains: + * *inc*, containing the public header files of the workbench UDs + * *drv/MyUD*, containing the private extracted files of MyUD + * *drv/MyUD/.adm*, containing the administration files dependent on the extraction profile + * *drv/MyUD/.tmp*, containing the temporary files dependent on the extraction profile. +* DBMS_Station contains: + * */lib* with all the libraries produced in the workbench + * */bin* with all the binaries produced in the workbench + * */MyUD* with all the station dependent files which are private to the development unit such as objects + * */MyUD/.adm* with all the station dependent administration files + * */MyUD/.tmp* with all the temporary files constructed in the development unit. + - * Your installation procedure is over. To run WOK in Emacs navigate in the Finder to the folder /site and double click on WokEmacs. +@image html /dev_guides/wok/images/wok_image011.png "Structure of the workbench Mywb" +@image latex /dev_guides/wok/images/wok_image011.png "Structure of the workbench Mywb" + +@subsection occt_wok_2_2_3 Workshops +A **workshop** is an independent workspace inside which the complete cycle of software production is carried out. Workbenches inside a workshop are organized so that development units can be shared either by being published in a father workbench or by being placed in reference in the root workbench. + +@image html /dev_guides/wok/images/wok_image012.png "Visibility between Workbenches in a Workshop" +@image latex /dev_guides/wok/images/wok_image012.png "Visibility between Workbenches in a Workshop" + +In this image: + * **A** is the development unit A from Grandchild 11 placed in reference in root. It is visible throughout the workshop. + * **B** is the development unit B from Grandchild 12 published in ancestor Child 1. It is visible to Child 1, Grandchild 11 and Grandchild 12. -@section wok2 Initialization of Workbench +In a large-scale development that involves one or more teams of developers, you should decide how you are going to structure a workshop right at the beginning. If need be, you can review your decision later. - To start working with OCCT, clone the OCCT Git repository from the server (see http://dev.opencascade.org/index.php?q=home/resources for details) or unpack the source archive. +An existing workshop can be duplicated and the original workshop can be used as the basis for maintaining the present version of a product. The new workshop can then be used to develop and maintain a new version of the product. + +When creating a new workshop, you specify - in the form of parcels – which resources are to be available within the workshop. + +@subsection occt_wok_2_2_4 Factories +A factory contains a number of workshops and a warehouse. When Open CASCADE Technology is installed, the system administrator creates a single factory. This contains a single workshop as well as the warehouse containing OCCT resources in the form of parcels. + +There is no theoretical limit to the number of workshops that can be added to a factory. However, a single factory should be enough. + +@section occt_wok_3 Development Process +@subsection occt_wok_3_1 WOK Environment +The WOK interface is based on tcl, a command language provided by the Regents of the University of California and Sun Microsystems, Inc. The WOK development environment is in fact a tcl session. + + +Before you run a tcl session you must make sure that your account is configured for using tcl, see the Configuring Your Account for Tcl and WOK section. + +To start a tcl session use the command: +~~~~~ +% tclsh +~~~~~ +Within this session, all WOK commands are available as well as standard tcl commands. You can also use tcl language extensions, if these are installed. +To exit from a tcl session use the command: +~~~~~ +> exit +~~~~~ +Online help is provided with tcl. To access this, use the following command: +~~~~~ +% tclhelp +~~~~~ +Online help is also available for all WOK commands. To display help on a particular WOK command, give the command name followed by the -h flag, as in the following example: +~~~~~ +> wokcd -h +~~~~~ + +@subsection occt_wok_3_2 Steps +Implementation of an application is based on the following steps: +1. Enter the software factory using the command wokcd MyFactory +2. Enter a workshop using the command wokcd MyWorkshop +3. Open a workbench using the command wokcd MyWorkbench +4. Search for the data types required among the existing OCCT libraries +5. Define one or more packages which will contain the classes +6. Define new data types as classes +7. Implement the methods of those classes in C++ +8. Implement any package methods in C++ +9. Unite the test packages +10. Define any nocdlpacks (if any) +11. Test the components + +**Note:** Steps 1-3 can be performed with a single WOK command: +~~~~~ +> wokcd MyFactory:MyWorkshop:MyWorkbench +~~~~~ + +@subsection occt_wok_3_3 Getting Started +@subsubsection occt_wok_3_3_1 Entity Names +Before you start, the following restrictions on WOK entity names must be noted: + * Entity names may only contain alphanumeric characters and dashes. + * Entity names must be unique within a hierarchy. For example, you must not have two workbenches called MyBench in the same Workshop. Likewise, you may not have a workshop called CSF in a factory of the same name. + * Do not use upper and lower case characters to distinguish between two entity names, for example ENT1 and eNt1. This restriction is for reasons of portability. + * Parcel names must be unique. - Then create a WOK workbench (command wcreate) setting its Home to the directory, where the repository is created ($CASROOT variable). The workbench should have the same name as that directory. +@subsubsection occt_wok_3_3_2 Entering the Factory +When you start work you go to the factory using the following command: +~~~~~ +> wokcd +~~~~~ +@subsubsection occt_wok_3_3_3 Creating a New Workshop +If you don’t want to work in a workshop already present in the factory, you can create a new one. To do this, use the following command: +~~~~~ +> screate –d +~~~~~ +This creates the new workshop **MyWorkshop** in the current factory. To create the same workshop in a different factory use the syntax below: +~~~~~ +> screate –d +~~~~~ + +When you create a new workshop, it is empty. + +@subsubsection occt_wok_3_3_4 Selecting Parcels +When you create a workshop, you select existing OCCT resources, for example, parcels, to use in it. To do this, you create the workshop and add the parcels using the following syntax: +~~~~~ +> screate –d -DparcelConfig=Parcel1,Parcel2… +~~~~~ +To display available OCCT resources, in other words, to see what parcels are available, you use the following command: +~~~~~ +Winfo –p +~~~~~ +**Note:** parcel configuration rarely needs to change. If it does, only the workshop administrator should make them. +@subsubsection occt_wok_3_3_5 Opening a Workshop +To open a workshop, you use the following command: +~~~~~ +> wokcd +~~~~~ +@subsubsection occt_wok_3_3_6 Creating a New Workbench +When you create a new workshop, it is empty. In other words, it does not contain any workbenches. +To create the root workbench of a new workshop, you use the following command: +~~~~~ +> wcreate -d +~~~~~ +This creates a tree of workbench subdirectories. +If workbenches already exist in your workshop, but you do not want to work in any of these, create a new workbench as a child of an existing one. You do this using the following syntax: +~~~~~ +> wcreate –d -f +~~~~~ +@subsubsection occt_wok_3_3_7 Opening a Workbench +To open a workbench, you use the command below: +~~~~~ +> wokcd +~~~~~ +This automatically takes you to the root directory of the workbench + +@subsubsection occt_wok_3_3_8 Using Existing Resources +Before creating new data types, you should look for existing components that you can reuse. In particular, you should look through the existing resources of your Open CASCADE Technology platform to see if any of the required components already exist, or if any existing generic components can be suitably implemented. This search can be conducted using the online documentation. You should note the packages and classes, which you can reuse. +@subsection occt_wok_3_4 Creating Software Components +@subsubsection occt_wok_3_4_1 Creating a Package +To develop new software components, you usually need to create one or more packages. You do this, by using the following command: +~~~~~ +> ucreate –p +~~~~~ +Because the key -p defines the default value for the *ucreate* command, you do not need to specify it. The following syntax, for example, will also create a package: +~~~~~ + > ucreate +~~~~~ +#### Enter a Package or other Development Unit Structure + +Enter the package or any other development unit structure using the *wokcd* command as in the syntax below: +~~~~~ +> wokcd MyPackage +~~~~~ +The current directory is now: +~~~~~ +MyWorkbenchRoot/src/MyPackage +~~~~~ + +#### Writing the Package and Class Specifications in CDL + +Write the descriptions of the software components in CDL using an editor of your choice. Write each class in its own .cdl file and write one .cdl file (MyPackage.cdl) to specify the package that contains those classes. + +#### CDL Compilation of the Package + +Compile and check the package and its classes using: +~~~~~ + > umake –e xcpp +~~~~~ +This command also extracts the C++ header files (.hxx) and stores them in the derived files directory. + +#### Implementing Methods in C++ + +A package will contain methods, which may be: + * Instance methods + * Class methods + * Package methods. +Extract **prototypes** for the C++ methods using the following command: +~~~~~ + > umake -o xcpp.fill -o xcpp.template +~~~~~ + +You should not confuse this syntax with the template feature of C++ used to implement the genericity. +The *umake -o xcpp.template* command creates a skeleton C++ file for: + * Each class + * All the package methods. +The packages methods will be created in a file called *package.cxx.template*. This command is not included in the umbrella command *MyPackage*. +You will need to use an editor to implement these methods in C++. + + +#### Compiling the Package + +To compile the package, use the command: +~~~~~ + > umake -o obj +~~~~~ +If you do not specify a package, the current development unit is compiled. + +#### Sample Construction of a Package + +In the following example a workbench named **MyWb** is created as a child of an existing workbench **Topo**. MyWb is used for working on the package **MyPack**. Commands preceded by an asterisk below are used only once per session: +1. Create the MyWb workbench as a child of Topo. +~~~~~ + > wcreate MyWb -f Topo -d +~~~~~ +2. Create MyPack in MyWb. +~~~~~ + > ucreate MyPack     +~~~~~ +3. Move to the source directory of MyPack. +~~~~~ + > wokcd MyPack +~~~~~ +4. Edit the source files (MyPack.cdl etc.). You do this outside tcl, using the editor of your choice. +5. Start the extraction of MyPack. +~~~~~ +  > umake -e xcpp +~~~~~ +6. Generate the .cxx templates for MyPack: MyPack.cxx.template +~~~~~ +   > umake -o xcpp.fill -o xcpp.template -t +~~~~~ +7. Edit the source files (MyPack.cxx etc). You do this outside tcl, using the editor of your choice. + +**Note** that *umake* command used without arguments will carry out all the above *umake* steps. You can also use it with specific arguments as above to go through the development process step by step. + +#### Package Files + +* Primary Files for a Package + + .cdl Primary package file. + + _.cdl Primary class file. +* C++ Files for a Package + + .cxx Primary package source file. + + _[1..9[0..9]*].cxx Secondary package source files. + + .lxx Inline package methods source file. + + .pxx Private instructions source file. +* C++ Files for a Class + + _.cxx Primary class source file. + + __[1..9[0..9]*].cxx +* Secondary class source files. + + _.gxx Generic class methods source file. This is an alternative to the .cxx file(s), you do not have both. + + _.lxx Inline methods source file. + + _.pxx Private instructions source file. +* Derived C++ Files for a Package + + .hxx User header file. + + .ixx User header file included in .cxx. + + .jxx User header file included in _[1-9].cxx. +* Derived C++ files for a class + + _.hxx User header file. + + _.ixx User header file included in _.cxx. + + _.jxx User header file in __[1..9[0..9]*].cxx. + + Handle__.hxx Persistent or Transient class header file. + + __0.cxx For instantiated classes. + +Umake Steps for a Package +------------------------- +The umake steps for development units of package type are explained below. +* *src* Processes the file *MyPackage.cdl* to generate a list of all the CDL files in the development unit. Processes FILES to list source files. +* *xcpp.fill* Compiles the internal data structure to prepare for subsequent extractions. +* *xcpp.src* Lists the source files (.cxx, .gxx, .lxx) deduced from the CDL files. +* *xcpp.header* Extracts header files for the classes in the development unit. +* *xcpp.template* Extracts a template for implementation of methods. (Hidden step.) +* *obj.inc*     Based on the list of source files generated by the src and xcpp.src steps, this step publishes the include files for the development unit so that other units can use them. +* *obj.cgen* Processes the source files to generate code. +* *obj.comp*   Compiles each file that can be compiled. +* *obj.idep*     Generates dependency information for the unit. This comprises: + + Includes performed by unit compilation (Unit.MakeState) + + Implementation dependencies in terms of the unit suppliers (Unit.ImplDep) +* *obj.lib*    Generates the shared library for the development unit. + +@subsubsection occt_wok_3_4_2 Creating a Nocdlpack +If your executable requires the use of a nocdlpack, create a development unit of nocdlpack type and move to its structure using the commands below: +~~~~~ + > ucreate -n + > wokcd +~~~~~ +Use an editor to write *FILES*, which is a nomenclature file for a nocdlpack. This file must list all the C, C++, Fortran, lex, and yacc sourcs files (one per line). +Build the nocdlpack using the following command: +~~~~~ + > umake [] +~~~~~ +**Note** that a nocdlpack unit is not intended to perform tests. Use an executable unit instead. + + +#### Sample Construction of a Nocdlpack + +In the following example a nocdlpack *MyNocdlpack*, is created. Commands preceded by an asterisk below are used only once per session: +1. \*Create MyNocdlpack in MyWb. +~~~~~ +> ucreate -n +~~~~~ +2. Move to the source directory of MyNocdlpack. +~~~~~ +> wokcd +~~~~~ +3. Write the FILES list. You do this outside tcl, using the editor of your choice. +4. Write the source code. +5. Build MyNocdlpack. +~~~~~ +> umake [] +~~~~~ + +#### Umake Steps for a Nocdlpack + +The *umake* steps for development units of *nocdlpack* type are explained below. +* *src*   Processes FILES to list source files. +* *obj.cgen* Processes the source files to generate code. +* *obj.inc* Based on the list of source files, this step publishes the header files for the unit so that other units can use them. +* *obj.comp* Compiles each file that can be compiled. +* *obj.idep* Generates dependency information for the unit. This comprises: + + Includes performed by unit compilation. (Unit.MakeState) + + Implementation dependencies in terms of the unit suppliers. (Unit.ImplDep) +* *obj.lib* Generates the shared library for the unit. + +@subsubsection occt_wok_3_3_3 Creating a Schema +If the application, which you intend to build, stores data in a file, you need to define a schema for the persistent data types that are known. + +You create a schema and go to its root directory using the commands: +~~~~~ +> ucreate -n +> wokcd +~~~~~ +Using the editor of your choice, write a .cdl file to define the schema. This schema file lists all the packages that contain persistent data types used in the implementation of your application. It has the following format: +~~~~~ + schema MySchema + is +class from ; + end; +~~~~~ + +#### Building a Schema + +Compile and check the coherence of the CDL specification for the schema: +~~~~~ +> umake -e xcpp.fill +~~~~~ +Extract the C++ description: +~~~~~ +> umake -o xcpp +~~~~~ +Compile the C++ description of the schema: +~~~~~ +> umake -o obj +~~~~~ +Alternatively, the above three steps can all be carried out by one command: +~~~~~ +> umake +~~~~~ +#### Sample Construction of a Schema + +In the following example the schema *MySchema* is created. It contains all the schemas of the persistent classes of your own packages and the packages they depend on. Commands preceded by an asterisk below are used only once per session: +1. Create MySchema in MyWb. +~~~~~ + > ucreate -s MySchema +~~~~~ +2. Move to the source directory of MySchema. +~~~~~ +> wokcd MySchema +~~~~~ +3. Edit the source file MySchema.cdl. You do this outside tcl, using the editor of your choice. +4. Derive implementation files. +~~~~~ + > umake -e xcpp.sch +~~~~~ +5. Derive application schema files. +~~~~~ + > umake -o xcpp.ossg +~~~~~ +6. Compile the schema. +~~~~~ + > umake -o obj +~~~~~ + +#### Schema Files + +* Primary Files for a Schema + + *.cdl* Primary schema file. +* Derived C++ Files for a Schema + + *.hxx* User header files. + + *.cxx* Schema implementation files. + + *.cxx* Schema implementation files. + +#### Umake Steps for a Schema + +The umake steps for development units of schema type are explained below. +* *src*        Processes MySchema.cdl to generate a list of CDL files for the development unit. Processes the FILES file to list source files. +* *xcpp.fill*  Compiles the internal data structure to prepare for subsequent extractions. +* *xcpp.sch*   Extracts the schema implementation code. +* *obj.comp*   Compiles the extracted files that can be compiled. +* *obj.lib*    Generates the shared library for the unit. +* *obj.idep*   Generates dependency information for the schema. + +@subsection occt_wok_3_5 Building an Executable +@subsubsection occt_wok_3_5_1 Creating an Executable +To make an executable from one or more of the packages, which you have created, write a .cdl file to specify the packages to use. + +#### Writing an Executable + +Refer to the **CDL User’s Guide** for full details. A simple example is given below. + +~~~~~ + executable // the executable unit +is + executable myexec // the binary file +uses +Tcl_Lib as external +is + myexec; // the C++ file +end; // several binaries can be specified in one .cdl file. +executable myex2 +is + myex2; +end; + end; +~~~~~ + +Write the C++ file(s). For the example above you write two files: *myexec.cxx* and *myex2.cxx*. + +#### Building the Executable + +To build the executable, use the command *umake* + +#### Construction of an Executable + +In the following example an executable, *MyExec*, is created in the workbench *MyWb*. Commands preceded by an asterisk below are used only once per session: +1. \*Create MyExec in MyWb. +~~~~~ + > ucreate -x MyExec +~~~~~ +2. Move to the source directory of *MyExec*. +~~~~~ + > wokcd MyExec +~~~~~ +3. Edit the cdl source file *MyExec.cdl*. You do this outside tcl, using the editor of your choice. +4. Edit the C++ files *AnExe.cxx*, etc. You do this outside tcl, using the editor of your choice. +5. Build MyExec. +~~~~~ + > umake +~~~~~ +6. Run the executable file. +~~~~~ + > wokcd -PLib + > MyExec +~~~~~ + +#### Executable Files + +| .cdl | primary executable file | +| .cxx | Source C++ file | +| _[1-9].cxx | Other source C++ files | + +#### Umake Steps for an Executable + +The umake steps for development units of executable type are explained below. +* *src* Processes MyExe.cdl to generate a list of CDL files for the development unit. Processes FILES to list source files. +* *src.list* Based on MyExe.cdl, works out the list of parts and the source files involved for each part. +* *exec.comp* Compiles the files that can be compiled for each part of the executable. +* *exec.idep* Generates dependency information for each part of the executable. +* *exec.libs* Computes full implementation dependency to prepare for linking for each part of the executable. +* *exec.tks* Performs toolkit substitution according to TOOLKITS for each part of the executable. +* *exec.link* Links each part of the executable. + +@subsection occt_wok_3_6 Test Environments +@subsubsection occt_wok_3_3_1 Testing an Executable +To test an executable, you create an executable development unit and move to its structure. + +When you write the .cdl file for your test executable, specify the packages to test, for example: +~~~~~ +executable MyTest // the executable unit + is +executable mytest1 // the binary file +is + mytest1; //the C++ file +end; // several binaries can be specified in one .cdl file. +executable mytest2 +is + mytest2; +end; + end; +~~~~~ +Write the C++ test file(s), in the example, *mytest1.cxx* and *mytest2.cxx*. +#### Building the Executable + +To build the executable use the command: +~~~~~ +> umake +~~~~~ + +#### Setting up a Test Environment + +To set up a test environment, move to the /drv subdirectory that corresponds to the current profile (e.g. /MyExec/drv/DFLT/sun) and run the executable test file. +~~~~~ +> wokcd -PLib +> wokenv -s +> myApp +~~~~~ +The command *wokenv* is used with -s option to configure the test environment. +The command *wokenv –s* uses the current workbench to decide what actions are needed to configure the tcl shell for use as your test environment. +WOK sets the following environment variables: + +* $STATION - The current station. +* $TARGET_DBMS - The current database platform. +* $PATH - The current path, plus the bin directories of the parcels. +* $LD_LIBRARY_PATH The current path, plus the lib directories of the parcels. +WOK then sets a variable for each parcel listed in the parcel configuration of the current workshop. This variable is the original name of the delivery unit in the uppercase, with the suffix *HOME*. +* $ORIGDELIVUNITHOME is set as the root directory of the parcel. +WOK then sources the following files: + * MyFactory.tcl, found in the admin directory of the factory. + * MyWorkshop.tcl found in the admin directory of the workshop. +Then for each Workbench, WOK sources according to the hierarchy of the workbenches: + * Workbench.tcl, found in the /Adm directory of the workbench. - For example, assuming that OCCT repository has been cloned into D:/occt folder: - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl} - LOC:dev> wcreate occt -DHome=D:/occt - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +After the environment is set up, you are at a C shell prompt and can run the executable. - Note: $CASROOT is equal to D:/occt now +**Note** Environment variables are only set when the command is used with the option -s. Thus, if you change a workbench or a factory within WOK and then return to the test environment you must use *wokenv -s* to ensure that the set environment variables configuration is correct for the current WOK state. +The configuration actions that WOK performs can be written to a file and saved as a script. You can then edit this script to suit it to your own needs, and generate a personalized test environment. - Then you can work with this workbench using normal WOK functionality (wprocess, umake, etc.; see WOK Users Guide for details) or use it only for generation of derived sources and project files, and build OCCT with Visual Studio on Windows or make command on Linux, as described below. - -@section wok3 Generation of building projects +To create the script file use the following command: +~~~~~ + > wokenv -f -t csh +~~~~~ +This command generates a file, ScriptFile, which configures a C shell to mirror the current WOK environment. An example script file is given below. +~~~~~ +setenv STATION *sil* +setenv TARGET_DBMS *DFLT* +setenv KERNELHOME */adv_22/WOK/BAG/KERNEL-K1-2-WOK* +setenv LD_LIBRARY_PATH */adv_22/WOK/BAG/wok-K1-2/lib/sil:/adv_22/WOK/BAG/KERNEL-K1-2-WOK/sil/lib/* +setenv PATH */usr/tcltk/bin:/usr/bin:/bin:/usr/bin/X11:/lib:.:/SGI_SYSTEM/util_MDTV/factory_proc:/adv_22/WOK/BAG/KERNEL-K1-2-WOK/sil/bin/* +source /adv_22/WOK/BAG/KERNEL-K1-2-WOK/adm/Kernel.csh +~~~~~ - Use command wgenproj in WOK to generate derived headers, source and building projects files: - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl} - LOC:dev> wokcd occt - LOC:dev:occt> wgenproj [ -target= ] [ -no_wprocess ] - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -TARGET: - * vc8 - Visual Studio 2005 - * vc9 - Visual Studio 2008 - * vc10 - Visual Studio 2010 - * vc11 - Visual Studio 2012 - * cbp - CodeBlocks - * cmake - CMake - * amk - AutoMake - * xcd - Xcode --no_wprocess - skip generation of derived headers and source files +@subsection occt_wok_3_7 Building a Toolkit +@subsubsection occt_wok_3_7_1 Creating a Toolkit -Note that this command takes several minutes to complete at the first call. +You create and enter a toolkit development unit using the following commands: +~~~~~ + > ucreate -t + > wokcd +~~~~~ -Re-execute this step to generate derived headers, source and building projects files if some CDL files in OCCT have been modified (either by you directly, or due to updates in the repository). Note that in some cases WOK may fail to update correctly; in such case remove sub-directories drv and .adm and repeat the command. +#### Write the Nomenclature File for the Toolkit -To regenerate derived headers and source files without regeneration of projects use command: - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl} - LOC:dev> wokcd occt - LOC:dev:occt> wprocess -DGroups=Src,Xcpp - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The generated building project has been placed into $CASROOT/adm folder: - * for vc8 - $CASROOT/adm/msvc/vc8 - * for vc9 - $CASROOT/adm/msvc/vc9 - * for vc10 - $CASROOT/adm/msvc/vc10 - * for vc11 - $CASROOT/adm/msvc/vc11 - * for cbp - $CASROOT/adm/ /cbp - * for cmake - $CASROOT/adm/cmake - * for amk - $CASROOT/adm/lin/amk - * xcd - $CASROOT/adm//xcd +Using an editor, write a nomenclature file called PACKAGES which lists all the packages, one per line, that make up the toolkit. Add PACKAGES to FILES. +Build the shareable library for this toolkit as follows: +~~~~~ +\> umake [] +~~~~~ +**Note:** when one of the packages in the toolkit is modified, recompile the toolkit. A package should belong to one toolkit only. -@section wok4 Generation of documentation +#### Sample Construction of a Toolkit - Use command wgendoc in WOK to generate reference documentation: - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl} - :LOC:dev> wokcd occt - :LOC:dev:occt> wgendoc - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following options can be used: - * -wb=< workbench name > the name of OCCT workbench (the current one by default); - * -m=< list of modules > the list of modules that will be contained in the documentation; - * -outdir=< path > the output directory for the documentation; - * -chm the option to generate CHM file; - * -hhc=< path > the path to HTML Help Compiler (hhc.exe) or equivalent; - * -qthelp=< path > the option to generate Qt Help file, it is necessary to specify the path to qthelpgenerator executable; - * -doxygen=< path > the path to Doxygen executable - * -dot=< path > the path to GraphViz dot executable \ No newline at end of file +In the following example, the toolkit **TKMyToolkit** is created. Commands preceded by an asterisk are used only once per session: +1. \*Create MyToolkit in MyWb. +~~~~~ +\> ucreate -t TKMyToolkit +~~~~~ +2. Move to the source directory of MyToolkit. +~~~~~ +\> wokcd TKMyToolkit +~~~~~ +3. Edit the nomenclature files, PACKAGES and FILES. You do this outside tcl, using the editor of your choice. +4. \*Create the library for MyToolkit +~~~~~ +\> umake TKMyToolkit +~~~~~ + +#### Umake Steps for a Toolkit + +The umake steps for development units of toolkit type are explained below. +* *src* Processes FILES to list source files. +* *lib.list* Works out the objects and archive library to add to the toolkit shared library. +* *lib.limit* Manages the build process strategy within the limitations of a particular platform. +* *lib.arch* Builds archives according to the building strategy. +* *lib.uncomp* Decompresses third party archives. +* *lib.arx* Extracts object files from archives. +* *lib.build* Generates the shared library for the toolkit. + +Building strategy depends on the platform. The following step sequences apply: + * On Sun (Solaris): +~~~~~ +src +lib.list +lib.arx +lib.build +~~~~~ + * On sil (IRIX): +~~~~~ +src +lib.list +lib.uncomp +lib.build +~~~~~ + +#### The TOOLKITS File + +When executables are compiled, a TOOLKITS file is used to determine which toolkits are included. This file is located in the src directory of the entity being compiled. The process is as follows: +* If no TOOLKITS file has been found, all toolkits are candidates for substitution. To find out which toolkits are candidates, use the command *w_info -k*. +* If an empty TOOLKITS file has been found, there is no toolkit candidate for substitution. +* If a non-empty TOOLKITS file has been found, only the toolkits listed in this file are candidates for substitution. + +#### Toolkit Substitution + +Toolkit substitution is performed as follows: +1. MyEngine uses A, B and C; +2. The toolkit TK provides A and D; D uses E; +3. Compilation of *MyEngine* includes TK, B C and E. + +Here, for simplicity, assume that additional toolkits are not substituted for B, C and E. + +@subsection occt_wok_3_8 Building a Delivery Unit +@subsubsection occt_wok_3_8_1 Creating a Delivery Unit +~~~~~ +\> ucreate -d +~~~~~ + +#### Writing the COMPONENTS File + +Create a file named COMPONENTS in the src subdirectory of the delivery development unit. List in this file the prerequisites of the delivery and the components that are part of the delivery. Use the syntax shown below. +Note that keywords and default options are shown in bold. + +| **Name** | ParcelName | +| Put path | | +| Put include || +|Put lib || +| **Requires** | DeliveryName\* | +| **Package** | MyPack **[CDL][LIBRARY][INCLUDES][SOURCES]** | +| **Nocdlpack** | MyNcdl **[LIBRARY][INCLUDES][SOURCES]** | +| **Executable** | MyExec **[CDL][DYNAMIC][SOURCES]** | +| **Interface** | MyIntf **[CDL][STUB_SERVER][SOURCES]** | +| **Client** | MyClient **[CDL]**[STUB_CLIENT][SOURCES] | +| **Engine** | MyEng **[CDL][DYNAMIC][SOURCES]** | +| **Schema** | MyShma **[CDL][LIBRARY][SOURCES][DOC]** | +| **Toolkit** |MyTk **[LIBRARY][SOURCES]** | +| **Get** | DevelopmentUnitName::Type:::File | + +\* Without mention of the version + +If no keywords are specified then all default arguments shown in bold are taken into account. To select arguments, list the ones required explicitly. The arguments are explained below: +* **Name** The full name of the current delivery, including a version number. This is the name of the parcel. +* **Put path** Requires that the delivery be inserted in the user path (bin directory). +* **\[CDL\]** Copy the cdl files to the delivery. +* **\[LIBRARY\]** Generate the static library. Copy the shareable library to the delivery. Copy the list of objects of the library. +* **\[INCLUDES\]** Generate includes.origin. Copy the includes to the delivery. Copy the ddl to the delivery. +* **\[DYNAMIC\]** Select to copy the static or dynamic executable file. +* **\[SOURCES\]** Copy the source files. + +#### Build the Delivery + +To build the delivery unit, use the command: +~~~~~ +\> umake +~~~~~ +The result of building a delivery unit is a **parcel**, which can be installed in a warehouse and used by other workbenches. + +#### Sample Delivery of a Parcel + +In the following example a delivery is created, compiled and made into a parcel. Commands preceded by an asterisk below are used only once per session: +1. Move to the root workbench under which the parcel is to be made. +~~~~~ +> wokcd MyRootWb +~~~~~ +2. \*Create MyDelivery in MyRootwb. +~~~~~ +> ucreate -d MyDelivery +~~~~~ +3. Move to the source directory of MyDelivery. +~~~~~ +> wokcd MyDelivery +~~~~~ +4. Use an editor to list all the prerequisites and components of the delivery in the COMPONENTS files using the appropriate syntax. +5. Build MyDelivery. +~~~~~ +> umake MyDelivery +~~~~~ +The output of the umake process is a parcel + +#### Umake Steps for a Delivery Unit + +The umake steps for development units of type delivery are explained below. +* *src* Processes FILES to list source files. +* *base*     Creates directories, defines the list of units, copies the parcels and the release notes. +* *get.list*        Lists files to get (using Get, Resource). +* *get.copy* Copy the files listed by get.list. +* *cdl.list*    Lists CDL files to copy. +* *cdl.copy*   Copies the files listed by cdl.list. +* *source.list* Lists units from which sources are to be copied. +* *source.build*    Creates a file for sources (in the format: unit.type.Z). +* *inc.list*         Lists includes to copy. +* *inc.copy*   Copies files listed by inc.list. +* *lib.shared* Works out the inputs for building or copying shareable libraries. +* *lib.shared.build* Copies or builds (depending on the platform) the shareable libraries. +* *lib.server.list*   Lists interface files to copy. +* *exec.list*    Lists inputs for executable delivery. +* *exec.build* Creates executable in the parcel. +* *files*   Works out the list of files delivered in the parcel. + +@subsubsection occt_wok_3_8_2 Installing a Parcel +You open the root workbench of the workshop where you want to install the parcel using the following command: +~~~~~ +\> wokcd +~~~~~ +To install the parcel, use the following syntax: +~~~~~ +\> pinstall +~~~~~ + +@subsection occt_wok_3_9 Working with Resource + +### Building a Resource + +There is a single umake step for development units of resource type. +* *src*                 Processes FILES to list source files. + +@subsection occt_wok_3_10 Java wrapping +@subsubsection occt_wok_3_10_1 Creating an interface + +To create an interface development unit and move to its structure, use commands: +~~~~~ +\> ucreate -i +\> wokcd +~~~~~ + +### Writing an Interface + +Having created the interface, you select the classes and packages that you wish to make available for Java wrapping in the jni units. Use an editor of your choice to write a .cdl interface file that specifies these exported services. This file has the format: + +~~~~~ +interface MyInterface +uses +  ListOfPackages; +is +  ListOfPackages; +  ListOfClasses; +  ListOfMethods; +end; +~~~~~ + +### Building an Interface + +To make the services of the interface available for further wrapping, build the interface, using the command: +~~~~~ +> umake [] -o src +~~~~~ + +### Sample Construction of an Interface + +In the following example a workbench, *MyWb*, is used for working on the interface *MyInterface*. Commands preceded by \* (asterisk) are used only once during a session. + +1. \*Create MyInterface in MyWb. +~~~~~ +>ucreate -i MyInterface +~~~~~ +2. Move to the source directory of MyInterface. +~~~~~ +>wokcd MyInterface +~~~~~ +3. Edit the source file MyInterface.cdl. You do this outside tcl, using an editor of your choice. +4. Build the interface. +~~~~~ +> umake -o src +~~~~~ + +### Interface Files + +_.cdl_ is the primary interface file. + +### Umake Steps for an Interface + +The umake steps for development units of type interface are explained below. + +* *src* - processes *MyInt.cdl* to list the CDL files for the development unit. Processes the FILES file to list source files. + +**Note** Make sure you only use the *src* step of umake. Using umake without arguments will lead to an attempt of launching other steps relevant to the interface unit. However these steps will fail and anyway are not required for use in Java wrapping. + +@subsubsection occt_wok_3_10_2 Creating a jni +To create a development unit of type jni and move to its structure, use commands: +~~~~~ +> ucreate -j +> wokcd +~~~~~ + +### Writing a Jni + +Use an editor to write a .cdl file that specifies the interface or interfaces required by the jni. This file has the following format: +~~~~~ +client MyJni +is +{interface MyInterface;} +{interface YourInterface;} +end; +~~~~~ + +### Building a Jni + +To wrap services exported by the interfaces to Java, build the jni, using the command: +~~~~~ + > umake [MyJni] +~~~~~ + +### Sample Construction of a Jni + +In the following example a workbench, *MyWb*, is used for working on the jni, *MyJni*. Commands preceded by \* (asterisk) are used only once during a session. + +1. \*Create MyJni in MyWb. +~~~~~ +> ucreate -j MyJni +~~~~~ +2. Move to the source directory of *MyJni*. +~~~~~ +> wokcd MyJni +~~~~~ +3. Edit the source file *MyJni.cdl*. You do this outside tcl, using an editor of your choice. +4. Derive Java files (.java and .class files) and C++ files (.h and .cxx) used for wrapping. +~~~~~ + > umake -e xcpp +~~~~~ +5. Compile the sources. +~~~~~ +> umake -o obj +~~~~~ +6. Link the object files. +~~~~~ +> umake -o exec +~~~~~ + +Primary jni file is *Jni.cdl* + +Derived Java files for a Jni are: +* _.java - Java source file of the class to be wrapped. +* _.class - Compiled java source file. + +Derived C++ files for a Jni are: +* ___java.h - Include file for the C++ implementation of JNI. +* ___java.cxx - C++ implementation of JNI. + +### Umake Steps for a Jni + +The umake steps for development units of type jni are explained below. +* *src*        Processes MyJni.cdl to list the CDL files for the development unit. Processes the FILES file to list source files. +* *xcpp.fill*     Compiles the internal data structure to prepare for subsequent extractions. +* *xcpp.client* Extracts the services declared in included interface unit(s) into Java and creates .java and \*_java.cxx files. +* *xcpp.javac* Compiles .java files into .class files. +* *xcpp.javah* Creates .h header files. +* *obj.comp* Compiles generated C++ files. +* *obj.idep*    Generates dependency information for the unit. +* *exec.libs* Computes full implementation dependency to prepare for linking. +* *exec.tks*    Performs toolkit substitution. +* *exec.link*    Generates the shared library for the development unit. + +@subsection occt_wok_3_11 More Advanced Use +@subsubsection occt_wok_3_11_1 Default User Profile +There is a default user profile. If you wish to change this profile the command *wokprofile* is available. + +An example profile is given below. +~~~~~ + Info : Profile in : WOK:k1dev:ref + Info : Extractor : DFLT + Info : Compile Mode : Optimized + Info : Station Type : sil +~~~~~ +@subsubsection occt_wok_3_11_2 Changing Parcel Configuration +Parcel configuration rarely needs changes. However, if you do need to modify the list of resources, you can do so by editing the admin parameter file of the factory. This file is found in the admin directory of the factory and is named after the workshop. It has the suffix .edl. Its full name has the following format: +~~~~~ +.edl. +~~~~~ + +Move to the admin directory of the factory: +~~~~~ +\> wokcd -PAdm +~~~~~ + +Then use the editor of your choice to edit the admin parameter file, MyWorkshop.edl. +In this file, the parcel configuration is defined by an entry of the form: +~~~~~ +\@set %_ParcelConfig = “Parcel1 Parcel2...Parceln”; +~~~~~ +The resources are listed within quotation marks. They are separated by spaces. +Edit this list as required. Save the file and close it. +To validate and take into account your changes use the command: +~~~~~ +\> wokclose -a +~~~~~ +This command closes and reopens all the entities. Without the -a option, *wokclose* only applies to the current entity. + +@section occt_wok_4_ Available Services +@subsection occt_wok_4_1 Synopsis +WOK provides sets of services, which can be grouped according to the entity they apply to: + * General Services + * Factories + * Warehouses + * Parcels + * Workshops + * Workbenches + * Development Units + * Source Management Services + * Session Services +@subsubsection occt_wok_4_1_1 Common Command Syntax + +#### Command Names + +All WOK commands follow a common naming convention. This is based on a set of common command names and a group of prefixes, which denote entity type. The command name takes a prefix representing the entity to which it applies. +The following prefixes exist: + * f: for factories + * s: for workshops + * w: for workbenches + * u: for development units + * W: for warehouses + * p: for parcels + * wok: for commands that apply to any type of entity +These prefixes are followed by a command that determines the action to be executed. Examples of such commands are: + * create: create an entity + * rm: delete an entity + * info: request information +Consequently, the command ucreate creates a development unit. The command wrm removes a workbench. + +#### Command Options + +All command options are expressed using a dash (-) followed by one or more key letters and, if applicable, an argument. For example: +~~~~~ +> umake -f -o MyUnit +~~~~~ +The compact version of this syntax is also valid: +~~~~~ + umake -fo argument MyUnit +~~~~~ +This syntax conforms to the POSIX recommendations for UNIX commands. +For all commands, there is a –h option, which displays help on usage. + +#### Presentation of Commands + +The general syntax of the commands is presented in this document as follows: +~~~~~ +CommandName [option(s) [] []] +~~~~~ +Consequently, there are four general cases for a command: +~~~~~ +CommandName +CommandName [] +CommandName [] +CommandName +~~~~~ +**Note** a few commands described in this chapter do not completely respect this syntax; for example, *create* and *rm*. + +As a rule, where an __ is given as an argument it specifies which entity the command applies to. Where no __ is specified, the command applies to the nearest appropriate entity. The *create* and *rm* commands are notable exceptions: you **must** specify an entity path with these commands. + +@subsection occt_wok_4_2 General Services +General services are commands that apply to any entity manipulated by WOK. They are used for: + * Navigation + * Managing parameters + * Managing profiles. + +@subsubsection occt_wok_4_2_1 wokcd +~~~~~ +wokcd +wokcd +wokcd -P [] +~~~~~ + +Navigates between different WOK entities and changes the current working directory. Without any arguments wokcd lists the current position (the WOK equivalent of ‘pwd’). With an argument, wokcd moves to the specified location. +Options: +* __ Moves to the home directory of the entity specified by , i.e. moves to the location given by the parameter: %wokcd _Home. +* _-P []_ Moves to the directory of the entity specified by . i.e. moves to the location given by the parameter: %_. If no entity path is specified, this command moves to the directory of the current entity. + +Possible values for are: Home, Adm and Src. +Use the following commands to change directories within a development unit: +* **wsrc** To access the source files. +* **winc** To access the include files. +* **wobj** To access objects. +* **wlib** To access shareable libraries. +* **wbin** To access executables. +* **wadm** To access the workbench administration files. + +#### Examples + +*wokcd* - Lists the current position. + +*wokcd MODEL:GTI:gti:gp* - Moves to the home directory of the gp package of the gti workbench in the GTI workshop in the MODEL factory. + +*wokcd -P Adm* - Moves to the administration directory of the current entity. + + +@subsubsection occt_wok_4_2_2 wokclose +~~~~~ +wokclose [-a] +~~~~~ +Closes and reopens entities, i.e. reloads them into memory thus taking any changes into account. +Option -a closes and reloads all entities. + +#### Examples + +~~~~~ +wokclose +~~~~~ +Closes and reopens the current entity. +~~~~~ +wokclose -a +~~~~~ +Closes and reopens all the entities. +@subsubsection occt_wok_4_2_3 wokenv +~~~~~ +wokenv -f -t csh +~~~~~ +Creates the file . This file is a script, which configures a C shell to mirror the current WOK environment. See the Test Environments section for more details. +Options: +* -f - Specifies the name of the file to produce. +* -t csh - Produces a file for configuring a C shell. +* -s - Sets up environment variables for application launching. +Example +------- +~~~~~ +> wokenv -f MyTestEnvScript -t csh +~~~~~ +Generates the shell script *MyTestEnvScript* to configure a C shell so that it mirrors the current WOK environment. +@subsubsection occt_wok_4_2_4 wokinfo +~~~~~ +wokinfo -