8713dddf4faf4a1311398209089d70b24a1f4237
[occt.git] / dox / dev_guides / wok / wok.md
1 Workshop Organisation Kit  {#dev_guides__wok}
2 =========================
3
4 @tableofcontents
5
6 @section occt_wok_0 DEPRECATION WARNING
7
8 Please note that this document describes use of WOK as comprehensive
9 build system. This use is outdated, and WOK is to be removed in
10 one of future releases of OCCT.
11
12 Currently only small subset of WOK capabilities described in this document
13 are actually necessary for building OCCT. See @ref dev_guides__building__wok
14 for more practical guide.
15
16 @section occt_wok_1_ Introduction Glossary
17
18 @subsection occt_wok_1_1 About the Development Environment
19
20 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.  
21 @subsection occt_wok_1_2 Brief Overview of Open CASCADE Technology Development Environment
22 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.   
23
24 @image html /dev_guides/wok/images/wok_image005.png "Schematic View of OCCT Development Platform"
25 @image latex /dev_guides/wok/images/wok_image005.png "Schematic View of OCCT Development Platform"
26
27 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**.  
28
29 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.  
30 @subsection occt_wok_1_3 WOK Components
31 @subsubsection occt_wok_1_3_1 Entities
32 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 <a href="#occt_wok_1_4">Glossary</a> section. 
33 @subsubsection occt_wok_1_3_2 Files
34 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.  
35
36 @subsection occt_wok_1_4 Glossary
37 @subsubsection occt_wok_1_4_1 Development Units
38 A **development unit** is the smallest unit that can be subject to basic development operations such as modifying, compiling, linking and building.  
39 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*. 
40 * package (p) A set of related classes and methods along with their CDL definitions. 
41 * schema (s) A set of persistent data types. 
42 * executable (x) An executable is used for unit and integration test purposes. It is based on one or more packages. 
43 * nocdlpack (n) A package without a CDL definition. Used for low-level programming or for incorporating foreign resources. 
44 * interface (i) A specific set of services available for wrapping (an interface contains packages, classes, and methods). 
45 * jni (j) A development unit used to wrap C++ classes to Java. It is based on one or more interfaces. 
46 * toolkit (t) A set of packages. Useful in grouping packages together when there is a large number of packages based around a particular subject. 
47 * delivery (d) A development unit for publishing development units. 
48 * resource (r) A development unit containing miscellaneous files. 
49
50 @subsubsection occt_wok_1_4_2 Workbenches
51 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. 
52 @image html /dev_guides/wok/images/wok_image006.png "Schema of a Workbench Containing three Development Units"
53 @image latex /dev_guides/wok/images/wok_image006.png "Schema of a Workbench Containing three Development Units"
54
55 @subsubsection occt_wok_1_4_3 Workshops
56 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. 
57 The root workbench is in a valid state and contains the working versions of the development units. 
58 Development units in a root workbench are visible in its child workbenches. 
59
60 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
61 @image html /dev_guides/wok/images/wok_image007.png "Workbenches"
62 @image latex /dev_guides/wok/images/wok_image007.png "Workbenches"
63
64 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. 
65
66 @image html /dev_guides/wok/images/wok_image008.png "Two Workshops Delivering and Borrowing Parcels"
67 @image latex /dev_guides/wok/images/wok_image008.png "Two Workshops Delivering and Borrowing Parcels"
68
69 @subsubsection occt_wok_1_4_4 Factories
70 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. 
71 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. 
72
73 @image html /dev_guides/wok/images/wok_image009.png "Factory Contains Workshops and Warehouse"
74 @image latex /dev_guides/wok/images/wok_image009.png "Factory Contains Workshops and Warehouse"
75
76 @section occt_wok_2_ Elements of the Platform
77 @subsection occt_wok_2_1 Development Units
78 A **development unit** is the basic element of WOK development. It includes the following three entities: 
79   *  A directory structure (a minor component) 
80   *  Source files, also called primary files 
81   *  The result of the build process (compilation, etc.), also called derived files. 
82
83 @subsubsection occt_wok_2_1_1 Directory Structure of a Development Unit
84 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 <a href="#occt_wok_2_2">Workbenches</a> section for further details on the workbench structure. 
85 @subsubsection occt_wok_2_1_2 Files in a Development Unit
86
87 #### Source Files
88  
89 Source files are written by the developer in the source section (the *src* directory) of the development unit. 
90 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: 
91 * 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. 
92 * schema (s) No description of the source files is needed. There is a single source file: *schema.cdl*. 
93 * executable (x) The names of all source files are worked out from the CDL description. The format of this file is described in the <a href="#occt_wok_3_5">Building an Executable</a> section. 
94 * nocdlpack (n) The list of source files is contained in the FILES file stored in the unit’s src directory. 
95 interface (i). No description of the source files is needed. There is a single source file: *interface.cdl*. 
96 * jni (j). No description of the source files is needed. There is a single source file: *jni.cdl*. 
97 * 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. 
98 * 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. 
99 * 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*. 
100
101 #### Derived files
102
103 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. 
104
105 @subsubsection occt_wok_2_1_3 Package
106 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.  
107 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. 
108 C++ implementation files are also stored in the src subdirectory of the package development unit. These implementation files are: 
109   *  .cxx for an ordinary class 
110   *  .lxx for any inline methods 
111   *  .pxx for any private declarations 
112   *  .gxx for a generic class 
113   
114 To create the Development Unit structure for a package use the following syntax:
115 ~~~~~
116 ucreate –p MyPackage 
117 ~~~~~
118
119 The package description has the following CDL syntax: 
120 ~~~~~
121 package PackageName 
122 [uses AnotherPackage {‘,’ YetAnotherPackage}] 
123 is 
124 [{type-declaration}] 
125 [{package-method}] 
126 end [PackageName]’:’ 
127 ~~~~~
128
129 For example:
130 ~~~~~
131 package CycleModel 
132 uses 
133 Pcollection 
134 Tcollection 
135 BREpPrimAPI 
136 TopExp 
137 Geom 
138 Pgeom 
139 is 
140 deferred class Element; 
141 class Wheel; 
142 class Frame; 
143 class LocalReference; 
144 Adjust(awheel: wheel from CycleModel; 
145   aframe: Frame from CycleModel); 
146 end CycleModel; 
147 ~~~~~
148 For full details on the CDL syntax, refer to the *CDL User’s Guide*. 
149
150 @subsubsection occt_wok_2_1_4 Schema
151
152 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**. 
153
154 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. 
155
156 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. 
157
158 To create the Development Unit structure for a schema use the syntax below: 
159 ~~~~~
160 ucreate –s MySchema 
161 ~~~~~
162
163 The schema description has the following CDL syntax : 
164
165 ~~~~~
166 schema SchemaName 
167 is 
168 ListOfPackagesContainingPersistentClasses; 
169 ListOfPersistentClasses; 
170 end; 
171 ~~~~~
172
173 For example:
174 ~~~~~ 
175 schema MyCycleSchema 
176 is 
177 class Wheel from package CycleModel; 
178 class Frame from package CycleModel; 
179 .. 
180 class Spanner from package CycleTools; 
181 end; 
182 ~~~~~
183 For full details on the CDL syntax, refer to the *CDL User’s Guide*. 
184
185 @subsubsection occt_wok_2_1_5 Executable
186 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. 
187
188 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. 
189
190 To create the Development Unit structure for an executable, use the syntax below: 
191 ~~~~~
192 ucreate –x MyExec 
193 ~~~~~
194
195 The executable description has the following CDL syntax: 
196 ~~~~~
197 executable ExecName 
198 is 
199 executable BinaryFile 
200 uses 
201 LibFile as external 
202 is 
203 C++File; 
204 end; 
205 end; 
206 ~~~~~
207
208 For example:
209 ~~~~~
210 executable MyExecUnit’ 
211 is 
212 executable myexec 
213 uses 
214 Tcl_Lib as external 
215 is 
216 myexec; 
217 end; 
218 executable myex2 
219 is 
220 myex2; 
221 end; 
222 end; 
223 ~~~~~
224 For full details on the CDL syntax, refer to the *CDL Reference Manual*. 
225
226 @subsubsection occt_wok_2_1_6 Toolkit
227 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: 
228   *  Linking of large numbers of packages 
229   *  Faster loading of executable files that use toolkits such as test files. 
230   
231 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. 
232
233 You then compile the toolkit to create a shareable library. 
234
235 @subsubsection occt_wok_2_1_7 Nocdlpack
236 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. 
237
238 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. 
239
240 On compilation, the result is a shareable library. 
241
242 @subsubsection occt_wok_2_1_8 Interface
243 An interface is a development unit that defines a set of services available for wrapping into Java. 
244 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. 
245
246 To create the Development Unit structure for an interface, use the syntax below: 
247 ~~~~~
248 ucreate -i MyInterface 
249 ~~~~~
250
251 The interface description has the following CDL syntax: 
252
253 ~~~~~
254 interface InterfaceName 
255 is 
256 ListOfPackages 
257 ListOfClasses 
258 ListOfMethods 
259 end; 
260 ~~~~~
261
262 For example:
263 ~~~~~
264 interface MyInterface 
265 is 
266         package TopoDS; 
267         class Shape from ShapeFix; 
268 end ; 
269 ~~~~~
270
271 @subsubsection occt_wok_2_1_9 Jni
272 A jni is a development unit that wraps declared services into Java using JNI (Java Native Interface). 
273
274 A jni creates Java classes that are used as C++ counterparts when developing in Java. 
275
276 To create the Development Unit structure for an Jni, use the syntax below: 
277 ucreate -j MyJni 
278
279 The interface description has the following CDL syntax: 
280 ~~~~~
281 client JniName 
282 is 
283 {interface InterfaceName;} 
284 end; 
285 ~~~~~
286
287 For example :
288 ~~~~~
289 client MyJni 
290 is 
291         interface MyInterface; 
292         interface MyAnotherInterface; 
293 end ; 
294 ~~~~~
295
296 @subsubsection occt_wok_2_1_10 Delivering Parcels
297 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. 
298
299 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. 
300
301 All Open CASCADE Technology resources are seen as parcels. 
302
303 @image html /dev_guides/wok/images/wok_image010.png "Parcels"
304 @image latex /dev_guides/wok/images/wok_image010.png "Parcels"
305    
306 You create a delivery unit under a specified workbench. 
307
308 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. 
309
310 **Note** If you do not specify a workbench when you make a delivery, it is created under the current workbench.
311  
312 @subsection occt_wok_2_2  Workbenches
313 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. 
314
315 @subsubsection occt_wok_2_2_1  Roots
316 The following roots are used in the structure of a workbench: 
317 * **Home** Workbench root containing various administration files of the workbench. 
318 * **Src** Root of the workbench sources, which facilitates the integration into WOK of version management software such as CVS. 
319 * **DBMS** Root of the derived files dependent on the extraction profile (.hxx, _0.cxx files, etc.). 
320 * **DBMS_Station** Roots of the derived files dependent on the extraction profile and on the platform (.o, .so files, etc.). 
321
322 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: 
323 * **Home** Workbench root, 
324 * **Src** Root of the source files, 
325 * **DFLT** Root of the derived files, 
326 * **DFLT_sun** Root of the files built on Sun platforms, 
327 * **DFLT_sil** Root of the files built on SGI platforms, 
328
329 For a workbench additionally supporting *ObjectStore*, the following additional roots are also found: *OBJS, OBJS_sun, OBJS_sil*.
330  
331 These roots are defined in the workbench definition file *MyWorkbench.edl* as the parameter <i>\%MyWorkbench_RootName</i>. 
332
333 **Note** that default values help to define various roots.
334  
335 @subsubsection occt_wok_2_2_2  Directories
336 Under each root, a hierarchy of directories allows to store various files. 
337 * Under the Home root are found: 
338         *  *work*, the private workbench directory reserved for the developer 
339         *  *Adm*, the directory reserved for administration files. 
340 * Src contains: 
341         *  *src/MyUD*, the directory containing the source files of the development unit MyUD. 
342 * DBMS contains: 
343         *  *inc*, containing the public header files of the workbench UDs 
344         *  *drv/MyUD*, containing the private extracted files of MyUD 
345         *  *drv/MyUD/.adm*, containing the administration files dependent on the extraction profile 
346         *  *drv/MyUD/.tmp*, containing the temporary files dependent on the extraction profile. 
347 * DBMS_Station contains: 
348         * *<station>/lib* with all the libraries produced in the workbench
349         * *<station>/bin* with all the binaries produced in the workbench
350         * *<station>/MyUD* with all the station dependent files which are private to the development unit such as objects
351         * *<station>/MyUD/.adm* with all the station dependent administration files
352         * *<station>/MyUD/.tmp* with all the temporary files constructed in the development unit.
353
354   
355 @image html /dev_guides/wok/images/wok_image011.png "Structure of the workbench Mywb"
356 @image latex /dev_guides/wok/images/wok_image011.png "Structure of the workbench Mywb"
357
358 @subsection occt_wok_2_2_3  Workshops
359 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.
360  
361 @image html /dev_guides/wok/images/wok_image012.png "Visibility between Workbenches in a Workshop"
362 @image latex /dev_guides/wok/images/wok_image012.png "Visibility between Workbenches in a Workshop"
363
364 In this image:
365  * **A** is the development unit A from Grandchild 11  placed in reference in root. It is visible throughout the workshop. 
366  * **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.
367
368
369 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. 
370
371 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. 
372
373 When creating a new workshop, you specify - in the form of parcels – which resources are to be available within the workshop. 
374
375 @subsection occt_wok_2_2_4  Factories
376 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. 
377
378 There is no theoretical limit to the number of workshops that can be added to a factory. However, a single factory should be enough. 
379
380 @section occt_wok_3 Development Process
381 @subsection occt_wok_3_1  WOK Environment
382 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.
383
384
385 Before you run a tcl session you must make sure that your account is configured for using tcl, see the <a href="#occt_wok_8_3">Configuring Your Account for Tcl and WOK</a> section. 
386
387 To start a tcl session use the command: 
388 ~~~~~
389 % tclsh 
390 ~~~~~
391 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. 
392 To exit from a tcl session use the command: 
393 ~~~~~ 
394 > exit
395 ~~~~~ 
396 Online help is provided with tcl. To access this, use the following command: 
397 ~~~~~
398 % tclhelp  
399 ~~~~~
400 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: 
401 ~~~~~
402 > wokcd -h
403 ~~~~~
404
405 @subsection occt_wok_3_2  Steps
406 Implementation of an application is based on the following steps: 
407 1. Enter the software factory using the command wokcd MyFactory 
408 2. Enter a workshop using the command wokcd MyWorkshop 
409 3. Open a workbench using the command wokcd MyWorkbench 
410 4. Search for the data types required among the existing OCCT libraries 
411 5. Define one or more packages which will contain the classes 
412 6. Define new data types as classes 
413 7. Implement the methods of those classes in C++ 
414 8. Implement any package methods in C++ 
415 9. Unite the test packages 
416 10. Define any nocdlpacks (if any) 
417 11. Test the components 
418
419 **Note:** Steps 1-3 can be performed with a single WOK command: 
420 ~~~~~
421 > wokcd MyFactory:MyWorkshop:MyWorkbench
422 ~~~~~
423  
424 @subsection occt_wok_3_3  Getting Started
425 @subsubsection occt_wok_3_3_1  Entity Names
426 Before you start, the following restrictions on WOK entity names must be noted: 
427   *  Entity names may only contain alphanumeric characters and dashes. 
428   *  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. 
429   *  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. 
430   *  Parcel names must be unique. 
431   
432 @subsubsection occt_wok_3_3_2  Entering the Factory
433 When you start work you go to the factory using the following command: 
434 ~~~~~
435 > wokcd <MyFactory>
436 ~~~~~ 
437 @subsubsection occt_wok_3_3_3  Creating a New Workshop
438 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: 
439 ~~~~~
440 > screate –d <MyWorkshop> 
441 ~~~~~
442 This creates the new workshop **MyWorkshop** in the current factory. To create the same workshop in a different factory use the syntax below: 
443 ~~~~~
444 > screate –d <MyFactory:MyWorkshp>
445 ~~~~~
446
447 When you create a new workshop, it is empty. 
448
449 @subsubsection occt_wok_3_3_4  Selecting Parcels
450 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: 
451 ~~~~~
452 > screate –d <MyWorkshop> -DparcelConfig=Parcel1,Parcel2…
453 ~~~~~
454 To display available OCCT resources, in other words, to see what parcels are available, you use the following command: 
455 ~~~~~
456 Winfo –p <WarehouseName>
457 ~~~~~
458 **Note:** parcel configuration rarely needs to change. If it does, only the workshop administrator should make them. 
459 @subsubsection occt_wok_3_3_5  Opening a Workshop
460 To open a workshop, you use the following command: 
461 ~~~~~
462 > wokcd <MyWorkshop>
463 ~~~~~
464 @subsubsection occt_wok_3_3_6  Creating a New Workbench
465 When you create a new workshop, it is empty. In other words, it does not contain any workbenches. 
466 To create the root workbench of a new workshop, you use the following command: 
467 ~~~~~
468 > wcreate -d <MyWorkbench>
469 ~~~~~
470 This creates a tree of workbench subdirectories. 
471 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: 
472 ~~~~~
473 > wcreate –d <MyWorkbench> -f <ParentWorkbench>
474 ~~~~~
475 @subsubsection occt_wok_3_3_7  Opening a Workbench
476 To open a workbench, you use the command below: 
477 ~~~~~
478 > wokcd <MyWorkbench>
479 ~~~~~
480 This automatically takes you to the root directory of the workbench 
481
482 @subsubsection occt_wok_3_3_8  Using Existing Resources
483 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. 
484 @subsection occt_wok_3_4  Creating Software Components
485 @subsubsection occt_wok_3_4_1  Creating a Package
486 To develop new software components, you usually need to create one or more packages. You do this, by using the following command: 
487 ~~~~~
488 > ucreate –p <MyPackage> 
489 ~~~~~
490 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: 
491 ~~~~~
492  > ucreate <MyPackage> 
493 ~~~~~
494 #### Enter a Package or other Development Unit Structure
495
496 Enter the package or any other development unit structure using the *wokcd* command as in the syntax below: 
497 ~~~~~
498 > wokcd MyPackage 
499 ~~~~~
500 The current directory is now: 
501 ~~~~~
502 MyWorkbenchRoot/src/MyPackage 
503 ~~~~~
504
505 #### Writing the Package and Class Specifications in CDL 
506
507 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. 
508
509 #### CDL Compilation of the Package
510
511 Compile and check the package and its classes using: 
512 ~~~~~
513  > umake –e xcpp 
514 ~~~~~
515 This command also extracts the C++ header files (.hxx) and stores them in the derived files directory. 
516
517 #### Implementing Methods in C++ 
518
519 A package will contain methods, which may be: 
520   *  Instance methods 
521   *  Class methods 
522   *  Package methods. 
523 Extract **prototypes** for the C++ methods using the following command: 
524 ~~~~~ 
525  > umake -o xcpp.fill -o xcpp.template 
526 ~~~~~
527
528 You should not confuse this syntax with the template feature of C++ used to implement the genericity. 
529 The *umake -o xcpp.template* command creates a skeleton C++ file for: 
530   *  Each class 
531   *  All the package methods. 
532 The packages methods will be created in a file called *package.cxx.template*. This command is not included in the umbrella command *MyPackage*. 
533 You will need to use an editor to implement these methods in C++. 
534
535
536 #### Compiling the Package
537
538 To compile the package, use the command: 
539 ~~~~~
540         > umake -o obj <MyPackage>
541 ~~~~~   
542 If you do not specify a package, the current development unit is compiled. 
543
544 #### Sample Construction of a Package
545
546 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: 
547 1. Create the MyWb workbench as a child of Topo. 
548 ~~~~~
549         > wcreate MyWb -f Topo -d
550 ~~~~~
551 2. Create MyPack in MyWb. 
552 ~~~~~
553         > ucreate MyPack     
554 ~~~~~
555 3. Move to the source directory of MyPack. 
556 ~~~~~
557         > wokcd MyPack 
558 ~~~~~
559 4. Edit the source files (MyPack.cdl etc.). You do this outside tcl, using the editor of your choice. 
560 5. Start the extraction of MyPack. 
561 ~~~~~
562          >  umake -e xcpp 
563 ~~~~~
564 6. Generate the .cxx templates for MyPack: MyPack.cxx.template 
565 ~~~~~
566    > umake -o xcpp.fill -o xcpp.template -t 
567 ~~~~~
568 7. Edit the source files (MyPack.cxx etc). You do this outside tcl, using the editor of your choice. 
569
570 **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. 
571
572 #### Package Files
573
574 * Primary Files for a Package 
575         + <Package>.cdl                         Primary package file.
576         + <Package>_<Class>.cdl         Primary class file.
577 * C++ Files for a Package
578         + <Package>.cxx                         Primary package source file.
579         + <Package>_[1..9[0..9]*].cxx   Secondary package source files.
580         + <Package>.lxx                         Inline package methods source file.
581         + <Package>.pxx                         Private instructions source file.
582 * C++ Files for a Class
583         + <Package>_<Class>.cxx         Primary class source file.
584         + <Package>_<Class>_[1..9[0..9]*].cxx
585 * Secondary class source files.
586         + <Package>_<Class>.gxx         Generic class methods source file. This is an alternative to the .cxx file(s), you do not have both.
587         + <Package>_<Class>.lxx         Inline methods source file.
588         + <Package>_<Class>.pxx         Private instructions source file.
589 * Derived C++ Files for a Package
590         + <Package>.hxx                         User header file.
591         + <Package>.ixx                         User header file included in <Package>.cxx.
592         + <Package>.jxx                         User header file included in <Package>_[1-9].cxx.
593 * Derived C++ files for a class
594         + <Package>_<Class>.hxx         User header file.
595         + <Package>_<Class>.ixx         User header file included in <Package>_<Class>.cxx.
596         + <Package>_<Class>.jxx         User header file in <Package>_<Class>_[1..9[0..9]*].cxx.
597         + Handle_<Package>_<Class>.hxx Persistent or Transient class header file.
598         + <Package>_<Class>_0.cxx       For instantiated classes.
599
600 Umake Steps for a Package 
601 -------------------------
602 The umake steps for development units of package type are explained below. 
603 * *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. 
604 * *xcpp.fill*   Compiles the internal data structure to prepare for subsequent extractions. 
605 * *xcpp.src*            Lists the source files (.cxx, .gxx, .lxx) deduced from the CDL files. 
606 * *xcpp.header*         Extracts header files for the classes in the development unit. 
607 * *xcpp.template* Extracts a template for implementation of methods. (Hidden step.)
608 * *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. 
609 * *obj.cgen*            Processes the source files to generate code. 
610 * *obj.comp*   Compiles each file that can be compiled. 
611 * *obj.idep*         Generates dependency information for the unit. This comprises: 
612         + Includes performed by unit compilation (Unit.MakeState) 
613         + Implementation dependencies in terms of the unit suppliers (Unit.ImplDep) 
614 * *obj.lib*           Generates the shared library for the development unit. 
615
616 @subsubsection occt_wok_3_4_2  Creating a Nocdlpack
617 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: 
618 ~~~~~
619         > ucreate -n <MyNoCDLPack>
620         > wokcd <MyNoCDLPack> 
621 ~~~~~
622 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). 
623 Build the nocdlpack using the following command: 
624 ~~~~~
625         > umake [<MyNoCDLPack>]
626 ~~~~~
627 **Note** that a nocdlpack unit is not intended to perform tests. Use an executable unit instead.
628
629
630 #### Sample Construction of a Nocdlpack
631
632 In the following example a nocdlpack *MyNocdlpack*, is created. Commands preceded by an asterisk below are used only once per session: 
633 1. \*Create MyNocdlpack in MyWb. 
634 ~~~~~
635 > ucreate -n <MyNoCDLPack>
636 ~~~~~
637 2. Move to the source directory of MyNocdlpack. 
638 ~~~~~
639 > wokcd <MyNoCDLPack>
640 ~~~~~
641 3. Write the FILES list. You do this outside tcl, using the editor of your choice. 
642 4. Write the source code. 
643 5. Build MyNocdlpack. 
644 ~~~~~
645 > umake [<MyNoCDLPack>]
646 ~~~~~ 
647
648 #### Umake Steps for a Nocdlpack 
649
650 The *umake* steps for development units of *nocdlpack* type are explained below. 
651 * *src*                Processes FILES to list source files. 
652 * *obj.cgen*    Processes the source files to generate code. 
653 * *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. 
654 * *obj.comp*    Compiles each file that can be compiled. 
655 * *obj.idep*    Generates dependency information for the unit. This comprises: 
656         + Includes performed by unit compilation. (Unit.MakeState) 
657         + Implementation dependencies in terms of the unit suppliers. (Unit.ImplDep) 
658 * *obj.lib*     Generates the shared library for the unit. 
659
660 @subsubsection occt_wok_3_3_3  Creating a Schema
661 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. 
662
663 You create a schema and go to its root directory using the commands: 
664 ~~~~~
665 > ucreate -n <MySchema>
666 > wokcd <MySchema>
667 ~~~~~ 
668 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: 
669 ~~~~~
670         schema MySchema
671         is
672 class <MyClass> from <Package>;
673         end;
674 ~~~~~
675         
676 #### Building a Schema 
677
678 Compile and check the coherence of the CDL specification for the schema: 
679 ~~~~~
680 > umake -e xcpp.fill
681 ~~~~~
682 Extract the C++ description: 
683 ~~~~~
684 > umake -o xcpp
685 ~~~~~
686 Compile the C++ description of the schema: 
687 ~~~~~
688 > umake -o obj
689 ~~~~~
690 Alternatively, the above three steps can all be carried out by one command: 
691 ~~~~~
692 > umake
693 ~~~~~
694 #### Sample Construction of a Schema 
695
696 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: 
697 1. Create MySchema in MyWb. 
698 ~~~~~
699  > ucreate -s MySchema
700 ~~~~~
701 2. Move to the source directory of MySchema. 
702 ~~~~~
703 > wokcd MySchema
704 ~~~~~
705 3. Edit the source file MySchema.cdl. You do this outside tcl, using the editor of your choice. 
706 4. Derive implementation files. 
707 ~~~~~
708         > umake -e xcpp.sch
709 ~~~~~
710 5. Derive application schema files. 
711 ~~~~~
712         > umake -o xcpp.ossg
713 ~~~~~
714 6. Compile the schema. 
715 ~~~~~
716         > umake -o obj
717 ~~~~~
718
719 #### Schema Files
720
721 * Primary Files for a Schema
722         + *<Schema>.cdl* Primary schema file.
723 * Derived C++ Files for a Schema
724         + *<Schema>.hxx* User header files.
725         + *<Schema>.cxx* Schema implementation files.
726         + *<Sch_MyPack_MyClass>.cxx* Schema implementation files.
727
728 #### Umake Steps for a Schema 
729
730 The umake steps for development units of schema type are explained below. 
731 * *src*        Processes MySchema.cdl to generate a list of CDL files for the development unit. Processes the FILES file to list source files. 
732 * *xcpp.fill*  Compiles the internal data structure to prepare for subsequent extractions. 
733 * *xcpp.sch*   Extracts the schema implementation code. 
734 * *obj.comp*   Compiles the extracted files that can be compiled. 
735 * *obj.lib*    Generates the shared library for the unit. 
736 * *obj.idep*   Generates dependency information for the schema. 
737
738 @subsection occt_wok_3_5  Building an Executable
739 @subsubsection occt_wok_3_5_1  Creating an Executable
740 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. 
741
742 #### Writing an Executable
743
744 Refer to the **CDL User’s Guide** for full details. A simple example is given below. 
745
746 ~~~~~
747         executable <MyExec> // the executable unit
748 is
749         executable myexec // the binary file
750 uses
751 Tcl_Lib as external
752 is
753         myexec; // the C++ file
754 end;    // several binaries can be specified in one .cdl file.
755 executable myex2
756 is
757         myex2;
758 end;
759         end;
760 ~~~~~   
761         
762 Write the C++ file(s). For the example above you write two files: *myexec.cxx* and *myex2.cxx*.
763  
764 #### Building the Executable 
765
766 To build the executable, use the command *umake*
767
768 #### Construction of an Executable 
769
770 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: 
771 1. \*Create MyExec in MyWb. 
772 ~~~~~
773         > ucreate -x MyExec
774 ~~~~~
775 2. Move to the source directory of *MyExec*. 
776 ~~~~~
777         > wokcd MyExec
778 ~~~~~   
779 3. Edit the cdl source file *MyExec.cdl*. You do this outside tcl, using the editor of your choice. 
780 4. Edit the C++ files *AnExe.cxx*, etc. You do this outside tcl, using the editor of your choice. 
781 5. Build MyExec. 
782 ~~~~~
783         > umake
784 ~~~~~   
785 6. Run the executable file. 
786 ~~~~~
787         > wokcd -PLib
788                 > MyExec
789 ~~~~~
790
791 #### Executable Files 
792
793 | <Exec>.cdl |  primary executable file |
794 | <AnExe>.cxx |         Source C++ file |
795 | <AnExe>_[1-9].cxx |   Other source C++ files |
796
797 #### Umake Steps for an Executable
798
799 The umake steps for development units of executable type are explained below. 
800 * *src* Processes MyExe.cdl to generate a list of CDL files for the development unit. Processes FILES to list source files. 
801 * *src.list* Based on MyExe.cdl, works out the list of parts and the source files involved for each part. 
802 * *exec.comp* Compiles the files that can be compiled for each part of the executable. 
803 * *exec.idep* Generates dependency information for each part of the executable. 
804 * *exec.libs* Computes full implementation dependency to prepare for linking for each part of the executable. 
805 * *exec.tks* Performs toolkit substitution according to TOOLKITS for each part of the executable. 
806 * *exec.link* Links each part of the executable. 
807
808 @subsection occt_wok_3_6  Test Environments
809 @subsubsection occt_wok_3_3_1  Testing an Executable
810 To test an executable, you create an executable development unit and move to its structure.
811
812 When you write the .cdl file for your test executable, specify the packages to test, for example: 
813 ~~~~~
814 executable MyTest // the executable unit 
815         is 
816 executable mytest1 // the binary file 
817 is 
818         mytest1; //the C++ file 
819 end; // several binaries can be specified in one .cdl file. 
820 executable mytest2 
821 is 
822         mytest2; 
823 end; 
824         end; 
825 ~~~~~
826 Write the C++ test file(s), in the example, *mytest1.cxx* and *mytest2.cxx*. 
827 #### Building the Executable 
828
829 To build the executable use the command: 
830 ~~~~~
831 > umake
832 ~~~~~
833
834 #### Setting up a Test Environment
835
836 To set up a test environment, move to the <i>/drv</i> subdirectory that corresponds to the current profile (e.g. <i>/MyExec/drv/DFLT/sun</i>) and run the executable test file.  
837 ~~~~~
838 > wokcd -PLib
839 > wokenv -s
840 > myApp
841 ~~~~~
842 The command *wokenv* is used with -s option to configure the test environment.  
843 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.  
844 WOK sets the following environment variables: 
845
846 * <i>$STATION</i>  - The current station. 
847 * <i>$TARGET_DBMS</i> - The current database platform. 
848 * <i>$PATH</i> - The current path, plus the bin directories of the parcels. 
849 * <i>$LD_LIBRARY_PATH</i> The current path, plus the lib directories of the parcels. 
850 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*.  
851 * <i>$ORIGDELIVUNITHOME</i> is set as the root directory of the parcel. 
852 WOK then sources the following files: 
853   *  MyFactory.tcl, found in the admin directory of the factory. 
854   *  MyWorkshop.tcl found in the admin directory of the workshop. 
855 Then for each Workbench, WOK sources according to the hierarchy of the workbenches: 
856   *  Workbench.tcl, found in the /Adm directory of the workbench.  
857   
858 After the environment is set up, you are at a C shell prompt and can run the executable. 
859
860 **Note** Environment variables are only set when the command is used with the option <i>-s</i>. 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.  
861 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. 
862
863 To create the script file use the following command: 
864 ~~~~~
865  > wokenv -f <ScriptFile> -t csh
866 ~~~~~ 
867 This command generates a file, ScriptFile, which configures a C shell to mirror the current WOK environment. An example script file is given below. 
868 ~~~~~
869 setenv STATION *sil* 
870 setenv TARGET_DBMS *DFLT* 
871 setenv KERNELHOME */adv_22/WOK/BAG/KERNEL-K1-2-WOK* 
872 setenv LD_LIBRARY_PATH */adv_22/WOK/BAG/wok-K1-2/lib/sil:/adv_22/WOK/BAG/KERNEL-K1-2-WOK/sil/lib/* 
873 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/* 
874 source /adv_22/WOK/BAG/KERNEL-K1-2-WOK/adm/Kernel.csh 
875 ~~~~~
876
877 @subsection occt_wok_3_7  Building a Toolkit
878 @subsubsection occt_wok_3_7_1  Creating a Toolkit
879
880 You create and enter a toolkit development unit using the following commands: 
881 ~~~~~
882         > ucreate -t <TKMyToolkit>
883         > wokcd <TKMyToolkit>
884 ~~~~~
885
886 #### Write the Nomenclature File for the Toolkit 
887
888 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. 
889 Build the shareable library for this toolkit as follows: 
890 ~~~~~
891 \> umake [<TKMyToolkit>]
892 ~~~~~
893 **Note:** when one of the packages in the toolkit is modified, recompile the toolkit. A package should belong to one toolkit only.
894
895 #### Sample Construction of a Toolkit 
896
897 In the following example, the toolkit **TKMyToolkit** is created. Commands preceded by an asterisk are used only once per session: 
898 1. \*Create MyToolkit in MyWb. 
899 ~~~~~
900 \> ucreate -t TKMyToolkit
901 ~~~~~
902 2. Move to the source directory of MyToolkit. 
903 ~~~~~
904 \> wokcd TKMyToolkit
905 ~~~~~
906 3. Edit the nomenclature files, PACKAGES and FILES. You do this outside tcl, using the editor of your choice. 
907 4. \*Create the library for MyToolkit 
908 ~~~~~
909 \> umake TKMyToolkit
910 ~~~~~
911
912 #### Umake Steps for a Toolkit 
913
914 The umake steps for development units of toolkit type are explained below. 
915 * *src*  Processes FILES to list source files. 
916 * *lib.list* Works out the objects and archive library to add to the toolkit shared library. 
917 * *lib.limit* Manages the build process strategy within the limitations of a particular platform. 
918 * *lib.arch* Builds archives according to the building strategy. 
919 * *lib.uncomp* Decompresses third party archives. 
920 * *lib.arx* Extracts object files from archives. 
921 * *lib.build* Generates the shared library for the toolkit.  
922
923 Building strategy depends on the platform. The following step sequences apply: 
924   *  On Sun (Solaris): 
925 ~~~~~
926 src 
927 lib.list 
928 lib.arx 
929 lib.build 
930 ~~~~~  
931   *  On sil (IRIX): 
932 ~~~~~
933 src 
934 lib.list 
935 lib.uncomp 
936 lib.build 
937 ~~~~~
938
939 #### The TOOLKITS File
940  
941 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: 
942 * 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*. 
943 * If an empty TOOLKITS file has been found, there is no toolkit candidate for substitution. 
944 * If a non-empty TOOLKITS file has been found, only the toolkits listed in this file are candidates for substitution. 
945
946 #### Toolkit Substitution
947
948 Toolkit substitution is performed as follows: 
949 1. MyEngine uses A, B and C; 
950 2. The toolkit TK provides      A and D; D uses E; 
951 3. Compilation of *MyEngine* includes TK, B C and E.
952  
953 Here, for simplicity, assume that additional toolkits are not substituted for B, C and E. 
954
955 @subsection occt_wok_3_8  Building a Delivery Unit
956 @subsubsection occt_wok_3_8_1  Creating a Delivery Unit
957 ~~~~~
958 \> ucreate -d <MyDeliveryUnit>
959 ~~~~~
960
961 #### Writing the COMPONENTS File
962
963 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. 
964 Note that keywords and default options are shown in bold. 
965
966 | **Name** | ParcelName |
967 | Put path | |
968 | Put include ||
969 |Put lib ||
970 | **Requires** | DeliveryName\* |
971 | **Package** | MyPack **[CDL][LIBRARY][INCLUDES][SOURCES]** |
972 | **Nocdlpack** | MyNcdl **[LIBRARY][INCLUDES][SOURCES]** |
973 | **Executable** | MyExec **[CDL][DYNAMIC][SOURCES]** |
974 | **Interface** | MyIntf **[CDL][STUB_SERVER][SOURCES]** |
975 | **Client** | MyClient **[CDL]**[STUB_CLIENT][SOURCES] |
976 | **Engine** | MyEng **[CDL][DYNAMIC][SOURCES]** | 
977 | **Schema** | MyShma **[CDL][LIBRARY][SOURCES][DOC]** |
978 | **Toolkit** |MyTk **[LIBRARY][SOURCES]** |
979 | **Get** | DevelopmentUnitName::Type:::File |
980
981 \* Without mention of the version 
982
983 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: 
984 * **Name** The full name of the current delivery, including a version number. This is the name of the parcel. 
985 * **Put path** Requires that the delivery be inserted in the user path (bin directory). 
986 * **\[CDL\]** Copy the cdl files to the delivery. 
987 * **\[LIBRARY\]** Generate the static library. Copy the shareable library to the delivery. Copy the list of objects of the library. 
988 * **\[INCLUDES\]** Generate includes.origin. Copy the includes to the delivery. Copy the ddl to the delivery. 
989 * **\[DYNAMIC\]** Select to copy the static or dynamic executable file. 
990 * **\[SOURCES\]** Copy the source files. 
991
992 #### Build the Delivery
993
994 To build the delivery unit, use the command: 
995 ~~~~~
996 \> umake <MyDeliveryUnit>
997 ~~~~~
998 The result of building a delivery unit is a **parcel**, which can be installed in a warehouse and used by other workbenches. 
999
1000 #### Sample Delivery of a Parcel
1001
1002 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: 
1003 1. Move to the root workbench under which the parcel is to be made.
1004 ~~~~~
1005 > wokcd MyRootWb
1006 ~~~~~
1007 2. \*Create MyDelivery in MyRootwb.
1008 ~~~~~
1009 > ucreate -d MyDelivery
1010 ~~~~~
1011 3. Move to the source directory of MyDelivery.
1012 ~~~~~
1013 > wokcd MyDelivery
1014 ~~~~~
1015 4. Use an editor to list all the prerequisites and components of the delivery in the COMPONENTS files using the appropriate syntax.
1016 5. Build MyDelivery.
1017 ~~~~~
1018 > umake MyDelivery 
1019 ~~~~~
1020 The output of the umake process is a parcel
1021  
1022 #### Umake Steps for a Delivery Unit
1023
1024 The umake steps for development units of type delivery are explained below. 
1025 * *src*                                 Processes FILES to list source files. 
1026 * *base*                             Creates directories, defines the list of units, copies the parcels and the release notes. 
1027 * *get.list*                     Lists files to get (using Get, Resource). 
1028 * *get.copy*                    Copy the files listed by get.list. 
1029 * *cdl.list*                          Lists CDL files to copy. 
1030 * *cdl.copy*                   Copies the files listed by cdl.list. 
1031 * *source.list*                 Lists units from which sources are to be copied. 
1032 * *source.build*              Creates a file for sources (in the format: unit.type.Z). 
1033 * *inc.list*             Lists includes to copy. 
1034 * *inc.copy*                          Copies files listed by inc.list. 
1035 * *lib.shared*                  Works out the inputs for building or copying shareable libraries. 
1036 * *lib.shared.build*    Copies or builds (depending on the platform) the shareable libraries. 
1037 * *lib.server.list*            Lists interface files to copy. 
1038 * *exec.list*                 Lists inputs for executable delivery. 
1039 * *exec.build*                  Creates executable in the parcel. 
1040 * *files*                              Works out the list of files delivered in the parcel. 
1041
1042 @subsubsection occt_wok_3_8_2  Installing a Parcel
1043 You open the root workbench of the workshop where you want to install the parcel using the following command: 
1044 ~~~~~
1045 \> wokcd <MyWorkshop> 
1046 ~~~~~
1047 To install the parcel, use the following syntax: 
1048 ~~~~~
1049 \> pinstall <MyParcel>
1050 ~~~~~
1051
1052 @subsection occt_wok_3_9  Working with Resource
1053
1054 ### Building a Resource 
1055
1056 There is a single umake step for development units of resource type. 
1057 * *src*                 Processes FILES to list source files. 
1058
1059 @subsection occt_wok_3_10  Java wrapping
1060 @subsubsection occt_wok_3_10_1  Creating an interface
1061
1062 To create an interface development unit and move to its structure, use commands: 
1063 ~~~~~
1064 \> ucreate -i <MyInterface>
1065 \> wokcd <MyInterface>
1066 ~~~~~
1067
1068 ### Writing an Interface 
1069
1070 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: 
1071
1072 ~~~~~
1073 interface MyInterface 
1074 uses 
1075   ListOfPackages; 
1076 is 
1077   ListOfPackages; 
1078   ListOfClasses; 
1079   ListOfMethods; 
1080 end; 
1081 ~~~~~
1082
1083 ### Building an Interface
1084
1085 To make the services of the interface available for further wrapping, build the interface, using the command: 
1086 ~~~~~
1087 > umake [<MyInterface>] -o src
1088 ~~~~~
1089
1090 ### Sample Construction of an Interface
1091
1092 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. 
1093
1094 1. \*Create MyInterface in MyWb. 
1095 ~~~~~
1096 >ucreate -i MyInterface 
1097 ~~~~~
1098 2. Move to the source directory of MyInterface. 
1099 ~~~~~
1100 >wokcd MyInterface 
1101 ~~~~~
1102 3. Edit the source file MyInterface.cdl. You do this outside tcl, using an editor of your choice. 
1103 4. Build the interface. 
1104 ~~~~~
1105 > umake -o src 
1106 ~~~~~
1107
1108 ### Interface Files
1109
1110 _<Interface>.cdl_ is the primary interface file. 
1111
1112 ### Umake Steps for an Interface
1113
1114 The umake steps for development units of type interface are explained below. 
1115
1116 * *src* - processes *MyInt.cdl* to list the CDL files for the development unit. Processes the FILES file to list source files. 
1117
1118 **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. 
1119
1120 @subsubsection occt_wok_3_10_2  Creating a jni
1121 To create a development unit of type jni and move to its structure, use commands: 
1122 ~~~~~
1123 > ucreate -j <MyJni>
1124 > wokcd <MyJni>
1125 ~~~~~
1126
1127 ### Writing a Jni 
1128
1129 Use an editor to write a .cdl file that specifies the interface or interfaces required by the jni. This file has the following format: 
1130 ~~~~~
1131 client MyJni 
1132 is 
1133 {interface MyInterface;} 
1134 {interface YourInterface;} 
1135 end; 
1136 ~~~~~
1137
1138 ### Building a Jni
1139
1140 To wrap services exported by the interfaces to Java, build the jni, using the command: 
1141 ~~~~~
1142  > umake [MyJni] 
1143 ~~~~~
1144
1145 ### Sample Construction of a Jni
1146
1147 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. 
1148
1149 1. \*Create MyJni in MyWb. 
1150 ~~~~~
1151 > ucreate -j MyJni  
1152 ~~~~~
1153 2. Move to the source directory of *MyJni*. 
1154 ~~~~~
1155 > wokcd MyJni  
1156 ~~~~~
1157 3. Edit the source file *MyJni.cdl*. You do this outside tcl, using an editor of your choice. 
1158 4. Derive Java files (.java and .class files) and C++ files (.h and .cxx) used for wrapping. 
1159 ~~~~~
1160  > umake -e xcpp 
1161 ~~~~~
1162 5. Compile the sources. 
1163 ~~~~~ 
1164 > umake -o obj 
1165 ~~~~~
1166 6. Link the object files. 
1167 ~~~~~
1168 > umake -o exec
1169 ~~~~~
1170
1171 Primary jni file is *Jni.cdl*
1172
1173 Derived Java files for a Jni are:
1174 * <Package>_<Class>.java - Java source file of the class to be wrapped. 
1175 * <Package>_<Class>.class - Compiled java source file. 
1176
1177 Derived C++ files for a Jni are:
1178 * <Jni>_<Package>_<Class>_java.h        - Include file for the C++ implementation of JNI. 
1179 * <Jni>_<Package>_<Class>_java.cxx      - C++ implementation of JNI.
1180
1181 ### Umake Steps for a Jni
1182
1183 The umake steps for development units of type jni are explained below. 
1184 * *src*           Processes MyJni.cdl to list the CDL files for the development unit. Processes the FILES file to list source files. 
1185 * *xcpp.fill*     Compiles the internal data structure to prepare for subsequent extractions. 
1186 * *xcpp.client*         Extracts the services declared in included interface unit(s) into Java and creates .java and \*_java.cxx files. 
1187 * *xcpp.javac*  Compiles .java files into .class files. 
1188 * *xcpp.javah*  Creates .h header files. 
1189 * *obj.comp* Compiles generated C++ files. 
1190 * *obj.idep*          Generates dependency information for the unit. 
1191 * *exec.libs*   Computes full implementation dependency to prepare for linking. 
1192 * *exec.tks*          Performs toolkit substitution. 
1193 * *exec.link*         Generates the shared library for the development unit. 
1194
1195 @subsection occt_wok_3_11  More Advanced Use
1196 @subsubsection occt_wok_3_11_1  Default User Profile
1197 There is a default user profile. If you wish to change this profile the command *wokprofile* is available. 
1198
1199 An example profile is given below. 
1200 ~~~~~
1201         Info : Profile in : WOK:k1dev:ref 
1202         Info : Extractor : DFLT 
1203         Info : Compile Mode : Optimized 
1204         Info : Station Type : sil 
1205 ~~~~~
1206 @subsubsection occt_wok_3_11_2  Changing Parcel Configuration
1207 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: 
1208 ~~~~~
1209 <MyWorkshop>.edl.
1210 ~~~~~
1211
1212 Move to the admin directory of the factory: 
1213 ~~~~~
1214 \> wokcd <MyFactory> -PAdm
1215 ~~~~~
1216
1217 Then use the editor of your choice to edit the admin parameter file, MyWorkshop.edl. 
1218 In this file, the parcel configuration is defined by an entry of the form: 
1219 ~~~~~
1220 \@set %<MyWorkshop>_ParcelConfig = “Parcel1 Parcel2...Parceln”;
1221 ~~~~~
1222 The resources are listed within quotation marks. They are separated by spaces. 
1223 Edit this list as required. Save the file and close it. 
1224 To validate and take into account your changes use the command: 
1225 ~~~~~
1226 \> wokclose -a 
1227 ~~~~~
1228 This command closes and reopens all the entities. Without the -a option, *wokclose* only applies to the current entity. 
1229
1230 @section occt_wok_4_ Available Services
1231 @subsection occt_wok_4_1  Synopsis
1232 WOK provides sets of services, which can be grouped according to the entity they apply to: 
1233   *  General Services 
1234   *  Factories 
1235   *  Warehouses 
1236   *  Parcels 
1237   *  Workshops 
1238   *  Workbenches 
1239   *  Development Units 
1240   *  Source Management Services 
1241   *  Session Services 
1242 @subsubsection occt_wok_4_1_1  Common Command Syntax
1243
1244 #### Command Names 
1245
1246 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. 
1247 The following prefixes exist: 
1248   *  f: for factories 
1249   *  s: for workshops 
1250   *  w: for workbenches 
1251   *  u: for development units 
1252   *  W: for warehouses 
1253   *  p: for parcels 
1254   *  wok: for commands that apply to any type of entity 
1255 These prefixes are followed by a command that determines the action to be executed. Examples of such commands are: 
1256   *  create: create an entity 
1257   *  rm: delete an entity 
1258   *  info: request information 
1259 Consequently, the command ucreate creates a development unit. The command wrm removes a workbench. 
1260
1261 #### Command Options
1262
1263 All command options are expressed using a dash (-) followed by one or more key letters and, if applicable, an argument. For example: 
1264 ~~~~~
1265 > umake -f -o <argument> MyUnit
1266 ~~~~~
1267 The compact version of this syntax is also valid: 
1268 ~~~~~
1269  umake -fo argument MyUnit 
1270 ~~~~~
1271 This syntax conforms to the POSIX recommendations for UNIX commands. 
1272 For all commands, there is a –h option, which displays help on usage. 
1273
1274 #### Presentation of Commands
1275
1276 The general syntax of the commands is presented in this document as follows: 
1277 ~~~~~
1278 CommandName [option(s) [<argument(s)>] [<Entity>]]
1279 ~~~~~
1280 Consequently, there are four general cases for a command: 
1281 ~~~~~
1282 CommandName <Entity>
1283 CommandName <option(s)> [<argument(s)>] <Entity>
1284 CommandName <option(s)> [<argument(s)>]
1285 CommandName
1286 ~~~~~
1287 **Note** a few commands described in this chapter do not completely respect this syntax; for example, *create* and *rm*. 
1288
1289 As a rule, where an _<EntityPath>_ is given as an argument it specifies which entity the command applies to. Where no _<EntityPath>_ 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. 
1290
1291 @subsection occt_wok_4_2  General Services
1292 General services are commands that apply to any entity manipulated by WOK. They are used for: 
1293   *  Navigation 
1294   *  Managing parameters 
1295   *  Managing profiles. 
1296
1297 @subsubsection occt_wok_4_2_1  wokcd
1298 ~~~~~
1299 wokcd
1300 wokcd <EntityPath>
1301 wokcd -P <ParamSuffix> [<EntityPath>]
1302 ~~~~~
1303
1304 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. 
1305 Options: 
1306 * _<EntityPath>_        Moves to the home directory of the entity specified by <EntityPath>, i.e. moves to the location given by the parameter: %wokcd <EntityPath>_Home.
1307 * _-P <ParamSuffix> [<EntityPath>]_ Moves to the <ParamSuffix> directory of the entity specified by <EntityPath>. i.e. moves to the location given by the parameter: %<EntityPath>_<ParamSuffix>. If no entity path is specified, this command moves to the <ParamSuffix> directory of the current entity.
1308
1309 Possible values for <ParamSuffix> are: Home, Adm and Src.
1310 Use the following commands to change directories within a development unit: 
1311 * **wsrc** To access the source files. 
1312 * **winc** To access the include files. 
1313 * **wobj** To access objects. 
1314 * **wlib** To access shareable libraries. 
1315 * **wbin** To access executables. 
1316 * **wadm** To access the workbench administration files. 
1317
1318 #### Examples 
1319
1320 *wokcd* - Lists the current position. 
1321
1322 *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. 
1323
1324 *wokcd -P Adm* - Moves to the administration directory of the current entity. 
1325
1326
1327 @subsubsection occt_wok_4_2_2  wokclose
1328 ~~~~~
1329 wokclose [-a] 
1330 ~~~~~
1331 Closes and reopens entities, i.e. reloads them into memory thus taking any changes into account. 
1332 Option <i>-a</i> closes and reloads all entities. 
1333
1334 #### Examples
1335
1336 ~~~~~
1337 wokclose 
1338 ~~~~~
1339 Closes and reopens the current entity. 
1340 ~~~~~
1341 wokclose -a 
1342 ~~~~~
1343 Closes and reopens all the entities. 
1344 @subsubsection occt_wok_4_2_3  wokenv
1345 ~~~~~
1346 wokenv -f <ScriptFile> -t csh
1347 ~~~~~
1348 Creates the file <ScriptFile>. This file is a script, which configures a C shell to mirror the current WOK environment. See the <a href="#occt_wok_3_6">Test Environments</a> section for more details. 
1349 Options: 
1350 * -f <ScriptFile> - Specifies the name of the file to produce. 
1351 * -t csh - Produces a file for configuring a C shell. 
1352 * -s - Sets up environment variables for application launching. 
1353 Example
1354 ------- 
1355 ~~~~~
1356 > wokenv -f MyTestEnvScript -t csh
1357 ~~~~~
1358 Generates the shell script *MyTestEnvScript* to configure a C shell so that it mirrors the current WOK environment. 
1359 @subsubsection occt_wok_4_2_4  wokinfo
1360 ~~~~~
1361 wokinfo -<option> [<EntityPath>]
1362 wokinfo -<option> <argument> [<EntityPath>]
1363 ~~~~~
1364 Displays information about _<EntityPath>_. The information displayed is common to all the entities. If no _<EntityPath>_ is specified, information about the current entity is returned. 
1365 This command can be used to find the path of a file. 
1366 Options: 
1367 * -t - Returns the type of entity (factory, warehouse, parcel, workbench, development unit). 
1368 * -T - Lists the types of files known in the entity. 
1369 * -f - Gets factory from path. 
1370 * -N - Gets the nesting path, i.e. where the current entity is nested. 
1371 * -n - Gets entity name. 
1372 * -P - Gets parcel from path. 
1373 * -s - Gets workshop from path. 
1374 * -u - Gets development unit from path. 
1375 * -W - Gets warehouse from path. 
1376 * -w - Gets workbench from path. 
1377 * -x - Tests if entity exists. 
1378 * -d <type> - Gets type definition. 
1379 * -a <type> - Gets type arguments. 
1380 * -p <type>:<filename> - Gets the path for a file, which is of the type type that depends on %File. In other words, the path for a file of this type depends on the file name, <filename>. 
1381 * -p <type> - Gets the path for a file, which is of the type <type> that is not %File dependent, for example EXTERNLIB. 
1382
1383 #### Examples
1384
1385 ~~~~~
1386 wokinfo -p source:gp.cdl MODEL:GTI:gti:gp 
1387 ~~~~~
1388 Returns the path of the source file gp.cdl in the MODEL:GTI:gti:gp. 
1389 ~~~~~
1390 wokinfo -t MODEL:GTI:gti:gp 
1391 ~~~~~
1392 Returns the development unit. 
1393
1394 @subsubsection occt_wok_4_2_5  woklocate
1395 ~~~~~
1396 woklocate -<option> <argument> [<WorkbenchPath>]
1397 woklocate -P [<WorkbenchPath>]
1398 ~~~~~ 
1399 Using WorkbenchPath as the starting point, this command locates files associated with the development unit and specified by the argument argument. 
1400 Options are: 
1401 * -f <Unit:Type:File> - Locates a file and gives its ID. 
1402 * -p <Unit:Type:File> - Locates a file and gives its path. 
1403 * -u <Unit> - Locates a development unit. 
1404 * -P - Displays all available WOK public types. 
1405
1406 #### Example
1407
1408 ~~~~~
1409 woklocate <MyFile> 
1410 ~~~~~
1411 Displays the location of the file, MyFile. 
1412
1413 @subsubsection occt_wok_4_2_6  wokparam
1414 ~~~~~
1415 wokparam -<option> [<EntityPath>]
1416 wokparam -<option> <argument> [<EntityPath>]
1417 ~~~~~
1418 Queries system parameters such as variables and templates. For more information about parameters refer to the appendix *Parameters and EDL Files* at the end of this User’s Guide. If an <EntityPath> is specified this indicates the entity to which the command applies. 
1419 Options: 
1420 * -L - Lists the directories used to search for the parameter files. 
1421 * -C - Displays the subclasses list. 
1422 * -a <TemplateName> - Gets arguments for the template TemplateName. 
1423 * -e <ParamName> - Evaluates the parameter ParamName. 
1424 * -F <ClassName> - Displays the files comprising the definition of the class *ClassName*. 
1425 * -l <Class> - Lists parameters concerning class (prefix) class. 
1426 * -S <FileName> - Finds the first file FileName in the list of directories cited afterwards. 
1427 * -t <Name> - Tests if the variable Name is set. 
1428 * -v <ParamName> - Displays the value of the parameter *ParamName*. 
1429 * -s <Name>=\<Value> Reserved for advanced use. Sets the variable *Name* to value *Value*. 
1430 * -u <Name> Reserved for advanced use. Unsets the variable Name. 
1431
1432 #### Examples 
1433
1434 ~~~~~
1435 wokparam -L MODEL:GTI:gti 
1436 ~~~~~
1437 Returns a list of directories used for parameters by the gti workbench. 
1438 ~~~~~
1439 wokparam -S CSF.edl 
1440 ~~~~~
1441 Locates the nearest CSF.edl file used by the current entity. 
1442 ~~~~~
1443 wokparam MODEL:GTI:gti:gp -e %WOKUMake_Steps 
1444 ~~~~~
1445 Displays the value of the _\%WOKUMake_Steps_ parameter in the *gp* package. The _\%WOKUMake_Steps_ parameter contains a description of the steps used by umake. 
1446 @subsubsection occt_wok_4_2_7  wokprofile
1447 ~~~~~
1448 wokprofile
1449 wokprofile -<option> [<argument>]
1450 ~~~~~
1451 Modifies session parameters. This command changes the mode of the current compilation and the profile of the current database. It also displays the current value of the session parameters. If no argument is specified, it displays the values of different parameters in the current session as well as the current position *wokprofile -v*. 
1452 Options: 
1453 * -b - Returns the current database profile (OBJS, DFLT). 
1454 * -d -  Switches to compilation with debug. 
1455 * -m - Returns the current compilation mode. 
1456 * -o - Switches to optimized compilation. 
1457 * -s - Returns the current station type 
1458 * -v - Switches to wokprofile verbose mode. In this mode all the parameters of the session are displayed. Running this command displays the current/changed profile. 
1459
1460 #### Examples 
1461
1462 ~~~~~
1463 wokprofile 
1464 ~~~~~
1465 Displays all the session parameters. 
1466 ~~~~~
1467 wokprofile -b 
1468 ~~~~~
1469 Displays the current database profile. 
1470 ~~~~~
1471 wokprofile -v -o 
1472 ~~~~~
1473 Switches to optimized compilation and displays the parameters of the current session after the change has been made. 
1474 ~~~~~
1475 wokprofile -o -v 
1476 ~~~~~
1477 Switches to optimized compilation and displays the parameters of the current session after the change has been made. Note that the order in which these options are specified does not affect the result. 
1478
1479 @subsection occt_wok_4_3  Services Associated with Factories
1480 There is a dedicated list of commands for the management of factories. The commands to create and destroy factories are reserved for the exclusive use of the site administrator. 
1481 * *fcreate* Creates a factory. 
1482 * *finfo* Displays information about the factory. 
1483 * *frm* Deletes a factory if it is empty. 
1484
1485 @subsubsection occt_wok_4_3_1  fcreate
1486 *Reserved for administrator’s use* 
1487 ~~~~~
1488 fcreate -<option> [-D <Suffix>=<Value>]* <EntityPath>
1489 ~~~~~
1490 Creates a factory. The name of the factory to create is specified by EntityPath. You can also specify the entity that will contain the entity to be created. 
1491
1492 Once the creation is completed, a file containing the parameters of the creation of the factory is created in the administration directory of the container to which the factory belongs. 
1493
1494 Parameters: 
1495 The following parameters are mandatory when a factory is created: 
1496 * **Adm** - Path name for administration directory 
1497 * **Home** - Path name for home directory 
1498 * **Stations** - List of supported stations 
1499 * **DBMSystems** - List of supported dbms 
1500 * **Warehouse** - Name of factory warehouse. 
1501
1502 Options: 
1503 * -P - Propose defaults. Returns a list of default values for the parameters necessary for the creation of the factory. No entity is created if this option is used. 
1504 * -d Use default. Uses default values to create the factory. 
1505 * -D<Suffix>=\<Value> - Defines parameter(s). Specifies the value to use for the given parameter(s) explicitly. This option can be used in conjunction with the –d option to take default values for all the mandatory parameters except the parameter(s) explicitly specified here. 
1506
1507 #### Examples 
1508
1509 ~~~~~
1510 fcreate -P NewFactoryName 
1511 ~~~~~
1512 Returns a list of default values for the parameters that are mandatory when creating a factory. 
1513 ~~~~~
1514 fcreate MyFactory -d -DHome=/fred/myfactory 
1515 ~~~~~
1516 Creates the factory MyFactory using default values for all mandatory parameters, except for Home, which is set to: /fred/myfactory 
1517
1518 @subsubsection occt_wok_4_3_2  finfo
1519 ~~~~~
1520 finfo -<option> [<EntityPath>]
1521 ~~~~~
1522 Displays details about the factory. If an EntityPath is specified this determines the factory to apply to. If no entity path is given, the command applies to the nearest factory. 
1523 Options: 
1524 * -s - Displays a list of workshops in the factory. 
1525 * -W - Displays the name of the warehouse in the factory. 
1526 * -S - Displays the name of the source repository. 
1527
1528 #### Examples
1529
1530 ~~~~~
1531 finfo -s 
1532 ~~~~~
1533 Displays a list of workshops in the nearest factory. 
1534 ~~~~~
1535 finfo MyFactory -W 
1536 ~~~~~
1537 Displays the name of the warehouse in MyFactory. 
1538
1539 @subsubsection occt_wok_4_3_3  frm
1540 *Reserved for administrator’s use* 
1541 ~~~~~
1542 frm <EntityPath>
1543 ~~~~~
1544 Deletes the factory specified by EntityPath if it is empty. 
1545
1546 Note, that you must not be in the factory you intend to destroy. 
1547
1548 #### Example
1549
1550 ~~~~~
1551 frm MyFactory 
1552 ~~~~~
1553 Deletes the factory MyFactory provided that it is empty. 
1554
1555 @subsection occt_wok_4_4  Services Associated with Warehouses
1556 A warehouse contains the parcels that are available in a factory. There is a dedicated list of commands for management of warehouses. 
1557 The commands you use to create and destroy the warehouses are reserved for the exclusive use of the site administrator. 
1558 * *Wcreate*   - creates a warehouse. 
1559 * *Winfo* - displays information about the warehouse 
1560 * *Wrm* - deletes a warehouse if it is empty. 
1561 * *Wdeclare* - declares a parcel in the warehouse. 
1562
1563 @subsubsection occt_wok_4_4_1  Wcreate
1564 *Reserved for administrator’s use.* 
1565 ~~~~~
1566 Wcreate [-<option>] -D<Suffix>=<Value>* <WarehouseName>
1567 Wcreate -<option> [-D <Suffix>=<Value>]* <WarehouseName>
1568 ~~~~~
1569 Creates a warehouse. The name of the warehouse to create is given by *<WarehouseName>*. You can also specify the factory that will contain the warehouse. 
1570 Once the creation is completed, a file containing the parameters of warehouse creation is in its turn created in the administration directory of the factory to which the warehouse belongs. 
1571
1572 Parameters: 
1573 The following parameters are mandatory when a warehouse is created: 
1574 * **Adm** - Path name for administration directory. 
1575 * **Home** - Path name for home directory. 
1576 * **Stations** - List of supported stations. 
1577 * **DBMSystems** - List of supported dbms. 
1578
1579 Options: 
1580 * -P - (Propose defaults.) Returns a list of default values for the parameters necessary for the creation of a warehouse. No entity is created if this option is used. 
1581 * -d - (Use defaults.) Uses default values to create the warehouse. 
1582 * -D <Suffix>=\<Value> (Define parameter.) Explicitly specifies the value to use for this parameter. This option can be used in conjunction with the –d option to take default values for all the mandatory parameters except the parameter(s) explicitly specified here. 
1583
1584 #### Examples
1585
1586 ~~~~~
1587 Wcreate -P MyWarehouse 
1588 ~~~~~
1589 Returns a list of default values for the parameters that are mandatory when creating a warehouse. 
1590 ~~~~~
1591 Wcreate MyWarehouse -d 
1592 ~~~~~
1593 Creates the warehouse *MyWarehouse* using default values for all mandatory parameters. 
1594 @subsubsection occt_wok_4_4_2  Winfo
1595 ~~~~~
1596 Winfo -p [<EntityPath>]
1597 ~~~~~
1598 Displays details about the warehouse and its contents. If an EntityPath is specified, this determines the warehouse to apply to. 
1599 Option -p displays the parcels in the warehouse. 
1600
1601 #### Example
1602
1603 ~~~~~
1604 Winfo -p 
1605 ~~~~~
1606 Displays a list of parcels in the current warehouse. 
1607 @subsubsection occt_wok_4_4_3  Wrm
1608 *Reserved for Administrator’s Use.* 
1609 ~~~~~
1610 Wrm <EntityPath> 
1611 ~~~~~
1612 Deletes the warehouse specified by EntityPath if it is empty. You should not be in the warehouse you intend to destroy. 
1613 #### Example
1614
1615 ~~~~~
1616 Wrm MyWarehouse 
1617 ~~~~~
1618 Deletes the warehouse *MyWarehouse* provided that it is empty. 
1619 @subsubsection occt_wok_4_4_4  Wdeclare
1620 *Reserved for administrator’s use* 
1621 ~~~~~
1622 Wdeclare -p<Parcel> [-d] [-D<ParamName>=<Value>]* <House>
1623 ~~~~~
1624 Declares the *Parcel*. This command adds the parcel to the list of parcels available in the warehouse House. 
1625 Note that a factory has a default list of deliveries (which are represented by parcels) available to it. This list only needs to be modified when moving to a new version of the delivery. This is done using the *Wdeclare* command, and then by editing the .edl file of the appropriate workshop. 
1626
1627 The following parameters are mandatory when declaring parcels: 
1628 * **Adm** - Path name for administration directory of a parcel. 
1629 * **Home**  - Path name for home directory of a parcel. 
1630 * **Stations** - List of available stations. 
1631 * **DBMSystems**  - List of available dbms. 
1632 * **Delivery** - Delivery name. 
1633
1634 Options: 
1635 * -p <Parcel> Defines the name of the parcel to declare. This name must be given with the option. 
1636 * -d Creates a parcel using defaults. 
1637 * -P Proposes defaults. 
1638
1639 #### Example
1640
1641 ~~~~~
1642 Wdeclare -pMyParcel -d MyWarehouse 
1643 ~~~~~
1644 Adds the parcel MyParcel to the warehouse MyWarehouse. 
1645
1646 @subsection occt_wok_4_5  Services Associated with Parcels
1647 A parcel is a receptacle for development units. You use it to group together the units, which comprise a delivery unit. There is a dedicated list of commands for management of parcels. Only the site administrator should perform installation of parcels in a warehouse. 
1648 * *pinfo* - displays information about the contents of the parcel 
1649 * *pinstall* - installs the parcel in a Warehouse. 
1650
1651 @subsubsection occt_wok_4_5_1  pinfo
1652
1653 pinfo -<option> [<ParcelPath>] - displays details about the contents of the parcel. If *ParcelPath* is specified this determines the parcel to apply to. If no parcel path is specified the command applies to the nearest parcel. 
1654
1655 Options: 
1656 * -d - Displays the delivery contained in the parcel. 
1657 * -l - Displays the development units in the parcel. 
1658 * -a - Lists the development units in the parcel together with their types. 
1659
1660 #### Examples 
1661
1662 ~~~~~
1663 pinfo -l MyParcel 
1664 ~~~~~
1665 Displays a list of units in the parcel MyParcel. 
1666
1667 @subsubsection occt_wok_4_5_2  pinstall
1668 *Reserved for administrator’s use* 
1669 ~~~~~
1670 pinstall <ParcelName> 
1671 ~~~~~
1672 Installs the parcel <ParcelName> in the current warehouse. The process of installing a parcel sets up various paths and variables to ensure that the application can locate necessary resources and so on. 
1673 The administrator must perform *pinstall* for each platform used. 
1674
1675 #### Example
1676
1677 ~~~~~ 
1678 pinstall MyParcel 
1679 ~~~~~
1680 Installs the parcel *MyParcel* in the current warehouse. 
1681
1682 @subsection occt_wok_4_6  Services Associated with Workshops
1683 A workshop is a tree of workbenches using the same parcel configuration. There is a dedicated list of commands for management of workshops. The commands to create and destroy workshops are reserved for the exclusive use of the site administrator. 
1684 * *screate* - creates a workshop. 
1685 * *sinfo* - displays information about the workshop 
1686 * *srm* - deletes a workshop if it is empty. 
1687
1688 @subsubsection occt_wok_4_6_1  screate
1689 *Reserved for administrator’s use* 
1690 ~~~~~
1691 screate [-<option>] {-D<Suffix>=<Value>}* <WorkshopName>
1692 screate -<option> <WorkshopName>
1693 ~~~~~
1694 Creates a workshop, <WorkshopName>. You can also specify the factory that contains this workshop. 
1695 Once the creation is completed, a file containing the parameters for the creation of the workshop is generated in the administration directory of the factory to which it belongs. 
1696
1697 The following parameters are mandatory when creating a workshop: 
1698 * **Adm** - Path name for administration directory. 
1699 * **Home** - Path name for home directory. 
1700 * **Stations** - List of supported stations. 
1701 * **DBMSystems** - List of supported dbms. 
1702 * **ParcelConfig** - List of parcels used. 
1703 * **Workbenchlist** - Path name for the list of workbenches. 
1704
1705 Options: 
1706 * -P (Propose defaults.) Returns a list of default values for the parameters necessary for the creation of a workshop. No entity is created if this option is used. 
1707 * -d (Use defaults.) Uses default values to create the workshop. 
1708 * -D <Suffix>=\<Value> (Define parameter.) Specifies the value to use for this parameter explicitly. This option can be used in conjunction with the –d option to accept default values for all the mandatory parameters except the parameter(s) explicitly specified here. 
1709
1710
1711 #### Examples
1712
1713 ~~~~~
1714 screate -P <WorkshopName>
1715 ~~~~~
1716 Returns a list of default values for the parameters that are mandatory for creating a workshop. 
1717 ~~~~~
1718 screate MyFactory:MyWorkshop -d 
1719 ~~~~~
1720 Creates the workshop *MyWorkshop* in the factory *MyFactory*, using default values for all mandatory parameters. 
1721 ~~~~~
1722 screate -DParcelConfig=Parcel1,Parcel2 MyFactory:MyWorkshop -d 
1723 ~~~~~
1724 Creates the workshop *MyWorkshop* in the factory *MyFactory*, using default values for all mandatory parameters except for *ParcelConfig*, which is set to *Parcel1 Parcel2*. 
1725
1726 @subsubsection occt_wok_4_6_2  sinfo
1727 ~~~~~
1728 sinfo -<option> [WorkshopName] 
1729 ~~~~~
1730 Displays details about the workshop. If *WorkshopName* is specified this determines the workshop this command is applied to. If no workshop is specified the command applies to the nearest workshop. 
1731 Options: 
1732 * -w - Displays a list of workbenches in the workshop. 
1733 * -p - Displays the parcel configuration of the workshop. 
1734
1735 #### Example 
1736
1737 ~~~~~
1738 sinfo -w 
1739 ~~~~~
1740 Displays a list of workbenches in the nearest workshop. 
1741
1742 @subsubsection occt_wok_4_6_3  srm
1743 *Reserved for administrator’s use* 
1744 ~~~~~
1745 srm WorkshopName 
1746 ~~~~~
1747 Deletes the workshop <WorkshopName> if it is empty. You must not be in the workshop you intend to destroy.
1748
1749 #### Example
1750
1751 ~~~~~
1752 srm MyWorkshop 
1753 ~~~~~
1754 Deletes the *MyWorkshop* provided that it is empty. 
1755
1756 @subsection occt_wok_4_7  Services Associated with Workbenches
1757 A workbench is the place where a developer (or a team of developers) works on a particular product. There is a dedicated list of commands for management of workbenches. 
1758
1759 * *wcreate* - creates a workbench. 
1760 * *w_info* - displays information about a workbench. 
1761 * *wrm* - deletes a workbench if it is empty. 
1762 * *wmove* - moves a workbench to a new location. 
1763
1764 @subsubsection occt_wok_4_7_1 wcreate
1765 ~~~~~
1766 wcreate -f <ParentWB> [-D <Suffix>=<Value>]* <WBName>
1767 wcreate -f <ParentWB> -P|d [-D <Suffix>=<Value>]* <WBName>
1768 wcreate -f <ParentWB> -P|d <WBName>
1769 ~~~~~
1770 Creates the workbench <WBName> as a child of the workbench <ParentWB>. The result of this creation is a directory structure. 
1771 Compared to the creation of other entities, creating a workbench requires an additional piece of information: you must specify the parent of the workbench to create. 
1772 Once the creation is completed, a file containing the parameters of the creation of this workbench is created in the administration directory of the workshop that contains it. 
1773 Parameters: 
1774 The following parameters are mandatory when creating a workbench: 
1775 * **Adm**               Path name for administration directory. 
1776 * **Home**              Path name for home directory. 
1777 * **Stations**  List of supported stations. 
1778 * **DBMSystems**        List of supported dbms. 
1779
1780 Options: 
1781 * -f - Specifies the parent workbench. 
1782 * -P - (Propose defaults.) Returns a list of default values for the parameters necessary for the creation of the workbench. No entity is created if this option is used. 
1783 * -d - (Use defaults.) Uses default values to create the workbench. 
1784 * -D <Suffix>=\<Value> - (Define parameter.) Specifies the value to use for this parameter explicitly. This option can be used in conjunction with the –d option to take default values for all the mandatory parameters except the parameter(s) explicitly specified here. 
1785
1786 #### Example
1787
1788 ~~~~~
1789 wcreate -P WorkBenchName 
1790 ~~~~~
1791 Returns a list of default values for the mandatory parameters to create a workbench. 
1792 ~~~~~
1793 wcreate MyWorkbench -d 
1794 ~~~~~
1795 Creates the workbench MyWorkbench using default values for all mandatory parameters. 
1796 **Note** The –f option of this command is not obligatory. The system administrator can create the root workbench of a workshop without specifying a parent workbench.
1797  
1798 @subsubsection occt_wok_4_7_2  w_info
1799 ~~~~~
1800 w_info -option[Workbench] 
1801 w_info -option argument[Workbench] 
1802 ~~~~~
1803 The *w_info* command is the exception to the common command syntax. The form w_info is used instead of winfo because the latter already exists as a tcl/tk command and cannot be reused as a name by WOK. If <Workbench> is specified, this determines the workbench to apply to. If no <Workbench> is specified, the nearest workbench is used. 
1804
1805 Using the tcl winfo command by mistake generates an error message, but does not cause any damage. 
1806
1807 Options: 
1808 * -l - Lists the development units in the workbench. 
1809 * -a - Lists the development units in the workbench along with their respective types. 
1810 * -f - Displays the parent workbench. 
1811 * -A - Lists all the ancestors of the workbench. 
1812 * -k - Lists visible toolkits. 
1813 * -S <arg> - Lists suppliers of the unit <arg> within the visibility of the workbench. 
1814 * -S <execname:partname> - Lists the suppliers of the component executable partname within an executable development unit execname. 
1815 * -I <arg1, arg2 ... argN> - Lists the development units, sorted by order of implementation dependency. 
1816
1817 #### Example
1818
1819 ~~~~~
1820 w_info -S MyDevUnit 
1821 ~~~~~
1822
1823 Returns a list of suppliers of the development unit MyDevUnit within the visibility of the current workbench. 
1824
1825 @subsubsection occt_wok_4_7_3  wrm
1826 ~~~~~
1827 wrm Workbench 
1828 ~~~~~
1829 Deletes the workbench, provided that it is empty and has no children. You must not be in a workbench you intend to destroy. 
1830
1831 #### Example
1832 ~~~~~
1833 wrm MyWorkbench 
1834 ~~~~~
1835 Deletes *MyWorkbench*, provided that it is empty and has no children. 
1836
1837 @subsubsection occt_wok_4_7_4  wmove
1838 *Reserved for advanced use* 
1839 wmove -f <NewParentWorkbench> <Workbench>
1840 Moves the <Workbench> (and its children), to a different parent *NewParentWorkbench* within the same workshop. 
1841 Option  -f <argument> specifies the new parent workbench. 
1842
1843 #### Example
1844
1845 ~~~~~
1846 wmove -f MyOtherWorkbench MyWorkbench 
1847 ~~~~~
1848 Moves the *MyWorkbench* under *MyOtherWorkbench*. 
1849
1850 @subsubsection occt_wok_4_7_5  wprocess
1851 ~~~~~
1852 wprocess <WorkbenchName> <options>
1853 ~~~~~
1854 Allows automatic reconstruction of a workbench. 
1855
1856 Options: 
1857 * -DGroups =Obj,Lib,Exec                - Selects groups Obj, Lib and Exec. 
1858 * -DUnits = MyUd1,MyUd2,...     - Selects the development units MyUd1, MyUd2 etc. 
1859 * -DXGroups =Src,Deliv                  - Excludes groups Obj and Deliv. 
1860 * -DXUnits=MyUd1,MyUd2,...              - Excludes units MyUd1, MyUd2 etc. 
1861 * -B <Profile>                                  - Selects the extraction profile. 
1862 * -f                                                    - Forces all selected steps. 
1863 * -d | -o                                               - Switches between debug and optimized modes. 
1864 * -P                                                    - Prints out the selected steps. 
1865 * -S                                                    - Silent mode (no print of the banner). 
1866 * -L                                                    - Logs output to MyUD_<step code>. Log in step administration directory. Valid group names are: Src, Xcpp, Obj, Dep, Lib, Exec, Deliv. 
1867
1868 #### Example
1869
1870 ~~~~~
1871 wprocess -DGroups=Src,Xcpp,Obj,Lib,Exec 
1872 ~~~~~
1873 Compiles the whole workbench 
1874
1875 @subsection occt_wok_4_8  Services Associated with Development Units
1876 The development unit is the basic building block of development work in the WOK environment. It is the base component of Open CASCADE Technology architecture. For a list of available types of development units refer to the <a href="#occt_wok_2_1">Development Units</a> section. There is a dedicated list of commands for management of development units. 
1877
1878 * *ucreate* **Creates** a development unit. 
1879 * *uinfo* **Displays** information about the development unit. 
1880 * *urm* **Deletes** a development unit. 
1881 * *umake* **Builds** a development unit. 
1882
1883 @subsubsection occt_wok_4_8_1  ucreate
1884 ~~~~~
1885 ucreate [-<TypeCode>] <UnitName>
1886 ucreate -P 
1887 ~~~~~
1888 Creates a development unit named <UnitName> of type <TypeCode>. 
1889
1890 Once the creation is completed, a file containing the parameters of the creation of the development unit is generated in the administration directory of the workbench to which the development unit belongs. 
1891
1892 TypeCodes: 
1893 * -p - Creates a development unit of type package. This is the default option. Where no option is specified, a development unit of type package is created. 
1894 * -n - Creates a development unit of type nocdlpack. 
1895 * -s - Creates a development unit of type schema. 
1896 * -t - Creates a development unit of type toolkit. 
1897 * -d - Creates a development unit of type delivery. 
1898 * -x - Creates a development unit of type executable. 
1899 * -f - Creates a development unit of type frontal. 
1900 * -r - Creates a development unit of type resource. 
1901 * -P - Displays ucreate creation possibilities in format: <TypeCode> <TypeName>. 
1902
1903 #### Examples
1904
1905 ~~~~~
1906 ucreate -p MyWorkbench:MyPackage 
1907 ~~~~~
1908 Creates the development unit *MyPackage* in *MyWorkbench*. The unit is of package type. 
1909
1910 @subsubsection occt_wok_4_8_2  uinfo
1911
1912 ~~~~~
1913 uinfo -t|c [<UnitPath>]
1914 uinfo -f|F|p [-<FilterOption> [<Type>]]* [<UnitPath>]
1915 ~~~~~
1916
1917 Displays details about the development unit. Where no <UnitPath> is specified, details of the current unit are displayed. Filter options are available for use in conjunction with the options -f, -F, -p to filter the file list. Combinations of filter options can be used.
1918  
1919 Note that the uinfo command is based on the results of construction using umake. As a consequence, the list of files displayed by uinfo is only valid if the construction has completed normally. Similarly, the list of files derived from the CDL is only valid if the CDLs of the unit have been translated successfully. 
1920
1921 Options: 
1922 * -t - Displays the type of the development unit as a string. 
1923 * -c - Displays the typecode of the development unit, i.e. a single character, as used by *ucreate* to indicate package (p), schema (s) and so on. 
1924 * -f - Displays a list of file names associated with the unit. 
1925 * -F - Displays a list of file names associated with the unit, together with their respective types. Types of files include for example: *source*, *library*, *executable*, and *pubinclude*. To display a full list of file types, use the command *ucreate*. 
1926 * -p - Displays the full paths of the files associated with the unit. 
1927 Filter Options: 
1928 * -T - <Type> Displays files of type <Type> only. 
1929 * -i - Displays only *independent* files, i.e. files that are not specific to a DBMS, for example sources. 
1930 * -s - Displays only station dependent files. 
1931 * -b - Displays only DBMS dependent files. 
1932 * -B - Displays only files that are dependent on *both *DBMS and Station. 
1933 * -l - Displays only files that are local to the workbench. 
1934 * -m - Displays only missing files, i.e. files that are listed, but not found. 
1935 * -e - Displays only existing files, i.e. files that are listed and found. 
1936
1937 #### Examples
1938
1939 ~~~~~
1940 uinfo -Fp 
1941 ~~~~~
1942 Displays the types, paths and names of all files associated with the unit. 
1943 ~~~~~
1944 uinfo -f -Tpubinclude MyWorkbench:MyUnit 
1945 ~~~~~
1946 Lists the names of the header files associated with the unit MyUnit which is in MyWorkbench. 
1947
1948 @subsubsection occt_wok_4_8_3  urm
1949 ~~~~~
1950 urm <UnitPath> 
1951 ~~~~~
1952 Deletes the development unit <UnitPath> with its directory structure and its files, even if the unit is referenced by another one. 
1953
1954 #### Example
1955 ~~~~~ 
1956 urm MyWorkBench:MyPack 
1957 ~~~~~
1958 Deletes the development unit *MyPack* found in *MyWorkBench*. 
1959
1960 @subsubsection occt_wok_4_8_4  umake
1961 ~~~~~
1962 umake -S [<UnitPath>]
1963 umake [-f][<UnitPath>]
1964 umake [-f]-o<step> [-t<target>]* [-o<step> [-t<target>]*]*[<UnitPath>]
1965 umake [-f][-s <step>] [-e <step>][<UnitPath>]
1966 umake
1967 ~~~~~
1968 Builds a development unit. The build process includes compilations, links, and various other actions, which make the development unit usable. The build process is specific for each type of development unit, refer to chapter 3 for details. 
1969 The following properties apply: 
1970 1. There are steps identified by a keyword. 
1971 2. The steps involved and their content depends on the type of development unit being treated. 
1972 3. You can ask for single step execution using the -o option. 
1973 4. Unless explicitly requested using the –f option, the operations are carried out in those steps where necessary. 
1974 5. Only the processed development unit is modified. 
1975
1976 Used without any arguments the *umake* command carries out all of the steps appropriate for the development unit to be constructed. Using keywords and arguments you can perform the build process step by step. 
1977
1978 Options: 
1979 * -S                    - Displays the list of steps. 
1980 * -s <step>     - Starts the build process at the step specified. 
1981 * -e <step>     - Ends the build process at the step specified. 
1982 * -o <step>     - Only executes the step specified. 
1983 * -t <target>   - Specifies the target to build. 
1984 * -f                    - Forces the build process, skipping the verification of dependencies. 
1985
1986 #### Example
1987
1988 ~~~~~
1989 umake gp 
1990 ~~~~~
1991 Builds the gp package. 
1992
1993 @subsubsection occt_wok_4_8_5 Specifying Targets (-t) for umake
1994
1995 The umake command is also used to specify build targets and extract C++ method prototypes. src, xcpp and obj units can be targeted. The syntax is explained below. 
1996 For delivery units (for all options apart from *.list) the syntax is as follows: 
1997 ~~~~~
1998 -\*.\* -t MyDU 
1999 umake MyDeliv -olib.shared.build -tMyUD. 
2000 ~~~~~
2001
2002 #### src
2003
2004 This target computes a source file list as in the example below: 
2005 ~~~~~
2006 umake -o src MyUnit 
2007 ~~~~~
2008
2009 #### xcpp
2010
2011 Extracts C++ header files. For -xcpp.\* (with the exception of \*.fill), the syntax is as follows: 
2012 ~~~~~
2013 umake -o -xcpp.* -t MyPack_MyClass 
2014 ~~~~~
2015 You extract the method prototypes using the following command: 
2016 ~~~~~
2017 umake -o xcpp.template [-t<class>|-t<package>]
2018 ~~~~~
2019 This syntax of  *umake* command is only used with packages. It extracts the C++ prototypes of the methods of the classes contained in the package. 
2020 The generated files are placed in the src directory of the current package. These files always have a .template suffix. With each extraction of a class, these files will contain all the methods of the class. 
2021 Prototypes are extracted for: 
2022   *  Ordinary classes (non-instantiated) 
2023   *  Generic classes (including nested generic classes) 
2024   *  Package methods 
2025 Classes, which are instantiations of generic classes, are not extracted. Nor are other CDL types (exceptions, alias, etc.) which have no user implementation. 
2026 For each class, we extract the prototypes of: 
2027   *  Instance methods 
2028   *  Class methods 
2029   *  Constructors 
2030 The extracted files are the following: 
2031   *  for an ordinary class C 
2032           +  C.cxx.template for the non-inline class methods. 
2033           +  C.lxx.template for the inline class methods. 
2034   *  for a generic class G 
2035           *  G.gxx.template for the non-inline class methods. 
2036           *  G.lxx.template for the inline class methods. 
2037   *  for a package method P 
2038           *  P.cxx.template for the non-inline package methods. 
2039           *  P.lxx.template for the inline package methods. 
2040           
2041           
2042 #### obj
2043
2044 Specifying the target, *obj* compiles the object files for one or more files. The syntax for -obj.* is as follows: 
2045 ~~~~~
2046 umake -o -obj.* -t MyPack_MyClass.cxx 
2047 ~~~~~
2048 In a package, the following command executes all construction steps up to and including obj, doing for each of them only what is strictly necessary: 
2049 ~~~~~
2050 umake -s obj 
2051 ~~~~~
2052 The following command will recompile all the primary sources of a package which are out of date: 
2053 ~~~~~
2054 umake -o obj 
2055 ~~~~~
2056
2057 @subsubsection occt_wok_4_8_6  Customizing umake
2058 You can use three levels of umake customization for a development unit. 
2059   *  Compiler and link options, EXTERNLIB 
2060   *  Step definition 
2061   *  Tcl umake step implementation 
2062 These different levels of complexity correspond to the needs of regular users and more advanced users. 
2063
2064 #### Modification of Compiler and Link Options and EXTERNLIB
2065
2066 Customization at this level involves setting parameters of existing umake steps using an .edl file. This file is taken into account each time umake is performed. It contains a series of assignments or appended variables used when creating the development unit. These commands can be preceded by instructions dedicated to the preprocessor in order to adjust its behavior within the actual context. 
2067
2068 EXTERNLIB uses resources contained in Open CASCADE Technology prerequisites. To avoid referencing the path of these resources more than one time, the user may use the component EXTERNLIB to include these resources automatically via the link. The file contains the name of parameters, which are set independently. 
2069
2070 The umake command does not generate actual dependencies. To avoid any cumbersome dependencies, for example, if you do not want the shareable library file for a package but the package enumeration only, use the INTERNLIB component listed in FILES, to get only the given dependencies. 
2071
2072 In practice, the generated file, <myUD>.ImplDep, in the /drv/adm directory, is copied into INTERNLIB. INTERNLIB contains lines of enumerations, as below: 
2073 ~~~~~
2074 Dependence 1 
2075 Dependence 2 
2076 ... 
2077 ~~~~~
2078 The example below illustrates how you can modify your WOK compiler options. Refer to *Using EDL to Define WOK Parameters* for an example of how to set link options as well as for more details about available parameters and .edl files. 
2079 ~~~~~ 
2080 -- File Name: Kernel_CMPLRS.edl 
2081 -- Copyright: Matra Datavision 1996 
2082 #--------------------------------- 
2083 #// First, ensure that we only execute this file once 
2084 \@ifnotdefined ( %Kernel_CMPLRS_EDL ) then 
2085         \@set %Kernel_CMPLRS_EDL = **; 
2086 #// Then set C++ compilation options, based on workstation type: 
2087         \@if( %Station == *sil* ) then 
2088 \@set %ModeOpt =  * *; 
2089         \@endif; 
2090         \@if( %Station == *ao1* ) then 
2091 \@set %ModeOpt = *-g *; 
2092         \@endif; 
2093         \@if( %Station == *hp* ) then 
2094 \@string %CMPLRS_C_Options +=  * -Aa -D_HPUX_SOURCE +e*; 
2095         \@endif; 
2096 \@endif; 
2097 ~~~~~
2098
2099 #### Step Definition
2100
2101 The WOK umake command uses a dependency tree. This dependency tree is a graph that shows the umake steps, their inputs and their dependencies. You use it to perform the build, for example to ensure that only files, which have changed, and the files, which depend on these modified files, are recompiled. 
2102
2103 This dependency tree is defined in an .edl file. The steps are listed in an order. Each is assigned a name and has its inputs specified. The output of one or more steps is the input to another step. 
2104
2105 The following steps are standard for WOK umakes: src, src.list, exec.comp and exec.link. Any new step that you insert into the tree must be associated with a tcl program, which will be responsible for performing the step. You supply these tcl programs. For more details of tcl programming refer to the examples below and also to the <a href="#occt_wok_8">Tcl Overview</a> section. 
2106
2107 The following example defines a umake dependency tree and introduces two new steps: exec.kerobj and exec.core. Each of these steps is then associated with a tcl program. 
2108 ~~~~~
2109 -- File Name: DCube_WOKSteps.edl 
2110
2111 \@ifnotdefined (%DCube_WOKSteps_EDL) then 
2112         \@set %DCube_WOKSteps_EDL = **; 
2113         \@string %WOKSteps_ObjGroup += *obj.libs obj.arx obj.objs *; 
2114 ---\@set %WOKUmake_Steps =**src obj.inc(src) objc.cgen(src) obj.comp(src, obj.cgen) obj.libs(src) obj.arx(obj.libs) obj.objs(obj.arx) obj.lib(obj.comp, obj.objs) obj.idep(obj.comp,src)*; 
2115         \@set %WOKSteps_obj_libs = *DCube_Libs(src)*; 
2116         \@set %WOKSteps_obj_arx = *WOKStep_LibExtract(obj.libs)*; 
2117         \@set %WOKSteps_obj_objs = *DCube_Objs(obj.arx)*; 
2118 \@set %WOKSteps_obj_lib = *WOKStep_DynamicLibrary(obj.comp, obj.objs)*; 
2119         \@set %WOKSteps_toolkit_ListWith = *obj.comp obj.objs*; 
2120 \@endif; 
2121 ~~~~~
2122
2123 #### Tcl Step Implementation
2124
2125 Customization at the tcl step level requires an understanding of the build process and the WOK dependency tree. Modification at this level is generally used to add elements to the build which are not described in the CDL. For example one possible use is to include external libraries or files into the final shareable library. Refer to <a href="#occt_wok_8_3_4">Writing Tcl Steps for a WOK Build</a> for more details.
2126  
2127 @subsection occt_wok_4_9  Source Management Services
2128 You use the source management services to integrate source files between a root workbench and one of its children. The services are related to a particular workshop. 
2129
2130 * *wprepare* - displays a report of the files state in the current workbench (as compared with the files in the root workbench). 
2131 * *wstore* - queues a report for further integration and stores the related files. 
2132 * *wintegre* - performs check-in operations for requested files and updates the root workbench. 
2133 * *wnews* - allows management and use of data stored in the integration journal. 
2134 * *wget* - imports source files to the current workbench. 
2135
2136 @subsubsection occt_wok_4_9_1  wprepare
2137 ~~~~~
2138 wprepare –wb <father workbench> [-ud <ud1,ud2,...,udN>] -o [<filename>]
2139 wprepare –wb <father workbench> [-ref][-ud <ud1,ud2,...,udN>] -o [<filename>]
2140 ~~~~~
2141 Prepares a report for integration to a reference (root) Workbench. This command prints a comparison of the state of source files contained in the specified units, <ud1,ud2,...,udN,> of the current workbench. 
2142
2143 This workbench must be a direct descendant of the root workbench. If no unit names are specified, all the units in the workbench are processed. By default, the results of the comparison are printed to the standard output. The differences are computed in relation to the root workbench. 
2144
2145 For each file, the status is indicated as follows: 
2146 * \# The file has been modified. 
2147 * \= The file was found in the current workbench but was not modified. 
2148 * \- The file has been removed. In other words, the entry was deleted from FILES). 
2149 * \+ The file has been added. In other words, the entry has been added in FILES). 
2150
2151 Options: 
2152 * -ref - Creates a report that is used to initialize a base of source files. This report is used with the *wintegre -ref* command. 
2153 * -ud <ud1>, <ud2>, ..., <udN> - Specifies the list of development units to prepare for integration. Separate the unit names with a comma. If no unit names are specified, all the units in the workbench are processed. 
2154 * -o <fileName> - Writes the integration report to the specified file. By default, the report is displayed (i.e. written to standard output). 
2155 * -wb <The name of target workbench> - Specifies the name of target workbench. It should be one of father workbenches with attached integration queue. 
2156
2157 @subsubsection occt_wok_4_9_2  wstore
2158 ~~~~~
2159 wstore –ls –wb <MasterWb>
2160 wstore -cat <ID>
2161 wstore [-trig] -rm <ID> [-f] –wb <MasterWb>
2162 wstore –create –wb <MasterWb>
2163 wstore [<FileName>]
2164 ~~~~~
2165 This command manages the queue of pending reports. When a report is queued it is given a unique number also called a report-ID. 
2166
2167 Options: 
2168 * <FileName> - Adds a report from the file FileName to the report queue. 
2169 * -trig - Calls a tcl procedure after the report has been processed. This tcl procedure must be located in the admin directory of the workshop and the file must be named wstore_trigger.tcl. An example of a trigger can be found in the file <i>$env(WOK_LIBRARY)/wstore_trigger.example</i>. 
2170 * -ls - Lists pending reports, together with their owners and their IDs. This is a default option. If two files are found with the same name in the same development unit in two different reports the full path of each of these files is displayed. 
2171 * -cat <Report_ID> - Displays the contents of the report <i><Report_ID></i>. 
2172 * -rm - Removes a report from the report queue. 
2173 * -f - Forces deletion. This option must be used with the -rm option when you delete a report that you do not own. 
2174 * -param - Lists queue parameters associated with the workbench. 
2175 * -create –wb <MasterWb> -queue <any/dir> -type SCCS - Creates an integration queue associated with MasterWb workbench, queue should be located at any/dir and specify SCCS type of database. 
2176
2177 Possible options for –create are: 
2178 * -queue - Specify the name of directory under which queue is created 
2179 * -type - Specify the type of database (can be SCCS or RSC, SCCS by default) 
2180 * -base - Specify the location where to put the repository (only for SCCS database). Default behavior: creates repository in the adm directory of the master workbench. 
2181 * -counter - Specify the name of directory where the integration counter is located. Default behavior: creates subdirectory adm in directory created using –base option 
2182 * -journal - Specify the location of integration journal. Default behavior: : creates subdirectory adm in directory created using –base option 
2183 * -welcome - If increment contains new development units, by default store will refuse such increment. If you want to be able to add new units to MasterWb through integration mechanism use – welcome option. 
2184
2185 #### Example 
2186
2187 ~~~~~
2188 wstore ReportName –wb MasterWb 
2189 ~~~~~
2190 Queues the report ReportName and saves a copy of the files mentioned in the report. This copy will be used when the report is actually processed by the command *wintegre*.
2191 ~~~~~
2192 wstore –wb MasterWb -f -rm Report_ID 
2193 ~~~~~
2194 Removes the report Report_ID from the queue, even if you do not own it. 
2195
2196 @subsubsection occt_wok_4_9_3  wintegre
2197 ~~~~~
2198 wintegre [<reportID>] –wb <MasterWb> 
2199 ~~~~~
2200 Processes a report and removes it from the queue in the current workshop. 
2201
2202 Parameters: 
2203 * <reportID> - Number indicating the rank of the report in the integration queue. Use the command *wstore –l* to get this number. 
2204
2205 Options: 
2206 * -ref <BaseNumber> - Initializes the version of the elements in the repository. 
2207 * -all - Processes all the reports in the integration queue. 
2208 * -wb - Specify the integration queue of which workbench should be used 
2209 * -norefcopy - Updates the repository but not the target workbench. 
2210 * -nobase - Updates the target workbench but not the repository. This option is rather useful when copying a set of UDs from a workbench into another. 
2211 * -param - Shows the parameters’ current value. 
2212
2213 **Note** that the -nobase and -norefcopy options are mutually exclusive.
2214
2215 #### Examples
2216
2217 ~~~~~
2218 wintegre -ref 2 1 –wb ref 
2219 ~~~~~
2220 Uses the report whose ID is 1 to initialize the ref workbench with BaseNumber equal to 2. 
2221 ~~~~~
2222 wintegre 1 –wb ref 
2223 ~~~~~
2224 Integrates the report whose ID is 1 to ref workbench. 
2225 ~~~~~
2226 wintegre -f 8 –wb ref 
2227 ~~~~~
2228 Forces the integration of report 8. Use the –f option if you want report 8 to be processed first. 
2229
2230
2231 ~~~~~
2232 wprepare -MyWb -o/tmp/MyReport 
2233 wstore /tmp/MyReport (GetID say 3) –wb ref 
2234 wintegre –wb ref -nobase 3 
2235 ~~~~~
2236 Edit the comment and modify <i>/tmp/MyReport</i> if required with current workbench accessed from ref workbench. 
2237 You may use the -nobase option adding the following line in the VC.edl file (Adm of the concerned file): 
2238 ~~~~~
2239 \@set %VC_TYPE = *NOBASE*; 
2240 ~~~~~
2241 @subsubsection occt_wok_4_9_4  wnews
2242
2243 The command has the following syntax: 
2244 ~~~~~
2245 wnews [-x] [-from p1 -to p2] [-headers|-units|-comments|- all] [-command TclCmd] 
2246 wnews -set markname [ -at p ] 
2247 wnews -ls [-bydate] 
2248 wnews -rm markname 
2249 wnews -admin 
2250 wnews -purge 
2251 ~~~~~
2252
2253 The *wnews* command allows managing and using the data stored in the integration journal. 
2254 The integration journal is updated via the command *wintegre* each time an integration is performed; it contains all the UDs and files concerned with the integration, as well as the comments provided by the developers (reports). 
2255
2256 Every integration is numbered and the associated files are archived with a specific version number. 
2257 Marks can be set on specific zones of the integrations via the wnews command. A mark is a character string which does not contain any dash character (-) and is associated with an integration number. Several marks may point to the same number, but one mark may only point to one number. 
2258
2259 **Note** that *BEGIN* and *END* are reserved mark names. You cannot use them. 
2260
2261 Options: 
2262 * -from p1 -to p2 - Extracts a portion of the journal file between index p1 and p2, with p1 and p2 integration numbers or marks. If p1 is not specified, reports are extracted from the beginning of the journal file. If p2 is not specified, reports are extracted up to the end of the journal file. 
2263 * -at p - Places a mark at index p, with p being an integration number. If p is not specified, the mark is placed at the end of the journal. 
2264 * -ls [-bydate] - Lists the marks. If -bydate is specified, the marks are listed in the order they were created. Otherwise, they are listed according to their place in the journal file. 
2265 * -rm <markname> - Removes the mark *markname*. 
2266 * -admin - Displays the journal location, date and other information. 
2267 * -purge - Saves the journal file and creates a new empty one. 
2268
2269 Additional options: 
2270 * -o file <name> - Redirects output in file. This option is ignored if -command is specified. 
2271 * -ws <shop> - Uses journal of shop instead of the current one. shop must belong to the current factory. 
2272 * -command <MyCommand> - Runs the command *Tcl MyComm* on the specified part of the journal. The syntax is the following: *proc MyComm { comments table args } { ...}*, where *comments* is a string containing all the comments on the integration between n1 and n2, and *table* is a table indexed with the names of the concerned *uds* (each element of the table is a list of UD files with definition of their status and version). Additional arguments may be passed using *userdata* with the argument *args* containing *mydata1, mydata2*. 
2273
2274 Wok provides a similar procedure *wnews:cpwb*, which allows to copy UDs from one workbench into another. 
2275
2276 **Note** that you may access the associated code of this command by typing *tclsh>cat $env(WOK_LIBRARY)/news_cpwb.tcl*
2277  
2278 For example, we can add the following to the file *Me.tcl*: 
2279 ~~~~~
2280 proc MyComm {comments table args} { 
2281 puts *comments = $comments* 
2282 parray table 
2283 puts *args = $args* 
2284 return 
2285
2286 ~~~~~
2287 Then type the following commands: 
2288 ~~~~~
2289 \> source Me.tcl 
2290 \> wnews -x -from n1 -to n2 -command MyComm -userdata wb1 wb2 
2291 ~~~~~
2292
2293 Examples
2294 --------
2295 ~~~~~
2296 wnews -set BETA_V1.1 -at 345 
2297 ~~~~~
2298 Sets a mark on integration number 345 
2299 ~~~~~
2300 wnews -set RELEASED_V1.1_CLOSED 
2301 ~~~~~
2302 Sets a mark after the last integration performed 
2303 ~~~~~
2304 wnews -ls 
2305 ~~~~~
2306 Lists all the marks set in the journal 
2307 ~~~~~
2308 wnews -x -from INT_DEB -to INT_END -units 
2309 ~~~~~
2310 Gets all the UDs modified between integrations INT_DEB and INT_END. Integration numbers and marks may be mixed as in the following: 
2311 ~~~~~
2312 wnews -x -from INT_DEB -to 856 -comments 
2313 wnews -x -from INT_DEB -to INT_END -comments 
2314 ~~~~~
2315 Gets all the comments from the integrations between *INT_DEB* and *INT_END* 
2316 ~~~~~
2317 source Mycommand.tcl 
2318 wnews -x -from INT_DEB -to INT_END -command Mycommand 
2319 ~~~~~
2320 In a more elaborate way, a Tcl process may be called to get all information on the reports between *INT_DEB* and *INT_END*.
2321 ~~~~~ 
2322 wnews -x -from n1 -to n2 -command wnews:cpwb –userdata w1,w2,[ulist, notes] 
2323 ~~~~~
2324 All modified files between n1 and n2 are copied from workbench w1 into workbench w2. New UDs are created in w2 if required If *ulist* is specified, only the UDs contained in this list are Processed. If notes is specified, all comments between n1 and n2 are written into this file. 
2325
2326 @subsubsection occt_wok_4_9_5  wget
2327 ~~~~~
2328 wget [-l] –wh <MasterWb>
2329 wget [-f] –wb <MasterWb> [-ud <UnitName>] <SourceFile> [-v <Version>]
2330 wget [-f] –wb <MasterWb> [-ud <UnitName>] <SourceFile1>...<SourceFileN>
2331 ~~~~~
2332 The *wget* command allows importing source files into the workbench. The files are fetched from the SCCS database of the factory. This operation is known as a check-out operation. You can specify one or more files or a unit name. By default, the latest version of the files is fetched.
2333  
2334 Options: 
2335 * <SourceFile> - Fetches a copy of the specified file. 
2336 * -ud <UnitName> Fetches all the source files of the development unit you specified. 
2337 * -f Forces existing files to be overwritten. 
2338 * -v <Version> Fetches <Version> of the file you specified. 
2339 * -l Lists the files of the development unit that can be copied (i.e. that you can **get**). This is a default option. 
2340
2341 #### Example
2342
2343 ~~~~~
2344 wget –wb MasteWb –ud MyUd File1.cxx File2.hxx 
2345 ~~~~~
2346 Fetches the latest version of *File1.cxx* and *File2.hxx*.
2347  
2348 @subsubsection occt_wok_4_9_6  Installation Procedure
2349
2350 In the new WOK model: 
2351   *  each workbench can have its own database 
2352   *  the version control environment variables are relative to the workbench. 
2353 @image html /dev_guides/wok/images/wok_image014.png "Workshop Installation Model"
2354 @image latex /dev_guides/wok/images/wok_image014.png "Workshop Installation Model"
2355
2356 The following procedure explains how to set up the source management environment for a workshop. 
2357 1. Open the factory and the workshop. 
2358 ~~~~~
2359 \> wokcd <factory:workshop> -P Adm
2360 ~~~~~
2361 2. Define the environment variables for version control by editing the file *VC.edl*. Your entries should respect the following syntax: 
2362 ~~~~~
2363 \@set %VC_TYPE=”SCCS”
2364 \@set %VC_ROOT=”/dirA/dirB/.../<MyDir>”
2365 ~~~~~
2366 3. Reopen the workbench that you want to connect to the database. 
2367 ~~~~~
2368 \> wokcd <factory:workshop:workbench>
2369 ~~~~~ 
2370 4. Create SCCS database associated with workbench. 
2371 ~~~~~
2372 \> wstore –create –wb <factory:workshop:workbench> -queue <PathToQueue>
2373 ~~~~~
2374 5. Create a report associated with the root workbench. 
2375 ~~~~~
2376 \> wprepare –wb <workbench> -o ref.report
2377 ~~~~~
2378 6. Queue this report. 
2379 ~~~~~
2380 \> wstore –wb <workbench> ref.report
2381 ~~~~~
2382 7. Perform the actual creation of the SCCS database. 
2383 ~~~~~
2384 > wintegre –wb <workbench> < BaseNumber >
2385 ~~~~~
2386 Here <BaseNumber> is the first digit of the SCCS version numbers. 
2387
2388 @subsubsection occt_wok_4_9_7  Integration Procedure
2389
2390 To integrate, proceed as follows: 
2391 1. Create the report for the current workbench.
2392 ~~~~~ 
2393  \> wprepare –wb MasterWb -o MyReport 
2394 ~~~~~
2395 2. If necessary, edit this report to remove lines and append comments. Comments should begin with -- (double hyphen). 
2396 3. Queue the report and store the files. 
2397 ~~~~~
2398 \> wstore –wb MasterWb MyReport
2399 ~~~~~
2400 By this step, all the files you have modified have been stored and the report has been queued. You can continue with modifying these files. 
2401 4. Examine the state of the integration queue to get the ID of your report. 
2402 ~~~~~
2403 \> wstore –wb MasterWb -ls
2404 ~~~~~
2405 5. Perform the integration and be sure you can write in the root workbench. This operation is usually reserved for the workshop administrator. 
2406 ~~~~~
2407 \> wintegre –wb MasterWb [ID]
2408 ~~~~~
2409
2410 @subsection occt_wok_4_10 Session Services
2411
2412 A single session service is also available to allow you to query WOK. 
2413 *Sinfo* command returns details of the WOK session. 
2414 ~~~~~
2415 Sinfo -option 
2416 ~~~~~
2417
2418 Options: 
2419 * -F Gets factory list 
2420 * -f Gets current factory 
2421 * -s Gets current workshop 
2422 * -w Gets current workbench 
2423 * -u Gets current development unit 
2424 * -t <entity_path> Gets the entity type 
2425 * -E Reserved for internal use. Gets known Entity List 
2426 * -N Reserved for internal use. Gets known Entity Names 
2427
2428 #### Example
2429
2430 ~~~~~ 
2431 Sinfo -F 
2432 ~~~~~
2433 Returns a list of WOK factories. 
2434
2435 @subsubsection occt_wok_4_10_2  Convenience Aliases
2436
2437 To ease the upgrade to the new version of WOK a number of aliases, compatible with the old version, have been set up. These convenience aliases include: 
2438 * **fcd** - Moves to the specified factory. 
2439 * **scd** - Moves to the specified workshop. 
2440 * **wcd** - Moves to the *src* directory of the specified development unit. 
2441 * **wdrv** - Moves to the *drv/DBMS/Station* directory of the current development unit. 
2442 * **wls** - Lists the development units in the current workbench. 
2443 * **wsrc** - Moves to the *src* directory of the current development unit. 
2444
2445 @section occt_wok_5 Using the Graphic Interface
2446 The following is an overall description of the IWOK main menu bar. Please, refer to the on-line help to get more detailed information on the various applications accessed via the graphic interface. 
2447 @subsection occt_wok_5_1  Main menu bar
2448 @image html /dev_guides/wok/images/wok_image015.png
2449 @image latex /dev_guides/wok/images/wok_image015.png
2450 @subsubsection occt_wok_5_1_1  Menus
2451 The main menu bar contains three menus: 
2452   *  **File** to exit the iwok session, 
2453   *  **Windows** to display all windows created in the session, 
2454   *  **Help** to display the associated on-line help. 
2455
2456 @subsubsection occt_wok_5_1_2  Application icons
2457 The four icons on the left are used to access applications: 
2458   *  **wprepare**, allows preparing the integration queue being associated with a given workshop, 
2459 @image html /dev_guides/wok/images/wok_image016.png
2460 @image latex /dev_guides/wok/images/wok_image016.png
2461   *  **umake**, gives access to all available umake options plus compilation options, 
2462 @image html /dev_guides/wok/images/wok_image017.png
2463 @image latex /dev_guides/wok/images/wok_image017.png
2464   *  **CDL browser**, provides information on the class structure or translated classes, 
2465 @image html /dev_guides/wok/images/wok_image018.png
2466 @image latex /dev_guides/wok/images/wok_image018.png
2467
2468  *  **parameters**, allows displaying and editing all EDL files. 
2469 @image html /dev_guides/wok/images/wok_image019.png
2470 @image latex /dev_guides/wok/images/wok_image019.png
2471
2472
2473 **Note:** for further information on CDL, refer to the CDL Reference Manual. 
2474
2475 @subsubsection occt_wok_5_1_3  Display management
2476 Click on the logo to either display or not the session in a window just below the main menu bar. 
2477
2478 You may choose to display icons in the window, either in **columns**, with the **last modified first**, by **date and size**, or in **rows**. 
2479
2480 Use the **go up** icon to navigate through the session and **wokcd** to update the window where the session was started. 
2481 @image html /dev_guides/wok/images/wok_image020.png
2482 @image latex /dev_guides/wok/images/wok_image020.png
2483
2484 The field **Location** gives the exact address of the item in the session. Use the arrow on the right to select already visited addresses. 
2485
2486 @subsection occt_wok_5_2  Popup menus
2487 Two types of popup menus may be accessed according to the context. Just click MB3 to display the popup menu. 
2488
2489 Click on an item in the left window to get the popup menu providing access to applications. 
2490
2491 @image html /dev_guides/wok/images/wok_image021.png
2492 @image latex /dev_guides/wok/images/wok_image021.png
2493
2494 In the right window you get the selection popup menu for the item types: 
2495
2496 @image html /dev_guides/wok/images/wok_image022.png
2497 @image latex /dev_guides/wok/images/wok_image022.png
2498
2499 @section occt_wok_6 Appendix A. Using the Emacs Editor
2500
2501 WOK is operated using the editor Emacs. Emacs is not provided in the Open CASCADE Technology distribution but is available from http://www.gnu.org/software/emacs/#Releases
2502
2503 A CDL mode has been created for Emacs. The .el file for this mode is not provided in the distribution, but is available on request from OPEN CASCADE. 
2504
2505 List of Keys and their Bindings in cdl Mode
2506 -------------------------------------------
2507
2508 |C-c |Command prefix |
2509 |TAB | cdl-tab |
2510 |DEL | backward-delete-character-untabify |
2511 |ESC | Command prefix |
2512 |C-c C-x | cdl-new-exception |
2513 |C-c C-e | cdl-new-enumeration |
2514 |C-c C-b | cdl-new-buffer |
2515 |C-c C-p | cdl-new-package |
2516 |C-c C-r | cdl-new-rubric |
2517 |C-c C-c | cdl-new-class |
2518 |C-c f | cdl-fill-mode |
2519 |C-c s | cdl-structure |
2520 |C-c t | cdl-tabsize |
2521 |C-c e | cdl-comment-end |
2522 |ESC k | cdl-find-class |
2523 |ESC q | cdl-comment-fill |
2524 |ESC TAB | cdl-untab |
2525 |ESC-RET | cdl-raw-newline |
2526
2527 @section occt_wok_7 Appendix B. Parameters and EDL Files
2528 @subsection occt_wok_7_1 EDL language
2529 @subsection occt_wok_7_1_1 Key Concepts
2530
2531 EDL is a script-like programming language.
2532
2533 **Comment** - text, preceded by two hyphens. 
2534 ~~~~~
2535 -- Comment text.... 
2536 ~~~~~
2537 * **Identifier** - any combination of characters in the ranges A-Z, az, 0-9 and _ (underscore). 
2538 * **Variable** - an identifier preceded by % (percent sign). 
2539 * **Actions** The following actions are available: 
2540 ~~~~~
2541 \@string 
2542 \@set 
2543 \@apply 
2544 ~~~~~
2545 * **Execution**  <i>@uses</i> is an execution operator.
2546 * **Input/Output** The following input/output operators are provided: 
2547 ~~~~~
2548 \@file 
2549 \@write 
2550 \@close 
2551 \@cout
2552 ~~~~~ 
2553 * **Conditional Operators** The following conditional operators are provided: 
2554 ~~~~~
2555 \@iffile 
2556 \@ifdefined 
2557 \@ifnotdefined 
2558 \@ifnotfile 
2559 \@if 
2560 then 
2561 \@else 
2562 \@endif
2563 ~~~~~
2564  
2565 * **Operators** The following operators are available: 
2566 <code>
2567 == 
2568 != 
2569 || 
2570 && 
2571 file 
2572 notfile 
2573 defined 
2574 notdefined 
2575 </code>
2576
2577 **Templates** The following template commands/keywords are available: 
2578 ~~~~~
2579 \@template 
2580 is 
2581 \@end 
2582 \@addtotemplate 
2583 \@cleartemplate 
2584 ~~~~~
2585 **Miscellaneous** The following miscellaneous commands exist: 
2586 ~~~~~
2587 \@verboseon 
2588 \@verboseoff 
2589 ~~~~~
2590
2591 @subsubsection occt_wok_7_1_2  Syntax
2592 The following conventions are used in the explanations below: 
2593
2594 | *<Variable>*  | refers to a variable, for example: *%myvariable* |
2595 | *<Id>*                | refers to an identifier, for example: *myidentifier* |
2596 | *“String”*        | refers to a string of characters, for example: *“my string of characters”* |
2597 | *<Condition>* | refers to a condition, for example: *(%mytest == “ok”) || (%mytest == “good”)* |
2598 | *<Template>*  | refers to the name of a template, for example: mytemplate. |
2599 |{}             | indicates possible repetition of what is within the curly brackets. |
2600
2601 @subsubsection occt_wok_7_1_3  EDL Actions
2602 \@string 
2603 --------
2604 ~~~~~
2605 \@string <Variable> = {<Variable> or “String”} ;
2606 \@string <Variable> += {<Variable> or “String”} ;
2607 ~~~~~
2608 Concatenates the contents of the variables and strings on the right of the equals sign and assigns the result to the variable situated on the left. Using the operator ‘+=’ instead of ‘=’ adds the concatenation to the current contents of the variable on the left. 
2609
2610 \@set
2611 ---- 
2612 ~~~~~
2613 \@set <Variable> = “ String” ;
2614 ~~~~~
2615 Sets <Variable> to the value “String”
2616
2617 \@apply
2618 ------ 
2619 ~~~~~
2620 \@apply <Variable> = <Template> ;
2621 ~~~~~
2622 Evaluates the template, <Template>, and sets <Variable> equal to this.
2623
2624
2625 \@uses
2626 -----
2627 ~~~~~
2628 \@uses <Variable>;
2629 \@uses “ String”;
2630 ~~~~~
2631 Runs an EDL file. The name of this file is either contained in the variable <Variable> or is given as a string, <String>.
2632
2633 \@file
2634 -----
2635 ~~~~~
2636 \@file <Id> <Variable> ;
2637 \@file <Id> “String” ;
2638 ~~~~~
2639 Opens a file and associates it with the identifier <Id>. This <Id> identifies the file until it is closed. The name of the file is given as a string <String>, or using a variable <Variable>.
2640
2641 \@write
2642 ------
2643 ~~~~~
2644 \@write <Id> <Variable> ;
2645 ~~~~~
2646 Writes the contents of the variable out to a file indicated by the file <Id>. This <Id> is the identifier allocated to the file when is opened using \@file.
2647
2648 \@close
2649 ------
2650 ~~~~~
2651 \@close <Id> ;
2652 ~~~~~
2653 Closes the file identified by <Id>. This <Id> is the identifier allocated to the file when is opened using \@file.
2654
2655 \@cout
2656 -----
2657 ~~~~~
2658 \@cout {<Variable> or “String”} ;
2659 ~~~~~
2660 Concatenates the contents of the variables and strings and displays the result on standard out.
2661
2662 \@iffile
2663 -------
2664 ~~~~~
2665 \@iffile ( <Variable> or “String”) then
2666 \@endif ;
2667 \@iffile ( <Variable> or “String”) then
2668 \@else
2669 \@endif ;
2670 ~~~~~
2671 Checks for the existence of a file, the name of which is given in the string  ‘String”, or else contained in the variable <Variable>.
2672 If the file exists, the instructions contained in the ‘then’ loop are executed up to the *\@endif*, (or an \@else if one is found before the \@endif ).
2673 If the files do not exist, the ‘else’ loop is executed (if one exists).
2674
2675 \@ifnotfile
2676 ----------
2677 ~~~~~
2678 \@ifnotfile ( <Variable> or “String”) then
2679 \@endif ;
2680 \@ifnotfile ( <Variable> or “String”) then
2681 \@else
2682 \@endif ;
2683 ~~~~~
2684 Checks for the existence of a file, the name of which is given in the string ‘String”, or else contained in the variable <Variable>.
2685 If the file does not exist, the instructions contained in the ‘then’ loop are executed up to the \@endif, (or an \@else if one is found before the \@endif).
2686 If the file does exist, the ‘else’ loop is executed (if one exists).
2687
2688 \@ifdefined 
2689 ----------
2690 ~~~~~
2691 \@ifnotdefined ( <Variable> or <Template>) then
2692 \@endif ;
2693 \@ifnotdefined ( <Variable> or <Template>) then
2694 \@else
2695 \@endif ;
2696 ~~~~~
2697 Checks for the existence of a variable or template, the name of which is given by <Template>, or else contained in the variable <Variable>.
2698 If a variable or a template by this name exists the instructions contained in the ‘then’ loop are executed up to the \@endif, (or an \@else if one is found before the \@endif).
2699 If neither a variable nor a template exists, the ‘else’ loop is executed (if one exists).
2700
2701
2702 \@ifnotdefined
2703 -------------
2704 ~~~~~
2705 \@ifnotdefined ( <Variable> or <Template>) then
2706 \@endif ;
2707 \@ifnotdefined ( <Variable> or <Template>) then
2708 \@else
2709 \@endif ;
2710 ~~~~~
2711 Checks for the existence of a variable or template, the name of which is given by <Template>, or else contained in the variable <Variable>.
2712 If neither a variable nor a template by this name exists the instructions contained in the ‘then’ loop are executed up to the \@endif, (or an \@else if one is found before the \@endif).
2713 If a variable or a template does exist, the ‘else’ loop is executed (if one exists).
2714
2715 \@if 
2716 -----
2717 ~~~~~
2718 \@if (<Condition>) then
2719 \@endif ;
2720 \@if (<Condition>) then
2721 \@else
2722 \@endif ;
2723 ~~~~~
2724 Tests a condition.
2725 If the condition is true the instructions in the ‘then’ loop are executed up to the \@endif, (or an \@else if one is found before the \@endif).
2726 If the condition is false, the ‘else’ loop is executed (if one exists).
2727
2728 \@template
2729 ---------
2730 ~~~~~
2731 \@template <Template> (<Variable>, ... , <Variable>) is
2732         $ text...
2733         .
2734         .
2735         $ text...
2736 \@end;
2737 ~~~~~
2738 Creates a template, which is a definition that contains variables. The variables on which a template relies are given in parentheses, following the name of the template. These variables are used to evaluate the template, and are referred to as ‘variables of evaluation’. When a template is evaluated (see \@apply) the variables in its definition are replaced by the current values of the ‘variables of evaluation’.
2739 A template is re-evaluated each time it is used.
2740
2741 \@addtotemplate
2742 --------------
2743 ~~~~~
2744 \@addtotemplate <Template> is
2745         $ text
2746         .
2747         .
2748         $ text
2749 \@end;
2750 ~~~~~
2751
2752 Adds the specified lines to an existing template.
2753
2754 \@cleartemplate
2755 --------------
2756 ~~~~~
2757 \@cleartemplate <Template> ;
2758 ~~~~~
2759 Removes all the lines of a template. 
2760
2761 \@verboseon
2762 ----------
2763 ~~~~~
2764 \@verboseon ; 
2765 ~~~~~
2766 Turns on the verbose mode, such that lines of text are displayed on standard out when you run EDL files. 
2767
2768 \@verboseoff
2769 -----------
2770 ~~~~~
2771 \@verboseoff ; 
2772 ~~~~~
2773 Turns off the verbose mode, such that lines of text are not displayed on standard out when you run EDL files. 
2774
2775 @subsubsection occt_wok_7_1_4  EDL Conditions
2776 Conditions are used with *\@if* commands. Complex and simple conditions are available. The syntax is similar to C++. 
2777
2778 #### Simple Conditions
2779 Simple conditions test for equality, the existence of a particular file and so on. The general format is: 
2780 ~~~~~
2781 \@if(<Condition>) then 
2782 ... 
2783 ~~~~~
2784 The syntax of simple conditions is given below. 
2785 ~~~~~
2786 <Variable> == “String” -- (equals)
2787 <Variable> != “String” -- (does not equal)
2788 defined(<Variable>) -- (see \@ifdefined)
2789 defined(<Template>) -- (see \@ifdefined)
2790 notdefined(<Variable>) -- (see \@ifnotdefined)
2791 notdefined(<Template>) -- (see \@ifnotdefined)
2792 file(<Variable>) -- (see \@iffile)
2793 file(“String”) -- (see \@iffile)
2794 notfile(<Variable>) -- (see \@ifnotfile)
2795 notfile(“String”) -- (see \@ifnotfile)
2796 ~~~~~
2797
2798 #### Complex conditions
2799
2800  
2801 Complex conditions take into account the results of other conditions. Complex conditions use the operators || (logical OR) or the operator  (logical AND). There are no restrictions on the formulation of these conditions: 
2802 * (Simple condition) operator (Simple condition) 
2803 * (Complex condition) operator (Simple condition) 
2804 * (Simple condition) operator (Complex condition) 
2805 * (Complex condition) operator (Complex condition) 
2806
2807 For example,
2808 ~~~~~
2809 \@if ((%a == “0” && %b == “1” && %c == “1”) || %d == “1” && ((%a == “1”) && %b == “1”)) then
2810         \@cout “CONDITION TRUE”;
2811 \@else
2812         \@cout “CONDITION FALSE”;
2813 \@endif;
2814 ~~~~~
2815
2816 @subsection occt_wok_7_2  WOK Parameters
2817 WOK parameters are defined using EDL. There are two types of EDL parameters: Variables and Templates. 
2818
2819 Variables have a ‘fixed’ value. By contrast a template relies on the values of other variables, and must re-evaluate itself each time it is used. 
2820
2821 @subsubsection occt_wok_7_2_1  Classes of WOK Parameters
2822 WOK parameters are grouped according to their class. The following classes exist: 
2823 | CODEGEN  | Code generator options, for example options for lex and yacc. |
2824 | CMPLRS   | Compiler options. |
2825 | LDAR     | Archive creation options. |
2826 | ARX      | Archive extraction options. |
2827 | LDEXE    | Executable linker options. |
2828 | LDSHR    |  Shared linker options. |
2829
2830 @subsubsection occt_wok_7_2_2  Defining WOK Parameters
2831 The WOK distribution includes a base configuration for each class of parameters. This base configuration is provided in the form of EDL files, one file per a class of parameters. Each file is named according to the parameter class: 
2832 ~~~~~
2833 <ParamClassName>.edl
2834 ~~~~~
2835 This configuration file sets the values of all the parameters in the class. 
2836
2837 For example, consider a parameter class FOO. There are two variable parameters in this class: FOO_Shared and FOO_Name. These two parameters are assigned a value in the FOO.edl file. The file is given as an example below: 
2838 ~~~~~
2839 -- standard protection against multiple execution 
2840 \@ifnotdefined ( %FOO_EDL) then 
2841 \@set %FOO_EDL = **; 
2842
2843 -- set %FOO_Shared according to the platform 
2844 \@if ( %LocalArch != *hp* ) then 
2845 \@set %FOO_Shared = *libCPPExt.so*; 
2846 \@endif; 
2847 \@if ( %LocalArch == *hp* ) then 
2848 \@set %FOO_Shared = *libCPPExt.sl*; 
2849 \@endif; 
2850
2851 -- set the FOO_Name parameter to FOO 
2852 \@set %FOO_Name = *FOO*; 
2853 \@endif; 
2854 ~~~~~
2855
2856 Note that all the parameters in a class take the name of the class as a prefix to their own name. Parameters of type variable are also prefixed by % (percent symbol): 
2857 ~~~~~
2858 %ClassName_VariableParamName 
2859 ClassName_TemplateParamName 
2860 ~~~~~
2861 A simplified template definition is given as an example below. This definition is based on the FOO parameters set in the previous example above. 
2862
2863 Let us define the variable parameter(s) to be used in the template and then the template itself:
2864 ~~~~~
2865 \@set %FOO_Shared = *libCPPExt.so*; 
2866 \@set %FOO_Name = *FOO*; 
2867
2868 \@template FOO_Load ( %FOO_Shared, %FOO_Name) is 
2869 $ %FOO_Load_%FOO_Shared %FOO_Name 
2870 \@end; 
2871 ~~~~~
2872
2873 @subsubsection occt_wok_7_2_3  Redefining Parameters
2874 Occasionally you may want to redefine WOK parameters. For example, you can change the compiler options to force ANSI mode compilation, or redefine how external libraries are referenced. 
2875 Before redefining anything, decide on the scope of the redefinition. Is the redefinition to apply to the whole factory, a single workshop, a workbench, or just a development unit? In some cases you may want to redefine parameters within a delivery unit, so that a parcel is delivered with particular options. 
2876
2877 The order in which redefinitions are applied (order of precedence) may mean your options are overwritten by subsequent redefinitions.
2878
2879 #### Redefinition Files
2880
2881 Each entity can have an associated redefinition file for each class of parameters. A redefinition file is an EDL file. It always takes the name of the entity to which it belongs, followed by the name of the class of parameters that it applies to: 
2882 ~~~~~
2883 <EntityName>_<ParamClassName>.edl
2884 ~~~~~
2885 For example, the file MyFactory_CMPLRS.edl redefines one of more of the parameters in the CMPLRS class. The scope of this redefinition is MyFactory. To be taken into account by WOK, this redefinition file must be created in the administration directory of the entity to which it belongs. To find out the pathname of this directory, use the command: 
2886 ~~~~~
2887 wokinfo -p admfile:<EntityName>_<ParamClassName>.edl <EntityPath>
2888 ~~~~~
2889 To test whether the file exists actually, use the command: 
2890 ~~~~~
2891 wokinfo -p adminfile:WOK_LDAR.edl WOK=> /adv22/wok/adm
2892 ~~~~~
2893 There is one exception to this rule for file placement. For a development unit, the redefinition file is treated as a *source *file, and consequently it must be located in the src directory of the unit. To find out the path of this directory, use the command: 
2894 ~~~~~
2895 wokinfo -p source:<UnitName>_<ParamClassName>.edl <UnitPath>
2896 ~~~~~
2897
2898 One of the most common reasons to redefine WOK parameters is to modify compiler options. To do this, for example to add a compile option to the package *MyPack*: 
2899 * In the source directory of MyPk, create file *MyPk_CMPLRS.edl* 
2900 * In this file add the definition: 
2901 ~~~~~
2902 \@string %CMPLRS_CXX_Options +=  * -DMyDefine=string *; 
2903 ~~~~~
2904
2905 Order of Precedence for Parameter Redefinitions 
2906 -----------------------------------------------
2907 WOK takes parameter (re)definitions into account in the following order. 
2908 * WOK 
2909 * Factory 
2910 * Workshop 
2911 * Parcels (within the Workshop configuration, in the order in which they are declared in the parcel configuration). 
2912 * Workbench (in order of inheritance) 
2913 * Development unit 
2914 WOK provides commands to find out what parameter definitions (and redefinitions) are used, and in what order. You can see what compiler parameters are used by WOK in *CMPLRS.edl* file. To find this file, use the command: 
2915 ~~~~~
2916  wokparam -S CMPLRS.edl 
2917 ~~~~~
2918 Then run the command. 
2919 ~~~~~
2920 wokparam -F CMPLRS EntityPath 
2921 ~~~~~
2922 This command displays a list of all the definition files, for parameters of type compiler, that are taken into account for EntityPath. These file are listed in the order in which they are taken into account. The last definition is the one that is used. 
2923
2924 @subsection occt_wok_7_3  Using EDL to Define WOK Parameters
2925 @subsubsection occt_wok_7_3_1  Modification of Link Options - Example
2926
2927 #### How to add a define to the compilation
2928
2929 To add a define for all C++ files compiled in the package *MyPackage*, *MyPackage_CMPLRS.edl* is declared in the development unit *MyPackage* This file contains: 
2930 ~~~~~
2931 \@string %CMPLRS_CXX_Options = 
2932 %CMPLRS_CXX_Options  * -DMYDEFINE*; 
2933 ~~~~~
2934
2935 #### How to use a code generator
2936
2937 In this example, a C code generator is used, which takes the input <i><file>.mygen</i> and generates a <i><file>.c</i>. The step *obj.cgen* automatically recognizes all files with the extension mygen and uses the generator on these files. The resulting .c files are compiled by the step *obj.comp*. 
2938 The file *MyUnit_CODEGEN.edl* is written in a nocdlpack development unit *MyUnit*. This file contains the following code: 
2939
2940 ~~~~~
2941 -- list of tools recognized by the step obj.cgen 
2942 -- the tool MYGEN is added 
2943 \@ string %CODEGEN_Tools = %CODEGEN_Tools  * CODEGEN_MYGEN*; 
2944
2945 -- the tool MYGEN is called via the template CODEGEN_MYGEN_CmdLine 
2946
2947 \@set %CODEGEN_MYGEN_Template = *CODEGEN_MYGEN_CmdLine*; 
2948
2949 -- the extension of files processed by MYGEN is mygen 
2950
2951 \@set %CODEGEN_MYGEN_Extensions = *foo.mygen*; 
2952
2953 -- the tool MYGEN is the executable /usr/local/bin/mygen 
2954
2955 \@set %CODEGEN_MYGEN_Tool =  * /usr/local/bin/mygen*; 
2956
2957 -- the tool MYGEN produces a .c file 
2958
2959 \@template CODEGEN_MYGEN_Production ( %BaseName ) is 
2960 $%BaseName.c 
2961 \@end; 
2962
2963 -- the command executed to construct the .c file is: 
2964
2965 \@template CODEGEN_MYGEN_CmdLine ( %CODEGEN_MYGEN_Tool, 
2966 %Source, %BaseName, %OutputDir ) is 
2967 $cd %OutputDir 
2968 $%CODEGEN_MYGEN_Tool -f %Source -o %BaseName.c 
2969 \@end; 
2970 ~~~~~
2971
2972 @section occt_wok_8 Appendix C. Tcl
2973 @subsection occt_wok_8_1  Tcl Overview
2974 Tcl stands for ‘‘tool command language* and is pronounced ‘‘tickle*. It is actually two things: a language and a library. 
2975
2976 As a simple textual language, tcl is intended primarily for issuing commands to interactive programs such as text editors, debuggers, illustrators, and shells. It has a simple syntax and is also programmable, so tcl users can write command procedures to provide more powerful commands than those in the built-in set. 
2977
2978 As a library package, tcl can be embedded in application programs. The tcl library consists of a parser for the cl language, routines to implement the tcl builtin commands, and procedures that allow each application to extend tcl with additional commands specific to that application. The application program generates tcl commands and passes them to the tcl parser for execution. Commands may be generated by reading characters from an input source, or by associating command strings with elements of the application's user interface, such as menu entries, buttons, or keystrokes.
2979
2980 For Linux platform it is possible to download Tcltk 8.5 or 8.6 from http://www.tcl.tk/software/tcltk/8.6.html
2981 For Windows platforn it is possible to download ActiveTcl 8.5 or 8.6 from http://www.activestate.com/activetcl/downloads
2982
2983 A help application, tclhelp, is also provided with tcl and can be activated by command *tclhelp*.  
2984
2985 @subsection occt_wok_8_2  Tcl and WOK
2986 The tcl interpreter offers WOK the following advantages: 
2987 * an environment in which both WOK and UNIX commands are available, 
2988 * dynamic loading of WOK as it is needed, 
2989 * a high performance portable environment, in which the user can write customized procedures. 
2990
2991 The following tcl commands are most commonly used with WOK: *expr, foreach, glob, if, package, proc, puts, set, source* and *unlink*. 
2992
2993 Refer to the tcl documentation, or the tcl help application, for details of these and other tcl commands. 
2994
2995 @subsection occt_wok_8_3  Configuring Your Account for Tcl and WOK
2996 To have access to WOK you must modify the configuration files of your account as described below. 
2997 @subsubsection occt_wok_8_3_1  The cshrc File
2998 To allow the C shell session to configure tcl add the following line to your .chsrc file: 
2999 ~~~~~
3000 source/<sun|ao1|sgi|hp>_SYSTEM/util_LOG/cshrc_TCL
3001 ~~~~~
3002 To configure your account to allow access to WOK add the following line to your .cshrc file: 
3003 ~~~~~
3004 if(!$?WOKHOME) then
3005 setenv WOKHOME /YOURCONTAINER/wok-<version of wok>
3006 source /<sun|ao1|sgi|hp>_SYSTEM/util_LOG/cshrc_Wok
3007 ~~~~~
3008 @subsubsection occt_wok_8_3_2  The tclshrc File
3009 To enable configuration of the tcl interpreter, add the following line to your .tclshrc if it exists (if not create one): 
3010 ~~~~~
3011 source $env(WOKHOME)/site/tclshrc_Wok 
3012 ~~~~~
3013
3014 @subsubsection occt_wok_8_3_3  The WOK_SESSIONID Variable
3015 The *WOK_SESSIONID* environment variable ensures that you start a new WOK session in the same state and with the same parameter values as your previous WOK session. This continuity is provided by using the same WOK_SESSIONID. Note that your *WOK_SESSIONID* does not change, unless you change it manually. 
3016
3017 Make sure that *WOK_SESSIONID* points to (a subdirectory of) your home directory. 
3018
3019 @subsubsection occt_wok_8_3_4  Writing Tcl Steps for a WOK Build
3020 There are three advanced WOK commands available for writing umake steps in tcl: 
3021   *  *msgprint* 
3022   *  *stepoutputadd* 
3023   *  *stepaddexecdepitem* 
3024  
3025 *msgprint [-i|-w|-e|-v|-V Class]* prints a message. The output is directed to a WOK internal process that is in charge of printing messages. 
3026
3027 The following options are available:  
3028 | -i  | Prints an information message. |
3029 | -w  | Prints a warning message. |
3030 | -e  | Prints an error message. |
3031 | -v  | Prints a verbose message. |
3032 | -V<Class> | Prints a verbose message for class <Class>. |
3033 | -c  | Prints context of message, i.e. the procedure that called it. |
3034
3035 For example, 
3036 ~~~~~
3037 msgprint -e -c *CCLKernel_GetObjects::Execute* *Cannot locate object file :  * $file; 
3038 ~~~~~
3039 Writes an error message, in format: 
3040 ~~~~~
3041 ERROR: CCLKernel_GetObjects::Execute - Cannot locate object file : MyFile 
3042 ~~~~~
3043 *stepoutputadd <options> <OutputFileID> [<filepath>]* adds an output file to the outputs of the step. This file is treated by subsequent steps in the same way as all the other output files of the step. The following options are available:  
3044
3045 | -p<path> |  Specifies the path where the file is located. |
3046 | -L | Output can be located (default). |
3047 | -N | Not a WOK file. Cannot be located. |
3048 | -F | Physical file (i.e. resides on a disk somewhere). |
3049 | -M | File is a member of the unit being built (default). |
3050 | -X | File is not a member of the unit being built. Not a WOK file. Cannot be located. |
3051 | -P | File is produced by this umake step (i.e. WOK can delete it because it will be regenerated). |
3052 | -R | File is not produced by this umake step (i.e. WOK must not delete it because it can not be regenerated). 
3053 | -S<StepID> | Reserved for advanced use. Specifies stepID. |
3054 | -V | Reserved for advanced use. Virtual ‘file’ (i.e. an MSEntity). This option is used for passing keywords between steps for example. | 
3055
3056 For example, 
3057 ~~~~~ 
3058 stepoutputadd -X -R -N -F /usr/myfiles/res.o -p /usr/myfiles/res.o 
3059 ~~~~~
3060 Adds the file */usr/myfiles/res.o* to the outputs of this step. Specifies that this file is not a WOK file, cannot be located automatically by WOK, and is not generated by this step. Here the full file path is used as the unique file identifier. This appears to be duplicated when it is also given as the physical location of the file. 
3061
3062 *stepaddexecdepitem <options> <InputFileID> <OutputFileID>* adds a dependency between one file and another. Typically when introducing external object libraries the files are set to be dependent on the CDL file. We do this because the CDL file changes rarely, so the external files are not needlessly reprocessed, but they are always included in the final executable. The following options are available:  
3063
3064 | -d  | Adds a direct dependency (default). |
3065 | -i  | Adds an indirect dependency. |
3066
3067 For example, 
3068 ~~~~~
3069 stepaddexecdepitem -d MyInFile MyOutFile 
3070 ~~~~~
3071 States that the file *MyOutFile* depends directly on the file *MyInFile*. 
3072
3073 @subsubsection occt_wok_8_3_5  Components of a Tcl UMake Step
3074
3075 Each tcl umake step has the following components: 
3076 * *HandleInputFile* - a filter: for each input file this component decides whether or not to accept the file. 
3077 * *OutputDirTypeName* returns one of three strings, according to the dependency of the file: 
3078         * *tmpfile* = the file is independent (i.e. dependent only on its source);
3079         * *dbtmpdir* = the file is dependent on the database profile;
3080         * *sttmpdir* = the file is dependent on the station profile. 
3081 * *AdmFileType* returns one of three strings, according to the dependency of the file: 
3082         * *admfile* = the file is independent (i.e. dependent only on its source); 
3083         * *Dbadmfile* = the file is dependent on the database profile; 
3084         * *stadmfile* = the file is dependent on the station profile. 
3085
3086 *Execute* processes each input file that is out of date (i.e. has changed since it was last processed, or depends on a file that has changed since it was last processed). Typically this procedure takes the form of a *foreach* loop. Argument: a development unit to process and a list of one or more arguments. 
3087
3088 @subsubsection occt_wok_8_3_6  Sample Tcl Steps
3089
3090 #### Sample 1
3091
3092 ~~~~~
3093 # CCLKernel_GetObjects.tcl 
3094 proc CCLKernel_GetObjects::AdmFileType {} { 
3095         return stadmfile; 
3096
3097 proc CCLKernel_GetObjects::OutputDirTypeName {} { 
3098         return sttmpdir; 
3099
3100 proc CCLKernel_GetObjects::HandleInputFile { ID } { 
3101         scan $ID *%\[^:\]:%\[^:\]:%\[^:\]* unit type name 
3102         return 1; 
3103         switch [file extension $name] { 
3104 .cdl { 
3105                 return 1; 
3106                 } 
3107         default { 
3108                 return 0; 
3109                 } 
3110         } 
3111
3112 proc CCLKernel_GetObjects::Execute { unit args } { 
3113         msgprint -i -c *CCLKernel_GetObjects::Execute* 
3114         *Processing unit : $unit*; 
3115         msgprint -i -c *CCLKernel_GetObjects::Execute* 
3116         set failed 0; 
3117         set inid [lindex $args 0] 
3118         foreach file { Frontal_Ccal_Init_Request.o Frontal_Ccal_Send_Request.o \ 
3119 Frontal_Ccal_sd.o Frontal_Get_Response.o Frontal_Ccal_Connect.o } { 
3120 set resid *Frontal:object:$file* 
3121 set path [woklocate -p $resid] 
3122 if { $path == ** } { 
3123         msgprint -e -c *CCLKernel_GetObjects::Execute* 
3124 *Cannot locate object file :  * $file; 
3125         set failed 1; 
3126 } else { 
3127         msgprint -i -c *CCLKernel_GetObjects::Execute* *Add 
3128 object $file at  * $path 
3129         stepoutputadd -X -R -L -F $resid 
3130         stepaddexecdepitem -d $inid $resid 
3131         } 
3132
3133 if { [wokparam -e %Station] == *sun* } { 
3134         set file *risc_return.o* 
3135         set resid *CCLKernel:source:$file* 
3136         set path [woklocate -p $resid] 
3137 ## set path */adv_23/wb/kl/Kernel7/prod/EngineStarter/ 
3138 src/risc_return.o* 
3139         msgprint -i -c *CCLKernel_GetObjects::Execute* *Add 
3140 object $file at  * $path 
3141         stepoutputadd -X -R -N -F $path -p $path 
3142         stepaddexecdepitem -d $inid $path 
3143
3144 set home [wokparam -e %Ilog_Home] 
3145 if { $home == ** } { 
3146         msprint -c *CCLKernel_GetObjects::Execute* -e *Cannot 
3147 evaluate parameter : %Ilog_Home 
3148         return 1; 
3149
3150 foreach file { llstdio.o llfloat.o llfloat31.o cfix.o 
3151 lelisp.o getgloba.o cload.o } { 
3152         set path *$home/o/$file* 
3153         msgprint -i -c *CCLKernel_GetObjects::Execute* *Add 
3154 object $file at  * $path 
3155         stepoutputadd -X -R -N -F $path -p $path 
3156         stepaddexecdepitem -d $inid $path 
3157
3158 set file *lelisp31bin.o* 
3159 set path *$home/lelisp31bin.o* 
3160 msgprint -i -c *CCLKernel_GetObjects::Execute* *Add 
3161 object $file at  * $path 
3162 stepoutputadd -X -R -N -F $path -p $path 
3163 stepaddexecdepitem -d $inid $path 
3164 if { $failed } {return 1;} 
3165 return 0; 
3166
3167 ~~~~~
3168 Sample 2
3169 --------
3170 # File Name: CCLKernel_core.tcl 
3171 proc CCLKernel_core::AdmFileType {} { 
3172         return stadmfile; 
3173
3174 proc CCLKernel_core::OutputDirTypeName {} { 
3175         return sttmpdir; 
3176
3177 proc CCLKernel_core::HandleInputFile { ID } { 
3178         scan $ID *%\[^:\]:%\[^:\]:%\[^:\]* unit type name 
3179         switch $type { 
3180 executable { 
3181         return 1; 
3182
3183         } 
3184         switch $name { 
3185 CCL_lelisp.ll { 
3186         return 1; 
3187         } 
3188
3189         return 0; 
3190         } 
3191 proc CCLKernel_core::Execute { unit args } { 
3192         global WOK_GLOBALS env 
3193 msgprint -i -c *CCLKernel_core::Execute* *Processing unit : $unit*; 
3194         msgprint -i -c *CCLKernel_core::Execute* 
3195         set workbench [wokinfo -N $unit] 
3196         set unitname [wokinfo -n $unit] 
3197         set failed 0; 
3198         set lispbin ** 
3199         set lispfile ** 
3200         set lispbinid ** 
3201         set lispfileid ** 
3202         foreach ID $args { 
3203 scan $ID *%\[^:\]:%\[^:\]:%\[^:\]* Unit type name 
3204 switch $type { 
3205         executable { 
3206                 set lispbinid $ID 
3207                 set lispbin [stepinputinfo -p $ID] 
3208         } 
3209
3210 switch $name { 
3211 CCL_lelisp.ll { 
3212 set lispfileid $ID 
3213 set lispfile [stepinputinfo -p $ID] 
3214
3215
3216
3217 if { $lispfile == **} { 
3218 set lispfileid *CCLKernel:source:CCL_lelisp.ll*; 
3219 set lispfile [woklocate -p $lispfileid $workbench] 
3220
3221 if { $lispbin == **} { 
3222 msgprint -e -c *CCLKernel_core::Execute* *Cannot find lelispbin in input* 
3223 return 1; 
3224
3225 msgprint -i -c *CCLKernel_core::Execute* *Using lelisp.bin at  * $lispbin 
3226 msgprint -i -c *CCLKernel_core::Execute* 
3227 set config *[wokparam -e %Ilog_Home]/config* 
3228 set tmpdir [wokinfo -p sttmpdir:. $unit] 
3229 set output [wokinfo -p executable:. $unit] 
3230 set lelisppointbin [wokinfo -p executable:lelisp.bin $unit] 
3231 unlink -nocomplain $lelisppointbin 
3232 link -sym $lispbin $lelisppointbin 
3233 msgprint -i -c *CCLKernel_core::Execute* *Setting Environment* 
3234 set WOK_GLOBALS(setenv_proc,tcl) 1 
3235 wokenv -s 
3236 set WOK_GLOBALS(setenv_proc,tcl) 0 
3237 set olddir [pwd] 
3238 cd [wokinfo -p source:. $unit] 
3239 set FrontSIZE *-stack 12 -code 1500 -heap 2048 -number 0 -vector 32 -string 50 -symbol 30 -float 0 -cons  * 
3240 msgprint -i -c *CCLKernel_core::Execute* *Exec : $config $tmpdir $lispbin $lispfile $output $FrontSIZE 8* 
3241 puts *exec /bin/env \\ 
3242 COREDIR=$output \\ 
3243 WBPACKAGE=[wokinfo -n $unit] ILOG_LICENSE_FILE=[wokparam -e %Ilog_LicenseFile] \\ 
3244 CSF_EngineStarterList=/usr/local/etc/ 
3245 EngineStarter.Hosts \\ 
3246 ILOG_LICENSE_FILE=[wokparam -e %Ilog_LicenseFile] \\ 
3247 \*FrontSIZE=$FrontSIZE\* \\ 
3248 $config $tmpdir $lispbin $lispfile $output $FrontSIZE 8* 
3249 msgprint -i -c *CCLKernel_core::Execute* [eval *exec /bin/env \\ 
3250         COREDIR=$output \\ 
3251         WBPACKAGE=[wokinfo -n $unit] \\ 
3252         ILOG_LICENSE_FILE=[wokparam -e %Ilog_LicenseFile] \\ 
3253         CSF_EngineStarterList=/usr/local/etc/ EngineStarter.Hosts \\ 
3254         \*FrontSIZE=$FrontSIZE\* \\ 
3255 $config $tmpdir $lispbin $lispfile $output $FrontSIZE 8*] 
3256         stepoutputadd -P $unitname:corelisp:$unitname.core 
3257         stepaddexecdepitem -d $lispbinid 
3258 $unitname:corelisp:$unitname.core 
3259         stepaddexecdepitem -d $lispfileid 
3260 $unitname:corelisp:$unitname.core 
3261         cd $olddir 
3262         return 0; 
3263 }
3264 ~~~~~