mirror of
https://git.dev.opencascade.org/repos/occt.git
synced 2025-08-04 13:13:25 +03:00
0024269: Content of occt documentation should be formated
building subsection introduced; wok moved to dev guides section;
Requirements and Installation sections were interchanged;
some Unicode characters removed from .md files; \DeclareUnicodeCharacter{00A0}{ } instruction added into refman file
images insertion rolled back to dual html,latex insertion; mainpage now is processed (index.tex);
surplus part of overview has been removed
foundation_classes.md and technical_overview.md updated;
Reviewed step, tobj, xde and partly iges; Corrections in other guides.
Overview installation and requirements changes updated
This commit is contained in:
ysn
bugmaster
32
dox/dev_guides/building/building.md
Normal file
32
dox/dev_guides/building/building.md
Normal file
@@ -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
|
||||
BIN
dox/dev_guides/building/wok/images/wok_image001.jpg
Normal file
BIN
dox/dev_guides/building/wok/images/wok_image001.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 43 KiB |
BIN
dox/dev_guides/building/wok/images/wok_image002.jpg
Normal file
BIN
dox/dev_guides/building/wok/images/wok_image002.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 72 KiB |
|
Before Width: | Height: | Size: 43 KiB After Width: | Height: | Size: 43 KiB |
|
Before Width: | Height: | Size: 50 KiB After Width: | Height: | Size: 50 KiB |
157
dox/dev_guides/building/wok/wok.md
Normal file
157
dox/dev_guides/building/wok/wok.md
Normal file
@@ -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 <WOK_INSTALL_DIR>.
|
||||
|
||||
* Perform the following commands assuming that you have unpacked WOK distributive archive into <WOK_INSTALL_DIR>:
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
|
||||
cd <WOK_INSTALL_DIR>/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 <WOK_INSTALL_DIR>/site
|
||||
wok_init.sh
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* Your installation procedure is over. To run WOK use one the following commands:
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
|
||||
cd <WOK_INSTALL_DIR>/site
|
||||
wok_emacs.sh
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
or
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
|
||||
cd <WOK_INSTALL_DIR>/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. <WOK_INSTALL_DIR>.
|
||||
|
||||
* Browse in the Finder to the folder <WOK_INSTALL_DIR>/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 <WOK_INSTALL_DIR>/site
|
||||
wok_init.sh
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* Your installation procedure is over. To run WOK in Emacs navigate in the Finder to the folder <WOK_INSTALL_DIR>/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 User<65>s 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=<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/<OS> /cbp
|
||||
* for cmake - $CASROOT/adm/cmake
|
||||
* for amk - $CASROOT/adm/lin/amk
|
||||
* xcd - $CASROOT/adm/<OS>/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
|
||||
@@ -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.
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
</td>
|
||||
<td>
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
@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.
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
</td>
|
||||
<td>
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
@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
|
||||
<table>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
</td>
|
||||
<td>
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
@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.
|
||||
|
||||
|
||||
@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.
|
||||
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
</td>
|
||||
<td>
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
@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.
|
||||
<table>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
</td>
|
||||
<td>
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
@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**.
|
||||
|
||||
|
||||
@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.
|
||||
<table>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
</td>
|
||||
<td>
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table> 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
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
</td>
|
||||
<td>
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
@image html /dev_guides/cdl/images/cdl_image012.jpg
|
||||
@image latex /dev_guides/cdl/images/cdl_image012.jpg
|
||||
|
||||
@@ -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
|
||||
@@ -20,6 +20,9 @@ The latest version: http://www.mathjax.org/download/
|
||||
<b>MiKTeX</b> 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
|
||||
|
||||
|
||||
@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
|
||||
|
||||
@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
|
||||
<a href="#OCCT_DOC_SECTION_5">Doxygen Configuration file</a>
|
||||
@endhtmlonly
|
||||
@endverbatim
|
||||
|
||||
to get a link to paragraph : @htmlonly <a href="#OCCT_DOC_SECTION_5">Doxygen configuration</a> @endhtmlonly
|
||||
|
||||
@subsection OCCT_DM_SECTION_A_7 Images
|
||||
|
||||
To insert image into document the developer can write the following code(in Doxygen-style):
|
||||
@verbatim
|
||||
|
||||
@endverbatim
|
||||
|
||||
This code tells Doxygen to insert a picture right in the place this code was written. Like this:
|
||||
@verbatim
|
||||
|
||||
@endverbatim
|
||||
|
||||
|
||||
|
||||
@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 \<head\> block has to contain
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.html}
|
||||
<script type="text/x-mathjax-config">
|
||||
MathJax.Hub.Config({
|
||||
tex2jax: {inlineMath: [["$","$"],["\\(","\\)"]]},
|
||||
displayAlign: "left"
|
||||
});
|
||||
</script>
|
||||
|
||||
<script type="text/javascript"
|
||||
src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
|
||||
</script>
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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
|
||||
<a href="#OCCT_DM_SECTION_X_X_X">Directory Structure</a> @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}
|
||||
<doxygenlayout version="1.0">
|
||||
<!-- Generated by doxygen 1.8.3.1 -->
|
||||
<!-- Navigation index tabs for HTML output -->
|
||||
<navindex>
|
||||
<tab type="mainpage" visible="yes" title="Introduction"/>
|
||||
<tab type="pages" visible="yes" title="Documents" intro=
|
||||
"This section contains links to all OCCT documents that are available at the moment"/>
|
||||
<tab type="modules" visible="no" title="" intro=""/>
|
||||
<tab type="namespaces" visible="no" title="">
|
||||
<tab type="namespacelist" visible="no" title="" intro=""/>
|
||||
<tab type="namespacemembers" visible="no" title="" intro=""/>
|
||||
</tab>
|
||||
<tab type="classes" visible="no" title="">
|
||||
<tab type="classlist" visible="no" title="" intro=""/>
|
||||
<tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
|
||||
<tab type="hierarchy" visible="no" title="" intro=""/>
|
||||
<tab type="classmembers" visible="no" title="" intro=""/>
|
||||
</tab>
|
||||
<tab type="files" visible="yes" title="Files">
|
||||
<tab type="filelist" visible="yes" title="" intro=""/>
|
||||
<tab type="globals" visible="yes" title="" intro=""/>
|
||||
</tab>
|
||||
<tab type="examples" visible="no" title="" intro=""/>
|
||||
</navindex>
|
||||
...
|
||||
</doxygenlayout>
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The tag \<tab\> 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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@image html /dev_guides/tests/images/tests_image001.png
|
||||
@image latex /dev_guides/tests/images/tests_image001.png
|
||||
|
||||
Figure 1. Layout of tests folder
|
||||
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 43 KiB After Width: | Height: | Size: 6.7 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 72 KiB After Width: | Height: | Size: 3.5 KiB |
BIN
dox/dev_guides/wok/images/wok_image005.jpg
Normal file
BIN
dox/dev_guides/wok/images/wok_image005.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 33 KiB |
BIN
dox/dev_guides/wok/images/wok_image005.png
Normal file
BIN
dox/dev_guides/wok/images/wok_image005.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 29 KiB |
BIN
dox/dev_guides/wok/images/wok_image006.png
Normal file
BIN
dox/dev_guides/wok/images/wok_image006.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 7.9 KiB |
BIN
dox/dev_guides/wok/images/wok_image007.png
Normal file
BIN
dox/dev_guides/wok/images/wok_image007.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 15 KiB |
BIN
dox/dev_guides/wok/images/wok_image008.png
Normal file
BIN
dox/dev_guides/wok/images/wok_image008.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 39 KiB |
BIN
dox/dev_guides/wok/images/wok_image009.png
Normal file
BIN
dox/dev_guides/wok/images/wok_image009.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
BIN
dox/dev_guides/wok/images/wok_image010.png
Normal file
BIN
dox/dev_guides/wok/images/wok_image010.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
BIN
dox/dev_guides/wok/images/wok_image011.png
Normal file
BIN
dox/dev_guides/wok/images/wok_image011.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 26 KiB |
BIN
dox/dev_guides/wok/images/wok_image012.png
Normal file
BIN
dox/dev_guides/wok/images/wok_image012.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 15 KiB |
BIN
dox/dev_guides/wok/images/wok_image013.jpg
Normal file
BIN
dox/dev_guides/wok/images/wok_image013.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 7.0 KiB |
BIN
dox/dev_guides/wok/images/wok_image014.jpg
Normal file
BIN
dox/dev_guides/wok/images/wok_image014.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
BIN
dox/dev_guides/wok/images/wok_image015.png
Normal file
BIN
dox/dev_guides/wok/images/wok_image015.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 25 KiB |
BIN
dox/dev_guides/wok/images/wok_image016.png
Normal file
BIN
dox/dev_guides/wok/images/wok_image016.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.2 KiB |
BIN
dox/dev_guides/wok/images/wok_image017.png
Normal file
BIN
dox/dev_guides/wok/images/wok_image017.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.5 KiB |
BIN
dox/dev_guides/wok/images/wok_image018.png
Normal file
BIN
dox/dev_guides/wok/images/wok_image018.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.5 KiB |
BIN
dox/dev_guides/wok/images/wok_image019.png
Normal file
BIN
dox/dev_guides/wok/images/wok_image019.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.5 KiB |
BIN
dox/dev_guides/wok/images/wok_image020.png
Normal file
BIN
dox/dev_guides/wok/images/wok_image020.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.4 KiB |
BIN
dox/dev_guides/wok/images/wok_image021.png
Normal file
BIN
dox/dev_guides/wok/images/wok_image021.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 34 KiB |
BIN
dox/dev_guides/wok/images/wok_image022.png
Normal file
BIN
dox/dev_guides/wok/images/wok_image022.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 107 KiB |
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user