Users Guide Vxworks

SNiFF+/SNiFF+ PRO
U S E R S G U I D E A N D R E F E R E N C E
4.1
Copyright 8/29/02 Wind River Systems, Inc.

ALL RIGHTS RESERVED. No part of this publication may be copied in any form, by photocopy, microfilm,
retrieval system, or by any other means now known or hereafter invented without the prior written permission of Wind
River Systems, Inc.
AutoCode, Embedded Internet, ESp, FastJ, IxWorks, MATRIX X, pRISM, pRISM+, pSOS, RouterWare, Tornado,
VxWorks, wind, WindNavigator, Wind River Systems, WinRouter, and Xmath are registered trademarks or service
marks of Wind River Systems, Inc.
BetterState, Doctor Design, Embedded Desktop, Envoy, How Smart Things Think, HTMLWorks, MotorWorks,
OSEKWorks, Personal JWorks, pSOS+, pSOSim, pSOSystem, SingleStep, SNiFF+, VxDCOM, VxFusion, VxMP,
VxSim, VxVMI, Wind Foundation Classes, WindC++, WindNet, Wind River, WindSurf, and WindView are
trademarks or service marks of Wind River Systems, Inc. This is a partial list. For a complete list of Wind River
trademarks and service marks, see the following URL:
http://www.windriver.com/corporate/html/trademark.html
Use of the above marks without the express written permission of Wind River Systems, Inc. is prohibited. All other
trademarks mentioned herein are the property of their respective owners.
Corporate Headquarters
Wind River Systems, Inc.
500 Wind River Way
Alameda, CA 94501-1153
U.S.A.
toll free ( U.S.): 800/545-WIND
telephone: 510/748-4100
facsimile: 510/749-2010
For additional contact information, please visit the Wind River URL:
http://www.windriver.com
For information on how to contact Customer Support, please visit the following URL:
http://www.windriver.com/support
SNiFF+/SNiFF+ PRO Users Guide and Reference, 4.1

August 29, 2002
Part #: M000-5700-01
Contents
Part I
Documentation Guidelines
This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
The SNiFF+ Documentation SetGuidelines . . . . . . . . . . . . . . . . . 4
Feedback and Useful Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Menu References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A Note on Unix/Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Typography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Part II
7
8
8
8
9
Projects and Workspaces
What is a Project? . . . . . . . . . . . . . . . . . . .
IntroductionProjects . . . . . . . . . . .
Some Advantages of Projects . . . . .
What Does a Project Know? . . . . .
......
......
......
......
......
......
......
......
.......
.......
.......
.......
....
....
....
....
13
14
14
16
What is a Workspace? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IntroductionWorkspaces and Projects . . . . . . . . . . . . . . . . . . . .
What are Workspaces For? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sharing or Layering Workspaces. . . . . . . . . . . . . . . . . . . . . . . . . .
What is a Workspace? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Location of Root Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17
18
18
20
21
24
SNiFF+/SNiFF+ PRO 4.1

Users Guide and Reference
Part III
Workspace Management
Workspace Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
Workspace Organizational Systems . . . . . . . . . . . . . . . . . . . . . . . .30
Hierarchical vs. Flat Workspace System . . . . . . . . . . . . . . . . . . . . .31
Reorganizing Workspaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
The Workspaces Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
Stand-Alone Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
What is a Stand-Alone Workspace? . . . . . . . . . . . . . . . . . . . . . . . .36
Stand-Alone Workspace Plus Project . . . . . . . . . . . . . . . . . . . . . . .36
Stand-Alone Workspace without Project . . . . . . . . . . . . . . . . . . . . .38
Special Case: Stand-Alone Analysis Environment . . . . . . . . . . . . .39
Workspaces and User Autonomy . . . . . . . . . . .
Workspace Configuration Data . . . . . . . .
Autonomous Workspace Configuration . .
Site-Level Workspace Configuration . . . .
......
......
......
......
......
......
......
......
.......
.......
.......
.......
.41
.42
.42
.44
Team Workspaces from Scratch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
PreparationSetting Up Team Projects . . . . . . . . . . . . . . . . . . . . .46
The First Team Member . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
The Project Creation Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
The Build-Target Setup Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
Post-Setup Project Tuning [Optional] . . . . . . . . . . . . . . . . . . . . . . .52
First Check-In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
Behind the Scenes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
Organization and Coordination . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
New Team Members (Flat Workspace System) . . . . . . . . . . . . . . . . . . . .57
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
What Do You See? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Create a Repository Node? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
Create a New Workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
First Check-Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
Open the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
More Workspaces for Yourself . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
More Team Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Contents
New Team Members (Hierarchical Workspace System) . .

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What Do You See? . . . . . . . . . . . . . . . . . . . . . . . . .
Create a Repository Node . . . . . . . . . . . . . . . . . . . .
Create a Node for the Shared Workspace. . . . . . . .
Create a Dependent Workspace . . . . . . . . . . . . . . .
More Workspaces for Yourself . . . . . . . . . . . . . . . .
More Team Members . . . . . . . . . . . . . . . . . . . . . . .
....
....
....
....
....
....
....
....
65
66
66
67
67
68
69
70
Managing Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reorganizing Workspaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Workspace Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Modifying Workspace Build Properties . . . . . . . . . . . . . . . . . . . . .
Version-Controlling Build Properties . . . . . . . . . . . . . . . . . . . . . . .
71
72
72
73
74
75
Part IV
.......
.......
.......
.......
.......
.......
.......
.......
Working with Projects
Project Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
You Only Create a Project Once . . . . . . . . . . . . . . . . . . . . . . . . . .
Wizard or Template? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Project and Workspace Creation in One . . . . . . . . . . . . . . . . . . . .
Project Creation in Existing Workspaces. . . . . . . . . . . . . . . . . . . .
Post-Setup Project Tuning. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Project Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Absolute Projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
81
82
82
83
83
84
87
88
88
Working with Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Opening Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Open-Project Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Managing Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Modifying Project Structure and Content . . . . . . . . . . . . . . . . . . . . 97
Using the Project Managers Other Files Tab . . . . . . . . . . . . . . . 99
Modifying Project Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Working with File Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What are File Types?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing File Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PreferencesFile Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating New File Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What are Derived File Types? . . . . . . . . . . . . . . . . . . . . . . . . . . .
103
104
104
105
106
107

Working with Fortran . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111

Fixed and/or Free Form?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112
Modifying Project Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
File Type Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
Using Different Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
Fortran Parser Command Line Arguments . . . . . . . . . . . . . . . . . .116
Preprocessing Fortran . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
Documenting Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
Generating C++ Documentation . . . . . . . . . . . . . . . . . . . . . . . . . .121
Browsing Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
Documentation Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Synchronizing Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126
Synchronizing Projects within SNiFF+ . . . . . . . . . . . . . . . . . . . . .127
Synchronizing Projects Outside of SNiFF+ . . . . . . . . . . . . . . . . . .128
Update Script Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
Part V
SNiFF+ PRO Build/Debug: How To
C/C++ Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139

Build-Target Wizard or Project Properties? . . . . . . . . . . . . . . . . . .140
C/C++ Build: Summary of Steps . . . . . . . . . . . . . . . . . . . . . . . . . .140
Setting C/C++ Targets and the Debugger Adaptor . . . . . . . . . . . .141
Setting Include Paths. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143
Verify Tool Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146
Java Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149
Build-Target Wizard or Project Properties? . . . . . . . . . . . . . . . . . .150
Java Build: Summary of Steps . . . . . . . . . . . . . . . . . . . . . . . . . . .150
Identify Libraries for Browsing Only. . . . . . . . . . . . . . . . . . . . . . . .151
Setting Java Application Targets and the Debugger Adaptor . . . .153
Setting Java Build Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
Verify Compiler and Other Java Tool Settings . . . . . . . . . . . . . . .157
Building Java Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
Remote Java Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
Ada Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165
What You Need (General) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166
GNAT and Tornado/VxWorks Requirements . . . . . . . . . . . . . . . .166
Contents
Run the GNAT Integration Script . . . . . . . . . . . . . . . . . . . . . . . . .

What the GNAT Integration Script Does . . . . . . . . . . . . . . . . . . .
Check Workspace Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Ada Targets and Debugger Adaptor . . . . . . . . . . . . . . . .
Ada and C/C++ Mixed Language Projects . . . . . . . . . . . . . . . . .
170
171
173
175
176
JAR, Java IDL, JNI, and RMI Settings . . . . . . . . . . . . . . . . . . . . . . . . . .

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Set Project Targets and Build Tools . . . . . . . . . . . . . . . . . . . . . .
Check Tool Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
181
182
182
183
IDL Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IDL File Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Projects and Derived File Types . . . . . . . . . . . . . . . . . . . . . . . . .
What to Do. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How File Compilation Works . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Browsing IDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
187
188
188
189
189
190
191
Custom Build Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Projects with Custom Build Systems . . . . . . . . . . . . . . . . . . . . . .
Enable Menu Commands for Custom-Built Targets . . . . . . . . . .
193
194
194
195
Remote Build and Debug. . . . . . . . . . . . . . . . . . . . . . . . . .

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting up Remote Build Hosts for Workspaces . . .
Verify Project Platform Settings . . . . . . . . . . . . . . . .
Working on Remote Hosts. . . . . . . . . . . . . . . . . . . .
197
198
198
202
202
.......
.......
.......
.......
.......
...
...
...
...
...
Modifying Build Tools and Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Where to Change the Tool Settings. . . . . . . . . . . . . . . . . . . . . . . 206
Running and Debugging Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Application Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Running Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debugging Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Debugger Command Line . . . . . . . . . . . . . . . . . . . . . . . . . .
Debugger Views and Dialogues . . . . . . . . . . . . . . . . . . . . . . . . .
Working With Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Variables View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Execution Context View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
211
212
212
213
213
214
214
215
216

Memory View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217

Registers View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217
Multiple Simultaneous Debugger Sessions . . . . . . . . . . . . . . . . . .217
Part VI
SNiFF+ PRO Build System Concepts
SNiFF+ PRO Build System: Introduction . . . . . . . . . . . . . . . . . . . . . . . . .221

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222
Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222
Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .223
Make Command and Redirection Directory. . . . . . . . . . . . . . . . . .224
Build Tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .226
Build Tool Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228
A Closer Look at Build Tools, Tool Settings and Platforms . . . . . . . . . . .231
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232
How are Platforms and Build Tools Related? . . . . . . . . . . . . . . . .232
What is a Build Tool Template?. . . . . . . . . . . . . . . . . . . . . . . . . . .233
What is a Build Tool Template For? . . . . . . . . . . . . . . . . . . . . . . .235
What is a Platform? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .235
Platforms, Build Tools and Settings. . . . . . . . . . . . . . . . . . . . . . . .236
Build ToolsBits and Pieces . . . . . . . . . . . . . . . . . . . . . . . . . . . .237
Inheritance of Build Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241
Cascading and Levelling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .242
Preferences Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .242
Workspace Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .243
Project Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .243
File Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .243
Building Project Structures and Compiling Files . . . . . . . . . . . . . . . . . . .245
Project Structure and the Build System. . . . . . . . . . . . . . . . . . . . .246
File Compilation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .246
Part VII
Version Control and Configuration Management
Integration of Version Control Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . .251

Version Control Tools and SNiFF+ . . . . . . . . . . . . . . . . . . . . . . . .252
Setting the Version Control Integration . . . . . . . . . . . . . . . . . . . . .253
CMVC: Basic Concepts and Terminology . . . . . . . . . . . . . . . . . . . . . . . .255
Basic CMVC Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .256
What is a Configuration? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .256
Contents
What is a Freeze-Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What is a Change-Set? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What is a Branch? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What is HEAD? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What is INIT? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
257
257
257
258
258
Working with Branches: Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . .

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Situations for Using SNiFF+s Branch Support . . . . . . . . . . . . . .
Creating a Branch Revision . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working on the Branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
259
260
261
261
262
Workspaces, Configurations, and Branches . . . . . . . . . . . . . . . . . . . . .

How Does a Workspace Access the Repository? . . . . . . . . . . . .
Workspaces, Branches and Default Configurations . . . . . . . . . .
Example: Default Configurations and Branch-Work . . . . . . . . . .
Default Configurations and Hierarchical Workspaces . . . . . . . . .
263
264
264
265
268
Integrating ClearCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Integration Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to integrate SNiFF+ and ClearCase . . . . . . . . . . . . . . . . . .
VOBs and Views in SNiFF+. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating SNiFF+ Projects for ClearCase-Controlled Code . . . . .
Changing the config spec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Synchronizing SNiFF+ Projects with View Changes . . . . . . . . . .
Using clearmake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
269
270
270
271
271
271
272
273
273
Integrating SNiFF+ with CVS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tell SNiFF+ to use CVS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Import Code not yet under CVS Control . . . . . . . . . . . . . . . . . . .
Import Code From a CVS Repository . . . . . . . . . . . . . . . . . . . . .
Create Additional Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . .
Initial Check Out in New Workspace . . . . . . . . . . . . . . . . . . . . . .
CVS/SNiFF+ Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Synchronizing SNiFF+ Projects with Changes on Disk . . . . . . . .
Other Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
277
278
279
279
282
284
286
287
287
288
Integrating SNiFF+ with PVCS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Version and Compatibility information . . . . . . . . . . . . . . . . . . . . . 293

PVCS Version Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .293

The SNIFF+ PVCS Adaptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . .294
Setting up Projects with SNiFF+ and PVCS . . . . . . . . . . . . . . . . .295
PVCS and Adaptor Configuration Files . . . . . . . . . . . . . . . . . . . . .295
Integrating SNiFF+ with Visual SourceSafe . . . . . . . . . . . . . . . . . . . . . .299
Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .300
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .300
Setting up a SNiFF+ Project with Visual SourceSafe . . . . . . . . . .301
Checking In Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .302
Integration Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .303
Part VIII
Editor and Other Integrations
Emacs Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .307

Integration Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .308
How the Emacs Integration Works . . . . . . . . . . . . . . . . . . . . . . . .308
Integrating Emacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .309
Working with Emacs and SNiFF+ . . . . . . . . . . . . . . . . . . . . . . . . .311
Command Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313
SlickEdit Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .315
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .316
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .316
Working with Visual SlickEdit and SNiFF+ . . . . . . . . . . . . . . . . . .316
Vim Integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .319
Integration Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .320
How the Integration Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .320
Making the Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .323
Working with Vim and SNiFF+ . . . . . . . . . . . . . . . . . . . . . . . . . . .324
Command Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .325
Rational Rose Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .329
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .330
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .330
Navigation from SNiFF+ to Rational Rose . . . . . . . . . . . . . . . . . .332
Navigation from Rational Rose to SNiFF+ . . . . . . . . . . . . . . . . . .335
File Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .336
Technical Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .336
Contents
Part IX
SniffAPI
SniffAPI - Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Basic Idea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Overall Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Query Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Usage Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scope Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The ID Concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
339
340
340
340
341
342
345
347
SniffAPIGetting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What You Need . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Directory Structure of SniffAPI. . . . . . . . . . . . . . . . . . . . . . . .
Setting up JAR files for compilation of a SniffAPI client. . . . .
Compiling the Sample Program. . . . . . . . . . . . . . . . . . . . . . .
Running the Sample Program . . . . . . . . . . . . . . . . . . . . . . . .
...
...
...
...
...
...
353
354
354
354
356
356
...
...
...
...
...
361
362
362
363
367
Sniffaccess. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introducing Sniffaccess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Preparing the Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Invoking Sniffaccess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Connection Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Input and Output of Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sniffaccess Command Reference . . . . . . . . . . . . . . . . . . . . . . . .
Appendix: What is Python? . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
371
372
372
373
374
375
381
391
391
Configuring the C++ Parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
General Format of the Parser Configuration File . . . . . . . . . . . . .
Ignore-Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Replace Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Definition of Wordchars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
393
395
395
396
397
397
Part X
Advanced Reference
Custom Menus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Custom Menu Configuration File . . . . . . . . . . . . . . . . . .
Custom Menu Configuration File: EBNF Specification . . . . .

Parser Filter Patterns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .398

Context Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .401
General Parser Configuration Options . . . . . . . . . . . . . . . . . . . . .406
C++ Parser Specific Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . .406
Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .408
Cross-Reference Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .413
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .414
Extracting Symbol Information. . . . . . . . . . . . . . . . . . . . . . . . . . . .414
C/C++: Automatic Generation of Cross-Reference Information . .415
Workspaces and Cross-Referencing. . . . . . . . . . . . . . . . . . . . . . .416
Location and Repair of X-Ref Databases . . . . . . . . . . . . . . . . . . .419
Synchronizing Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .419
Part XI
Appendix
Regular Expressions in SNiFF+ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .423

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .424
Quick Reference - Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .424
Literals and Metacharacters . . . . . . . . . . . . . . . . . . . . . . . . . . . . .426
Character Classes or Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .432
Groups, Alternatives and Back References. . . . . . . . . . . . . . . . . .435
Glossary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .439
SNiFF+ System Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .440
Version Control Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .443
Build Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .447
Part I
Documentation Guidelines
This Manual
Conventions

1
This Manual
Overview
The SNiFF+ Documentation SetGuidelines page 4
Beginners Guides page 4
Users Guide and Reference page 5
GUI and Menu Command Reference page 5
Getting Started for Tornado Teams page 5
Installation Guide, Release Notes, SNiFF+ Papers page 5
Feedback and Useful Links page 6

1.1 The SNiFF+ Documentation SetGuidelines

This manual is part of the SNiFF+ documentation set, and this chapter
offers a few guidelines as to what you can expect to find where in the
documentation.
Most SNiFF+ documentation is available online, under the Help menu.
If you have installed the documentation package, print-formatted PDFs
are located in the docs subdirectory of your SNiFF+ installation.
1.1.1 Beginners Guides

Two Beginners Guides, one for C/C++ Projects, and the other for Java
Projects, should help to get you going.
Examples, tips, and hands-on how-to descriptions introduce you to many
aspects of using SNiFF+.
The Beginners Guides are divided into four major sections.
Browsing Tour
Create a Project to browse either your own source code, or sample code
provided with SNiFF+. Get to know the SNiFF+ browsing tools and navigation features.
SNiFF+ PRO: Build and Debug Tutorial

Use sample code in a hands-on tutorial for setting up, building, and
debugging targets.
CMVCConfiguration Management and Version Control

Create a version controlled Project and apply basic version control
commands.
Working in Teams
An outline of procedures for setting up a team work-organization.
This Manual
The SNiFF+ Documentation SetGuidelines
1.1.2 Users Guide and Reference
The Users Guide and Reference provides more in-depth information

than the Beginners Guides. Topics covered include:
Fundamental SNiFF+ concepts: Projects and Workspaces
Workspace and Project management
How-to guides to procedures
Technical descriptions of various subsystems (e.g. Build System)
Version Control and Configuration Management
Integrations of version control tools, editors, and other tools
Regular expression usage in SNiFF+
1.1.3 GUI and Menu Command Reference

This is a reference to functionality of graphical user interface elements
and menu commands. This is also accessed when you use the Context
Help (<F1>).
1.1.4 Getting Started for Tornado Teams

This tutorial introduces creating, building and debugging a downloadable
application module, as well as how to access various Tornado tools from
the SNiFF+ PRO IDE.
1.1.5 Installation Guide, Release Notes, SNiFF+ Papers

The Installation Guide takes you through installation and licensing on
Unix/Windows
Release Notes include important, late-breaking information on the current release.
SNiFF+ Papers provide additional information on topics not covered in
the standard documentation.

1.2 Feedback and Useful Links

Feedback
Your feedback is always very welcome.
Please send feedback to one of our support e-mail addresses.
Europe
support-ec@windriver.com
USA
support@windriver.com
Useful Links
A number of useful links (Knowledge Base, FAQs, Users Mailing List ...)
are available under:
http://www.windriver.com/sniff
2
Conventions
Overview
Terminology page 8
Menu References page 8
A Note on Unix/Windows page 8
Typography page 9

2.1 Terminology
The terminology described in this section is used throughout this guide
and in all SNiFF+ documentation.
SNIFF_DIR4
This refers to your SNiFF+ installation directory.
Symbol
Any programming language construct such as a class, method, etc.
2.2 Menu References
Choose MenuName > MenuCommand.

Read this as: "From the menu named MenuName, choose the menu
command named MenuCommand."
Choose Right-click > MenuCommand

Read this as: Choose a menu command from the context menu that
appears when you click the right mouse button.
2.3 A Note on Unix/Windows
We use forward slashes ( / ) in path specifications. If you are on Windows, read backslash ( \ ) instead.
The screenshots in this manual are all done on Windows NT. If you are
working on Unix, what you see on your screen may look slightly different.
Conventions
Typography
2.4 Typography
2
Capitalized Words
Names of tools, windows, dialogs and menus start

with capital letters.
Examples: Symbol List, Tools menu, File dialog.
Also SNiFF+ specific meanings of concepts are capitalized.
Examples: Project, Workspace.
Italics
Names of manuals, newly introduced terms, and emphasized words are in italics.
Examples: User's Guide , the Workspace concept, do
not do something.
Boldface and
Bold italics
Menu, field and button names are printed in boldface.

Place-holders for symbols, selections or other strings
in menus are in bold italics.
Example: Browse > ClassName ...
Monospace
Code examples and symbol, file and directory names,

as well as user entries are printed in monospace type.
Examples: .login, PATH , class VObject.
On the command line, enter abc.
<Keys>
Special keys are printed in monospace type with enclosing '< >'.
Examples: <CTRL>, <Return> , <Meta>.

10
Part II
Projects and Workspaces
What is a Project?
What is a Workspace?

12
3
What is a Project?
Overview
IntroductionProjects page 14
Working with Projects page 14
Some Advantages of Projects page 14
What Does a Project Know? page 16
13

3.1 IntroductionProjects
A SNiFF+ Project is the main structuring element for grouping files on
your file system that logically belong together. In other words, elements
that you want to handle (browse, build, or document) together can be
grouped (modularized) in Projects, without having to modify file-system
locations.
A software system will generally be structured as a hierarchical tree of
Projects (or trees of Projects), whereby the relative position of nodes in
the tree reflects logical (build-)dependency relationships. For example,
building a top-level Project target will generally depend on a prior build of
its (recursive) Subprojects.
3.1.1 Working with Projects

This chapter merely serves as an introduction to the SNiFF+ Project as a
concept. The where-and-how of Project creation, maintenance etc. is
described under Working with Projects page 79.
3.2 Some Advantages of Projects

File-system directories can be, and generally are, used for grouping files
that belong together in some way.
However, over time (legacy!) the code base grows, interfaces blur, and
directories are no longer the clearly delimited logical units they might
once have been.
But changing file system locations on any scale is generally expensive
due to potential problems with the build and version control systems
(depending on the system used).
This is where Projects come into the picture.
What a Project knows is persistently stored in a Project Description File
(PDF). The PDF is itself part of the Project and can therefore be conveniently version controlled together with the source files.
Files and Subprojects are quickly added to, or removed from, Projects
without any changes being made to file-system locations. The PDF(s)
can be checked in, and then used by all the members of a development
team via SNiFF+ Workspace mechanisms (see What is a Workspace?
page 17).
14
What is a Project?
Some Advantages of Projects
If you use SNiFF+ Build Support, the Project structure defines the traversal order of Projects during system Build; furthermore SNiFF+ can,
based on the parsed source files, also generate per-Project dependency
information. This means that once targets and the structural organization of the tree have been defined, the build system is practically selfmaintaining.
15

3.3 What Does a Project Know?

Among other things, a Project knows:
The files that belong to the Project.

These can include source code files, as well as any other files (e.g. documentation) you define. The PDF itself will also always be listed, as well
as the PDF(s) of its immediate Subprojects.
The File Types that the Project recognizes.

A SNiFF+ File Type is identified by a signature pattern, not only the filename extension. File Types are categorized and associated with
numerous, configurable properties that tell SNiFF+ what to do with files
of a given type (which parser, compiler, template, etc. to use).
Project-specific Build properties.

This includes data such as target type and name, etc.
16
The location of Project-related symbol, cross-reference, and Build Support information.
4
Overview
IntroductionWorkspaces and Projects page 18
What are Workspaces For? page 18
Storage page 18
Different Tasks page 18
Working in Teams and Version Control page 19
Keeping up-to-date page 19
Default Configurations and Branch Development page 19
Building page 20
Flexibility page 20
Sharing or Layering Workspaces page 20
What is a Workspace? page 21
TerminologySource Root, Project and Makefiles Location, Generated Files Location, and Repository page 21
The Source Root page 22
The Project and Makefiles Location page 23
The Generated Files Location page 23
Location of Root Directories page 24
Source Root Location page 24
Relative Project and Makefiles Location page 25
Exception: Generated Files (and Project and Makefiles) Locations Not

Relative page 25
17

4.1 IntroductionWorkspaces and Projects

The two fundamental SNiFF+ Concepts, Workspace and Project, interrelate. We therefore recommend that you first familiarize yourself with the
chapter What is a Project? page 13 before going on to look at Workspaces.
4.2 What are Workspaces For?

A Workspace is an environment used for writing, analyzing, version controlling, and building products from your source code. Over and above
this, it is used for parallel work on (sharing) the same code base.
Again, it is an environment, and not simply a file-system location. But,
before going on to look at what a Workspace is , take a look at what it is
for.
4.2.1 Storage
One function of a Workspace is storage. When Projects are first opened
in a Workspace, you can have SNiFF+ generate symbol, cross-reference, and dependency information.
This information is stored persistently in the Workspace, and only needs
to be incrementally (if at all) updated when next you open Projects in the
Workspace.
4.2.2 Different Tasks

If you, as an individual, are working on different, unrelated software systems, you may or may not use a different Workspace for each of these.
This is a question of personal preference; different Projects already modularize different systems.
The real power of Workspaces is that you can use multiple Workspaces
to work on one and the same software system, for example, to use for
experimental work, testing, and parallel work on different Configurations
of the system.
18
What are Workspaces For?
4.2.3 Working in Teams and Version Control

If you are a member of a development team, you, and every other member of the team, must be able to access a common code base, and yet
also be able to work in isolation, without interference.
This means that, while individuals might want to work on the same code
in different environments, each member of a development team must
have at least one personal Workspace.
To handle this, each Workspace knows two things. Firstly, where to check
files out from (a Repository, or your version control systems equivalent);
all related Workspaces will access the same Repository. Secondly, a
Workspace must know where to check out files to (a root directory,
known as the Workspaces Source Root); each Workspace has its own,
unique Source Root.
4.2.4 Keeping up-to-date

By regularly (for example overnight) updating (or Synchronizing , as it is
called in SNiFF+) Projects in a Workspace, you can be sure that all
source files, Projects, symbol, dependency and (optionally for C/C++
Projects) cross-reference information are up-to-date, no matter which
subset of Projects you open.
4.2.5 Default Configurations and Branch Development

You can set a default Configuration for a Workspace, or, if your version
control system supports Branches, a default Branch.
That is, for example, a part of your team works on forward-development
on the main application Branch, another team is adapting a library, and
yet another group is working on bugfixes for a released Configuration of
the software system.
Each of these groups can configure their Workspaces so that files are
automatically checked in/updated to the respective branches; check-outs
will also automatically try Branch revisions first.
When Projects are synchronized, this is automatically done with respect
to the Branch/Configuration that is set for the Workspace.
(See also Workspaces, Configurations, and Branches page 263.)
19

4.2.6 Building
A teams work may be distributed over different operating systems, and
the product may be targeted to run on multiple systems.
On the one hand, this may mean that you are working on a Windows
machine but need to build and debug on a remote Unix machine. On the
other, if you access your sources over a network file system, you can
improve Build performance by redirecting output to a directory on your
local machine.
Workspace defaults can be set for the target operating system, where
and how you build (for example, with debug information or optimized),
and you can switch between different options and target platforms within
one and the same Workspace.
(See also SNiFF+ PRO Build/Debug: How To page 137.)
4.2.7 Flexibility
Development teams are dynamic, they can grow and shrink again. As a
team grows, new Workspaces that are consistent with existing ones are
quickly created, and, conversely, simply removed when no longer
needed.
4.3 Sharing or Layering Workspaces

Workspaces can be shared. This is done by layering Workspaces in
trees.
The most common tree is probably one Workspace (first layer) which is
shared, or accessed , by a number of personal Workspaces (second
layer).
Layering Workspaces can have some advantages; however, there are
also a number of caveats. This is discussed under Workspace Organization page 29.
20
4.4 What is a Workspace?

Although the physical organization of a Workspace is more or less an
implementation detail that you need not worry too much about, it is useful
to at least have an idea of how it looks, which is what Figure 4-1 A WorkspacePhysical Organization (Simplified) page 22 is about.
A Workspace is a multi-bodied thing; an organized collection of subsystems. These subsystems are maintained below three root locations,
the Source Root, and the Project and Makefiles Location, and the Generated Files Location. Each Workspace has these root locations.
Furthermore, if you are working in a development team and/or version
control your Projects, a Workspace must know, at least indirectly, where
your version control system stores file revisions.
4.4.1 TerminologySource Root, Project and Makefiles Location, Generated Files

Location, and Repository
Each Workspace points to its own Source Root, its own Project and
Makefiles Location, and its own Generated Files Location, and may be
associated with a specific Repository.
The Source Root of a Workspace points to the root directory (somewhere) below which all sources of a software system should lie (or will lie
when they are checked out/opened for the first time).
The Project and Makefiles Location is used for storing Project Description
Files, Makefiles, and Build Support files. These can therefore kept in a
directory separate from the source files, but still be normally version controlled. Generally, a subdirectory below the Source Root is used.
The Generated Files Location of a Workspace is the root location for

SNiFF+-generated files (symbol tables, etc.) relating to the sources below
the Source Root .
(There are some exceptions to this rule, however, these will be pointed
out in the appropriate contexts.)
A Repository is a location used by your version control system to archive

file revisions.
21

Figure 4-1
A WorkspacePhysical Organization (Simplified)
Workspace
Pointer to Source Root location and other global information

Project and
Makefiles &
Generated Files
Tree of
source code
directories
Once sources are in Projects,
file system locations are no
longer relevant.
The copy of the original
directory structure is an
organizational artifact used
internally by SNiFF+.
Copy of
directory
structure
only
Workspace Info
Project Information
File System Directory
4.4.2 The Source Root

The only thing a Workspace knows about your source code files is the
location of a root directory.
All the source files that are, or can be, in a Workspace should be somewhere below this root directory, known as the Source Root.
Apart from this, a Workspace knows nothing about the source files themselves, or how they are organized.
Information about which files are, or can be, in a Workspace, and how
they are organized is maintained in SNiFF+ Projects.
The important thing about the Source Root is that each Workspace must
have its own, unique Source Root.
(See also Source Root Location page 24.)
22
4.4.3 The Project and Makefiles Location

The second root location that a Workspace knows is the Project and
Makefiles Location.
This is can be the same as the Source Root location, or, as is usually the
case (unless you use ClearCase ), the same as the Generated Files
Location.
If you use ClearCase for version controlling, this will normally be a subdirectory of the Source Root; however, the Generated Files Location will be
a separate location (see below).
4.4.4 The Generated Files Location

The third root location that a Workspace knows is the Generated Files
Location . Unless you are using ClearCase , this location is usually the
same as the Project and Makefiles Location (above). If you are using
ClearCase, performance can be improved by specifying this location outside the Source Root.
SNiFF+ generates and maintains all the information it needs below this
root directory. (See also Relative Project and Makefiles Location page
25).
Much of this information is specific to Projects. However, global information that applies to all Projects in (that use) the Workspace is also maintained here.
The data maintained under the Generated Files Location can be subdivided into the following sub-systems:
The Project System

This is discussed in more detail under What is a Project? page 13. A
system of Project Description Files (PDFs) describes, among other
things, which files can be opened in a Workspace, and how these files
are organized (this need not necessarily conform to the file-system organization). These files may, however, especially under ClearCase, also be
stored elsewhere.
Symbol and other information

This includes parser-generated data about symbols (classes, methods,
etc.), a database with cross-reference and (C/C++) dependency information, and indexes for string retrievals.
The Version Control System

The Workspace inherits this information from a Repository node and,
under some version control systems, a Default Configuration node.
These nodes know which version control system is used and where to
23

check files out from, for example, a Repository location for RCS, or the
view extended path name for ClearCase and which revisions to check
out/in by default. File revisions are checked out from the version control
system to the locations below the Source Root.
The Build System

Using the SNiFF+ Build System is optional (licensed as SNiFF+ PRO). If
you use the SNiFF+ Build System, global Build macros, rules, and
settings are generated and maintained per Workspace. Many of these
settings represent defaults that can be individually overridden at Project
and, if necessary, file level. These files may, however, especially under
ClearCase, also be stored elsewhere.
(See also SNiFF+ PRO Build System Concepts page 219.)
4.5 Location of Root Directories

In theory, the subsystems that make up a Workspace could be anywhere.
That is, their respective root locations could be specified by different,
unrelated absolute paths.
Although this is not generally recommended, it can be useful under certain circumstances.
4.5.1 Source Root Location

The Source Root location will always be different for each Workspace.
When you create a Project for existing sources, the Source Root should
be the root directory that holds all sources belonging to the software system you are importing to SNiFF+. (You would, of course, exclude
unwanted directories and file types from the Project.)
Once the Project exists (Projects are only created once), you create new
Workspaces that each point to a different Source Root location (the user
of the Workspace must have write permission to the new location).
Then, you check out the existing root Project to the new Workspace.
24
Location of Root Directories
4.5.2 Relative Project and Makefiles Location

To ensure consistency and portability, and to be able to properly build
and synchronize a teams work (also in multi-layered Workspaces), the
Project and Makefiles Location name and relative position (below the
Source Root) must be the same in all Workspaces.
In other words, it is best (highly recommended) if the Source Root location can be used as the single common point of reference from which
both the location of your sources and all the related SNiFF+ stuff can be
calculated.
For example, the SNiFF+ Project Creation Wizard always creates, by
default, the Project and Makefiles Location immediately below the
Source Root and gives it the name sniff_data (this name is a Preferences setting). When you create a new Workspace, the same default
location is offered. It is a good idea to follow, and stick to, this pattern.
Note that, unless you use ClearCase, the Generated Files Location is
normally the same directory as the Project and Makefiles LOcation.
Note also that, if you do not have write permission under the Source
Root, you may have to point to somewhere else. This will mean that
some restrictions apply; see below.
4.5.3 Exception: Generated Files (and Project and Makefiles) Locations Not Relative
It may not always be possible, or even necessary, to create a Generated

Files directory below the Source Root.
Assuming you do not have write permission below the Source Root of,
for example, a library. But you want to browse this code.
When you create the Project, point the Generated Files (as well as the
Project and Makefiles Location) to an absolute location anywhere on
your file system where you do have write permission.
This will allow you to browse, and even build the library (Build output is
redirected to the Generated Files Location).
However, you will not be able to version control the files (not an issue if
you do not have write permissions) or share the Workspace.
If multi-layered Workspaces are and will not be used (for example, under
ClearCase this is not supported), you can also have the Generated Files
Location outside the Source Root.
However, for normal team development work and version controlling, you
have to make sure that SNiFF+ Project Description Files and Makefiles
are properly version controlled. So you can store Project Description and
Makefiles in a subdirectory of the Source Root, and other generated files
that are entirely SNIFF+-maintained elsewhere. This is the recom-
25

mended procedure for ClearCase users. By keeping the other SNiFF+

generated files (e.g. symbol information) outside the Source Root, and
hence outside the VOB, performance is naturally better.
26
Part III
Workspace Management
Workspace Organization
Stand-Alone Workspaces
Workspaces and User Autonomy
Team Workspaces from Scratch
New Team Members (Flat Workspace System)
New Team Members (Hierarchical Workspace System)
Managing Workspaces

28
5
Overview
Introduction page 30
Workspace Organizational Systems page 30
Hierarchical vs. Flat Workspace System page 31
Do Not Use Layered Workspaces if... page 31
Disk Space page 32
Performance page 32
Other Issues page 32
Reorganizing Workspaces page 33
The Workspaces Administrator page 33
29

5.1 Introduction
We assume that you are familiar with the SNiFF+ concepts, Project and
Workspace. If not, please refer to Projects and Workspaces page 11.
5.2 Workspace Organizational Systems

By Workspace Organization we mean the way an individual Workspace relates to other Workspaces.
In this sense, there are three different organizational systems, all of
which can exist in parallel.
No relationship (non-version-controlled)
This, the trivial case, is where an individual Workspace has absolutely
nothing to do with anythingneither with any other Workspace, nor with
a version control Repository. It is completely isolated. Suitable for
browsing and code comprehension, or for small-scale experimental work
that is not shared or version controlled.
Creating this kind of Environment is described under Stand-Alone Workspaces page 35.
Indirect (flat) relationship

Here, Workspaces are indirectly related in that they share a common
Repository (the place your version control tool stores file-revision information).
This is the simplest, most generic, all-purpose organizational form and
can be recommended in most cases.
(See also Hierarchical vs. Flat Workspace System page 31.)
Hierarchical relationship
Workspaces are directly dependent on other Workspaces. More complicated, cannot be used in all cases (e.g. ClearCase, Java code...), does
not generally make sense on Windows. The main advantage is diskspace savings (only on Unix, where symbolic links are supported).
(See also Hierarchical vs. Flat Workspace System page 31.)
30
Hierarchical vs. Flat Workspace System
Figure 5-1
Different Workspace Organizational Systems
Stand-alone (no Repository)

Flat (sharing across a Repository)
Hierarchically layered
5.3 Hierarchical vs. Flat Workspace System
The flat system can be recommended in most cases.
If disk-space is an issue and you are on Unix, the hierarchical system

might be an option.
5.3.1 Do Not Use Layered Workspaces if...

Layered Workspaces do not work if
You are working on Java Projects on Unix. The Java compiler cannot follow symbolic links.
You are using ClearCase.
31

5.3.2 Disk Space
On Unix, where symbolic links are supported, hierarchically layered

Workspaces mean disk-space savings.
In the lower-level Workspaces, symbolic links to source files, symbol,
cross-reference and dependency information, as well as objects, in the
higher-level Workspace, are created.
On Windows, where symbolic links are not supported, hierarchically layered Workspaces require more disk-space.
In the lower-level Workspaces, local copies of source files, symbol,
cross-reference and dependency information, as well as objects in the
higher-level Workspace are created. This means one extra unnecessary (but see also below) set of data per higher-level Environment.
5.3.3 Performance
In hierarchically layered systems (Unix and Windows), performance
improvements can be expected under the following circumstances (on
Windows, however, less so than on Unix because of the copying-time
overhead):
When Projects are first opened in (newly created) lower-level Workspaces. This is because the initial parsing of symbol, cross-reference and
other information is not necessary.
The first Build in a new, lower-level Workspace will be faster, because

existing, up-to-date objects in higher Workspaces can be used (copied on
WIndows).
If, for example, a globally included header has been modified, a full rebuild is necessary. With layered Workspaces, this need be done only
once. In flat Workspace systems, a re-build has to be done for each
Workspace.
If something goes wrong at a higher level, all lower-level, dependent,

Workspaces are adversely affected.
Updates of Workspaces have to be done in two consecutive steps

(assuming a two-layer tree), first the higher-level, then the lower level.
Again, if something goes wrong in the first step, itll take a while before
everyone down below is up-to-date.
5.3.4 Other Issues
32
Reorganizing Workspaces
5.4 Reorganizing Workspaces

As long as your Workspaces are consistent in terms of internal structure
(see Location of Root Directories page 24), you can reorganize them
at any time.
That is, you can, for example, start version controlling a non-version-controlled Workspace, or move from a hierarchical to flat system, and vice
versa.
These, and other administrative issues are described under Managing
Workspaces page 71.
5.5 The Workspaces Administrator

The responsibility for overall Workspace co-ordination and maintenance
(e.g. update cycles) is usually delegated to one member of the team; this
person is referred to as the Workspace Administrator.
33

34
6
Overview
Assumptions page 36
What is a Stand-Alone Workspace? page 36
Stand-Alone Workspace Plus Project page 36
Workspace or Repository Selected? page 37
Create Project and Workspace page 37
Stand-Alone Workspace without Project page 38
Workspace or Repository Selected? page 37
Create the Workspace page 38
Special Case: Stand-Alone Analysis Environment page 39
35

6.1 Assumptions
Workspace. If not, please refer to Projects and Workspaces page 11,
or at least make sure you know what is meant by the terms Source Root,
Proect and Makefiles Loction, and Generated Files Location (see TerminologySource Root, Project and Makefiles Location, Generated Files
Location, and Repository page 21 for a summary description).
6.2 What is a Stand-Alone Workspace?

A Stand-Alone Workspace does not access a version control system.
If you do not need to do any serious development work on, for example, a
third-party library, and only want to browse and analyze code, this kind of
stand-alone Workspace is perfectly adequate. This applies particularly
also to read-only code, where version-controlling is not an issue. An interesting thing about this kind of Workspace is that it can be simultaneously
used by multiple users (see Special Case: Stand-Alone Analysis Environment page 39).
Or maybe you want to create a Workspace for code that does not yet
exist. For example, an Environment for experimental work that may, or
may not, grow into something bigger. If the experiment does grow into
something worth version controlling, you can easily change at any time.
6.3 Stand-Alone Workspace Plus Project

The easiest way to create a stand-alone Workspace is to use the Project
Creation Wizard to create both a Project and a Workspace.
The Wizard is equally suited for use both with existing code, and to create Environments where no code exists as yet.
36
Stand-Alone Workspace Plus Project
6.3.1 Workspace or Repository Selected?

Before creating a non-version controlled Workspace, make sure that neither a Repository, nor a Workspace is selected in the Workspace Manager.
If a Workspace is selected, the Wizard will try to create a Project in that
Environment.
If a Repository is selected, the Wizard will create a Workspace that
accesses the selected Repository.
To open the Workspace Manager, choose

Tools > Workspace Manager
In the Workspace Manager, click into the Workspaces Tree (left pane),
and press the <ESC> key.
Nothing should now be selected.
6.3.2 Create Project and Workspace
Now choose
Project > New > With Wizard...
In the Project Creation Wizard

(More extensive notes on using the Wizard are provided in the Beginners Guides.)
Specify that you do not want to use a version control tool for the Project.
Specify the root directory that holds (or will hold) your sources.
Use the Exclude... button to select which directories to include/exclude
in/from the Project.
Note that deselecting a directory also excludes all subdirectories.
Although the subdirectories are still checkmarked, Projects will not be
created for them (a missing link).
The Wizard scans the specified directory tree for known File Types.
If you are creating a Workspace/Project for an empty directory, obviously no File Types will be matched. So, simply click Next.
If there are source files below the root directory you specified, accept
or modify the File Types as necessary.
Enter the remaining information required by the Wizard.

When the Wizard is finished, the new Project is opened in the Project
Browser, and the new Workspace is shown in the Workspace Manager.
37

6.4 Stand-Alone Workspace without Project

You can also create an empty Workspace, and then later create Projects
that use the Environment.
To do so, open the Workspace Manager by choosing
6.4.1 Workspace or Repository Selected?
To create a stand-alone (non-version-controlled) Workspace, first make

sure that nothing is selected. If a Repository or Workspace is highlighted,
click into the left pane of the Tool and press the <ESC> key.
6.4.2 Create the Workspace
Choose Workspace > New > Workspace...
In the box that appears, enter a name for the Workspace, and the location
of the Source Root directory. SNiFF+ offers a default Project and Makefiles Location, and a default Generated Files Location (specified in the
Preferences).
It is best to accept, and always use, these defaults. If you do not have
write permission below the Source Root, you can specify locations
outside the Source Root.
When you click Add, the new Workspace is shown in the Workspace
Manager.
In the Workspace Manager, you can save the new Workspace constellation by choosing
Workspace > Save All
38
Special Case: Stand-Alone Analysis Environment
6.5 Special Case: Stand-Alone Analysis Environment

You may have code that is not subject to modification, but that you want
to browse and analyze, for example, in a re-engineering scenario.
In a case like this, you can specify that Projects in a given Workspace
are, by default, opened with read-only access to symbol information
databases.
This way, any number of users can open the same Projects in the same
Workspace and have (read) access to all the information in a common
database.
You can specify this default behavior in the Workspace Properties, GeneralAdvanced node.
39

40
7
Workspaces and User
Autonomy
Overview
Workspace Configuration Data page 42
Autonomous Workspace Configuration page 42
Setting the Working Environments Configuration Directory page 43
Site-Level Workspace Configuration page 44
SNiFF+/SNiFF+ PRO 4.0.2

7.1 Workspace Configuration Data

Workspace data are stored in a directory known as the Workspace Configuration Directory. The location of this directory is specified in the Preferences.
This can be maintained at site-level, or at user-level.
However, because of its restrictiveness, any attempt at site-level maintenance will probably, sooner or later, lead to parallelization.
7.2 Autonomous Workspace Configuration

Each team member has his/her own, user-level, Workspace Configuration Directory.
This allows team members to create, modify, or remove Workspaces in
their own sand-boxes. This reduces administration overhead, and gives
developers freedom to move.
It also means that team members see only the Workspaces/ Repositories they actually use. Which is all anyone needs or wants to see.
The team never-the-less needs to be coordinated. However, coordination in this context means no more than telling team members
where common Repositories are located
in flat Workspace systems, the name of a newly created team Project
or, in hierarchically layered Workspace systems, the location of the

shared Workspace(s).
The only other drawback is that each user has to re-create Repository
and, if used, shared Workspace nodes (which is why you have to tell
them the things mentioned above). However, this is also a comparatively
minor, one-time task.
42
Workspaces and User Autonomy

Autonomous Workspace Configuration
7.2.1 Setting the Working Environments Configuration Directory

To use your own, user-level Workspace Configuration Directory you have
to set the location in the Preferences.
The Preferences can be opened either from the Project Browser, or the
Workspace Manager.
In the Project Browser, choose

Tools > Preferences
Or, in the Workspace Manager, choose

7
Working Environment > Preferences
In the Preferences
In the Preferences, select the User Level tab.

If this is the only tab you see, this is perfectly normal. It means that you
do not have write permissions to the site-level Preferences file (only
experienced administrators should be allowed to write to this file).
In the Workspaces node (under Tools), enter (navigate to) a directory

where you have write permissions.
Notice (Figure 7-1) that the double-head icon next to the Workspace
Config Directory field changes to a single-head. This indicates that
you are no longer using the site-level location, but your own, personal
directory.
Figure 7-1
Personalizing Workspace Data

7.3 Site-Level Workspace Configuration

If you use a common, site-level Workspace Configuration Directory for all
team-members, only one person (the Workspace Administrator) should
have write permissions to this directory.
Giving everyone write permissions to this directory would defeat the purpose of centralized administration.
This means, however, that team members do not have the freedom to
create Workspaces for themselves when they need them; they have to
ask the Administrator to do this for them.
A further drawback is that, in the Workspace Manager, everyone always
sees all Workspaces used by all team members, which is needless clutter.
42
8
Team Workspaces from
Scratch
Overview
PreparationSetting Up Team Projects page 46
ClearCase Preparations page 47
Repository-Based Tools (RCS...) page 47
Write Permission page 48
The First Team Member page 48
Workspace Selected? page 49
The Project Creation Wizard page 49
In the Wizards Opening Page page 49
Where is the Repository? page 50
Select Project Type page 50
Create Project page 51
The Build-Target Setup Wizard page 52
Post-Setup Project Tuning [Optional] page 52
First Check-In page 53
Behind the Scenes page 53
Organization and Coordination page 54
Decision Time page 54
45

8.1 Introduction
Regardless of how you want to organize your Workspaces (Flat or Hierarchical, see Workspace Organization page 29), there will always be a
first Workspace.
Once things work for one person, its a small step to let Workspaces take
care of the rest of the team-setup work for you.
Theres no need to do everything at once. You can set up a team organization without, for example, initially worrying about any of the more complicated build-related stuff. Your in-house Build expert can set up the
Build system at any time (in his/her Workspace), and the benefits can
then be transparently passed on, via Workspace mechanisms, to the rest
of the team.
8.2 PreparationSetting Up Team Projects

For team development, you have to use a version control tool.
If you do not as yet use a version control tool, RCS is bundled with
SNiFF+, so you can always use that.
Depending on which tool you use, there are one or two things to make
sure of.
46

PreparationSetting Up Team Projects
8.2.1 ClearCase Preparations

If you use ClearCase:
Make sure that all the files for which you want to create the team Project
are under ClearCase control. In other words, the files should already be
elements of a VOB.
Make sure that you have a ClearCase view that accesses the VOB.
When you create a Project/Workspace for use with ClearCase you can
store Project Description FIles and Makefiles under a subdirectory
(default name sniff_data).
In this case, Project Description Files and Makefiles will still be under
ClearCase control, but not intermingled with the source code files.
To improve performance, use an absolute path that points to a location
outside the Source Root (and therefore outside ClearCase control) for
the Generated Files directory.
Please refer also to Integrating ClearCase page 269.
8.2.2 Repository-Based Tools (RCS...)

If you use a Repository-based version control tool (for example RCS), the
Project Creation Wizard lets you import code directly from an existing
Repository, or you can import the source code from a normal directory
and use a new Repository.
47

8.2.3 Write Permission

You need write-permission in the Source Root directory so that SNiFF+
can store relevant information there.
In order to properly share Project and, optionally, Build information, this
must be stored below the Workspace Source Root. Other (for example,
symbol) information can be stored elsewhere; this is however only really
relevant for version control tools that, like ClearCase, also control directories.
If the Source Root is writable, the Project Creation Wizard suggests a
sub-directory with the default name sniff_data (this default name
can be set in the Preferences). All necessary information is stored below
sniff_data; your source code remains otherwise untouched.
We recommend that you accept the Wizards suggestion; when you create new Workspaces, the same default will be suggested.
8.3 The First Team Member

If you think of every team as starting off with a first member, then the first
step is clearly to set up a first Workspace.
Furthermore, an empty Workspace isnt much use, you will want to create a Project for the team to work on.
The Project Creation Wizard does both these things at once.
The first team member creates the Project that will be used by the
entire team.
So, to set up the first team members Workspace, complete with Repository, ready-for-work source code, and Project information, use the Project
Creation Wizard.
48

The Project Creation Wizard
8.3.1 Workspace Selected?

Before using the Wizard, make sure no Workspace is selected in the
Workspace Manager.
If the Workspace Manager is not open, consider this step done.

If the Workspace Manager is open, either close it, or click into the Workspaces Tree (left pane), and press the <ESC> key.
Nothing should now be selected.
Now choose Project > New > With Wizard...
8.4 The Project Creation Wizard
In the opening page of the Wizard, make sure you specify that
you want to version control the Project you are about to set up.
the correct version control tool is selected.
8.4.1 In the Wizards Opening Page

The first question you are asked is:
Do you want to use a version control tool for this project?
This is exactly what we want to do.
Click: Yes, and make sure the correct version control tool is selected.
Here we will use RCS as an example for repository-based systems, and
also point out issues to be aware of if you are using ClearCase.
Click Next.
49

8.4.2 Where is the Repository?
This page does not appear for all version control tools.
The page prompting for a Repository Location only appears for some
version control tools, for example, RCS. The Repository Location can
point to any directory where you have write permission.
RCS will, for example, create a directory named RCS under the directory
you point to, and store all file revisions in this subdirectory.
If you are already using a Repository, obviously this is the directory you
will point to. Note that, in this case, you also have the option of checking
out the files directly from the Repository to the Source Root location you
specify on the following Wizard page.
8.4.3 Select Project Type
Select the Project type that most closely approximates the software system you will be working on. This generally relates to the standard File
Types that will be recognized by the Project (whether such files already
exist or not), as well as, in some cases, to the standard default build-targets that will be created (this applies specifically to VxWorks/Tornado
Project types).
Location: This will be the first Workspaces Source Root . Be sure to point
to a root directory that holds (or will hold) all source code somewhere
below it.
If unrelated directories exist below this root directory, use the Exclude...
button to clear the checkboxes next to these directories. No Projects will
be created for directories that are not checkmarked; nor will Projects be
created for subdirectories of uncheckmarked directories (missing link)!
If your source code is still in a Repository (this depends also on the
version control tool used, see Where is the Repository? page 50), the
Location here refers to the target directory where files will be checked
out to during the Project creation process.
50
A default Name for the Project is taken from the directory name; you
might want to change this.

The Project Creation Wizard
The Scan for existing files check-box:
Selecting the check-box means that SNiFF+ will scan directories and
check for file extensions that do not normally belong to the selected
Project type.
Clearing the checkbox means that SNiFF+ will not scan directories for
additional File Types over and above the ones it would normally
expect to belong to the type of Project you selected above. This can
save time for large directory trees.
8.4.4 Create Project

8
The Wizard offers default storage locations for Project and Makefiles as
well as for other Generated Files.
Accepting these defaults is generally recommended, especially also to
ensure consistency in team development situations.
Splitting these two types files is relevant mainly for version control tools
like ClearCase (that is, tools that also version control directories). Project
Description Files and build-related files are kept within (subdirectories of)
version controlled directories (that is, for example, within a ClearCase
view). Symbol tables and databases, on the other hand, need not be version controlled because they are maintained entirely by SNiFF+. Storing
these generated files outside version controlled directories will therefore
improve performance on such systems. In this case point the Generated
Files location to an absolute location outside the ClearCase view.
Select an appropriate default Platform.

For more information about Platforms, please see Platforms page
223.
Select an appropriate Build option.
Use SNiFF+ Build Support

This option implies that you want to use full SNiFF+ Build Support,
that is, the SNiFF+ Makefiles and (or at least) all the files included by
them. Selecting this option will automatically open the Build-Target
Setup Wizard once the Project has been created; this Wizard is discussed in the Beginners Guides.
I want to manage builds myself

This option implies you have your own, custom Makefiles and Makesupport. In this case you can still enter build-target names so that
these can be built and debugged from the SNiFF+ Build menu.
Selecting this option will automatically open the Build-Target Setup
Wizard once the Project has been created; this Wizard is discussed in
the Beginners Guides.
51

No Build Support
This option is for (sub-) Projects that you only want to browse, for
example, third party library code.
After the sources have been parsed and the necessary information
generated, the Project is opened in the Project Browser.
8.5 The Build-Target Setup Wizard

If you selected one of the Build options (above), the Build-Target Setup
Wizard is immediately started. You can use this Wizard to set various
standard build-targets. (The Wizard is introduced in the Beginners
Guides; please see there for more detailed information.)
Basically, the Wizard hides many of the build-settings that you do not
normally need or want to see, making it easy to quickly set standard
executable or library build-targets. To see and make use of all the more
tweakable settings, you would use Project Properties; see SNiFF+ PRO
Build/Debug: How To page 137 in this context.
8.6 Post-Setup Project Tuning [Optional]

Because not everything can, or often even should, be generically set by
the Wizard(s), you may want/have to fine-tune your Projects once they
have been created.
For example, as mentioned above, you can only set standard targets in
the course of Project creation. More complicated build-related, Projectspecific settings can be done later. Or, you may want to reorganize
Project structure and/or content. Remember, once the Project exists you
are no longer tied to file-system constraints. Furthermore, you may at
any time want to add or remove files or Subprojects. For information
about this and other day-to-day maintenance tasks, please refer to Working with Projects page 91.
However, as mentioned earlier, you can do the Build setup and other tuning at any time, and then share modifications.
52

First Check-In
8.7 First Check-In

The next step is to check all files in to the Repository (or for ClearCase
users, add them to ClearCase Source Control).
To check files in, you use the Project Browsers File List.
To display the File List, click the Files tab at the bottom-left of the Project
Browser (the main MDI window).
In the File List
Make sure that all Projects in the File Lists Project Tree are checkmarked.
Click into the File List and choose Edit > Select All,
then Right-click > Check In.
In the box that appears, enter a Change-set name.
(ClearCase users choose File > Add to Source Control.)

Its a good habit to get into right from the start.
Change-set labels are useful for recognizing and grouping files modified
for a particular purpose. (Even individual files should be checked in with
a Change-set label, that says who did what and why.)
Once the check-in process is complete, you will notice that the files in the
File List are no longer shown in bold typeface; this indicates that they are
no longer writable in the current Workspace.
8.8 Behind the Scenes

When you create a Project, the Wizard automatically creates a first
Workspace and a Repository behind the scenes.
To see this, open the Workspace Manager, by choosing
In the Workspace Manager

At the left of the Workspace Manager, you see all existing Workspaces.
Workspaces are represented by icons that look like desks.
At least one of these desks (the one that you have just created with the
Wizard) should be attached to a Repository node.
53

Depending on the version control system you use, the Workspaces may
be attached to the Repository node indirectly. That is, they are attached
to a Configuration node, which is in turn attached to the Repository (for
more information, please see Workspaces, Configurations, and Branches
page 263).
Note to ClearCase Users
If you are using ClearCase, the Repository node has no ClearCase-specific functionality. However, you (and SNiFF+) use this
node as a point of reference for adding new Workspaces.
8.9 Organization and Coordination

You have now done everything that is needed for the first user, or, if you
want to use a Hierarchical Workspace system, for the top-level, shared
Workspace.
Each team member who is to work on the Project you have just created,
needs to have their own Workspace to work in.
If a site-level Workspace Configuration Directory is to be used by everyone (see Site-Level Workspace Configuration page 44), you , the
Workspace Administrator, will have to create their Workspaces for them
(and then make sure they have write permission).
However, if each team member has their own, user-level Workspace
Configuration Directory (as is recommended, see Autonomous Workspace Configuration page 42), they will not be able to see the Repository and the Workspace the Wizard created.
In this case, your next step is to tell the team members one or two things,
so that they can go ahead and create their Workspace(s). What they
need to know depends on how Workspaces are to be organized.
8.9.1 Decision Time
Do you want to work in a Flat Workspace system, or in a Hierarchical

one?
You can either simply follow our recommendation and use the Flat
system, or, for more information, see Hierarchical vs. Flat Workspace
System page 31.
54

Organization and Coordination
Whichever system (Flat or Hierarchical) you use, you will have to tell all
team members where on the file system the Repository (or the ClearCase VOB) is located.
Note that you will only have to tell people this (and the other things
mentioned below) if they each use their own, user-level Workspace
Configuration Directory.
If a common, site-level location is used, you neednt tell them anything,
you will have to do everything for them.
If you want to use the standard, Flat Workspace system
Tell team members the name of the Project the Wizard has just created for you.
Continue with the chapter New Team Members (Flat Workspace System) page 57.
If you want to use a hierarchically layered Workspace system:
Tell team members the file-system location of the root directory holding your source code (the one you entered in the Wizard). This is
known as the Workspace Source Root, and will also be accessed by
all other Workspace.
Continue as described under New Team Members (Hierarchical

Workspace System) page 65.
55

56
9
New Team Members (Flat
Workspace System)
Overview
What Do You See? page 58
Create a Repository Node? page 59
Create a New Workspace page 60
First Check-Out page 61
Open the Project page 62
More Workspaces for Yourself page 63
More Team Members page 63

9.1 Introduction
If you want to set up a Hierarchical Workspace system, youre in the
wrong chapter; go to New Team Members (Hierarchical Workspace System) page 65.
One person (The First Team Member page 48) imports code into
SNiFF+ by creating a Project, a Workspace, and a Repository. (We
assume that this has been done. If not, youre also in the wrong chapter;
go to Team Workspaces from Scratch page 45.)
In a Flat Workspace system, each related Workspace must access the
same Repository. (Related here means the Workspaces used by developers working on the same software system.)
9.2 What Do You See?

Open the Workspace Manager by choosing
What do you see?
If you are not The First Team Member page 48, and if you use your
own, user-level Workspace Configuration Directory (see Autonomous
Workspace Configuration page 42), you will not see the Repository or
the Workspace that has already been created.
In this case, continue with Create a Repository Node? page 59.
If you are The First Team Member page 48, or you are using a common, site-level Workspace Configuration Directory (see Site-Level Workspace Configuration page 44), you will see the Repository and the
Workspace that has already been created.
In this case, continue with Create a New Workspace page 60.
56
New Team Members (Flat Working Environment System)

Create a Repository Node
9.3 Create a Repository Node?

If you are not The First Team Member page 48, and you have your
own, user-level Workspace Configuration Directory:
Your first step is to ask the The First Team Member page 48 where the
team Repository (ClearCase VOB) is located.
Then, open the Workspace Manager by choosing

First, create a Repository node by choosing

Workspace > New > Repository...
In the dialog that appears:
Enter a Name for the Repository
Make sure the correct Version Control Tool is selected.
Depending on the selected version control tool, enter the Location of

the team Repository (The First Team Member page 48 will tell you
where the Repository is located).
Close the dialog by clicking Add.

A new Repository node appears in the Workspace Manager. This node
now knows the location of the team Repository. If you use ClearCase or
other tool that does not require a Repository location, this node simply
knows the type of version control tool to use for all Workspaces that are
later attached to it.
57

9.4 Create a New Workspace

Before continuing, please check ClearCase Preparations page
47.
In the Workspace Manager, click on the Repository node, and choose

Right-click > New > Workspace...
In the dialog that appears, enter a Name.

To fill the Source Root field, click the Browse... button.
Depending on the version control tool you use, procedure differs slightly
here.
RCS and similar tools: navigate to a new, empty directory.
ClearCase: navigate to the (directory in) the view of the VOB you will
work in.
Remember, this directory will be the Source Root of a new Workspace.

(You will later check out the Project files to this Workspace.)
In the Project and Makefiles Files Location field, accept the default.
We assume that The First Team Member page 48 also accepted the
default.
To synchronize team Workspaces correctly, the name and relative location (default: immediately below the Source Root), must be the same in
each related Workspace.
Accept the default for Generated Files Location.

There is not usually any reason change this; it is displayed mainly for
informative reasons.
Click Add.
In the Workspace Manager you will see a new Workspace suspended
from the Repository.
56

Now is a good time to save the new Workspace structure.

Choose Workspace > Save All
If you made the necessary preparations described under ClearCase
Preparations page 47, you should now see the Projects in the
Workspace.
If not, on the new Workspace,
Right-click > Update Project Tree
You are ready to open the Project and start working in SNiFF+.
To open the Project in the new Workspace, double-click on

it.
The remainder of this chapter applies only to non-ClearCase users.
9.5 First Check-Out

The new Workspace you have just created knows which Repository it
has to access, but it does not yet know which Projects can be opened in
it.
So, the next step is to check out the (root) Project created by the The
First Team Member page 48, who will also tell you the name of the
Project he/she created.
57

To check out the Project, highlight the newly created Workspace, and
Right-click > Scan Repository.
The box that appears shows a list of all Project Description Files in the
Repository.
Click into the list and type the first few letters of the Project name. When
the list positions to the correct file name, click the Check Out button.
Note
This is not possible for all version control systems (e.g. CVS).
If you are using a version control system where this is not
supported, copy the root Projects Project Description File
(.proj extension) from the first Workspace to the new
Workspace.
Whether you copy it to the Source Root directory, or the
Generated Files directory will depend on how the Workspace you are copying from is set up (checkbox below Generated Files Location field in the Workspace Properties).
After you have copied the root Project Description File, proceed as described under Open the Project page 62
In the box that appears, click the No Lock button.

All you are doing is initializing a new Workspace, so there is no need to
lock the Project Description File. Also, it might already be checked out
(locked) by someone else.
You have now checked out only the root Project of what is normally a
whole tree of Projects. To recreate the entire Project structure, you have
to open this root Project as described below.
9.6 Open the Project

To open the Project you have just checked out, and thereby have SNiFF+
recreate the entire Project structure:
In the Workspace Manager, you should see the Project on the right.
If not, on the Workspace,
56
Double-click on the Project.

SNiFF+ recreates the Project structure, and checks out all the files to the
new Workspace. When this is done, the Project is opened in the new
Workspace, and you are ready to start work.
9.7 More Workspaces for Yourself
If you have your own, user-level Workspace Configuration Directory, and

you want to create additional Workspaces for yourself, proceed as
described under Create a New Workspace page 60 and the following
sections.
If you use a common, site-level Workspace Configuration Directory, and
you want additional Workspaces, ask whoever has write permission to
the site-level Workspace Configuration Directory to create them for you
as described under Create a New Workspace page 60 and the following sections.
9.8 More Team Members
If team-members have their own, user-level Workspaces Configuration

Directory, each new team member will need a Workspace.
To create one, each person proceeds as described under Create a
Repository Node? page 59 and the following sections.
If team-members use a common, site-level Workspace Configuration

Directory, whoever has write permission to the site-level Workspace Configuration Directory has to create a Workspace for each new team member.
The procedure is then as described under Create a New Workspace
page 60 and the following sections.
57

56
10
New Team Members
(Hierarchical Workspace
System)
Overview
What Do You See? page 66
Create a Repository Node page 67
Create a Node for the Shared Workspace page 67
Create a Dependent Workspace page 68
More Workspaces for Yourself page 69
More Team Members page 70
65

10.1 Introduction
If you want to set up a Flat Workspace system, youre in the wrong chapter; go to New Team Members (Flat Workspace System) page 57.
One person (The First Team Member page 48) imports code into
SNiFF+ by creating a Project, a Workspace, and a Repository. (We
assume that this has been done. If not, youre also in the wrong chapter;
go to Team Workspaces from Scratch page 45.)
The first Workspace created by The First Team Member page 48 is
the one that will be shared. That is, all other related Workspaces will
access (depend on), and inherit from, this shared Workspace. (Related
here means the Workspaces used by developers working on the same
software system.)
The shared Environment will not generally be used for day-to-day development. It will be a reference Environment containing the most stable,
canonical code.
Each developer needs (at least) one dependent Environment that
accesses the shared Environment.
10.2 What Do You See?

Open the Workspace Manager by choosing
What do you see?
If you are not The First Team Member page 48, and if you use your
own, user-level Workspace Configuration Directory (see Autonomous
Workspace Configuration page 42), you will not see the Repository or
the Workspace that has already been created.
In this case, continue with Create a Repository Node page 67.
If you are The First Team Member page 48, or you are using a common, site-level Workspace Configuration Directory (see Site-Level Workspace Configuration page 44), you will see the Repository and the
Workspace that has already been created.
In this case, continue with Create a Dependent Workspace page 68.
66

10.3 Create a Repository Node

If you are not The First Team Member page 48, and you have your
own, user-level Workspace Configuration Directory:
Your first step is to ask the The First Team Member page 48 where the
team Repository (ClearCase VOB) is located.
Then, open the Workspace Manager by choosing

First, create a Repository node by choosing

Workspace > New > Repository...
In the dialog that appears:

10
Enter a Name for the Repository
Make sure the correct Version Control Tool is selected.
Depending on the selected version control tool, enter the Location of

the team Repository (The First Team Member page 48 will tell you
where the Repository is located).
Close the dialog by clicking Add.

A new Repository node appears in the Workspace Manager. This node
now knows the location of the team Repository. If you use ClearCase or
other tool that does not require a Repository location, this node simply
knows the type of version control tool to use for all Workspaces that are
later attached to it.
10.4 Create a Node for the Shared Workspace

Again, if you are not The First Team Member page 48, and you have
your own, user-level Workspace Configuration Directory:
You need to know the Source Root location of the Workspace created by
The First Team Member page 48.
Remember, this will be the Workspace that you share.
In the Workspace Manager, click on the Repository node, and choose

67


To fill the Source Root field, click the Browse... button and navigate to
the Source Root location of the Workspace created by The First Team
Member page 48.
In the Project and Makefiles Files Location field, accept the default.
We assume that The First Team Member page 48 also accepted the
default.
To synchronize team Workspaces correctly, the name and relative location (default: immediately below the Source Root), must be the same in
each related Workspace.
Accept the default for Generated Files Location.

There is not usually any reason change this; it is displayed mainly for
informative reasons.
Click Add.
from the Repository.
You should also see the Project tree on the right.
If not, on the new Workspace node,
This node represents the Workspace that you will be sharing. Your next
step, therefore, is to a create Workspace for yourself. That is, the one
where you will actually work.
10.5 Create a Dependent Workspace
Click on the node of the shared Workspace created above, and


To fill the Source Root field, click the Browse... button and navigate to a
new, empty directory (create one in the navigation dialog if necessary).
Remember, this directory will be the Source Root of a new Workspace.
In the Project and Makefiles Files Location field the Generated Files
Location fields, accept the default.
(We assume that The First Team Member page 48 also accepted the
default.)
68

More Workspaces for Yourself
Click Add.
from the node of the Workspace that you want to share.
You should also see the Project tree on the right.
If not, on the new Workspace,
Now is a good time to save the new Workspace structure.

Choose Workspace > Save All
10.6 More Workspaces for Yourself
10
If you have your own, user-level Workspace Configuration Directory, and

you want to create additional Workspaces for yourself, proceed as
described under Create a Dependent Workspace page 68.
If you use a common, site-level Workspace Configuration Directory, and

you want additional Workspaces ask whoever has write permission to the
site-level Workspace Configuration Directory to create them for you as
described under Create a Dependent Workspace page 68.
69

10.7 More Team Members
If team-members have their own, user-level Workspace Configuration

Directory, each new team member will need a Workspace to work in.
To create one, each person proceeds as described under Create a
Repository Node page 67 and the following sections.
If team-members use a common, site-level Workspace Configuration

Directory. The person (Workspace Administrator) who has write permission to the site-level Workspace Configuration Directory has to create a
Workspace for each new team member.
The procedure is then as described under Create a Dependent Workspace page 68.
70
11
Managing Workspaces
Overview
Reorganizing Workspaces page 72
Workspace Properties page 73
Names and Locations page 73
Parsing Properties page 73
Modifying Workspace Build Properties page 74
Build Tool Settings page 74
Remote Build Host Settings page 74
Version-Controlling Build Properties page 75
The Build Properties File page 75
Creating a New File Type for the Build Properties File page 76
Creating a Project for the Build Properties File page 78
71

11.1 Introduction
As long as your Workspaces are consistent in terms of internal structure
(see Location of Root Directories page 24), you can reorganize them
at any time.
That is, you can, for example, move from a hierarchically layered system
to a flat system, or start version controlling a previously non-version-controlled Environment quite easily.
11.2 Reorganizing Workspaces

You use the Workspace Manager to reorganize Workspaces.
First, close any Projects that may be open in Workspaces you want to
move/modify.


The easiest way to move Workspaces is by drag-and-drop.
(Remember to close any Projects that are open in the Workspace, otherwise this wont work).
For example, lets assume you created a non-version controlled Workspace for experimental work. The experiment grows and looks promising.
You now want to start version controlling the Projects in the Environment.
Simply drag-and-drop it onto a Repository (create one if need be).
72
Managing Workspaces
Workspace Properties
11.3 Workspace Properties

You access a Workspaces Properties by highlighting it in the Workspace
Manager and choosing
Right-click > Properties
Some general notes on Workspaces follow; more information is available
online (use <F1> in the Workspace Properties dialog box).
11.3.1 Names and Locations

Settings in the Workspace Properties dialog, General node, can only be
modified if no Projects are open that use the Workspace.
A Name for the Environment (displayed in the Workspace Manager and

the title bar of the Project Browser).
The Owner of a Workspace is, by default, the login name of the person
who created the Workspace.
Source Root, Project and Makefiles and Generated Files locations.

These should not generally be modified. The only time you might want to
modify these locations is if you have physically moved the directories on
the file system.
Advanced
Locations for building on remote machines, and for redirecting build output to absolute locations are set here.
Specifying an absolute path for redirecting build-output can be useful for
improving build-performance. If your sources (and, more specifically, your
Generated Files location) are mounted over a network file system, for
example, build-time performance will naturally improve if the output is
written to a local disk.
(See also Remote Build and Debug page 197.)
11.3.2 Parsing Properties

The settings here influence what happens (how long it takes) when you
save files.
Whenever you save a file, symbol information is parsed and updated.
Optionally, cross-reference information can be updated, and preprocessing can be done to expand macros for more accurate information.
73
11

11.4 Modifying Workspace Build Properties

For a more detailed discussion of the SNiFF+ Build System, please refer
to SNiFF+ PRO Build System Concepts page 219.
11.4.1 Build Tool Settings

The Build System (SNiFF+ PRO) is Workspace centered. That is, all
Projects that can be opened in a given Workspace will take their general
Build settings from the Workspace Properties.
If settings are overridden at Project or file level, only differences are
stored by the Project. So, be careful about modifications at Workspace
level.
Ideally, the settings should match those required by Projects that use the
Workspace as closely as possible. Overrides should be the exception.
This saves you work, ensures consistency, and reduces the maintenance
overhead inherent in having many Projects with many settings, as
opposed to a single, central system.
11.4.2 Remote Build Host Settings

If you want to build on a remote machine, the host machine must be able
to find your sources, which is why you have to set the path to your
Source Root location as the remote machine you want to build on sees it
(see Names and Locations page 73).
While the Source Root location is unique to each Workspace, there is no
reason to keep host machine data Workspace specific. That is, host
machines you define for one Workspace are actually global, and will be
recognized by all Workspaces.
74
Managing Workspaces
Version-Controlling Build Properties
11.5 Version-Controlling Build Properties

Workspace Build Properties can (should) be version controlled. Apart
from the usual reasons for version controlling files, you will probably also
want to share Build Properties. That is, if everything is properly set up,
and works well for the Projects that use the Environment, you can simply
check the Build Properties file in, and then synchronize other Workspaces with the latest revision in the Repository.
The Workspace Manager provides the necessary, rudimentary, version
control functionality under the
Workspaces > Build Properties menu.
However, for more comfortable handling (looking at revision history, comments, etc.) you might want to create a SNiFF+ Project for the Workspaces Build Properties, or simply add the Build Properties file to an
existing Project.
11
11.5.1 The Build Properties File

Workspace Build Properties are maintained in a structured text file normally stored in a directory under the Workspaces Project and Makefiles
Location (or, if Project Description FIles are stored together with the
source files under the source directories).
The file is located in
<Source_Root>/<Proj_Makefiles_Dir>/.sniffwe.Vn.nn/
(whereby the final digits after the V are version-specific).
You can verify the Project and Makefiles Location in the Workspace
Properties. By default, this would be
<Source_Root>/sniff_data/
Note that, even if you did not accept the default name, or have changed
the default name in the Preferences, the Project and Makefiles Location
must lie (somewhere) below the Source Root for correct version controlling.
The file name is:
BuildAttributes.sniff.Vn.nn
(whereby the final digits after the V are version-specific).
75

11.5.2 Creating a New File Type for the Build Properties File
Whether you create a special Project for the Build Properties file, or simply add the file to an existing Project, you will probably have to create a
new File Type for it.
New File Types are best created in the Preferences. You can open the
Preferences either from the Workspace Manager, or the main Project
Browser.
The following outlines the minimum necessary steps for creating the new
File Type. (See Creating New File Types page 106 for more information.)
76
To open the Preferences from the Workspace Manager, choose

Workspace > Preferences
Or, to open the Preferences from the Project Browser, choose

Tools > Preferences
Managing Workspaces
Version-Controlling Build Properties
Figure 11-1
The PreferencesFile Types Node
11
In the tree on the left, select the File Types node.
In the File Types node, click the New button.
In the box that appears, enter a name for the new File Type, for example,
sniff_stuff
From the Category drop-down, select Other.
In the Language drop-down, make sure None is selected.

(You do not want SNiFF+ to try to parse the file.)
You do not need a special subcategory. Unless you want to, for example,
associate a special icon with this File Type, you can leave the Subcategory field blank.
In the Signatures field, enter
*.sniff.*
All files with the above filename pattern (not a regular expression!) will
now be recognized as belonging to the sniff_stuff File Type (or
whatever you named the new File Type, above).
In the Build Tool drop-down, make sure None is selected.

(You do not want SNiFF+ to try to compile the file.)
Close the Preferences
77

11.5.3 Creating a Project for the Build Properties File

If you do not want to create a Project for the Build Properties file, you can
add it to an existing Project as described under Adding/Removing Files
page 97.
How to create a Project for the Build Properties is described below.
In the Workspace Manager, highlight the Workspace for which you want
to create the Build Properties Project.
Choose Project > New > With Wizard...
In the Wizard
In the first Wizard page, click Browse... and navigate down to the Project
and Makefiles Location, normally (if you accepted, and have not since
modified, the defaults offered by SNiFF+ when the Workspace was first
created): you would navigate down to
<Source_Root>sniff_data/.sniffwe.Vn.nn:
If you proceeded as described under Creating a New File Type for the
Build Properties File page 76, the Wizard will recognize the Build
Properties file. Click Next.
In the final Wizard page give the Project a reasonable name that you will
later recognize, and click Finish.
The Build Properties can now be version controlled like any other
normal file.
78
Part IV
Project Creation
Working with File Types
Working with Fortran
Documenting Projects
Synchronizing Projects

80
12
Project Creation
Overview
You Only Create a Project Once page 82
Wizard or Template? page 83
More Information about Templates and the Wizard page 83
Project and Workspace Creation in One page 83
Project Creation in Existing Workspaces page 84
Source Code Location page 84
Open the Workspace Manager page 85
Creating Projects with the Wizard page 85
Creating Projects from a Template page 87
Post-Setup Project Tuning page 87
Project Templates page 88
Creating Custom Templates page 88
Absolute Projects page 88
Whats wrong with Absolute Projects? page 88
How and Why do Absolute Projects Happen? page 89
81

12.1 Introduction
Workspace.
If not, please refer to Projects and Workspaces page 11, or at least
make sure you know what is meant by the terms Source Root and Generated Files Location (see TerminologySource Root, Project and Makefiles Location, Generated Files Location, and Repository page 21).
12.2 You Only Create a Project Once

Creating a Project really means importing your code into SNiFF+.
Once you have imported a software system, it makes no sense to reimport it.
After a Project has been created, it can be shared via Workspaces. That
is, you create the Project, and other members of your development team
open the root Project (Description File) in their respective Workspaces.
The same applies if you yourself want to have different views to the same
software system, for example, to run tests, or refer to a specific Configuration of the system. In such cases, create new Workspaces for yourself,
and check out the existing root Project (Description File).
82
Project Creation
Wizard or Template?
12.3 Wizard or Template?

SNiFF+ provides two means of creating Projects; the Project Creation
Wizard, or using a Project Template.
Both the Wizard and the Template method can set many default properties for Projects.
However, not everything is or can/should be generically set. In this
context, please refer to Post-Setup Project Tuning page 87.
Templates can be customized to match your needs very closely.
You can use the Wizard to create a Project and a new Workspace all at
once.
Using a Template, you first create (must have) a Workspace, and then
only can you create the Project.
If your code is already under version-control in a repository-based system

(e.g. RCS), the Wizard lets you create Projects directly from the Repository.
The Wizard actually takes some of its default information from a Project
Template named default. So, be sure not to (re-)move this Template!
12.3.1 More Information about Templates and the Wizard

The Beginners Guides include notes on using the Project Creation Wizard, so please see there for more information.
For more information about Templates, please refer to Project Templates
page 88.
12.4 Project and Workspace Creation in One

To create a Project and a new Workspace all at once, you can use the
Wizard. This kind of from-scratch Project creation with the Wizard is
described in the Beginners Guides (please see there for more information).
83
12

One point to watch out for before starting the WIzard:
If you have used the Workspace Manager in the current SNiFF+ session,
make sure no Workspace is highlighted. You can deselect highlighted
Workspaces with the <ESC> key, or you can close the Workspace
Manager.
If a Workspace is highlighted, the Wizard will attempt to create a Project
using this Workspace, which is what the following section is all about.
12.5 Project Creation in Existing Workspaces

Here we assume you already have a Workspace and want to create a
Project in it.
Both the Project Creation Wizard and a Project Template let you create
Projects within existing Workspaces.
Using a Template, you must first create (have) a Workspace, and then
create the Project.
12.5.1 Source Code Location

Regardless of which mode you use to create a Project in an existing
Workspace, make sure the Workspace Source Root points to the location of your source code root directory (or higher).
If you need a Project for sources in read-only locations, see What is a
Stand-Alone Workspace? page 36.
84
Project Creation
Project Creation in Existing Workspaces
12.5.2 Open the Workspace Manager

To create a Project in an existing Workspace, you need the Workspace
Manager.

In the Workspace Manager, highlight the Workspace where you want to

create the Project.
12.5.3 Creating Projects with the Wizard
From the Workspace Manager menu, choose

Project > New > With Wizard...
The Wizard appears and offers a set of standard Project types.
Select the Project type that most closely approximates the Project you
intend creating.
The selected Workspaces Source Root Location is already entered

on the first page. Ideally, this is the correct root directory that holds all
your sources.
If not, then your sources should at least be somewhere below this
directory. In other words, you should not have to use the Browse...
button, to navigate up. You may need to use the Exclude... button to
exclude any unwanted directories under the Source Root location.
If you do have to navigate up, be aware that an Absolute Project will
be created (see Absolute Projects page 88).
A default Name for the Project is taken from the directory name; you
might want to change this.
If you do not select the Scan for existing files option the Project knows
a number of standard file types based on the Project Type you selected
above. If you select the option, the Wizard scans the directory tree and
presents a list of File Types (not) recognized by SNiFF+.
Note that if, for example, you create a new File Type here, this applies for
the current Project only. To make the File Type available also for future
Projects you would make the necessary changes in the SNiFF+ Preferences (see Creating New File Types page 106).
Finally, the Wizard prompts for a build-support option.
85
12

Use SNiFF+ Build Support

This option implies that you want to use full SNiFF+ Build Support,
that is, the SNiFF+ Makefiles and (or at least) all the files included by
them. Selecting this option will automatically open the Build-Target
Setup Wizard once the Project has been created; this Wizard is discussed in the Beginners Guides.
I want to manage builds myself

This option implies you have your own, custom Makefiles and Makesupport. In this case you can still enter build-target names so that
these can be built and debugged from the SNiFF+ Build menu.
Selecting this option will automatically open the Build-Target Setup
Wizard once the Project has been created; this Wizard is discussed in
the Beginners Guides.
No Build Support
This option is for (sub-) projects athat you only want to browse, for
example, third party library code.
86
Project Creation
Post-Setup Project Tuning
12.5.4 Creating Projects from a Template
From the Workspace Manager menu, choose

Project > New > With Template...
In the dialog that appears, select a Template from the List.

A number of Project Templates are supplied with SNiFF+. You can,
however, create your own. For more information, see Project Templates
page 88.
In the Source Directory field, the selected Workspaces Source Root

location is already entered. Ideally, this is the correct root directory that
holds all your sources.
If not, then your sources should at least be somewhere below this directory. In other words, if you use the Browse... button, you should not have
to navigate up. You may need to use the Exclude... button to exclude any
unwanted directories under the Source Root location.
If you do have to navigate up, be aware that an Absolute Project will be
created (see Absolute Projects page 88).
12.6 Post-Setup Project Tuning

Because not everything can, or often even should, be generically set
using a template or a Wizard, you may want/have to fine-tune your
Projects once they have been created.
For example, you can only set targets after the Project has been created.
In this context, please refer to SNiFF+ PRO Build/Debug: How To
page 137.)
Or, you may want to reorganize Project structure and/or content.
Remember, once the Project exists you are no longer tied to file-system
constraints. Furthermore, you may at any time, not just immediately after
Project Creation, want to add or remove files or Subprojects. For information about this and other day-to-day maintenance tasks, please refer to
Working with Projects page 91.
87
12

12.7 Project Templates

To open the Template Properties dialog, choose
Project > Templates...
A number of pre-configured Project Templates are supplied with SNiFF+.
By default, these Templates are read-only, and it is a good idea to keep
them that way. However, you can easily create your own, custom Templates.
12.7.1 Creating Custom Templates

To create a custom Template, modify an existing one and then save it
under a new name.
Most of the available Template options correspond to properties for existing Projects. You are therefore referred to the online GUI and Menu Reference, Project Properties chapter, for more information about individual
properties.
12.8 Absolute Projects

If you set up a Project for sources that lie outside (above) the Source
Root of a selected Workspace, SNiFF+ will create an Absolute Project.
An Absolute Project uses absolute paths to find source code and Project
Description files, whereas Projects for locations below a Workspaces
Source Root use relative paths.
12.8.1 Whats wrong with Absolute Projects?

Because absolute paths are used
Projects cannot be shared.

Teams can not work in parallel on the Project sources.
88
You cannot move these Projects around on the file system.
Project Creation
Absolute Projects
12.8.2 How and Why do Absolute Projects Happen?

The factors described under Whats wrong with Absolute Projects?
page 88 may not be an issue, for example, for browsing stable (thirdparty) libraries. Although parallel development work is not feasible, the
Project can nevertheless be used for browsing.
If a Workspace is selected (highlighted) in the Workspace Manager, and
you create a Project for sources outside of the Source Root, the Project
will be absolute.
That is, Projects locate source files using absolute paths. However, symbol, cross-reference, and other data are stored under the selected Workspaces Generated Files Location.
Implicit Workspace Selection

Scenario: In the Project Manager, you choose one of the options under
Project > SubProject > Add New Subproject
and create a (Sub-)Project for directories outside the scope (Workspace)
of the Project highlighted in the Project Manager.
In this situation, the highlighted Projects Workspace is implicitly
selected, and an absolute Project will be created for the Subproject.
As mentioned above, this will not be a problem if you only want to browse
and follow references into a library. (A classic case would be creating and
adding the JDK sources as a Subproject to a Java Project.)
Another way to go about this is described under Special Case: StandAlone Analysis Environment page 39.
89
12

90
13
Overview
Opening Projects page 92
Recent Projects page 92
Opening Projects from a Workspace page 92
Open-Project Options page 93
With/without Symbol Information page 93
Use Cache, or Re-Read All Data page 94
Write/Read-only Database-Access page 94
Accessing Open-Project Options page 95
Changing the Default Opening Mode page 95
Managing Projects page 96
Using the Project Manager page 96
Modifying Project Structure and Content page 97
Moving Projects and Files Around page 97
Adding/Removing Files page 97
Adding/Removing Subprojects page 98
Deleting Root Projects page 98
Using the Project Managers Other Files Tab page 99
Potentially Obsolete Files page 99
Potential Project Members page 99
Modifying Project Properties page 100
The Project Properties Dialog page 100
Where do Projects get their Properties? page 100
91

13.1 Opening Projects

You probably do not always need to open a whole tree of Projects (an
entire software system) at the same time. You can open individual Subtrees and open multiple Subprojects (subtrees), each in a different
Project Browser.
Furthermore, you can open Projects in a different ways. However, the
settings for how a Project is opened is not something you generally need
worry about. Most of the time, you do not even see these options; for normal day-to-day work, the defaults will apply. (Opening-mode options are
described under Open-Project Options page 93.)
13.1.1 Recent Projects

If you re-open a recently used Project, it is opened the same way it was
last opened. That is, using the Workspace indicated in the list, and with
the same settings for symbol information, cache usage, and database
access (see Open-Project Options page 93 for more information).
To re-open a recently used Project:
In the Welcome dialog, choose from a list of recent Projects. The list
shows recently opened projects in the form
Project Name - Workspace Name
In the Project Browser, choose

Project > Recent > ProjectName - WorkspaceName
13.1.2 Opening Projects from a Workspace

To open a (Sub-)Project in a particular Workspace you need the Workspace Manager.

Highlight the Workspace you want to use

Projects that can be opened from the highlighted Environment are
displayed on the right. If you do not see any Projects, choose
92
To open a Project, double-click on it.

Open-Project Options
To open a Project without symbol information, choose

Right-click > Open Project Without Symbols
(See Open-Project Options page 93 for more information.)
13.2 Open-Project Options

Generally, the default options for opening Projects will apply. However,
under certain circumstances you may want to open Projects using different settings.
Note that these settings are also used if you later re-open the Project
from the list of recent Projects.
The available options are
With/without symbol information
Use cached Project data, or re-read all data
Write/Read-only access to cross-reference and dependency database

(Where you see/set these options is described under Accessing OpenProject Options page 95.)
13.2.1 With/without Symbol Information

Default: With symbol information.
You may want/to to open Projects without Symbol information under the
following circumstances.
Administration only
If you have very large Projects, and you need to open them for purely
administrative reasons, e.g. structural changes, you can save time by
opening them without symbol information.
Building
Note that if you want to build Java Projects, you must open them with
symbol information. This is because the SNiFF+ Java Build Support uses
symbol information.
To build C/C++ and other Projects, you can open them without symbol
information.
93
13

Locked database
This is only really applicable to Projects in hierarchically layered Workspaces, or in situations as described under Special Case: Stand-Alone
Analysis Environment page 39.
If a higher level (shared) Workspace has an exclusive lock on the crossreference and dependency database (for example, during an update),
you can still open Projects in lower-level (or even the same) Environments without symbol information. (For more detailed information, see XRef Database Access Control page 416.)
13.2.2 Use Cache, or Re-Read All Data

Default: Use cache.
When Projects are closed, all necessary information for re-opening them
is cached in a single file to speed up Project opening. If caching is
selected, only this file is read. If not, all the original Project Description
Files (PDFs) are read, and all source files are checked.
Caution: The cached information can be incorrect if
Changes are made to Projects and files between SNiFF+ sessions, that
is, outside of SNiFF+,
The preceding SNiFF+ session was terminated unexpectedly.
13.2.3 Write/Read-only Database-Access

Default: Write access to database.
Read-only access is only really applicable to Projects in hierarchically
layered Workspaces, or in situations as described under Special Case:
Stand-Alone Analysis Environment page 39.
To open a Project in higher-level (shared) Workspace without blocking
database access for lower-level Workspaces, you can open it with readonly database-access.
Once the first Project has been opened with read-only database access,
this determines the access mode for all Projects in the current Workspace and the current SNiFF+ session.
(For more detailed information, see X-Ref Database Access Control
page 416.)
94

Open-Project Options
13.2.4 Accessing Open-Project Options

The option to open Projects without symbols is directly available in the
Workspace Manager and Project Manager Right-click context menu.
All options are directly available in the Open Project dialog box, default
modes can be set per Workspace in the Workspace Properties.
Note that the Project > Open... menu command will only open the dialog
if no Project is highlighted, neither in the Workspace Manager, nor in the
Project Manager (highlighted Projects can be deselected using the
<ESC> key).
13.2.5 Changing the Default Opening Mode

Normally, you would want to open Workspaces with full access to all
information.
However, if you use a Workspace as described under Special Case:
Stand-Alone Analysis Environment page 39, you want multiple users
to be able to see the same Projects in the same Workspace.
In such a case, you can specify that Projects in this Workspace are
opened with read-only access to databases by default.
You can also speed up opening of stable Projects by using cached
Project information (see Use Cache, or Re-Read All Data page 94).
To do so:
Choose Tools > Workspace Manager
Select the Workspace where you want to change the default openingmode and Right-click > Properties....
In the Workspace PropertiesGeneralAdvanced node, checkmark the
Open Database Read-Only and/or the
Use Project Cache option.
95
13

13.3 Managing Projects

The Project Manger is the primary tool for Project administration. You use
the Project Manager
To modify Project structure (tree organization) and content (adding/

removing files and Subprojects).
For administrative tasks to do with the relationship between the Project

system and the file system.
File system tasks like creating/deleting/renaming files.

Caution: Although SNiFF+ allows you to also save Projects under new
names, be very careful about using this feature. The current Project
structure is updated to reflect a renamed Project, but other Projects that
are not open will not know about the new Project name and will therefore
continue to include the original Project name. If its purely a naming question (perhaps the Project does not adequately reflect its content and
function) rather change the Projects display name in the Project Properties.
13.3.1 Using the Project Manager

First, open the Project you want to modify. Then, choose
Project > Manage
The Project Manager opens. You will notice that a number of new
Project menu entries are now enabled.
In the Project Manager
96
Checkmark Projects to display their files, or to see non-Project files in

Project-related file system directories (see Using the Project Managers
Other Files Tab page 99).
Highlight a Project you want to modify.
Double-click on a Project to see its properties.
Use the Files tab to see the files in checkmarked Projects.
Use the Other Files tab to see files that are not in checkmarked Projects,
but that are located in Project-related directories.

Modifying Project Structure and Content
13.4 Modifying Project Structure and Content

With SNiFF+ Projects, you are no longer tied to the file system.
You can therefore modify Project structure and content by moving
Projects and files around in the Project tree.
13.4.1 Moving Projects and Files Around

If you change the Project structure by moving Projects around the tree,
remember:
If you use SNiFF+ Build Support, Projects are built in the order they
appear (from bottom to top at each level) in the tree.
For Java Projects, the Project structure must conform to the package
structure.
Drag-and-Drop
The easiest way to modify Project structure and content is by drag-anddrop.
Drag-and-drop a Project to move it to around the tree.
Drag-and-drop a file onto a Project to move it to from one Project to

another.
<CTRL>drag-and-drop to move a copy of a Project or file.
13.4.2 Adding/Removing Files

In the Project Manager:
To remove a file from a Project, highlight the file and

Right-click > Remove from Project
To add a (new) file to a Project, highlight the Project, and use the
Right-click > File > Add commands.
If the file is not of a type that the Project knows, SNiFF+ checks the Preferences.
If SNiFF+ finds a defined File Type in the Preferences that matches the
signature, it is added to the Project, and so is the file.
If not, SNiFF+ will not add the file. In this case you would first have to
define a File Type, either in the Project Properties dialog, or (recommended) in the Preferences. Please refer to Creating New File Types
page 106 for more information.
97
13

Alternatively, files can also be added as described under Using the

Project Managers Other Files Tab page 99
13.4.3 Adding/Removing Subprojects

In the Project Manager:
To remove a Subproject, highlight it and choose

Right-click > Subproject > Remove Subproject <Subproject>
Under ClearCase and CVS version control systems, you are asked
whether you want to also permantly remove the files from the view (disk).
Under other version control systems, and in non version controlled
Projects, removing a Subproject means only that its superproject no
longer includes a reference to it; the Project as such and the source files
still exist. How to delete a root Project is described under Deleting Root
Projects page 98.
To add a (new) Subproject, highlight the Project you want to add it to and
use the Right-click > Subproject > Add commands.
If you add new Subprojects, that is, create and add in one step, please
be aware of the consequences if the new Projects sources lie outside
the currently open Projects Workspace Source Root (discussed under
Absolute Projects page 88).
13.4.4 Deleting Root Projects

Deleting a Project means that SNiFF+ Project data are deleted, not the
actual source files.
To delete a Workspace Root Project, open the Workspace Manager
(make sure the Project is closed), highlight the Root Project in the Wokspace Managers Project Tree and choose
Project > Delete
98

Using the Project Managers Other Files Tab
13.5 Using the Project Managers Other Files Tab

You can use the Project Managers Other Files tab for administrative
tasks to do with the relationship between the Project system and the file
system (in this context, please refer also to Synchronizing Projects with
the File System page 126, for information on using the Project Synchromization Wizard).
Basically, the Other Files tab provides a file system explorer, visualized
as a flat list. However, exploration is limited to directories that contain
files belonging to checkmarked Projects. If you recall that the files
belonging to each individual Project can be spread around any number of
directories, this is perhaps not as trivial as it might at first seem.
When you click the Update button on the Project Managers Other Files
tab, all directories that contain files belonging to the checkmarked
Projects are scanned (optionally subdirectories of such directories can
also be included).
After scanning these directories, a snapshot of all files that do not belong
to checkmarked Projects is displayed in the Other Files tab (the files that
do belong to Projects are already displayed in the Files tab).
Note that the list is snapshot, and may therefore be invalidated as soon
as any changes are made to Project content or structure.
13.5.1 Potentially Obsolete Files

Files displayed after a scan could potentially be obsolete, and you might
want to (re-)move them (Right-click > Remove from Project or Rightclick > Rename). However, only files in checkmarked Projects in the currently open Project tree can be recognized as belonging to a Project; files
belonging to any other (unopened or uncheckmarked) Projects will also
be displayed in the Other Files snapshot.
13.5.2 Potential Project Members

Files displayed after a scan might be in the same directories as Projectmember files for a reason. That is, maybe these files actually ought to be
in Projects, and are just sitting there waiting to be added to Projects.
For cases like this, SNiFF+ suggests a default Project to add such files
to. The default suggestion is a Project which already has member files in
in the same directory as the non-member file.
Files can also by added to Projects by drag-and-drop and the appropriate
(right-click) menu commands.
99
13

13.6 Modifying Project Properties

You use the Project Properties to set various properties for existing
Projects.
To open the Project Properties, choose

Project > Properties...
This opens the dialog box, and at the same time the Project Manager.
The Project Properties dialog is the graphical user interface to the
Project Description File (PDF). If this file is not writable (checked out), a
writable local copy is automatically created. If the file has already been
checked out and modified by someone else, you will need to merge the
differences.
If the Project Manager is already open, simply double-click on a Project to

open the Properties dialog.
13.6.1 The Project Properties Dialog

The Project Properties dialog has a tree at the left where properties are
grouped by nodes. At the right, you see a Project tree.
The properties you see in any node apply to the highlighted Project in the
tree on the right. However, you can set some properties for multiple
Projects. Where this is the case, a drop-list is provided allowing you to
sect whether a setting is to be applied only to the highlighted Project (the
one whose properties you see), or to Projects checkmarked in the tree at
the right. Any changes you make will only take effect when you click the
Apply button.
13.6.2 Where do Projects get their Properties?

For details about individual settings in the Project Properties dialog
please refer to the online GUI and Menu Reference.
Here, just a some general information to do with inheritance of properties
and defaults.
Default Project properties are initially determined by internal settings
(Wizard) or Project Templates, as well as Workspace and Preferences
information.
100

Modifying Project Properties
In the Project Properties Dialog
General Node
These are mostly per-Project settings defined during Project creation.
Build-related Nodes
Please refer to
SNiFF+ PRO Build/Debug: How To page 137 and
SNiFF+ PRO Build System Concepts page 219 for more detailed
information.
Build Options: Build-target names and the Build Tool used to build the
target naturally have to set on a per-Project basis.
Build Tool Settings: Workspace settings are used here by default. If you
need to modify them at Project level, only the differences are stored by
the Project. (The icon to the left of each field indicates which level is
used.)
Java Build Options: These are per-Project settings. In most cases,
these will be the same for all (checkmarked) Projects. As long as the
sourcepath begins somewhere below the Source Root location, the
difference can be generated during Project creation.
File Types Node

Wizard-created Projects take these settings from the Preferences.
Individual settings are references to whole fields of properties defined in
the Preferences. This means that changing any of the elements behind
the reference (that is, at Preferences-level) will immediately affect all
open Projects.
Parser Node
Preferences/Template determine defaults.
101
13

102
14
Overview
What are File Types? page 104
Managing File Types page 104
PreferencesFile Types page 105
Creating New File Types page 106
What are Derived File Types? page 107
Derived File Types as Intermediate Products page 108
File TypesDerived Settings page 109
103

14.1 What are File Types?

File Types tell SNiFF+ what to do with a file. A File Type is, therefore, a
collection of properties that will be consistently applied to all files that
SNiFF+ recognizes as belonging to a defined Type.
SNiFF+ identifies File Types by file Signature. The file Signature is a
defined text pattern (or patterns) anywhere in the file name (not just the
extension).
You can only include files of a known File Type in SNiFF+ Projects. The
reason for this is quite simple: If SNiFF+ cannot correlate a file to a
known Type, it does not know what (not) to do with it.
Properties assigned to a File Type include things like
Which tool (if any) is used to compile the files.
Which template, if any, to use when creating new files.
Programming language, if any, and therefore which parser to use, applicable syntax and keyword highlighting, and other language-specific
details.
The icon used to represent files in the graphical user interface.
14.2 Managing File Types

It may sometimes be convenient to create File Types on-the-fly, for example during Project creation with the Wizard. However, this is a short-term
convenience and not generally recommended.
Although you can create/modify a File Type at Project level, it is best to
define File Types in the Preferences.
(At Preferences level a kind of File Type class is defined, this can then
be instantiated in Projects).
104
A File Type created/modified at Project level (in the Project Properties

dialog, or in the Project Creation Wizard) is recognized only by the particular Project(s), whereas all existing and future Projects can use a File
Type form the Preferences.
The Preferences allow more fine-grained customization. The Project only

knows keys to groups of Properties; the individual properties of these
groups can only be defined in the Preferences.

PreferencesFile Types
Opening the Preferences
To open the Preferences, choose

Tools > Preferences...
In the tree at the left, select the File Types node.
14.3 PreferencesFile Types

Note that the File Types node of the Preferences is the only one you
would have access to at Project level (in the Project Properties dialog).
The subnodes you see here (Categories and Languages) are available
only in the Preferences.
Figure 14-1
The PreferencesFile Types Node
14
105

14.4 Creating New File Types
In the File Types node, either select a File Type that looks like it comes
close to the Type you want to create and click Copy, or click New.
In the box that appears, enter a name for the new File Type.
From the Category drop-down, select the entry that seems most appropriate. If in doubt select Other.
These Categories are predefined and you cannot create any new ones.
The Categories are used only for grouping (filtering) Subcategories in the
Categories node.
The Subcategory drop-down lets you select one of the Subcategories

defined in the Categories node. Each Subcategory has a number of
associated properties that you can set. To see what these properties are,
take a look at the Categories node. If none of the existing Subcategories
are appropriate, you can create a new one in the Categories node.
The Language drop-down lets you select a named group of programming-language-related properties as defined in the Languages node.
Since these properties relate to which parser is used, keyword highlighting, and syntax details, it will generally not make much sense to
create new languages (such property groups for all languages supported
by SNiFF+ are already provided).
The Signatures field lets you enter file-naming patterns (not necessarily
only file name extensions) that SNiFF+ will recognize as belonging to a
particular Type. If you enter multiple patterns, use a colon (:) as separator. Use an asterisk (*) as wild card.
If the file is to be compiled or otherwise processed by SNiFF+, select a

Build Tool from the drop-down; if not, select None.
Note that each compilable File Type can be associated with only one
Build Tool. For multi-step processing you would have to assign a File
Type for each intermediate product (see also below).
106

What are Derived File Types?
14.5 What are Derived File Types?

First, take a look at the relationship between Derived Files, Derived File
Types and Normal File Types in SNiFF+.
In general, a Derived File is one that is generated (derived) from an input

file by some Build Tool. Such files only need a specific File Type if they
are further modifiable, either by the user (editing), or by another Build
Tool. That is, a Derived File can, but need not, be an intermediate product
that requires further processing.
An existing object or class file, although derived from a source file, is not
generally subject to further modification. Any further handling (archiving,
linking) is therefore delegated entirely to the Build System, and these files
do not require any specific File Type.
Derived File Types differ from Normal File Types in that the former is
dynamically recognized. That is, if a Project knows about a Derived Type,
files of this type are automatically displayed and/or further processed if
and when they come into existence. On the other hand, a file of Normal
Type is ignored unless it has been explicitly added to a Project.
Why Create Derived File Types?

To summarize, you would create Derived File Types if they need to be
dynamically recognized by Projects. That is, if:
derived (generated) products require further processing.
you want to be able to view/edit the derived products, and therefore want
to access these files from SNiFF+ File Lists.
you want to version control the generated products from within SNiFF+
(see previous point).
107
14

14.5.1 Derived File Types as Intermediate Products

If an input (source) file is processed by a Build Tool to produce some sort
of output that, in turn, requires further processing, you must create a File
Type for each intermediate product type.
Figure 14-2
Multiple Derived File Types in Multi-Step Processing
Input File Type

(e.g. IDLInterface)
Intermediate
Derived File Type 1
(e.g. IDL-Client)
IDL Compiler
C++ Compiler
Intermediate
Derived File Type 2
(e.g. IDL-Server)
Final output
products (e.g.
object files).
No File Type
necessary
Example: IDL
The IDL compiler generates, for example, client- and server-side files
that are then further processed by a C++ compiler.
It would not be enough to create a File Type called, for example,
IDL_Output.
SNiFF+ has to be able to distinguish between the different Derived File
Types (client- and server-side) generated from IDL Interface Files in
order to generate unambiguous rules for creating final products.
(For information on how setting up IDL Projects, see IDL Projects
page 187.)
108

What are Derived File Types?
14.5.2 File TypesDerived Settings
Caution!
In the Preferences, File Types node, Derived Settings tab, you can specify:
Which File Type it (the Derived Type) is derived from.
Whether you want to see the generated files of the Derived File Type in
File Lists.
And, whether SNiFF+ should scan directories for more than one generated file per Derived Type and input file.
Caution is advised in two respects:
If the Scan for multiple Derived Files checkbox is selected, SNiFF+

assumes that there can be more than one such file. It is therefore not
possible to generate unambiguous rules for multi-step processing.
In other words, if the derived files require further processing do not
select this checkbox!
If the derived files are not needed for further processing, you can
select this checkbox. However, be aware that SNiFF+ always has
scan entire directories to ensure that it finds all possible derived files
in order to display them.
109
14

110
15
Overview
Fixed and/or Free Form? page 112
Fixed Form (Fortran 77) page 112
Free Form (Fortran 90) page 112
Fixed and Free Form page 112
Modifying Project Properties page 113
File Type Preferences page 115
Modifying Fortran File Types page 115
Using Different Templates page 115
Fortran Parser Command Line Arguments page 116
Preprocessing Fortran page 117
111

15.1 Fixed and/or Free Form?

SNiFF+ supports both fixed-form (Fortran 77) and free-form (Fortran 90)
files. However, different parser executables are needed to handle these
forms. This means you may have to modify File Type settings.
15.1.1 Fixed Form (Fortran 77)

If your files are fixed-form, the SNiFF+ defaults are all set to handle this,
so you need not change anything.
15.1.2 Free Form (Fortran 90)

If your files are free-form, be aware that the default setting for the SNiFF+
Fortran File Types is fixed-form.
This means that you need to modify the File Type definition in the
Project Properties (for existing Projects)
Preferences (for future Projects)
15.1.3 Fixed and Free Form

If you use both forms, these can be in the same tree of Projects, but not
in one and the same individual Project.
You have to then adjust the File Type settings on a per Project basis (see
Modifying Project Properties page 113.
As for future Projects, you may or may not want to modify the File Type in
the Preferences (File Type Preferences page 115). This will depend
on which form will predominate.
112

Modifying Project Properties
15.2 Modifying Project Properties

If you have already created Projects using the SNiFF+ default for Fortran
(fixed-form), you can modify the settings for (Sub-)Projects in the Project
Properties.
Open the (tree of) Project(s) containing Fortran 90 (free-form) files.
Choose Project > Properties...
In the Project Properties, select the File Types node.

(See Figure 15-1 Project Properties: Modify File Type Language page
114.)
In the File Types node, select the Fortran-Implementation File Type,

and in the Language drop-down, select Fortran-Free.
In the Project tree at the right, checkmark the Projects with free-form files.
From the drop-down above the File Type Settings group, choose
Replace in Checkmarked Projects
Click Apply.
Now select the Fortran-Header File Type.
From the drop-down above the File Type Settings group, choose
Replace in Checkmarked Projects
Click Apply.
You have now changed the Language associated with the FortranImplementation and the Fortran-Header File Types in the checkmarked Projects. A different Parser will therefore be used for the files in
these Projects.
113
15

Figure 15-1
Project Properties: Modify File Type Language
After you have closed the Project Properties, you have to reload and reparse the Project so that the changes take effect. To do so, choose
114
Project > Reload
Then make sure all Projects are checkmarked in the Project Manager and
choose one of the Project > Reparse commands.

File Type Preferences
15.3 File Type Preferences

Modifying File Type Preferences can, depending on the modifications,
affect existing and/or future Projects.
Associating a File Type with a different Language (what you will do here)
affects only future Projects, that is, Projects created using the Project
Creation Wizard.
If you know that future Projects will have only (or at least predominantly)
Fortran 90 (free-form) files, you will want to modify the Fortran File Types
accordingly.
Alternatively, you can also use the appropriate Project Templates to create future Projects (see Using Different Templates page 115).
To modify or create File Types at Preferences level, choose

Tools > Preferences
15.3.1 Modifying Fortran File Types
In the Preferences, select the File Types node.
In the File Types node, select the Fortran-Implementation File Type,

and in the Language drop-down, select Fortran-Free.
Now select the Fortran-Header File Type, and in the Language dropdown, select Fortran-Free.
Click OK.
Because you have changed the Language associated with the FortranHeader and the Fortran-Implementation File Types, a different Parser
will be used for all future Wizard-created Projects.
15.4 Using Different Templates

Templates are provided for both free-form and fixed-form Projects.
For more information about creating Projects with Templates, please see
Project Creation in Existing Workspaces page 84.
115
15

15.5 Fortran Parser Command Line Arguments

Fortran parser command-line arguments can be set
for existing Projects in the Project Properties
for future Template-based Projects, in the Project Templates
for future Wizard-created Projects in the Preferences.

In each case, select the appropriate dialogs Parser node, and enter
options (any order, separated by a blank) in the Parser Options field.
Line-Length, Tab Width and Syntax Checking
Change line length (fixed form):
-lnnn
whereby nnn is the line length
Default: 72
Interpret tabs as number of spaces (fixed form):
-tnn
whereby nn is the number of spaces a tab is interpreted as
Default: 6
Display syntax errors (found by parser) in Log window:
-e
Case Modes
Display symbol names all upper case:

Default. No -c (case) argument, or -cu (case upper).
Display symbol names all lower case:
-cl (case lower).
Display symbol names as typed in source code:
-cs (case source).

Note that if you use the case arguments (above), you never-the-less
have to refer to symbols (for example in the Retriever) as they appear in
your source files.
116

Preprocessing Fortran
15.6 Preprocessing Fortran

If your code uses Common blocks defined in included files, you will want
to enable preprocessing to resolve references to these blocks.
Preprocessing is enabled at WOrkspace level.
So, to open the Workspace Manager, choose

To open the Workspace Properties, double-click on the Workspace you

want to set preprocessing for.
In the Workspace Properties, select the Parsing Properties node.
In the Parsing Properties node, select the

Preprocess Source Code before Parsing checkbox.
15
117

118
16
Overview
Java Projects page 120
C++ Projects page 120
Generating C++ Documentation page 121
Browsing Documentation page 121
Documentation Comments page 122
General Form and Location page 122
Description section page 122
Tag list page 123
Tags Recognized in Java and C/C++ page 123
Tags Recognized in Java Only page 124
119

16.1 Introduction
The SNiFF+ Documenter works for Java Projects and C++ Projects. Documentation is generated as an inter-linked system of HTML files to a
directory of your choice.
Be aware that:
documentation generation cannot be done incrementally
generating documentation for large projects takes a lot of time and memory
cross-references to Projects/Java packages outside the currently generated documentation set cannot work
16.1.1 Java Projects

The SNiFF+ Documenter for Java sources provides a graphical interface
to the Sun javadoc tool. As such, documentation is generated for all files
in package directories (as opposed to files in SNiFF+ Projects). Because
Java Projects must correspond to the package structure, documentation
will be generated according to the checkmarking in the Project Manager.
Be aware, however, that all Java files in the corresponding directories will
be processed, regardless of whether or not they are actually part of
SNiFF+ Projects.
The javadoc application provides many options, only some of which have
been incorporated in the SNiFF+ Documenter GUI. All other options supported by javadoc can be entered in the SNiFF+ Documenters
Additional Java VM parameters field.
Full documentation for javadoc is available at
http://java.sun.com/j2se/javadoc/index.html
16.1.2 C++ Projects

For C++ Projects, the Documenter works, in principle, the same way as
javadoc, but with fewer options. Unlike javadoc, however, only files that
are members of SNiFF+ Projects are documented.
Documentation comments in C++ header files (only headers are documented) follow the syntax understood by javadoc (described in more
detail below).
Generated documentation includes
120
an overview of the directory structure
indexes of header files and classes
Generating C++ Documentation
generated class descriptions, as well as enumerators, variables and functions declared outside of classes.
descriptions taken from documentation comments in header files
16.2 Generating C++ Documentation

The menu command for documenting Projects is only active if the Project
Manager is open. So
First, choose Project > Manage

This opens the Project Manager and activates the
Project > Document... menu.
Documentation is generated for checkmarked Projects.
So, checkmark the Projects you want to document. Note, however, that
links into the Project that are not documented (checkmarked) will not
work (even if documentation for these Projects exists).
Choose Project > Document...

The Documenter dialog opens and provides various options (click into
the dialog and press <F1> for online context help).
16
16.3 Browsing Documentation

If Java Project documentation is generated, an Index.html is created in the output directory specified in the Documenter. This will be your
starting point for browsing the documentation.
If only C++ Projects are documented, a number of files with names of the
form *Index.html are created in the output directory specified in the
Documenter. These are all inter-liked so any one them will do as a starting point for browsing the documentation.
121

16.4 Documentation Comments

Documentation comments are special comments in the code that are
processed to generate documentation. These comments are delimited by
/** ... */.
16.4.1 General Form and Location
Documentation comments are only recognized when placed immediately

before symbol declarations.
A documentation comment is generally made up of two parts a

description (see Description section page 122) followed by zero or
more tags (see Tag list page 123).
/**
* This is the description part of a doc comment
*
* @tagname
Comment for the tag
*/
The first line starts with the begin-comment symbol ( /** ) followed by
a return.
Subsequent lines start with an asterisk.

When a documentation comment is parsed, leading asterisks on each
line are discarded; for lines other than the first, blanks and tabs
preceding the initial * characters are also discarded. These comments
may include HTML tags.
The last line begins with the end-comment symbol ( */ ) followed by a

return. Note that the end-comment symbol contains only a single asterisk.
16.4.2 Description section

The Documenter copies the first sentence of the description to the appropriate entity summary. The first sentence of the description section of
each documentation comment should therefore be a summary sentence, containing a concise but complete description of the entity.
122
Documentation Comments
16.4.3 Tag list

Tags must start at the beginning of a line. Keep tags with the same name
together within a doc comment, so that the Documenter can tell where
the list ends.
16.4.4 Tags Recognized in Java and C/C++
@author <text>
Creates an Author entry (if the Author option is selected in the Documenter dialog). The text has no special internal structure.
A comment may contain multiple @author tags.
@version <text>
Adds a Version entry (if the Version option is selected in the Documenter dialog). The text has no special internal structure. A comment
may contain at most one @version tag. Version normally refers to the
version of the software that contains this feature.
In Java: @param <parametername> <text>

In C++: @param <parametertype> <text>
Adds a parameter to the "Parameters" section. The description may
continue on the next line.
@return <text>
Adds a "Returns" section, which contains the description of the return
value.
123
16

16.4.5 Tags Recognized in Java Only
@throws <fully_qualified_class_name> <text>

Adds a "Throws" section, which contains the name of the exception that
may be thrown by the method. The exception is linked to its class documentation.
@since <text>
Adds a "Since" entry. The text has no special internal structure. This tag
means that this change or feature has existed since the release number
of the software specified by the since-text.
@see
Adds a hyperlinked "See Also" entry to the entity.
Examples:
@see #<symbolname> works if <symbolname> is a member of
the same class.
The character # separates the name of a class or interface from the
name of one of its fields, methods, or constructors.
One of several overloaded methods or constructors may be selected by
including a parenthesized list of argument types after the method or
constructor name.
Whitespace in @see's classname is significant. If there is more than
one argument, there must be a single blank character between the arguments.
A comment may contain more than one @see tag.
@see classname
Adds a hyperlinked See Also entry to the class.
Note
An URL (as follows) is not allowed in an @see tag if you use JDK
1.1.x:
@see <a href="spec.html">Java Spec</a>

Workaround:
Include this URL in the comment before the tags.
124
17
Overview
Synchronizing Projects with the Version Control System page 126
Synchronizing Projects with the File System page 126
Update-Order for Workspaces page 127
Synchronizing Projects within SNiFF+ page 127
Synchronizing with the Version Control System page 127
Synchronizing with the File System page 127
Obsolete Files? page 128
Synchronizing Projects Outside of SNiFF+ page 128
Runtime Environment page 129
Update Script Parameters page 131
SNiFF+ in Batch Mode page 130
Unattended Updates page 130
Update Script Parameters page 131
Parameters for updateWS.py page 131
Parameters for syncProject.py page 134
125

17.1 Introduction
SNiFF+ provides updating mechanisms to ensure that all members in
your development team are working on the latest, most stable version of
your software system. Updates and builds of Projects in Workspaces can
also be done outside of active SNiFF+ sessions, for example, also overnight.
17.1.1 Synchronizing Projects with the Version Control System

Synchronizing Projects usually means updating their files to, usually, the
latest Repository version (HEAD). That is, all files in the Workspace that
are not locked (checked out) will be replaced by the latest file revision
available in the Repository.
If a Workspace uses a default Configuration other than HEAD, updates
will be with respect to this Configuration. That is, all files in the Workspace that are not locked (checked out) will be replaced by the file revision that is an element of the specified Configuration.
See also Workspaces, Configurations, and Branches page 263.
17.1.2 Synchronizing Projects with the File System

Over and above synchronization with the version control system, it may
be useful to synchronizing SNiFF+ with file system changes. This will
apply in mixed development environments (that is, where not all team
members use SNiFF+), especially when ClearCase or CVS version control systems are used.
Because ClearCase and CVS also monitor changes in directory content,
new files/subdirectories, added outside of SNiFF+, may appear on the
file system after updates. As a SNiFF+ user you may then want to add
such files/subdirectories to the SNiFF+ Projects, either interactively or
automatically (e.g. after updates).
To interactively synchronize Projects with on-disk changes, choose

Project > Synchronize > With Disk...
This will open a Wizard allowing you filter according to file and directory
name patterns, as well as a number of other options.
126
For information about automatic with-disk synchronization, please refer to

Synchronizing Projects Outside of SNiFF+ page 128
Synchronizing Projects within SNiFF+
17.1.3 Update-Order for Workspaces

The order you synchronize Projects, both within and outside of SNiFF+,
depends on your Workspace organization.
If you use hierarchically layered Workspaces, always synchronize from
the top down. That is, first update the highest-level Workspace, then the
lower-level Environments that access it.
In flat Workspace systems, the Workspaces are independent of each
other, so it does not matter in which order you update.
17.2 Synchronizing Projects within SNiFF+

Note again that synchronizing with the version control system is useful
regardless of version control system used, whereas the disk synchronization feature will be especially useful in situations where (a) not everyone on the team uses SNiFF+, and (b) the version control system used is
ClearCase or CVS, that is, a system that also monitors directory content.
17.2.1 Synchronizing with the Version Control System

To synchronize all Projects in a Workspace with the version control system:
Open the root Project (ideally at the Workspaces Source Root).
To open the Project Manager choose

Project > Manage
In the Project Manager, checkmark all Projects.
Choose Project > Synchronize

All checkmarked Projects are updated with respect to the Workspaces
default Configuration (normally HEAD).
If you have more than one root Project (multiple, unrelated Project trees)
in a Workspace, repeat the process for each Root Project.
17.2.2 Synchronizing with the File System

To interactively synchronize Projects with on-disk changes, choose
Project > Synchronize > With Disk...
127
17

This will open a Wizard allowing you filter according to file and directory
name patterns, as well as a number of other options.
17.2.3 Obsolete Files?

If someone has removed files from Projects, a dialog will appear after the
update is complete. The dialog lists all files that have been removed from
Projects, and that are therefore potentially obsolete. You can delete such
files from the file system (if they really are obsolete) by highlighting them,
and clicking Delete.
17.3 Synchronizing Projects Outside of SNiFF+

External synchronization uses the following components provided with
your SNiFF+ installation:
sniffpython
This is a Python interpreter.
updateWS.py
This Python script is located in SNIFF_DIR4/etc.
The script starts SNiFF+ in batch mode (see also SNiFF+ in Batch Mode
page 130), or connects to a specific SNiFF+ session and synchronizes Projects in a given Workspace. Projects are updated with respect
to the latest file revisions, or with respect to specified Configurations, in
your Workspace.
After an update, SNiFF+ can create a log file with a summary report in
directories where the updateWS.py script was executed. This
summary report can also be automatically sent to you by e-mail (if e-mail
address and mail server are specified).
128
Synchronizing Projects Outside of SNiFF+
syncProject.py
This Python script is located in SNIFF_DIR4/etc.
The script starts SNiFF+ in batch mode (see also SNiFF+ in Batch Mode
page 130), or connects to a specific SNiFF+ session and synchronizes Projects with on disk changes that occurred outside of SNiFF+
control.
After synchronizing, SNiFF+ can create a log file with a summary report
in directories where the syncProject.py script was executed. This
summary report can also be automatically sent to you by e-mail (if e-mail
address and mail server are specified).
17.3.1 Runtime Environment

To ensure that all necessary Python libraries will be found by the Python
interpreter, set the SNIFF_DIR4 environment variable to point to the
SNiFF+ installation directory.
On Unix
To ensure that the Python interpreter can be called elsewhere in a Shell,

the PATH environment variable should point to
SNIFF_DIR4/bin
The LD_LIBRARY_PATH environment variable should point to
SNIFF_DIR4/lib
Start external Workspace updates from any Shell and call the script (all in
one line):
sniffpython $SNIFF_DIR4/etc/updateWS.py \
-ws <Workspace> -project <Project> [options]
Start external disk synchronization from any Shell and call the script (all
in one line):
sniffpython $SNIFF_DIR4/etc/syncProject.py \
On Windows
To ensure that the Python interpreter can be called elsewhere in a Command Prompt, the PATH environment variable should point to
SNIFF_DIR4\bin
SNIFF_DIR4\lib
SNIFF_DIR\bin\gnu-win32
129
17

Start external updates from the Command Prompt and call the script (all
in one line):
sniffpython %SNIFF_DIR4%\etc\updateWS.py \
Start external disk synchronization from the Command Prompt and call
the script (all in one line):
sniffpython %SNIFF_DIR4%\etc\syncProject.py \
17.3.2 Update Script Parameters

Please see Update Script Parameters page 131 for information on
how <Workspace> is specified, as well as for information on other
script parameters.
If <Project>, above, is the Source Root of the specified Workspace,
all Projects in the Workspace will be recursively updated and, unless
otherwise specified (-noBuild option), built.
17.3.3 SNiFF+ in Batch Mode

You can run SNiFF+ in batch mode, that is, without starting the graphical
user interface, using the sniffs executable (sniffs.exe on Windows), located in SNIFF_DIR4/bin.
To start sniffs, you would enter
sniffs [-s <SessionName>]
Whereby <SessionName> can be any string.
You use <SessionName> to identify the session later. In this context,
for example, to be used by the update script.
17.3.4 Unattended Updates

You can also use the script discussed above (Synchronizing Projects
Outside of SNiFF+ page 128) for unattended, e.g., overnight, updates.
130
On Unix, unattended updates can be run using the cron (crontab) utility.
On Windows NT, unattended updates are run using a utility like, for example, at.
Update Script Parameters
Example of an Unattended Update on Unix

The following cron file will execute an update at 4 oclock in the morning.
For a description of the parameters, please refer to Update Script Parameters page 131.
Please note that cron does not accept environment variables. For details
about cron and crontab, please refer to your man pages.
00 04 * * * SNIFF_DIR4=<SNIFF+_install_dir>; \
export SNIFF_DIR4; \
LD_LIBRARY_PATH=($SNIFF_DIR4/lib:$PATH) \
$SNIFF_DIR4/bin/sniffpython \
$SNIFF_DIR4/etc/updateWS.py \
-ws <Workspace> -project <Project>
17.4 Update Script Parameters

Note again that updateWS.py can be useful, regardless of version
control system used. The syncProject.py script, however, will be
especially useful in stations where (a) not everyone on the team uses
SNiFF+, and (b) the version control system used is ClearCase or CVS,
that is, a system that also monitors directory content.
17
17.4.1 Parameters for updateWS.py

The following parameters can be passed to updateWS.py.
Square brackets [ ] indicate that the parameter is optional.
[-help]
Show help message (usage summary).
Default: no help message will be shown.
131

-ws <Workspace>
Refers to the Workspace where Projects are to be updated.
Enter the full hierarchy of the Workspace (including the Workspace
Default Configuration), as displayed in the Workspace Manager. The
hierarchy always starts with a slash, each layer in the hierarchy is also
separated by a slash.
(When a Project is open, this hierarchy is displayed in the Project
Browsers title bar - after the relative Project path used in the project
parameter, see below.)
Example
/Repository/HEAD/common/complex
-project <project>
The specific Project that is to be updated. A Project is specified by the
relative path with respect to the Workspace Root directory (see
Workspace parameter above) and the physical Project Description File
name (as displayed in the Project Browsers title bar, where it is followed
by the - Workspace parameter, above).
Example
complex/complex.proj
[-noUpdate]
Prevents a Update of the Project. This may be useful in case you just
want to build.
Default: update files of Project.
[-noBuild]
Prevents a recursive Build of the Project after the update.
Default: build target (Workspace default Platform).
{-buildFlag <aFlag>}
Build flag, for example -i. The flag value will be directly handed to the
Build. Therefore you have to know the syntax of flags. In the given
example, the minus sign is mandatory.
Default: no flags will be used.
[-buildPlatform <platform>]
Specify a Platform other than the default platform to build target.
Option can be specified more than once to build target for multiple platforms.
Default: build target for Workspaces default Platform.
132
[-buildLog <file>]
File to save Build log information.
Default: a generated file name will be used.
[-noClean]
Prevent a recursive clean of the Project after the update.
Default: clean target before building it.
[-referenceTime <aTime>]
Update on a certain time stamp.
The time stamp format is YYY/MM/DD HH:MM:SS.
Default: recent file version will be used.
[-forceReparse]
Force a reparse of the Project.
Default: no reparse of Project will be done.
[-upDateIndex]
Update Retriever index.
Default: no update of Retriever index
[-updateXRef]
Force update of Cross-Reference Information.
Default: no update of Cross-Reference information.
17
[-projectDiffs]
List files added to/removed from Projects in update-log file.
Default: not listed.
[printTiming]
Show how long each operation takes.
Default: not shown.
[verbose]
Print informational text to stdout.
Default: non-verbose.
133

[-mailAddr <mailAddress> -mailServer <aServer>]

E-mail address and server to send notification of update result.
The update log file is attached to the e-mail.
Default: no mail will be sent.
[-session <sessionName>] | [[-host <hostname> ] port <portNumber> ]

SNiFF+ session running on the local host (this is the preferred method
for connecting to SNiFF+). Note: For a SNiFF+ session running on a
remote host, the -host and -port option has to be used.
Default for sessionName: a generated session name will be used.
Default for hostname: localhost is assumed.
17.4.2 Parameters for syncProject.py

The following parameters can be passed to syncProject.py.
Square brackets [ ] indicate that the parameter is optional.
[-help]
Show help message (usage summary).
Default: no help message will be shown.
-ws <Workspace>
Refers to the Workspace where Projects are to be updated.
Enter the full hierarchy of the Workspace (including the Workspace
Default Configuration), as displayed in the Workspace Manager. The
hierarchy always starts with a slash, each layer in the hierarchy is also
separated by a slash.
(When a Project is open, this hierarchy is displayed in the Project
Browsers title bar - after the relative Project path used in the project
parameter, see below.)
Example
/Repository/HEAD/common/complex
134
-project <project>
The specific Project that is to be updated. A Project is specified by the
relative path with respect to the Workspace Root directory (see
Workspace parameter above) and the physical Project Description File
name (as displayed in the Project Browsers title bar, where it is followed
by the - Workspace parameter, above).
Example
complex/complex.proj
[checkin]
Check in modified and newly added files.
Default: not checked in.
[absolutePaths]
Consider non Workspace-relative paths.
Default: not considered.
[connectProjects]
Add existing project definition files as sub-projects.
[createProjects]
Create Subprojects for new directories.
Default: Projects will be created; set to zero to disable.
17
[projectTemplate]
Template for new projects.
Default: default.ptmpl
[exclude <patterns>]
File and directory exclusion patterns (blank-separated list).
Default: *.bak *~ #* *,v'
[include <patterns>]
Additional file inclusion patterns (blank-separated list); that is, patterns
not belonging to recognized Project File Types.
Default: none
[recursive]
Scan directories recursively.
Default: Directories scanned recursively; set to zero to disable.
135

[dry]
Dry run; do not modify any files, report only.
Default: not dry.
[projectDiffs]
Report added/removed files after synchronization.
Default: No report
[printTiming]
Show how long each operation takes.
Default: not shown.
[verbose]
Print informational text to stdout.
Default: non-verbose.
[-mailAddr <mailAddress> -mailServer <aServer>]

E-mail address and server to send notification of update result.
The update log file is attached to the e-mail.
Default: no mail will be sent.
[-session <sessionName>] | [[-host <hostname> ] port <portNumber> ]

SNiFF+ session running on the local host (this is the preferred method
for connecting to SNiFF+). Note: For a SNiFF+ session running on a
remote host, the -host and -port option has to be used.
Default for sessionName: a generated session name will be used.
Default for hostname: localhost is assumed.
136
Part V
SNiFF+ PRO Build/Debug: How To
C/C++ Projects
Java Projects
Ada Projects
JAR, Java IDL, JNI, and RMI Settings
IDL Projects
Custom Build Setup
Remote Build and Debug
Modifying Build Tools and Settings
Running and Debugging Targets

138
18
C/C++ Projects
Overview
Build-Target Wizard or Project Properties? page 140
C/C++ Build: Summary of Steps page 140
Setting C/C++ Targets and the Debugger Adaptor page 141
Setting Include Paths page 143
Generated Include Paths page 144
Additional Includes page 145
Verify Tool Settings page 146
Promoting Project Build Tool Settings to Workspace Level page

147
139

18.1 Build-Target Wizard or Project Properties?

Standard build-targets can be set/modified/deleted in the Build-Target
Setup Wizard.
The Wizard, accessed using the Build > Build-target Setup... menu,
actually uses the settings defined in the Project Properties dialog, and
also writes modifications back to the Project Properties.
So, even if you set/modify build-targets in the Wizard you can always
check or tweak settings in the Project Properties dialog.
The following outline therefore provides information both about what happens behind the scenes when you use the Wizard, as well as introducing other aspects that may not be accessible in the Wizard.
18.2 C/C++ Build: Summary of Steps

The basic steps are summarized here, and described in more detail as
they are applied in the Project Properties further down.
(A hands-on tutorial in the Beginners Guide for C/C++ Projects discusses these steps as they are applied in the Build-target Setup Wizard.)
1. Define Project target(s).
That is, associate Project(s) with a target name(s).
2. Associate a Build Tool with the target(s) defined above.
That is, the type of target (e.g. library or executable) is determined by the
Build Tool used to create it.
3. If the target is an executable, define a debugger adaptor.
140
C/C++ Projects
Setting C/C++ Targets and the Debugger Adaptor
18.3 Setting C/C++ Targets and the Debugger Adaptor

To set/modify build-target settings in the Project Properties.
To access Project Properties, choose

Figure 18-1
In the navigation tree at the left, select the Build Options node.
Project Properties Build options
18
141

Make sure Build Support is checkmarked.

This checkbox will be checkmarked if this was specified during Project
creation, either using the Project Creation Wizard, or an appropriate
Template.
At Project creation time this is an all-or-nothing setting. That is, Build
Support is enabled for all Projects, or none at all.
If you want to change this setting after Project creation, you would selectively checkmark Projects in the tree on the right, and then specify that
Build Support must be enabled for Checkmarked Projects.
The Highlighted/Checkmarked Projects selection is used to set the
scope of a setting when you click the Apply button.
You would use the Ignore Dependencies to option only for Subprojects
you have added for browsing-only purposes. For example, you have
added a third-party library you want to browse. However, you do not want
the Build System to generate dependencies into this library, and subsequently therefore, to rebuild the dependent files if headers have changed.
If you change this setting, you need to reparse after you close the Project
Properties (choose Project > Reparse).
Set the Generate Dependencies to System Headers as appropriate for

your Project. Generally, this will not be necessary.
If you change this setting, you need to reparse after you close the Project
Properties (choose Project > Reparse).
In the Project Tree at the right, highlight the Project you want to set a (any
kind of) target for.
Target Definitions
Click the New... button.

At this point, all you do is associate a target name with the Project. The
type of target is defined in the next step.
Enter a name for the new target in the box that appears.
When you close the box the target name appears, and is highlighted, in
the Target Definitions list.
Settings for Selected Target
From the Build Tool drop-down, select the tool that will determine the
kind of target you want to build. For example, to build an executable, you
would select the Linker entry.
If you selected Linker, the Debugger Adaptor drop-down is enabled.

Note that the default Platform/Debugger Adaptor mappings are set in the
Preferences.
142
C/C++ Projects
Setting Include Paths
If you did not select the Linker to build an executable target, but, for
example, Librarian to build a library, the Passed to Superproject setting
for the defined target is enabled. This means that the target can be
exported to be linked into another target further up in the Project hierarchy.
Settings for Objects and Received Targets

Two settings can be toggled.
Pass Objects to Superproject

All object files created for the current Project (the one highlighted in the
Project Tree at the right of the dialog) can be exported (passed up) for
use in the Superproject.
Pass Received Targets to Superproject

All targets received from (=exported by) Subprojects can be passed on
for use in the next level of the Project hierarchy.
Note that a Received Target can equally be the Objects (see above)
passed by a Subproject. When objects are passed, an internally used
virtual target is created for them, and this can then be exported further
up the line.
18.4 Setting Include Paths
18
If source files include non-standard headers located outside the source

directories, the compiler needs to know where to look for them.
SNiFF+ maintains dependency tables for Project Structures. These can
be used to generate include paths to pass to the compiler.
Furthermore, search-paths can also be set to point to locations outside
the Project structure.
These things are set in the Project PropertiesBuild Tool Settings
node.
143

18.4.1 Generated Include Paths

Note that the steps outlined below are not normally necessary. By
default, include-paths are generated at Project creation time (both using
the Wizard, or using the predefined Project Templates with Build Support).
In the Project PropertiesBuild Tool Settings

Generated include paths can be set for multiple Projects and Platforms,
so your first step is to checkmark the Projects that you want to generate
include paths for (often, this will be all the Projects in the tree).
Your default Platform for the current Workspace will already be selected
in the Platform drop-down.
In the Build Tool list, select C++ Compiler (or C Compiler, as the case
may be).
Checkmark the Generate Includes For checkbox.

The drop-downs next to the checkbox are now enabled.
If you want to generate includes for All Platforms, select this in the first
drop-down. Verify the checkmarking in the Project Tree and select
Checkmarked Projects from the second drop-down.
Search-paths for the compiler to find included files anywhere in the
Project Structure will be generated for all checkmarked Projects (and
Platforms) when you click the Apply button.
After clicking Apply, if you did not generate includes for all Platforms, use
the Edit All Platforms... button to open a dialog box where you can
selectively apply/edit the currently highlighted build tool setting (current
Project only) for other platforms.
In particular, you would probably want to set the includes also for the
other Platform-variant (debug or release ).
144
C/C++ Projects
Setting Include Paths
Figure 18-2
Project PropertiesBuild Tool Settings: Generate Include Paths
18.4.2 Additional Includes
18
If your source files also include headers outside the current Project structure, set these at Workspace level!. Please see C/C++ Include Directives
page 229 for more information.
145

18.5 Verify Tool Settings

If this is the first Project-Build you are setting up, you might want to check
that the correct compiler, linker, etc. is set. Here, we will take a look at the
C++ compiler as an example.
Note that the procedure outlined below is a convenient, on-the-fly way of
doing things. For more generally recommended procedures, please refer
to Modifying Build Tools and Settings page 205.
In the Project PropertiesBuild Tool Settings
From the Platforms drop-down, select each Platform you use in turn, and
proceed as follows.
In the Build Tool list, select C++ Compiler

We are using the C++ Compiler as an example. If you do not see one in
the list, this means that there are no C++ files in the highlighted Project;
only tools actually used in the highlighted Project are listed.
The C++ compiler is assigned to the CXX field (default field name). Is the
correct value assigned to this field?
If not, in the Edit field, enter the correct value, and also modify the other
fields as necessary.
You will notice that the icons next to modified fields change from a Workspace icon to a Project icon.
This indicates that changes apply to the current (highlighted) Project
only, which is probably not what you want for a setting like this. So, read
on below.
146
C/C++ Projects
Verify Tool Settings
18.5.1 Promoting Project Build Tool Settings to Workspace Level

If you have to modify Build Tool Settings, for example if you want to use a
different compiler, you will generally not want to apply this to only the
highlighted Project.
SNiFF+ therefore allows you to promote settings from Project to Workspace level.
Figure 18-3
Note that the Workspace Build Properties must be writable (checked out)
for this to work.
Promote Build Tool Settings to Workspace Level
18
To promote the setting, on the Project icon

Right-click > Promote to Workspace Level
The icon changes to a Workspace icon.
The setting is now globalized, so that it applies to all Projects that are, or
will be, opened in the Workspace.
See also Modifying Build Tools and Settings page 205 and VersionControlling Build Properties page 75 for related topics.
147

148
19
Java Projects
Overview
Build-Target Wizard or Project Properties? page 150
Java Build: Summary of Steps page 150
Identify Libraries for Browsing Only page 151
Setting Java Application Targets and the Debugger Adaptor page 153
Multiple Application Targets page 153
Setting Java Build Options page 154
Java Source Path and SNiFF+ Source Root page 154
Setting Java Build Options page 154
Setting the Output Directory Path page 155
Classpath(s) to Libraries page 156
Verify Compiler and Other Java Tool Settings page 157
Correct Compiler? page 157
Compiler Flag for JDK 1.1.x (-c Command Line Length) page 158
Promoting Build Tool Settings to Workspace Level page 158
Building Java Projects page 159
Building the Application Target page 159
Building Projects and Files page 159
Java Projects and Build Platforms page 160
Remote Java Debugging page 160
JDK 1.1.x page 161
SDK 1.2.2 Environment Settings page 161
SDK 1.2.2 and Newer page 162
149

19.1 Build-Target Wizard or Project Properties?

Standard build-targets can be set/modified/deleted in the Build-Target
Setup Wizard.
19.2 Java Build: Summary of Steps

The basic steps are summarized here, and described in more detail as
they are applied in the Project Properties further down.
(A hands-on tutorial in the Beginners Guide for Java Projects discusses
these steps as they are applied in the Build-target Setup Wizard.)
See also JAR, Java IDL, JNI, and RMI Settings page 181 for related
topics.
1. Identify source code libraries used for browsing and code comprehension
only, for example, the JDK sources.
You need to disable the generation of build dependencies into such
libraries. If you dont, the libraries will also be built; this could be timeconsuming.
2. Set Java Interpreter ScriptBuilder as the Build Tool for the Application
Project(s) and Class(es); that is, where main is implemented.
You do this so that you can run and debug Java applications from the
SNiFF+ menu.
3. Set the Debugger Adaptor. This depends on which JDK version you use.
4. If you use JDK 1.1.x, in the SniffJMake tool, set a command-line length
for the compiler (unless you have already set this at Workspace level).
5. Depending on whether you created the Project with the Wizard or with a
Project Template, you will need to proceed as follows:
150
Java Projects
Identify Libraries for Browsing Only
If you created the Project using a Project Template, you need to generate/set the path to source code packages and, optionally, the destination directory for generated classes (the -sourcepath and -d
options). If your source packages start below the Workspaces Source
Root, the source path can be generated. If your packages start outside the Workspaces Source Root, you will have set an absolute path
(usually using an environment variable).
If you created the Project using the Wizard, and your source packages start below the Workspaces Source Root, the Wizard will have
generated the source path and a corresponding output directory
already (the -sourcepath and -d options); you need not do anything. If, however, your packages start outside the Workspaces
Source Root, you will have set an absolute path (usually using an
environment variable).
6. If your Project uses external (third party) class libraries that are not part of
the Project, you need to set the appropriate classpath(s).
19.3 Identify Libraries for Browsing Only

Java Build Options are set in the Project Properties dialog.

19
In the Project PropertiesBuild Options

Use the Ignore Dependencies to option and disable Build Support for
Subprojects you have added for browsing-only purposes. For example,
you have added the JDK sources to your Project. However, you do not
want the Build System to generate dependencies into the JDK sources,
and subsequently therefore, to build the JDK files.
Figure 19-1 Ignore Dependencies to Libraries page 152 illustrators
what you have to do.
Make sure none of your own Projects (the ones you want to build) are
checkmarked.
151

Figure 19-1
152
Select (highlight) the library root node (in Figure 19-1 this is the
jdk_src Project); collapse and checkmark it. This will automatically
checkmark all its subnodes. Note again: the collapsed library root Project
must be checkmarked and highlighted.
Make sure that Build Support is not checkmarked, and select

Checkmarked Projects from the adjacent dropdown.
Checkmark the Ignore Dependencies to checkbox and select

Checkmarked Projects from the adjacent dropdown.
Ignore Dependencies to Libraries
Java Projects
Setting Java Application Targets and the Debugger Adaptor
19.4 Setting Java Application Targets and the Debugger Adaptor

Java Build Options are set in the Project Properties dialog.

In the Project Properties Build Options
In the Project Tree at the right, highlight the Project where a main
method is implemented.
In the box that appears, enter the exact name (case-sensitive, no extension!) of the class implementing main.
When you close the box, the target name appears, and is highlighted, in
the Target Definitions list.
From the Build Tool drop-down, select

Java Interpreter ScriptBuilder
This builds a script to host the application so that you can run and debug
it from the SNiFF+ menu.
You will notice that the Debugger Adaptor drop-down is now also
enabled. From the Debugger Adaptor drop-down choose:
If you use the SDK 1.2.2 or higher, in the second drop-down, select
sniffjdb JPDA (java 2)
If you use JDK 1.1.x, in the second drop-down, select

sniffjdb (java 1)
Note that the default Platform/Debugger Adaptor mappings are set in

the Preferences.
Repeat the above steps for any other application classes in your Project.
19.4.1 Multiple Application Targets

You can set any number of Java application targets as described above.
Once you have specified your Debugger Adapter and other, more general settings (below), you can also quickly add targets directly from the
File List, without opening the Project Properties (the Project Description
File, however, must be writable).
153
19

To do so, you would select any Java File where a main (or init )
method is implemented and choose
Right-click > Add to Execution Targets.
19.5 Setting Java Build Options

In the Project Properties, select the
Build Options Java Build Options node.
Before stepping through the settings, some preliminary remarks to help
you decide what you have to do, if anything.
19.5.1 Java Source Path and SNiFF+ Source Root

If your source code packages start below the Workspace Source Root,
and you created the Project using the Wizard, the source path will
already have been generated; in other words you neednt do anything in
this respect.
If your source code packages start below the Workspace Source Root,
and you created the Project using a Project Template, you can have
SNiFF+ generate the source path in the Project Properties.
If source packages start outside the Workspace Source Root, these
paths cannot be generated, and you will have to enter the absolute path
(environment variable) to the start of your source packages manually.
154
According to the Java language specification, the class/source path used

by Java tools to find packages ends one directory level above the highestlevel directory containing named package code.
SNiFF+ Projects use the Workspace Source Root as their point of reference.
The generated source path is therefore the relative path, if any, from the
Workspace Source Root to the start of your packages. Because this path
is relative, it will be the same for all Workspaces.
Java Projects
Setting Java Build Options
If the start of your packages lies outside the Workspace Source Root,
however, a relative path that can be used by all team members cannot be
properly calculated.
The solution is to set the source path using an environment variable.
That way, different users can set the same variable name to point to
different absolute paths.
The environment variable is set outside of SNiFF+. Within SNiFF+, you
set the source path for the Project by entering the variable name, not the
actual path. The Project thus knows only the name of the variable.
However, at build-time, the variable is expanded to whatever it is set to in
the current users environment.
If your code does not use packages, all files must be in the Source Root
directory of the Project, and you neednt set anything.
19.5.2 Setting the Source Path

1. In the Project Tree at the right, checkmark the Projects (usually all, if they
are all Java Projects) you want to set the path to source packages for.
2. Checkmark Generate Source Path for Checkmarked Projects.
3. Click Apply.
If a correct source path cannot be generated (for example, packages
start outside Workspace Source Root), you will be alerted by a dialog
box.
In this case, you would need to enter an environment variable name in
the Source Root field (in the form $VariableName), and then click
Apply to set the source path that the variable expands to for the checkmarked Projects (see also Java Source Path and SNiFF+ Source Root
page 154).
19.5.3 Setting the Output Directory Path

Whereas, in SNiFF+, the source path is generated relative to the Workspaces Source Root, the output directory for generated byte-code (-d
option) is normally set relative to the Workspaces Generated Files Location . Specifically, it is normally located below the Platform Redirection
D i r e c t o r y. T h a t i s, f o r e x a m p l e , o u t p u t g e n e r a t e d f o r
<SomePlatform>-debug will be redirected to a different directory
than that for <SomePlatform>-release.
You can set the destination directory for classes either below the Generated Files directory (recommended), or as an absolute path (environment
variable).
155
19

If you simply enter a name, a directory of this name will be created below
the Platform Redirection Directory when the Project is first built.
If you use an absolute path (environment variable), the directory must
exist.
1. In the Output Directory field, enter either a name for a new directory to
be created below the Platform Redirection Directory, or (not recommended) an absolute path, or an environment variable (in the form
$VariableName).
2. Generally, you will generate all classes below this root directory. So, in the
Project Tree at the right, checkmark all (Java) Projects.
3. In the drop-down next to the Output Directory field, select
Checkmarked Projects.
4. To apply the settings, click Apply.
19.5.4 Classpath(s) to Libraries

If you use libraries that are not part of the current SNiFF+ Project you
need to set the -classpath option for these libraries.
1. In the (Class Path to) Libraries field, enter absolute paths to .jar,
.zip or .class files.
The special variable $WS_ROOT (expands to the source root location of
the current Workspace) and environment variables are permissible. If
$WS_ROOT is used, this is expanded first (prior to any environment variables).
Each path should end with a filename or directory, depending on what
you are setting the class path to:
For a .jar or .zip file that contains .class files, the path ends
with the name of the .zip or .jar file.
For .class files in an unnamed package, the path ends with the
directory that contains the .class files.
For .class files in a named package, the path ends with the directory that contains the root package (the first package in the full package name).
2. You can use the Preview button to see exactly what is written to the Build
Support files.
3. To apply the settings, click the Apply button.
All Projects will now be able to find the libraries.
156
Java Projects
Verify Compiler and Other Java Tool Settings
19.6 Verify Compiler and Other Java Tool Settings
If this is the first Project-Build you are setting up, you might want to check
that the correct tools are set. Here, we will look at the Java compiler as an
example.
Also, if you are using JDK 1.1.x, you have to modify a compiler flag.
In the Project Properties Build Tool Settings
From the Platforms drop-down, make sure the entry that corresponds
most closely to your compile-time system is selected. For Java this basically means either any Unix, or any Windows Platform.
In the Build Tool list select SniffJMake
If you do not see SniffJMake in the list, this means there are no Java
files in the Project highlighted in the tree on the right; highlight a Project
that does have Java files.
19.6.1 Correct Compiler?

Note that the procedure outlined below is a convenient, on-the-fly way of
doing things. For more generally recommended procedures, please refer
to Modifying Build Tools and Settings page 205.
In Build Tool Settings node, the Java compiler is assigned to
SniffJMakes JAVAC field (default field name).
Is this the correct compiler? If not, in the Edit field, enter the correct
value, and modify the other fields as necessary.
You can also use the Edit All Platforms... button to selectively apply/edit
the currently highlighted build tool setting (current Project only) for other
platforms.
In particular, you would probably want to do this, at least, for the other
Platform-variant (debug or release).
You will notice that the icons next to modified fields change from a Workspaces icon to a Project icon. This indicates that changes apply to the
current (highlighted) Project only, which is probably not what you want for
a setting like this.
So, read on under Promoting Build Tool Settings to Workspace Level
page 158.
(See also Modifying Build Tools and Settings page 205.)
157
19

19.6.2 Compiler Flag for JDK 1.1.x (-c Command Line Length)
In the Build Tool Settings, the SniffJMake Build Tool has is a field
named SNIFFJMAKE_FLAGS.
The preconfigured tool call command, SniffJMake, is optimized for SDK
1.2.x. That is, the compiler is passed a file list for compilation.
However, if you are using JDK 1.1.x compilation lists are not supported,
and you have to pass the -c flag, with your maximum command line
length, to the javac compiler.
To do so, you would highlight SNIFFJMAKE_FLAGS, and in the Edit
field, enter the value for the field as:
-c 1024
(assuming a maximum command-line length of 1024 characters).
As soon as you hit <Tab> (leave the field), you will notice that the icon
next to the SNIFFJMAKE_FLAGS field changes from a Workspace icon
to a Project icon. This indicates that changes apply to the current (highlighted) Project only, which is probably not what you want for a setting
like this.
So, read on below.
19.6.3 Promoting Build Tool Settings to Workspace Level

If you have to modify Build Tool Settings, for example if you want to use a
different compiler, you will generally not want to apply this to only the
highlighted Project.
SNiFF+ therefore allows you to promote settings from Project to Workspace level.
To promote the setting, on the Project icon

Right-click > Promote to Workspace Level
The icon changes to a Workspace icon.
The setting is now globalized, so that it applies to all Projects that are, or
will be, opened in the Workspace.
Note that this will only work if the Workspace Build Properties file is writable (checked out),
See also Modifying Build Tools and Settings page 205 and VersionControlling Build Properties page 75 for related topics.
158
Java Projects
Building Java Projects
19.7 Building Java Projects

The Build menu reacts to highlighted Projects in either the File Lists, the
Symbol Lists, or Project Managers Project Tree (whichever has focus).
19.7.1 Building the Application Target

If the Application Targets Project is highlighted, the Build menu lets you
build, among other things, the Application Target (see also Setting Java
Application Targets and the Debugger Adaptor page 153).
First, to make sure the Build-Support files are up to date, highlight your
top-most Project, and choose
Build > Update Build-Support Files
To build the Application Target, choose

Build > Build > PlatformTarget.sh
The .sh ending indicates a shell environment created and used by
SNiFF+ to let you run and debug the target from the menu.
To build any other kind of defined Target, highlight the Project for which a
target is defined, and choose
Build > Build > Platform Target.
If a Target depends on *.class files (e.g. a JAR), these must first
exist.
19.7.2 Building Projects and Files

19
Irrespective of which Project is highlighted, you can build
All classes in the highlighted Project (and necessary dependencies):

Build > Build > classes
All classes in all Projects (or subtree of Projects), irrespective of dependencies:

Build > Build > all
An individual file (and necessary dependencies). The file must have focus
(either in the Source Editor, or highlighted in a File List):
Build > FileName.class
159

19.7.3 Java Projects and Build Platforms

Because Java Projects do not use the same concept of object redirection
as implemented in the SNiFF+ PRO Build Support for C/C++ Projects,
there is something to be aware of.
While you can quickly switch between Platforms, for example between a
release or debug Platform, output is always generated to the same
place in Java. That is, the class files will all be up-to-date after a rebuild
in a different mode (unless sources have changed in the meantime).
So, you have two options if you want to rebuild in a different mode.
Highlight the top-most Project of the tree you want to rebuild, and choose
Build > Build > clean
This will remove all existing class files in the tree, up to and including
those for the highlighted Project.
Now change the Platform selection in the Builder (Tools > Builder), and
rebuild.
Or, change the Output Directory value in the Project Properties, Java
Build Options (see Setting the Output Directory Path page 155).
Now change the Platform selection in the Builder (Tools > Builder), and
rebuild.
19.8 Remote Java Debugging

Remote debugging in this context means debugging from one Virtual
Machine (the debuggers), referred to as the debugger VM , to another
Virtual Machine (the applications), referred to as the target VM.
The target VM has to be started externally, and in debug mode. That is,
you can not start the application you want to debug using the SNiFF+
Build menu.
How you invoke the target VM, and how you attach from the debugger
VM will depend on which JDK you use, or on your VM implementation,
however, the target VM must always be invoked
in debug mode
without using a JIT compiler

See below for a description using standard Java tools (please refer also
to your own tool-documentation).
160
Java Projects
Remote Java Debugging
See also Remote Java page 203 for notes on build and debug on a
remote physical machine.
19.8.1 JDK 1.1.x

To start the target VM, in a shell, enter
java_g -nojit -debug <YourAppClass>
Whereby <YourAppClass> is the target class to debug, and will be
located somewhere under the directory you set under Setting the Output
Directory Path page 155.
The VM generates a password and prints this to the standard output
stream in the form:
Agent password=55g4
This is the password you need to connect to the target VM from the
debugger VM.
Start the SNiFF+ Debugger.

(See Running and Debugging Targets page 211.)
In the SNiFF+ Debugger start-up dialog:
Select the Attach to VM option.
In the Connection field, you will see the default entry
-host localhost -password

if the target VM is running on a remote physical machine, change
localhost to the remote machines name (or IP address).
At the end of the field (after -password) enter the password generated above.
Click OK to connect.
19
19.8.2 SDK 1.2.2 Environment Settings

For remote Java debugging:
On Windows
Make sure your PATH environment variable points to
SNIFF_DIR4\lib\java\jpda\win
On Unix
Make sure your LD_LIBRARY_PATH environment variable points to
SNIFF_DIR4/lib/java/jpda/<platform>
161

19.8.3 SDK 1.2.2 and Newer

Using the SDK 1.3 and newer, no special environment settings are
required.
Starting the Target VM

To start the target VM, the command line entry depends on:
Operating System
On Windows, you can use the shared memory (dt_shmem ) transport.
With the shared memory transport, the debugger and the target VM must
reside on the same physical machine.
In all (other) cases you can use socket (dt_socket) transport.
Whether you want to start the target VM in running (suspend=n), or

suspended (default) mode.
Whether the Hotspot Performance Engine is installed.

If so, the -classic option is necessary to select the classic VM.
The Hotspot Performance Engine requires the
-Xdebug and -Xrunjdwp options.
The -Xnoagent and -Djava.compiler=NONE options are not
required; however, for compatibility, these options are accepted and
ignored (see below).
Example: Socket Transport (Target VM Running)

This example starts the target VM (classic, not Hotspot) in running mode,
using socket transport.
In a shell, enter the following all in one line, whereby <jdk> represents
the path to your Java SDK 1.2.2 (or 1.3) installation directory, and
<YourAppClass> is the target class to debug, and will be located
somewhere under the directory you set under Setting the Output Directory Path page 155.
In the following command, line continuation is indicated by a backslash
followed by an indented line.
java -Xdebug -Xnoagent -Djava.compiler=NONE \
-Xrunjdwp:transport=dt_socket,server=y,suspend=n \
-Xbootclasspath:<jdk>/jre/lib/rt.jar: \
<jdk>/lib/tools.jar <YourApp>
This will start the target VM and print a message to the standard output
stream in the following form:
Listening for transport dt_socket at address: 1179
162
Java Projects
Remote Java Debugging
This port address is the one you need to connect to the target VM from
the debugger VM. (Please refer to the Sun documentation mentioned
above for more information, especially also in connection with the
Xrunjdwp sub-options.)
Now, in the SNiFF+ Debugger start-up dialog:
Select the Attach to VM option.
The Connection field changes to show the default entry
-attach
In the end field (after -attach) enter the address generated above.
Click OK to connect.
19
163

164
20
Ada Projects
Overview
What You Need (General) page 166
GNAT and Tornado/VxWorks Requirements page 166
Check Preferences page 166
Windows Only: Platform Settings page 167
Run the GNAT Integration Script page 170
What the GNAT Integration Script Does page 171
Modification of Build Support (Native Make) page 172
Check Workspace Settings page 173
Workspace Default Platform page 173
Generation of Ada Macros in Old Workspaces page 174
Setting Ada Targets and Debugger Adaptor page 175
Ada and C/C++ Mixed Language Projects page 176
Assumptions page 176
The SNiFF+ Ada Make Build Tool page 177
165

20.1 What You Need (General)

By default, SNiFF+ uses GNU gmake (bundled with SNiFF+) and GNAT
gnatmake for building Ada Projects.
The GNAT gnatmake utility, aided by SNIFF+ Build Support, follows code
dependencies and calls the necessary tools for building your Projects.
For all the necessary tools to work together properly, including also C/
C++ compilers etc. in mixed language Projects, your system (tools, libraries, paths etc.) must naturally be correctly configured.
The following GNAT versions are supported
either GNAT Pro 3.15 or newer (recommended)
or, at least, the public domain GNAT 3.14 or newer
20.2 GNAT and Tornado/VxWorks Requirements

If you do not use Tornado/VxWorks , ignore this section and continue
with Run the GNAT Integration Script page 170.
To build Ada and mixed language (Ada/C/C++) Projects using Tornado/
VxWorks 2.x or 3.x (AE), you need the following:
one of the GNAT versions listed under What You Need (General) page
166, as well as
the corresponding (2.x or AE) GNATPro for VxWorks package(s) for your
target CPU(s)
a Tornado/VxWorks 2.x or 3.x (AE) integration with SNiFF+

Please refer to the SNiFF+/Tornado Integration Guide for details in this
respect.
20.2.1 Check Preferences

By default, the command for calling the debugger is set for PowerPC in
SNiFF+, so if this is not your target CPU, you will need to change this. To
do so,
166
Choose Tools > Preferences...
In the Preferences, click the Debugger Adaptors node (under Tools).
Modify the entry in the Executable field (the command line calling the
debugger) as needed.
Ada Projects
GNAT and Tornado/VxWorks Requirements
20.2.2 Windows Only: Platform Settings

If you use the SNiFF+/Tornado integration on Windows, you need to
change a few SNiFF+ Platform and Build Tool settings. The best way to
do this is to copy an existing SNiFF+ Platform and then make the necessary modifications in the copy.
Platform settings are stored at Workspace level, so open the Workspace
Manager
Choose Tools > Workspace Manager.
Highlight the Workspace for your Tornado Projects, and choose Workspace > Properties...
In the Workspace Properties

First, make a copy of your target Platform.
Choose the Definition node (under Platforms, see Figure 20-1 Make a
Platform Copy page 168).
Select your target Platform, and click Copy.
In the box that appears, enter a name for the copy.

(Do not close the Workspace Properties yet!)
20
167

Figure 20-1
Make a Platform Copy
After creating a copy Platform, you need to modify four settings in the
copy (you do all this in the Workspace Properties).
The first two relate to the location of Build output products and the setting
of the default Platform. The other two settings both relate to the output
file name extension (.exe).
Note that these latter two (Build Tool) settings are described here for
convenience (to keep all the Tornado/VxWorks-related information in one
place), you can only actually modify (see) them after you have integrated
GNAT (see Run the GNAT Integration Script page 170).
Platform Settings
In the Workspace Properties, select the Platforms node (see Figure 20-2
Set the New Platform page 169).
At top of the Settings group, select the name of your newly created copy
platform from the drop-down.
In the Redirection Directory field, modify the name to be the same as

the Platform name.
This is optional, but recommended for consistency.
168
Ada Projects
GNAT and Tornado/VxWorks Requirements
Figure 20-2
From the Default Platform drop-down, again select the name of your
newly created copy platform.
Set the New Platform
Note the Note under the Default Platform field!
Build Tool Settings

These settings are only possible after integrating GNAT (see Run the
GNAT Integration Script page 170).
In the Workspace Properties, select the Build Tool Settings node (see
Figure 20-3 Change the Output File Name Extension page 170).
In the Platforms drop-down, make sure your new platform is selected.
In the Build Tools List, select Ada Make

If you cannot see a Build Tool named Ada Make, you have not yet integrated GNAT (see Run the GNAT Integration Script page 170).
In the Derived File Signature field, change the value ( *.out) to read
*.exe
169
20

Now, select the ADA_MAIN_UNIT field and, in the edit field below the
Field/Value table, modify the value to read
`basename %OutFile% .exe`

That is, change the out to exe.
Figure 20-3
Change the Output File Name Extension
This completes the necessary Tornado/VxWorks related steps (on Windows, where applicable).
20.3 Run the GNAT Integration Script

The GNAT integration script sets a number of defaults that allow building
and debugging Ada targets from within SNIFF+ (see What the GNAT
Integration Script Does page 171).
170
Ada Projects
What the GNAT Integration Script Does
On Windows
From Start > Programs, choose

SNiFF+ 4.1 > Integrations > Install Additional Integrations
This will start the integration script.
On Unix
Run SNIFF_DIR4/integrations/install.sh
On Unix and Windows
Select the GNAT integration option offered by the script.

You can generally accept the defaults suggested by the script.
20.4 What the GNAT Integration Script Does

The following outline will, in most cases, simply serve as background
information. The modifications described are all automatically done by
the GNAT integration script and will therefore normally not require any
action by the user.
The exceptional cases that require user action are specifically pointed
out.
The most visible effect of the script is that a new GNAT Pro menu
appears in the SNiFF+ Project Browser.
This menu provides direct access to some GNAT functionality and the
GNAT documentation.
The integration, less visibly, also modifies the SNiFF+ Build Support system.
One of these automatic modifications, which you need look at only if

you do not use GNU gmake, is described under Modification of Build
Support (Native Make) page 172.
The other Build system modification done by the integration script is

the setting for the generation of Ada macros used by gnatmake.
This is a setting that you need only check for Workspaces (if any) that
were created prior to running the GNAT integration script. How to proceed in this case is described under Generation of Ada Macros in
Old Workspaces page 174.
171
20

20.4.1 Modification of Build Support (Native Make)

Note: This section is only important if you do not use GNU gmake !
Using SNiFF+ Build Support, recursive dependency- and date-checking
is delegated to gnatmake. The gnatmake utility is in turn called from
SNiFF+ by GNU gmake. If you do not use GNU gmake, make sure your
(native) make always calls gnatmake to build the target (see below).
The GNAT integration script modifies one of the SNIFF+ Build Support
file templates by introducing a phony target as described below. This
modification is necessary in order to force a call for gnatmake at every
Build request. If this is not done, targets will not be rebuilt after source
modifications.
If you do not use gmake, after running the GNAT integration script, open
the file:
SNIFF_DIR4/config/templates/template.general.incl
Look for the following lines (near the end of the file):
ifdef ADA_SEARCH_PATH
.PHONY: $(PROJECT_TARGETS)
endif
Change the line:

.PHONY: $(PROJECT_TARGETS)
to a syntax that your make utility understands. Remember, the object of
the exercise is to force a call for gnatmake which will handle date and
dependency checking. Here, this is achieved using the .PHONY target,
which never exists.
Save and close template.general.incl
Update Build Support Files

If you had to modify the Build Support template file as described above
(Modification of Build Support (Native Make) page 172), and if you
already have existing SNiFF+ Projects, you will also have to update the
Project-specific Build Support files as described below.
Open you Ada root Project in SNiFF+, and from the menu, choose
Build > Update Build Support Files...
172
In the box that appears, be sure to select Force Update, and click OK.
Ada Projects
Check Workspace Settings
Figure 20-4
Force Update of Build Support Files
This will ensure that the relevant Project Build Support file is also
recopied from the template you edited above.
20.5 Check Workspace Settings

Of the settings below, checking on the Workspace Default Platform
page 173 is recommended in all cases.
On the other hand, checking Generation of Ada Macros in Old Workspaces page 174 will only be necessary for Workspaces created prior
to running the GNAT integration script.
First, make sure that all Projects are closed (at least in the Workspace(s)
you want to set).

To open the Workspaces Properties, double-click on the Workspace that

holds Ada Projects
If you want to set more than one Workspace, repeat the procedure below
for each one.
20
20.5.1 Workspace Default Platform

Checking that the correct default Platform is set for Workspaces can help
save you from irritating checks (pitfalls) later.
In the navigation tree at the left, select the Platforms node.
In the Platforms node, make sure the correct platform is selected in the
Default Platform drop-down.
173

20.5.2 Generation of Ada Macros in Old Workspaces

Generation of Ada-specific macros (e.g. the ADA_SEACH_PATH macro,
referenced also in the file mentioned under Modification of Build Support
(Native Make) page 172) is set at Workspace level.
Again, you need only verify this setting for Workspaces that were created
prior to running the GNAT integration script. All subsequently created
Workspaces will already have this flag correctly set.
Select the Advanced Build Settings node (under Build Tool Settings).
Select the Generate Ada Macros checkbox.
Figure 20-5
Generate Ada Macros
Close the Workspace Properties
174
Click OK to close the Workspace Properties.
Close the Workspace Manager.
Ada Projects
Setting Ada Targets and Debugger Adaptor
20.6 Setting Ada Targets and Debugger Adaptor

These steps can be completed either in the Build-Target Setup Wizard.
(A hands-on tutorial in the Beginners Guide for C/C++ Projects discusses these steps as they are applied in the Build-target Setup Wizard.)
To access the Project Properties, choose

Figure 20-6
Project Properties Build options
20
175

Target Definitions
Make sure the Project containing your main procedure is highlighted in

the tree on the right.

At this point, all you do is associate a target name with the Project. The
type of target is defined in the next step.
Enter the name of your main procedure.

When you close the box, the target name appears highlighted in the
Target Definitions list.
Settings for Selected Target
From the Build Tool drop-down, select Ada Make.

This is the SNiFF+ Build tool that calls gnatmake.
Selecting Ada Make enables the Debugger Adaptor drop-down.

Select either:
gvd 1.2.x (unix) or

gvd 1.2.x (windows)
as appropriate.
if you are using Tornado/VxWorks, select gvd 1.2.x (vxworks)
For Ada Projects, you can ignore the rest of the settings.
Close the Project Properties, and choose Project > Save All.
You are now ready to build the Project.
20.7 Ada and C/C++ Mixed Language Projects

20.7.1 Assumptions
The following description applies to mixed language Projects where the

main procedure is in Ada. To build targets with a C/C++ main, please
refer to the GNAT documentation.
Note that mixed language Project implies that all source files (Ada and
C/C++) are in the same SNIFF+ Project tree.
176
Ada Projects
Ada and C/C++ Mixed Language Projects
A basic requirement for building mixed language Projects is that you have
all the necessary tools installed, and that these are mutually compatible
and properly configured.
In other words, a build using SNiFF+ Build Support will only be
successful if a command-line build would also work.
20.7.2 The SNiFF+ Ada Make Build Tool

If your main program is in Ada, all you have to do is pass gnatmake the
compiled C/C++ object or archive files as linker arguments.
You do this in the last field of the SNiFF+ Ada Make build-tool.
The tool is called in the main procedures Project (see Setting Ada Targets and Debugger Adaptor page 175, above).
To open the Project Properties, choose

In the Project Properties
Make sure the Project containing the main Ada procedure is highlighted.
In the Build Options node, make sure an executable target has been set
(see Setting Ada Targets and Debugger Adaptor page 175).
In the Build Tool Settings (see Figure 20-7 Selections in the Build Tool
Settings page 178):
In the Platform drop-down, verify that the correct Platform is selected.

(If not, you might also want to set the default in the Workspace Properties later.)
In the Build Tools list, select Ada Make.
Now select the ADA_POST_FLAGS field from the table of Field/

Value settings.
177
20

Figure 20-7
Selections in the Build Tool Settings
With ADA_POST_FLAGS highlighted, enter:
-largs
followed by a space and the name(s) of the object files and/or libraries
(recommend if many C/C++ files) created from C/C++ sources that you
want to link with Ada products.
Arguments must be separated by a space (or, if you use the Edit...
button, enter one argument per line).
Enter the object/archive file names with extension, and with the path
relative to the location of the executable target.
Note: Relative here can mean different things, depending on how your
build system is set up.
Objects/libraries in the same directory as the executable are always

entered without path specification.
If you use the standard SNiFF+ Build setup, that is with object redirection to subdirectories relative to the Workspace root directory, enter
the paths as follows
../relative_path_to_subdir/$(OBJ_DIR)/file.o
whereby $(OBJ_DIR) will be expanded by SNiFF+.
178
Ada Projects
Ada and C/C++ Mixed Language Projects
If you redirect Build output to an absolute location, simply enter
-largs %objects%
This syntax will be expanded to absolute paths by the SNiFF+ Build
service.
When you are finished, you will probably want to set these Project arguments for other Platforms as well, so click
Edit Multiple Platforms...
In the dialog box that appears, select the Overwrite tab, and then select
and set the required Platforms.
When you are finished you will notice that the icon next to the
ADA_POST_FLAGS has changed to a Project icon, indicating that the
setting is Project-specific, and does not apply to all Projects in the Workspace (you can right-click on the icon and use the context menu to promote the setting to Workspace level if this is what you want).
20
179

180
21
JAR, Java IDL, JNI, and RMI
Settings
Overview
Summary of Steps page 182
Set Project Targets and Build Tools page 182
Check Tool Settings page 183
Java Archive Builder page 184
IDL Java Compiler page 184
Java Native Interface Compiler page 184
RMI Stub Compiler page 185
181

21.1 Introduction
This chapter outlines the procedures for setting up Project Targets and
settings for the following preconfigured Build Tools:
Java Archive Builder to create *.jar archives from class files.
IDL Java Compiler to generate *.java files from IDL files.
Java Native Interface Compiler to generate *.h interface files from

java files.
RMI Stub Compiler to generate skeleton/stub *.class files (from

class files) to be used for remote method invocation by clients.
21.1.1 Summary of Steps

SNiFF+ Build Tools always have to know which Projects are targeted.
Once SNiFF+ knows a Target name and the Build Tool the target is associated with, the target can be built using the SNiFF+ Build menu.
First, set Project Targets and associate Build Tools.
Then, check Build Tool Settings.
21.2 Set Project Targets and Build Tools

Use the following guidelines for Project selection and Build Tool association.
Note that where Targets depend on classes as input, these will have to
exist (be built) first.
Java Archive BuilderTarget Project contains classes you want to

archive as a JAR.
Normally, the Target Project must contain *.java files, so that SNiFF+
Build Support works correctly.
Alternatively, if the JARs should also incorporate Projects without
*.java files, this can be set in Workspace Properties (Advanced Build
Settings, Always Generate Java Macros checkbox).
Note also that the Target Projects entire package tree is archived unless
explicit directory paths are set!
182
IDL Java CompilerTarget Project contains IDL files you want to generate Java files from.

Check Tool Settings
Java Native Interface CompilerTarget Project contains classes you

want to generate *.h interface files for.
RMI Stub CompilerTarget Project (server-side) contains classes with

methods that will be invoked remotely by client-side applications.
In the Project Properties
In the Project Properties, Build Options node, highlight the Project you
want to set a Target for (see also below for guidelines).
Click New, and, in the box that appears, enter a name for the Target.
Highlight the Target, and in the Build Tool drop-down, associate a Build
Tool with the Target.
21.3 Check Tool Settings
Select the Project Properties, Build Tool Settings node.
In the Project Tree on the right, make sure the Project you have created
the Target for is highlighted.
In the Build Tools list select the tool you want to check.
Under the Command, you will see the selected Build Tools Fields and
their assigned Values.
In the following, only the most commonly needed options (Fields) for the
respective tools are mentioned.
Please refer also to the (Java) tool-specific documentation for syntax of
tool options.
21
183
21.3.1 Java Archive Builder
JAR_FILES
By default, all classes in the package tree that the Project belongs to are
archived.
If you do not want to archive all classes in the package tree, click Edit, and
enter the names (with .class extension) of the classes you do want to
include. Direct entries (not using the Edit button), are separated by blanks.
If you only want to include certain (sub-) directories (=Subprojects), enter the
directory path.
For example, backoffice/*.class, this will archive only classes in
backoffice, and will not consider the rest of the package tree.
JAR_FILES_OPTION
If you use JDK 1.1.x this field should be set to
`cat $(@F).lst`
The ` (accents graves, or backticks) above are necessary!
If you use SDK 1.2.x or higher this field should be set to
@ $(@F).lst
21.3.2 IDL Java Compiler
IDLJ
Make sure the value here corresponds to the compiler you have installed
(generally either idlj or idltojava).
IDLJ_FLAGS
If you have to change the IDLJ value, you will also need to check the flags
passed to the new compiler; see your compiler documentation for details.
21.3.3 Java Native Interface Compiler
JNI_CLASSES
Click Edit to enter the names (without .class extension) of the classes for
which native interfaces need to be compiled.
Note: The location of C/C++ shared library for which the interface is generated,
and which is subsequently used by the Java application has to be set outside
of SNIFF+.
On Windows, make sure the PATH environment variable points to the

location of the *.dll files used by the Java application.

Check Tool Settings
On Unix, make sure the LD_LIBRARY_PATH environment variable

points to the location of the *.so files used by the Java application.
21.3.4 RMI Stub Compiler
RMI_CLASSES
Click Edit to enter the names (without .class extension) of classes
whose methods will be invoked remotely by clients.
21
185

186
22
IDL Projects
Overview
IDL File Types page 188
IDL Interface File Type page 188
IDL Derived File Types page 188
Projects and Derived File Types page 189
What to Do page 189
Requirements page 189
Adding File Types page 190
Adding Files page 190
How File Compilation Works page 190
Browsing IDL page 191
How IDL Information is Mapped by the IDL Parser page 191
187

22.1 Introduction
This chapter outlines the steps for generating IDL client- and server-side
output ( *C.cc and *S.cc , respectively, as well as the *.hh files)
using SNiFF+ PRO Build Support.
The chapter closes on a few notes on browsing IDL code with SNiFF+.
22.1.1 Assumptions
We assume
you have an IDL compiler
you have a SNiFF+ Build Support license
you are familiar with the fundamental SNiFF+ concepts of Workspaces

and Projects.
22.2 IDL File Types

The following are IDL File Types; the names used below conform to
those used in the SNiFF+ File Types (as defined in the Preferences).
22.2.1 IDL Interface File Type
IDL-Interface files (*.idl) are compiled with an IDL compiler to produce

the Derived File Types listed below.
22.2.2 IDL Derived File Types

SNiFF+ distinguishes between normal File Types (for example an IDL
Interface file) and Derived File Types (see below). The File Types derived
from the IDL Interface File Type are:
188
IDL-Client Implementation (*C.cc)
IDL-Server Implementation (*S.cc)
IDL-Header (*.hh)
IDL Projects
Projects and Derived File Types
22.3 Projects and Derived File Types

Projects for creating IDL output make use of the following SNiFF+ features.
SNiFF+ Projects are not constrained by the file system.

In the present context, this means that, although Projects are created per
file system directory, they can reference files physically located outside
that directory. Furthermore, this implies that multiple Projects can reference the same files.
The SNiFF+ Derived File Type concept.

IDL output files are defined as so-called Derived File Types.
A Derived File Type means that, if a Project knows of a given Derived
Type, SNiFF+ will know both how to create it, as well as what to do with
it once it exists. All without your having to explicitly add any newly
created files to the Project.
Conversely, if a Project does not know of a Derived Type, it will do
nothing. This allows automatic generation of Client and Server Implementation files, that are derived from the same IDL Interfaces, to different
directories.
22.4 What to Do
22.4.1 Requirements
All IDL-derived files must be somewhere below (or be generated to) the
same Workspace Source Root.
You should know where (to which directory) you want IDL-client files to
go, and where you want the server files to go. These are referred to as the
IDL output target directories.
A SNiFF+ (Sub-)Project must exist for each IDL output target directory.
All such (Sub-)Projects are referred to in the following as the Project.
The IDL-Interface (*.idl) source files for generated output per target
directory must be added to the Project. The physical location of the
IDL-Interface files themselves is irrelevant; they need not lie in the same
Project directory.
189
22
22.4.2 Adding File Types

The trick here is that you add (Derived) File Types for files that do not necessarily exist (yet).
If the target directory is to be for server-side files only (*S.cc and *.hh),
add the following File Types to the directorys Project:
IDL-Server Implementation
IDL-Header
IDL-Interface
Do not add the IDL-Client Implementation File Type!
If the target directory is to be for client-side files only (*C.cc and *.hh), add
the following File Types to the directorys Project:
IDL-Client Implementation
IDL-Header
IDL-Interface
Do not add the IDL-Server Implementation File Type!
When you build the Project, the correct IDL-compiler output files will be generated to the correct place; subsequently the *.cc files will be automatically
compiled by the C++ compiler.
You can of course generate both client- and server-side files to the same directories. In this case you would add all 4 IDL File Types to the Project(s).
22.4.3 Adding Files

For each directory where you want IDL output to be generated, add the corresponding source (=IDL Interface) files to the directorys Project.
22.5 How File Compilation Works

First, the IDL compiler is called for the IDL Interface files ( *.idl ) and,
depending on which Derived File Type the Project knows, either IDL-Client
(*C.cc) or IDL-Server (*S.cc ) Implementation files are created. Then, the
C++ compiler is called to compile these files to object files.
IDL Projects
Browsing IDL
22.6 Browsing IDL

To browse IDL code with SNiFF+, you need the SNiFF+ IDL Parser to
extract symbol information. This parser is separately licensed, and must
be separately purchased.
22.6.1 How IDL Information is Mapped by the IDL Parser

The SNiFF+ IDL Parser maps symbol information from IDL files to C/C++
data types according to the following mapping scheme:
Information in IDL
C/C++ data type
definition of an interface and its

base interfaces
class definition and base classes
definition of a type
type definition
definition/usage of a constant
constant
definition/usage of an attribute
instance variable
definition/usage of an operation
function
Note
Modal parameters (in, out, inout) and context arguments in IDL do
not have corresponding C/C++ data types.
22
191

192
23
Custom Build Setup
Overview
Projects with Custom Build Systems page 194
Project Creation Wizard for Custom-Build Projects page 194
Project Templates for Custom-Build Projects page 195
Enable Menu Commands for Custom-Built Targets page 195
193

23.1 Introduction
Custom Build as used here refers to a Build System where you already
have your own make and make support files in place to control your
product-builds. In this case you may want to continue using your own
system and not change to using (full) SNiFF+ Build Support. However, by
appropriately identifying executable targets, you can still build, run and
debug these from within SNiFF+ using the Build menu. You might also
find it useful to use SNiFF+s Build Support files (for example, generated
dependency information) for your own custom Build Support.
23.2 Projects with Custom Build Systems

You can apply both the normal SNiFF+ Project-creation methods, that is,
the Project Creation Wizard or Project Templates, for creating custombuild Projects.
For existing Projects, SNiFF+ Build Support can be enabled/disabled at
any time in the Project Properties.
23.2.1 Project Creation Wizard for Custom-Build Projects

If you import existing code into SNiFF+ using the Project Creation Wizard, it disables the Build Support option by default if it detects files that it
recognizes as a Makefiles in the source code location directories (see
Figure 23-1 Disabled Build Support in the Wizard page 195).
Makefiles are recognized by the file-name patterns specified for the
Makefile File Type in the Preferences.
194
Custom Build Setup

Enable Menu Commands for Custom-Built Targets
Figure 23-1
Disabled Build Support in the Wizard
23.2.2 Project Templates for Custom-Build Projects

As always, you need to create/select a Workspace before you can create a Project based on a Project Template. SNiFF+ provides a number of
templates where Build Support is disabled. The names of the templates
suitable for custom-build Projects are suffixed with _nobuild . In the
Project Template Properties (choose Project > Templates...) of such
preconfigured templates, the Build Support option, together with its associated sub-options are disabled.
If you want to create your own Project Templates, make sure that the
Build Support checkbox is cleared in the Project Templates Properties.
23.3 Enable Menu Commands for Custom-Built Targets

To enable building, running, and debugging of custom-built executable
targets from the SNiFF+ menu:
In the Project Tree (File List, Symbol List, or Project Manger), highlight
the Project corresponding to the directory where the target is to be built.
This Project is referred to in the following as the Target Project.
195
23

Choose Build > Target Setup...
In the Target Setup Wizard
196
Enter the name for the executable target as it appears in your Makefiles;
this name will later also appear in the Build menu. Click Next.
On the next page of the Wizard, select the required debugger adapter
and click Finish.
The following menus will now be enabled in the Build menu when the Target Project (above) is highlighted (the latter two will be enabled once the
target exists):
Build > Build > TargetName
Build > Run TargetName
Build > Debug TargetName
24
Overview
Setting up Remote Build Hosts for Workspaces page 198
Open the Workspace Properties page 199
Make Sure Remote Host(s) can Find Locations page 199
Define Settings for Remote Host(s) page 200
Setting a Default Remote Host page 201
Verify Project Platform Settings page 202
Working on Remote Hosts page 202
Correct Display Set? page 202
WindowsStandard Output page 203
Remote Java page 203
197

24.1 Introduction
You can build, run and debug applications from Windows to Unix, or Unix
to Unix.
All initial settings to do with building/running/debugging applications on
remote machines are defined at Workspace level.
Once you have set up the remote host(s) in the Workspaces, remember
to verify that Project Properties (debugger...) are also correctly set for the
remote machines Platform.
24.2 Setting up Remote Build Hosts for Workspaces

The steps for setting up your system to be able build/run/debug applications on remote machines are:
Make sure remote host(s) can find source files.

Each Workspace has its own Source Root location, which will not necessarily look the same for all machines on the network. A Unix machine
will, for example, not be able to find a Windows mapped network drive.
Define (settings for) remote host(s).

All Workspaces will know the same remote host machines once you
define them.
198
Optionally, define a remote machine as the default host to build, run, and
debug applications using a given Platform.
Verify that Project Properties are correctly set for the remote hosts Platform.

Setting up Remote Build Hosts for Workspaces
24.2.1 Open the Workspace Properties

In the Workspace Manager, highlight the Workspace you want to define

remote settings for.
Close all Projects that use the selected Workspace.

You cannot edit the necessary Working Properties if Projects are open.
To open the Workspace Properties dialog

24.2.2 Make Sure Remote Host(s) can Find Locations
Select the Advanced node (under General)

If none of the fields are writable, this means that there are Projects
opened in the current Workspace. So, close all open Projects that use
the Workspace.
In the (Source Root Location) As Seen From Remote Host field, enter
the path to the directory specified in the Local field (that is, the Source
Root Location) as the remote host would see it.
If the remote host(s) sees the Source Root exactly as it is specified in the
Local field, you can leave this field blank.
If you use multiple remote hosts, all of them must be able to find the
directory using this path.
Caution: Not all debuggers support the use of environment variables. To
be in the safe side (for this and other reasons), we recommend that you
enter an absolute path without environment variables in this field.
To improve build performance on a remote host, you can specify an absolute path to redirect build output to the build host, rather than having to
write output back over a network file system. You do so in the
(Absolute Redirection Directory) Remote field.
24
199
24.2.3 Define Settings for Remote Host(s)

While the Source Root location you defined above is unique to each Workspace, there is no reason to keep host-machine data specific to individual
Workspaces. That is, host machines you define for one Workspace are actually global, and will be recognized by all Workspaces.
Figure 24-1
Remote Host Settings are Global
To create a new remote host:
In the Remote Build Host Settings node, click the New button. In the box that
appears, enter a name for the host.
The name you enter is a label used by SNiFF+ (and you) to identify the host
machine and its associated settings.
In the Name field, enter the machine name as you address it when you log in
on the remote machine.
In the Username field, if you access the remote machine with the same username as on the local machine, leave this field blank.
In the Password Request field, enter the string used by the remote system to
prompt you for your password (not your password itself).
In the Wait field, enter the number of seconds to delay execution in order to
ensure that a shell is up, running, and ready to execute.

Setting up Remote Build Hosts for Workspaces
24.2.4 Setting a Default Remote Host

Once you have defined remote hosts, you can set a default host to be
used per defined Platform. These defaults are specific to each Workspace.
Figure 24-2
In the Workspace Properties, select the Platforms node (under Build Tool
Settings).
Setting a Default Host for a Platform
From the drop-down near the top, select a Platform that conforms to a
remote host operating system.
From the Default Remote Build Host drop-down, select a default host to
associate with the Platform you selected above.
Whenever you build using the selected Platform, this host will be used by
default.
24
201

24.3 Verify Project Platform Settings

Once you have defined remote machines, open the Project you want to
build/run/debug remotely. Then, choose
Project > Properties
In the Project Properties, check/update Build-related settings for the
remote machines Platform.
For more information in this respect, please refer to the appropriate (programming-language-specific) chapters in the SNiFF+ PRO Build/Debug:
How To page 137 section of this manual.
24.4 Working on Remote Hosts

Remote build/run/debug is almost the same as working locally. There
are, however, one or two things to look out for.
24.4.1 Correct Display Set?

When you start running or debugging an application on a remote host, a
dialog box opens that, among other things, lets you set the display.
By default, this is set to the local machine. But:
Local means: the machine where SNiFF+ is running.

For example, you are sitting at a Windows box (WinBox ), running
SNiFF+ on a Unix machine (Unix1), and you want to debug on another
Unix machine (Unix2). The default display setting will be to Unix1
(where the SNiFF+ session is running), and not to WinBox.
202
Furthermore, will remote machines recognize the name (WinBox) as

the local machine sees it? If not, set the Display to the IP address of, in
our example, WinBox.

Working on Remote Hosts
Note also that, if you do not use the IP address, set the display name
without the terminating :0.0.
If this does not work, and you have to use the terminating :0.0 to set
the display name, then you can modify the following file
SNIFF_DIR4/config/templates/remote_build.sh
Look for:
DISPLAY=$2:0.0
and change it to DISPLAY=$2
24.4.2 WindowsStandard Output

On Windows, make sure an XServer is running.
24.4.3 Remote Java

To build Java Projects on a remote machine, the build(debug)-host must
be able to find the sniffjmake executable on the remote host (located
in SNIFF_DIR4/bin).
24
203

204
25
Modifying Build Tools and
Settings
Overview
The C++ Compiler Example page 206
The Java Compiler page 206
Where to Change the Tool Settings page 206
Changing Site-Level Preferences page 207
Changing Workspace Build Properties page 208
Create a Copy of the Platform page 209
Change the Values page 209
Editing Field Values for Multiple Platforms page 209
Set the New Platform as the Default page 209
Save and Check In the Changes page 210
Synchronize Workspace Build Properties page 210
Properly Version-Controlling Build Properties page 210
205

25.1 Introduction
The SNiFF+ Build System uses Platforms to maintain information about
which tools are used to build targets for which operating system, and how
the target is to be built (for example, with or without debug information). A
number of these Platforms are preconfigured and supplied with
SNiFF+. Should you want to use, for example, a compiler other than the
one set in a preconfigured Platform, you can either change the settings in
an existing Platform or create a new Platform (copy of an existing one),
and change settings there.
25.1.1 The C++ Compiler Example

In the following, the C++ Compiler is used as an example to illustrate the
steps involved. This is to simplify the description; the procedure will be
analogous for any tool used in the build process.
25.1.2 The Java Compiler

Note that, if you want to change the setting for the Java compiler
(javac), you have to modify the Build Tool called SniffJMake.
25.2 Where to Change the Tool Settings

Whereas settings as to which flags are passed to, for example, a compiler might be set at Project-, or even file-level, the settings for which
compiler, or any other tool, is to be used in the build process, should be
set at Workspace and/or Preference level.
206
To change settings for existing Projects, that is in existing Workspaces,

you should modify them in the Workspace Properties. It is, however also
possible to modify Project Properties, and to then globalize the modifications. This procedure, which is not generally recommended, is
described under Promoting Project Build Tool Settings to Workspace
Level page 147. Note also that, if you want to globalize from Project
level, the Workspace Build Properties must be writable (checked out).

Where to Change the Tool Settings
To ensure that all newly created Workspaces use the changed settings,
you would change them in the Site-Level Preferences.
Once you are in the Preferences, the procedure is exactly the same as
you would go through at Workspace level.
So, below, we will only describe how to get to the right place in the Preferences. Once you are there, you can simply follow the steps as outlined
for Workspaces.
25.2.1 Changing Site-Level Preferences

To open the Preferences, choose
Tools > Preferences....
In the Preferences
Do you see two tabs, User Level and Site Level?

If you do not see a Site Level tab, this means you do not have write
permissions to the appropriate file. Generally, an administrator is
appointed to ensure that things like site-wide settings remain consistent.
And only this person should therefore be allowed to modify site-level
Preferences. If you are that person, you need to have write permissions
to the file:
SNIFF_DIR4/config/SitePrefs.sniff.V<n>
(the <n> is an internal version number).
If you need to change the permissions, the Site Level tab will be visible
the next time you start SNiFF+.
Select the Site Level tab.
In the tree on the left, select Build Tool Settings.

From here on, the procedure is exactly the same as that followed in the
Workspace Properties for existing Workspaces. (Remember, the Preferences only provide default templates for newly created Workspaces.) So,
please continue as outlined under In the Workspace Properties page
208.
25
207

25.2.2 Changing Workspace Build Properties

If you use a version control system, you may first have to check out the
Workspace Build Properties information. To do so
Highlight the Workspace you are interested in and choose
Workspace > Build Properties > Check Out
In the Check-Out dialog box, use the Exclusive option.
(Build Properties are not something everyone should be hacking around
in at the same time.)
To open the Workspace Properties, choose

In the navigation tree at the left of the Properties, select the Platforms
node.
From the Default Platform drop-down, select the platform that corresponds most closely to the compile-time requirements you need most
often.
Now, in the navigation tree, select the Build Tool Settings node.
In the Build Tools list select the C++ Compiler

(Remember we are using the C++ compiler as an example, but the
procedure will be analogous for any of the tools used by the Build
system.)
Take a look at the Command field.

The Command field displays the template command (defined in the
Build Tool Templates node) that is issued to call the C++ compiler.
The first field in the command is, naturally, the actual tool-call (must be
assigned the name of the compiler executable that is called). The field
itself, in the case of the C++ compiler, is named CXX (default field name).
In the tool settings below the command, the CXX field is assigned a
value, namely the name of the compiler to call (for example, gcc, cl ,
etc.).
208
To call a different compiler, you can do one of two things:
Edit the value of the CXX field, and also the values for the various
options.
Or (recommended and described below) create a copy of the Platform, and then modify the values in the copy.

Where to Change the Tool Settings
25.2.3 Create a Copy of the Platform

In the tree at the left, select Definition
(under the Build Tool Settings > Platforms node).
In the Platforms list, select the entry that corresponds most closely to
your compile-time default requirements.
Click Copy and, in the box that appears, enter a name for the new Platform.
The name of the new Platform appears in the list.
Assuming you made a copy of a debug variant of a platform, you will

probably also want a release variant. So, make another copy to modify
for this variant.
25.2.4 Change the Values
Now, go back to the Build Tool Settings node.
In the Build Tool Settings node, from the Platforms drop-down, select
the Platform you have just created.
In the Tool Settings, select the fields where you want to modify values,
and in the Edit field below, make the appropriate changes.
Repeat the procedure for the second copy (release/debug variant) of the
Platform.
25.2.5 Editing Field Values for Multiple Platforms

If you want to set/edit a field value for multiple Platforms, use the
Edit All Platforms... button.
This dialog box is especially useful if you want to selectively set the same
or similar field values for multiple platforms.
25.2.6 Set the New Platform as the Default

Dont forget to change the Default Platform:
In the navigation tree at the left, select the Platform node.
In the Default Platform drop-down, select the newly created platform you
want to use by default.
When you are done, click OK to close the Workspace Properties.
25
209

25.2.7 Save and Check In the Changes
Back in the Workspace Manager, choose

Workspace > Save All
To make the modified Build Properties available in other Workspaces

(your own, and those of others), make sure the Workspace whose Properties you have just modified is still highlighted, and choose
Workspace > Build Properties > Check In
25.2.8 Synchronize Workspace Build Properties

To synchronize the Build Properties of other Workspaces, highlight each
one in turn, and choose
Workspace > Build Properties > Synchronize
If you do not have write permissions in Workspaces, ask the respective
owners to synchronize their Workspace Build Properties.
25.2.9 Properly Version-Controlling Build Properties

For information on fuller, and more comfortable, version controlling than
the rudimentary functionality provided in the Workspace Manager, please
see Version-Controlling Build Properties page 75.
210
26
Running and Debugging
Targets
Overview
The Application Project page 212
The Build Menu page 212
Running Applications page 212
Debugging Targets page 213
Debugger Startup Dialog page 213
The Debugger Command Line page 213

Command Line Help page 214
Debugger Views and Dialogues page 214
Updating Views page 214
Working With Breakpoints page 214
Variables View page 215
Editing Variable Values page 216
Execution Context View page 216
Memory View page 217
Registers View page 217
Multiple Simultaneous Debugger Sessions page 217
211

26.1 The Application Project

Obviously, you can only run/debug a target once it has been defined and
built. Also the appropriate Debugger Adaptor must be set.
You must therefore have set an executable target (for example using a C
or C++ Linker, or the Java Interpreter ScriptBuilder) for a specific
Project. This Project is referred to as the Application Project.
See also Setting C/C++ Targets and the Debugger Adaptor page 141,
and Setting Java Application Targets and the Debugger Adaptor page
153.
26.1.1 The Build Menu

The Build menu, and therefore also the
Build > Run Platform/ProjectTarget and
Build > Debug Platform/ProjectTarget commands
apply to the highlighted Application Project in either the File Lists, the
Symbol Lists, or Project Managers Project Tree (whichever has focus).
26.2 Running Applications

To run an application, highlight the Application Project (the one you have
set an application target for), and choose
Build > Run Platform/ProjectTarget
A dialog box appears allowing you to enter Arguments you might want
to pass the application, as well as a Working Directory for data (e.g.
images) used by the application.
212

Debugging Targets
26.3 Debugging Targets

To debug, highlight the Application Project, and choose
Build > Debug PlatformTarget
26.3.1 Debugger Startup Dialog

The Debugger Startup dialog box offers a number of debugger start-up
options. These depend on your operating system and the Debugger
Adaptor. For more detailed information on individual options please use
the context help:<F1> key.
You can change various settings (e.g. Working Directory), or pass the
debugger additional options. Do not, however, remove any of the default
options in the Debugger Command (these are needed by SNiFF+).
The default location of the debugger executable can be set in the Preferences. This can also, for example, be a script that calls the debugger.
If you change settings, you can save these to a file using the Store
button. In subsequent debugging sessions you can than Load these
settings again. Both buttons default to the directory holding the target.
If you want to debug Java applications on a remote virtual machine,

please refer to Remote Java Debugging page 160.
For general information about remote debugging and settings, see

Remote Build and Debug page 197.
26.4 The Debugger Command Line

Most debuggers provide a command line interface. Depending on the
back-end debugger used, the command line serves as input/output shell
either for both the application and the debugger itself, or, if the back-end
supports a separate input/output shell for the application, only for the
debugger.
26
213

26.4.1 Command Line Help

At the debugger command line prompt, type help for a summary of
available commands and syntax. The most commonly used commands
can, however, also be posted from the toolbar, the Debugger menu, and
the debuggers Right-click context menu.
26.5 Debugger Views and Dialogues

Depending on the debugger backend you use, various views (described
below) may be available. You can toggle whether these Views are visible
from the View men, using the Right-click context menu, or with toolbar
buttons that appear when you are in debug mode.
26.5.1 Updating Views

For performance reasons, the graphical user interface is not always
updated with every command line entry. You can therefore use the command line to force GUI synchronization. At the debugger command line
prompt, enter sniff to see a list of the available update commands.
26.6 Working With Breakpoints

In debug mode, the Source Editor has a thick, mouse-sensitive left margin (gutter); you can set/see breakpoints here. This margin also has its
own Right-click context menu for global breakpoint-manipulation.
To set a breakpoint, double-click into the left margin of the Source Editor
(make sure the breakpoint is set at a line where there is executable code),
or click into the line you want to break at and use the appropriate toolbar
button, or use the Debug menu, or the command line, or the Breakpoints
dialog box.
The breakpoint is displayed in the margin.
214

Variables View
Breakpoints can be removed analogously to the ways they are set (see
above).
When you have set your breakpoint(s), choose

Debug > Breakpoints > Manage Breakpoints... or
Right-click > Breakpoints...
You can review, enable/disable, add, delete, save and load breakpoints in
the Breakpoints dialog box.
To enable/disable breakpoints click into the checkbox to the left of the

breakpoint description in the dialog box.
A checkmark in the box means that the breakpoint is enabled (active)
and that the programme will therefor stop at the breakpoint.
An empty checkbox means that the breakpoint is disabled (inactive) and
that the programme will not stop at the breakpoint. The line is merely
bookmarked for future use.
In the Source Editors gutter, enabled breakpoints are shown in red,
disabled (inactive) ones in yellow.
Note that in Java files, breakpoints will all be displayed in yellow until
such time as the programme (JVM) loads the class for execution.
Using the dialogs Store button, you can also save the breakpoints (files,
line numbers and enabled/disabled status) for reuse in subsequent
debugging sessions (Load button).
Note, however, that if you load a breakpoint configuration, any breakpoints you have manually set in the current session will be removed.
26.7 Variables View

The Variables View displays (trees of) variables. The variable name is on
the left, its value on the right.
Variables such as pointers, arrays, structs, unions, or classes will be displayed as expandible nodes. By expanding these nodes you can therefore de-reference pointers, browse class or struct members, etc.
After the debugger starts, the Variables View displays three expandible
root nodes:
this variable
In object oriented languages, displays members of current object
instance.
215
26

local variables
Displays arguments and variables defined in the current scope.
display variables
You can add variables to the display node either by entering
display <VariableName> at the command line, or by clicking on
a variable in the Source Editor and choosing
Right-click > Display <VariableName>
Values of variables added to this node are constantly displayed and
updated whenever the debugger gains control, or if you navigate the
programs call stack in the Execution Context View, or if you enter
sniff variables on the debugger command line.
If a displayed variables value changes, the value is shown in red.
Note that, if many variables are displayed in the View, this can slow
debugging considerably. To overcome this you can temporarily collapse
the nodes.
26.7.1 Editing Variable Values

To edit the value of a simple variable, double-click on it.
An entry field will appear, where you can enter the new value.
26.8 Execution Context View
Choose View > Execution Context

This opens a window displaying call stacks per thread.
Whenever your program stops at a breakpoint, the Execution Context
view shows you where the program is and how it got there.
216
The active thread is displayed in bold and has the call stack expanded
with the innermost stack frame on top.
If the frames are within the context of the currently open SNiFF+ Project,
Double-click on a frame to have the Source Editor jump to the call, and
to update data related to this stack frame in other open views.

Memory View
26.9 Memory View

This view is not available for all debuggers.
The Memory view is a read-only view of memory content over a range, in
a format (e.g. hexadecimal, decimal or character), and in entities (e.g.
byte or word) you can specify in fields and drop-downs along the top of
the view.
In the Address/Symbol field, you specify the start of the range either by
the physical hex address, by the symbol name (if the symbol is a pointer
or an array), or using address of symbol name (that is, for example in
C/C++, &symbolname).
In the Count field, enter the memory extent to display, starting from the
address specified above.
The remaining drop-downs along the top of the view allow you to specify
the display format and the entity size appropriate to your memory region.
26.10 Registers View

This view is not available for all debuggers.
The Register View displays a list of the processor register addresses and
their current values.
To change the current content of a register, double-click into the value
(on the right). An entry field appears, and you can enter a new value.
26.11 Multiple Simultaneous Debugger Sessions

One debug session per Project is supported, hence, you can start more
than one debugger within one SNiFF+ session for different Projects.
However, if you want to debug the same target in multiple Debugger sessions, you will have to start new SNiFF+ sessions and launch the Debugger in each of them.
217
26

218
Part VI
SNiFF+ PRO Build System Concepts
SNiFF+ PRO Build System: Introduction
A Closer Look at Build Tools, Tool Settings and Platforms
Inheritance of Build Information
Building Project Structures and Compiling Files

220
27
SNiFF+ PRO Build System:
Introduction
Overview
The Build System and Make page 222
Platforms page 223
Make Command and Redirection Directory page 224
Location of Redirection Directories page 225
Default Platform page 226
Remote Build Host page 226
Build Tools page 226
What is a SNiFF+ Build Tool? page 227
Build Tools and Platforms page 228
Build Tool Examples page 228
Compare Platform Settings page 228
C/C++ Include Directives page 229
Output Formats page 229
221

27.1 Introduction
SNiFF+ does not have its own compiler, debugger, or any other real
tools required in the build process. Instead, SNiFF+ supplies an open
and easily configurable interface to tools of your own choice.
Pre-configured tool-calls are provided for the most common tools and target operating systems. Over and above this, the SNiFF+ Build System is
designed to be able to produce and efficiently manage different kinds of
Build output for one and the same input.
The kind of output produced depends not only on where (which operating
systems) you want your product to run. It also depends on what you want
to do with the output. For example, do you need debug information, or an
optimized release version? SNiFF+ therefore lets you quickly switch
between build variants.
27.1.1 The Build System and Make

The Build process itself is handled by a standard make utility reading
Makefiles. SNiFF+ Makefiles include (that is, reference) a number of generated Build Support files with generated macros, rules, and dependency
information. Build Tool calls and options are therefore also defined using
make syntax.
Although using SNiFF+ Makefiles and generated Build Support files
offers many advantages, you can also use your own Makefiles. Or you
can use your own Makefiles in combination with SNiFF+ Build Support
information, for example, parser-generated dependency lists.
This chapter looks at the SNiFF+ Build System on the basis of the
SNiFF+ graphical user interface (Workspace Properties).
27.2 Assumptions
Workspace.
If not, please refer to Projects and Workspaces page 11, or at least
make sure you know what is meant by the terms Source Root and Generated Files Location (see TerminologySource Root, Project and Makefiles Location, Generated Files Location, and Repository page 21).
222

Platforms
27.3 Platforms
The SNiFF+ Build System uses the Platform as a concept to handle different kinds of output for the same software system.
Platforms are defined as Workspace Properties (defaults are inherited
from the Preferences when a Workspace is created). To look at this,
choose
In the Workspace Manager, choose

Workspace > Properties
In the tree at the left, navigate to the node:

Build Tool SettingsPlatformsDefinition
Figure 27-1
Workspace Properties The Platform Definitions Node
Because the SNiFF+ Build System supports multiple target operating

systems, build-information that is specific to given operating systems has
to be maintained. Furthermore you will generally need at least two prod-
223
27

uct variants per operating system, one with debug information, and
another, optimized release version. All this is done in a set of named
Platform definitions.
In SNiFF+, a Platform is a name, or label, for a set of Build Settings.
Generally, the intention is to produce output variants for a given target
operating system with a given set of tools.
The term Platform is, therefore, no more than a label that expresses this
general intention.
27.4 Make Command and Redirection Directory
Each Platform uses a standard command for calling your make utility.
Build output can be generated to a Redirection Directory.

Always specify a different Redirection Directory per Platform This avoids
problems such as linking together code compiled for different architectures, or accidently linking debug and optimized code together.
224
In the tree at the left of the Workspace Properties, select the Platforms
node (under the Build Tool Settings node).

Make Command and Redirection Directory
Figure 27-2
Workspace Properties The Platforms Node
Platform
27.4.1 Location of Redirection Directories

Redirection Directories for Platform output will usually be relative.
If you simply enter a string, build-output for the selected Platform is redirected to a tree under a subdirectory with the name you enter.
This subdirectory (actually a subdirectory-system in non-Java languages)
will be either under the Generated Files Location (General Properties),
or appended to an absolute path if you specified one (Advanced Properties).
If you enter an absolute path, build-output for the selected Platform is

redirected to a tree under the path you entered. If an absolute paths is
already entered in the Advanced Properties node, it will be overwritten.
27
225

27.4.2 Default Platform

A default Platform can be set per Workspace. This means that, unless
you explicitly change the Platform in the Builder window, a build command issued from the SNiFF+ menu will use the settings defined for the
current Workspaces Default Platform.
27.4.3 Remote Build Host

A Remote Build Host is a real, compile-time machine. That is, you can
set a specific, remote host (Unix) machine for the Build to run. (It has to
be a Unix machine so that remote login works.) Remote Build Hosts can
be defined in the Workspace Properties Remote Build Host Settings
node.
27.5 Build Tools

Build Tools in SNiFF+ are not to be confused with real tools (e.g. a specific compiler). A SNiFF+ Build Tool consists of a Build Tool Template (a
generic abstraction), and Build Tool Settings, whereby the real tool that
is used is just one of these settings. Also, you must have the real tool
installed, and in your PATH (or use absolute paths in the setting).
226

Build Tools
Figure 27-3
In the navigation tree at the left, select the Build Tool Settings node.
Workspace Properties The Build Settings Node
27.5.1 What is a SNiFF+ Build Tool?

A Build Tool in SNiFF+ is in fact mostly a tool call.
For example, one SNiFF+ Build Tool is named C++ Compiler. The template for this Build Tool is a call for a (any) C++ compiler. Which specific
compiler (e.g. g++, or cl ...) is called is one of a number of Build Tool
Settings, as are the flags that are passed to the specified compiler.
27
227

27.5.2 Build Tools and Platforms

The various Build Tools needed for building output targets are configured using the Platform concept described earlier. That is, all commands
and flags for all build-related tool calls (compiler, linker, etc.) are grouped
under the label of a Platform . The same generic Build Tool Template can
therefore use different Build Tool Settings per Platform.
Pre-configured tool calls are provided for most standard tools on common operating systems.
27.6 Build Tool Examples

Take a look at a couple of example Build Tools and various Settings for
different Platforms.
27.6.1 Compare Platform Settings

In the Workspace PropertiesBuild Tool Settings
(Illustration: Figure 27-3 Workspace Properties The Build Settings
Node page 227)
228
From the Platforms drop-down, choose Windows-Native-debug
In the Build Tools list, highlight C++ Compiler
Take a look at the value in the CXX field, you will see that the field is set to
the cl (unless you, or someone else, has changed it).
Now, from the Platforms drop-down, choose Unix-GNU-debug
Take a look at the value in the CXX field, you will see that the field is set to
the value gcc.
Now check the correspond -release Platforms, and notice the different
values in the CXXDEFINES and the CXXFLAGS fields.

Build Tool Examples
27.6.2 C/C++ Include Directives

For C/C++ Projects, SNiFF+ can generate include-paths that are passed
to a compiler.
In the Build Tools list, highlight the C++ Compiler
Take a look at the value in the CXXINCLUDES field, you will see that the
field is set to the $(SNIFF_INCLUDES).
The $(SNIFF_INCLUDES) macro will expand to the include paths
generated at Project-level. So, do not delete this macro!
If you want to add additional global includes at Workspace (or Project)
level, you can add these before and/or after the macro, depending on the
order you want them to be read by the compiler.
27.6.3 Output Formats

At the top of the Build Tool Settings, there are two fields relating to the
format of a Build Tools output products:
Derived File Signature

This defines a file-naming pattern for a Build Tools output files.
For example, the preconfigured Unix Shared Library Linker (g++) has an
output signature of lib*.so, that is, a defined prefix and extension.
Passed to SuperProject Format

Example: The preconfigured Windows Shared Library Linker (link)
produces *.dll files (specified in the Derived File Signature field), but
the format that is passed (exported) to the Superproject to be used for
the executable targets import-library is: %d/%f.lib.
For more information about %d/ and %f, see Arbitrary and Pre-Defined
Macros page 234.
27
229

230
28
A Closer Look at Build Tools,
Tool Settings and Platforms
Overview
To Make Things Easier page 232
How are Platforms and Build Tools Related? page 232
What is a Build Tool Template? page 233
Looking at a Build Tool page 233
Arbitrary and Pre-Defined Macros page 234
What is a Build Tool Template For? page 235
What is a Platform? page 235
Platforms, Build Tools and Settings page 236
Build ToolsBits and Pieces page 237
Reverse Order page 237
Build Tool Assignment page 238
Generated Target Settings page 238
231

28.1 Introduction
One of the keys to understanding the SNiFF+ Build System is to have a
clear idea of what the SNiFF+ concepts Build Tool, Build Tool Settings,
and a Platform really are. This chapter therefore concentrates on clarifying this, and tries to ignore everything that distracts from this objective.
You might want to do the same, or you might simply want to ignore this
chapter.
28.1.1 To Make Things Easier

You will probably find things easier to follow if you can see the subject
under discussion as it appears in the SNiFF+ user interface. The best
place to go for this is the Workspace Properties dialog box.
In the Workspace Manager, select a Workspace, and

Right-click > Properties...
In the Workspace Properties, navigate to the

Build Tool SettingsBuild Tool Templates node.
Note that Build Tool Templates are defined, and can only be modified, at
Workspace level, and not at Project level. These template definitions, and
therefore any modifications, are directly used by Projects. However,
Projects can, if necessary, override Build Tool Settings (not Templates).
28.2 How are Platforms and Build Tools Related?

If you look at the Build Tool Template node in the Workspace Properties,
you will notice that there is no mention anywhere of a Platform. This is
because the template for a SNiFF+ Build Tool has no direct relationship
with a Platform. Again:
Platforms know nothing about Build Tool Templates

Build Tool Templates know nothing about Platforms
Now, take a look at these two things as the separate entities they are.
232

What is a Build Tool Template?
28.3 What is a Build Tool Template?

A SNiFF+ Build Tool Template essentially defines a template for a tool
call Command.
The template command is made up of named Fields ; these are simply
place-holders.
A SNiFF+ Build Tool Template is a bunch of place-holders (Fields) strung
together in a particular way.
28.3.1 Looking at a Build Tool

When you look at a Build Tool here, do not, for the moment, allow yourself to be distracted by minor details like, for example, the use of make
syntax.
Take a look the Command definition of a SNiFF+ Build Tool named C++
Compiler (only a part of the definition is reproduced below).
$(CXX) $(CXXFLAGS) $(CXXDEFINES)...
Now, as far as the Build System is concerned, you could equally define
this same Build Tool as:
$(TOM) $(DICK) $(HARRY)...
That is, the names of the fields (place-holders) are arbitrary; you can call
the fields anything you like (but see CAUTION page 233). You can
also add new fields (but be careful about removing fieldsdiscussed
elsewhere). If you change/add fields, also change the Command accordingly.
The use, and usef ulness, of the Build Tool will depend on what
$(HARRY) etc. expand to. However, this is a Build Tool Setting, and
goes beyond the Template of a Build Tool.
CAUTION
Although macro names are arbitrary as far as the Build System is concerned, some of these names are referenced for use by parsers!
So, do not change the names of macros in pre-configured Build Tool
Templates provided with SNiFF+. But feel free to use whatever names
you like for new macros in new or existing Build Tool Templates.
The field names CXXFLAGS and CCFLAGS are also used internally by
SNiFF+ to provide GUI-supported editing for some compilers (Windows
native and Diab platforms).
28
233

28.3.2 Arbitrary and Pre-Defined Macros

All field names that make up a tool-call Command in the Build Tool Template are place-holders. Most field names can (at least, as far as the
Build system is concerned) have arbitrary names. However, the tool-call
Command also consists, apart from elements of make syntax, some
place-holders with pre-defined names. These are not included in the list
of fields.
If you look at various tool-call Commands, you will notice elements like
%InFile% or %OutFile%.
Elements bracketed by the % sign are pre-defined macro names.
The following pre-defined names exist:
%InFile%
Expands to the current input file.
%Outfile%
Expands to $@. This is interpreted by make as the current output file.
%Objects%
Expands to the file system locations of object files created from the
current Project and to those passed up from Subprojects.
%Libraries%
Expands to the file system locations of libraries passed from
Subprojects.
234

What is a Build Tool Template For?
28.4 What is a Build Tool Template For?

The definition so far is incomplete. The make syntax is more than a minor
detail; it is very much a part of the Build Tool Template.
However, because many pre-defined Build Tools are supplied with
SNiFF+, complete with syntax that is understood by make , defining or
adapting tool definitions should not be too much of a problem (or even
often necessary).
Generally, you should be able to get by with, at most, re-mapping placeholders, or fields, to specific Build Tool Settings.
The purpose of a Build Tool Template is, therefore, to provide a generic
and adaptable Command framework. The generic Commands fields
(place-holders) expand to values (Settings). The derived Command can
then be used by make in calling various real tools during the Build process. Which specific tools are called with which options depends on the
Build Tool Settings.
28.5 What is a Platform?

A Platform can be defined as follows:
In SNiFF+, a Platform is a name, or label, for a set of Build Settings.
Generally, the intention is to produce output variants for a given target
operating system with a given set of tools. The term Platform is, therefore, no more than a label that expresses this general intention.
So, when you map a Build Tool field (place-holder) to a specific value
(Build Tool Setting), you always do it within a collection of settings under
a certain label. This label is called a Platform.
When you build targets, you always build for a particular Platform. That
is, all the settings labelled as belonging to a particular group (Platform)
are applied.
28
235

28.6 Platforms, Build Tools and Settings

Although a Platform and a SNiFF+ Build Tool as such are not directly
related, the knot that never-the-less ties these two separate entities
together lies in the mapping of individual Build Tool fields (place-holders)
to specific values. This happens in the Build Tool Settings.
The individual values are strung together as defined by the Build Tool
Template to make up a tool-call Command.
All values, and therefore the derived commands, are grouped together in
different sets under headings called Platforms.
Figure 28-1
Build Tool Templates and Platforms
Build Tool
Template
Platform
Build Tool
Settings tie the
knot between
Platforms and
Build Tools
Take a look at the Build Tool Settings node of the Workspace Properties
dialog.
All settings apply to the selection in the Platform drop-down.
236

Build ToolsBits and Pieces
28.7 Build ToolsBits and Pieces

To get to a clearer understanding of what a SNiFF+ Build Tool is, we
have happily ignored various bits and pieces of the Build Tool Template
up to now.
The central part of the SNiFF+ Build Tool is the tool-call Command,
which was discussed above. However, since the tool-call Command consists mostly of arbitrarily named place-holders, this could raise problems; and that is what some of the other bits and pieces of the Build
Tool Template are about.
Figure 28-2
Workspace Properties Build Tool Templates Node
28.7.1 Reverse Order

The fields in the Build Tool Templates are assigned values in the Build
Tool Settings. These values are set per Workspace and apply to all
Projects that use the Workspace.
If Project-level settings differ from Workspace settings the Project differences are, by default, appended to whatever is set at Workspace level.
237
28

However, for some settings the order will be important, that is, you may
have to pass the Project-level values (e.g. to a compiler) before the
Workspace values.
Example: C/C++ Include Directives

Most compilers read include directives from left to right; so you will generally want Project-level includes prepended (not appended) to any global includes you have set at Workspace level.
In this case, you would set the Reverse Order flag. That is, you want to
reverse the default order that Workspace Properties and Project-level differences are concatenated (default: append Project-differences).
To see how this is used for include-directives:
From the Build Tool Templates select C++ Compiler
In the Fields List select CXXINCLUDES

Notice that the Reverse Order checkbox is checkmarked for the
CXXINCLUDES field, but not for any other fields.
28.7.2 Build Tool Assignment

In order to more appropriately match Build Tools to inputs and their output products, for example, in target/tool selection lists, the drop-down
flags whether a Build Tool is assigned to:
Target
For example, a linker, which is not directly dependent on a source file
type, but rather links together a number of object files to create a target.
File Type
For example, a compiler, which can be directly related to a source file
type.
Target + File Type

A multiple assignment for (rare) multi-purpose Build Tools that might
have to be able to handle either a file type, or a target.
28.7.3 Generated Target Settings

SNiFF+ distinguishes between three types of targets in the Build Tool
Template. These are all used internally.
238

Build ToolsBits and Pieces
Executable
If the tool called by the command generates an executable target (e.g.
Linker), select this checkbox. This will enable Run and Debug menu
commands for Projects where targets produced by this tool are specified.
(The Debug menu command also requires a debugger adaptor to be set
at Project level.)
Can be Passed to Superproject

Select to allow exporting targets created by the tool (e.g. Librarian).
Whether the target product is actually passed up to the Superproject can
be decided at Project level.
Object
Select to specify that the generated output an object. In this case the
output will be added to the list of objects that are (or can be) passed
(exported) to the Superproject for further processing.
If the output is not a machine-language object file (e.g lex or idl output),
do not select this checkbox.
Build Priority
This determines the order in which Build Tools are called; the higher the
number, the later the call. For example, a Compiler must be called
before a Linker or Librarian.
28
239

240
29
Overview
Cascading and Levelling page 242
Preferences Level page 242
Workspace Level page 243
Project Level page 243
File Level page 243
241

29.1 Cascading and Levelling

We assume that you are familiar with the SNiFF+ entities used here
(Preferences, Workspaces, Projects). If not, just accept for the moment
that the levels described in the following move from the most general
SNiFF+ levels down to the granular, source file level.
In SNiFF+, Build settings are cascaded over various levels. This allows
you to set Build options on a very general level, inherit settings on a more
granular level, and, where necessary, fine-tune individual options.
However, to avoid maintaining masses of redundant information, settings
are levelled in that only differences to higher levels are stored at lower
levels.
29.2 Preferences Level

Default Build information for newly created Workspaces is inherited from
Site Level Preferences, and then maintained at Workspace level and
below. That is, any changes in Site-Level Preferences Build information
will affect only defaults for newly created Workspaces.
Build-related File Type information, specifically, the Build Tool associated
with a given File Type, is inherited as default for newly created Projects
from the User Level Preferences (which in turn inherit from Site Level).
This information is then maintained at Project level.
Note that, although build-related File Type information is stored and can
be directly maintained per Project, this does not hold for all File Type
information. (See also Summary of Build Property Inheritance page
244.)
242

Workspace Level
29.3 Workspace Level
29
Each newly created Workspace is initialized using the site-wide Preference settings. All Build Tool information inherited from the Preferences
can be redefined in each Workspace.
A Workspace provides the Build defaults for all Projects it contains. Furthermore, the Build Tool Templates (as opposed to the actual Build Tool
Settings) are used, and cannot be overridden, by all Projects in the
Workspace.
Workspace Build Tool Settings can be levelled at Project level. That is, for
performance and efficiency reasons, individual Projects will store only
differences, if any, to the Workspace Settings.
Caution is therefore advised when changing Workspace Build Tool Settings or Build Tool Templates! Deleting any kind of build-related settings
at Workspace level can lead to strange problems at Project-level, where
only differences are stored (difference to what?)!
29.4 Project Level

To avoid unnecessary bloating of Project Description Files, Project Build
Settings are relative to those at Workspace level. That is, to restate the
point, each Project stores only differences (if any) to the Workspace settings. By default therefore, Project Build Settings will actually be those
specified at Workspace level (no differences).
Project-Target Settings cannot be determined at Workspace level, and
are set, together with any necessary Project-specific fine-tuning in the
Project Properties.
29.5 File Level

While files belonging to a given Project will generally use the Project level
settings, it is nevertheless possible to use custom compilation options for
individual files.
243

Figure 29-1
Summary of Build Property Inheritance
Build System Info
Site
Preferences
Newly created
Workspaces
inherit Build
System defaults
directly from
Site-Level
Preferences
File Type Info
Site
Preferences
User
Preferences
Workspaces know
nothing about File
Types
Workspace
Project
Project
File
File
Dotted downward arrows indicate that defaults are inherited from the higher level. As long as
there are no modifications at lower levels, these settings will be directly used; this avoids
maintaining the same information at different levels.
Solid upward arrows indicate that any modifications to the defaults at lower levels are
relative to the higher level. That is, only differences are stored for the lower levels.
Caution: Changes (especially removal or other decreases in scope) at higher levels can lead
to unpredictable results at lower levels!
Some properties are directly shared, and can only be modified at the higher level.
The dotted upward arrow between Project and User Preferences in the File Types inheritance
does not directly affect the Build system; it is included here for the sake of completeness.
This arrow indicates a back-reference, whereby the Project stores a keyword as a pointer to a
whole field of associated Preference-level elements. That is, a change in any Preference
elements associated with the keyword will be immediately effective for all Projects.
244
30
Building Project Structures and
Compiling Files
Overview
Project Structure and the Build System page 246
Project Build Structure Restrictions in C++ page 246
Project Build Structure Restrictions in Java page 246
File Compilation page 246
File Types and Build Tools page 247
Build Tool Settings page 247
245

30.1 Project Structure and the Build System

When you set up Projects, the file-system directory structure is used as
the default Project structure. Once you have created the Project, however, you are not tied to the file system structure. Subject to restrictions
(see below) imposed by the Build System, you can rearrange Projects by
drag-and-drop in the Project Managers Project Tree.
To open the Project Manager, choose
Project > Manage
30.1.1 Project Build Structure Restrictions in C++
The order in which Projects are built is determined by their order of

appearance, from bottom to top, in the Project Managers Project Tree.
If building a Projects Target depends on a prior build of its Subprojects,
make sure that any change in overall Project structure does not change
the build order for such Projects.
30.1.2 Project Build Structure Restrictions in Java
Project Structure in Java Projects must conform to the package structure.
Multiple packages per Project are not supported.
30.2 File Compilation

For file compilation, SNiFF+ knows, or should know, what to do. The
information is taken (a) from the File Type and its associated Build Tool,
and (b) from the Build Tools settings for the given Platform.
246
Building Project Structures and Compiling Files

File Compilation
30.2.1 File Types and Build Tools

Source code files that are part of SNiFF+ Projects are associated with a
particular File Type. The File Type is, in turn, associated with a Build
Tool.
For example, SNiFF+ knows that a file with a .C or .cpp extension is,
by default, a C++ Implementation File Type, and therefore that a C++
compiler (= Build Tool) is needed to produce the corresponding object
file.
30.2.2 Build Tool Settings

From the File Type information, SNiFF+ does not know which specific
C++ compiler (= Build Tool Setting) to use, nor anything about compiler
options. This information is taken from the Build Tool Settings for the
Platform.
The default Build Tool Settings for files are taken from the Project to which
the files belong. In rare cases, however, you might want to override the
file compilation settings for individual files.
You can view/modify compilation settings of an individual file by selecting
it in a File List and choosing
Right-click > Build Properties...
247
30

248
Part VII
Version Control and Configuration
Management
Version Control Tools and SNiFF+
CMVC: Basic Concepts and Terminology
Working with Branches: Introduction
Workspaces, Configurations, and Branches
Integrating ClearCase
Integrating SNiFF+ with CVS
Integrating SNiFF+ with PVCS
Integrating SNiFF+ with Visual SourceSafe

250
31
Integration of Version Control
Tools
Overview
Version Control Tools and SNiFF+ page 252
Supported Version Control Tools page 252
Creating your own Adaptor page 252
Setting the Version Control Integration page 253
251

31.1 Version Control Tools and SNiFF+

SNiFF+s version control functionality is provided via a consistent user
interface that sits on top of an abstract interface. In this sense, SNiFF+
does not implement any version storage functionality itself; it delegates
all actions via this interface to a tool like RCS , CVS, ClearCase , etc.
which is responsible for the actual version controlling.
If your version control tool is listed under Supported Version Control
Tools page 252, an adapter is provided with SNiFF+, and all you need
to do is tell SNiFF+ which version control tool you want use (see Setting
the Version Control Integration page 253.
If you do not have a version control tool, RCS is bundled with SNiFF+, so
you can always use that.
31.1.1 Supported Version Control Tools

The following version control tools are supported (adaptors provided) by
SNiFF+
CVS
ClearCase
PVCS
RCS (bundled with SNiFF+)
Visual SourceSafe
31.1.2 Creating your own Adaptor

The SNFF+ version control interface consists of about 40 commands that
can be mapped to any specific version control tool.
Adaptors should only be created by experienced users of the versioning
tool. However, it is a one-time task since SNiFF+ only needs to be
adapted once to a new version control tool.
You can use any scripting language e.g., Bourne Shell, Python, TCL, etc.
to create your own adaptor.
For information on how to do so, please get in touch with your Sales contact.
252
Integration of Version Control Tools

Setting the Version Control Integration
31.2 Setting the Version Control Integration

You tell SNiFF+ which version control tool you want to use in the Preferences.
To open the Preferences, choose Tools > Preferences
In the Preferences, select the Integrations node.
In the Integrations node, from the Default CMVC Tool drop-down, select
your version control tool.
The RCS and Clearcase version control commands are integrated in the
standard SNiFF+ File menu.
The integrations for PVCS, CVS, and Visual SourceSafe use a custom
menu (called Custom), the corresponding commands in the menu will be
enabled when you close the Preferences.
253
31

254
32
CMVC: Basic Concepts and
Terminology
Overview
Basic CMVC Terminology page 256
Repository page 256
Check out page 256
Lock page 256
Check in page 256
What is a Configuration? page 256
What is a Freeze-Point page 257
What is a Change-Set? page 257
What is a Branch? page 257
What is HEAD? page 258
Policy: Always Branch Out from a Freeze-Point page 258

HEAD and Branches page 258
What is INIT? page 258
255

32.1 Basic CMVC Terminology

This chapter introduces terminology related to configuration management and version control as used in SNiFF+.
32.1.1 Repository
A Repository is the place where your version control tool, for example,
RCS, maintains file revision history information.
ClearCase does not have a Repository as such. However, SNiFF+ needs
a Repository node in the Workspace Manager as a point of Reference.
32.1.2 Check out

The process of creating a working copy of a file revision in a Workspace.
32.1.3 Lock
When you check out a file revision from the Repository, you will generally want to lock that revision in the Repository to prevent others from
modifying it at the same time.
32.1.4 Check in
The process of creating a new file revision in the Repository and thus,
usually, at the same time making it available also to other team members.
32.2 What is a Configuration?

A Configuration is usually a coherent and consistent state of a system
(composed of a set of files). Typically, a configuration is a buildable state
of a system. You can freeze such a configuration by giving it a name and
thereby creating a virtual snapshot of the system. That is, specific revisions of files then belong to the same, named Freeze-point.
256
CMVC: Basic Concepts and Terminology

What is a Freeze-Point
In SNiFF+, a Configuration is a virtual snapshot of your Project at a certain point in time. The elements of a Configuration are the specific revisions of the files in the Repository at the time of the snapshot. Which
revisions are included in the snapshot is determined by the Workspace
Default Configuration setting.
Generally, you would have a main line of development and, at certain
times, either regularly, or whenever the software system reaches a consistent state, you would create a Freeze-point.
The Configuration Manager is the SNiFF+ tool for creating Freeze-points,
comparing, maintaining and merging Configurations.
32.3 What is a Freeze-Point

A Freeze-point is a configuration of file revisions (snapshot), usually a
stable system, that is given a name and frozen for future reference. See
also What is a Configuration? page 256.
32.4 What is a Change-Set?

A Change-Set is a label used to identify one or more files checked in at
the same time, generally all relating to a specific task. You can use this to
later identify files checked out and modified for a particular purpose. A
Change-Set is therefore like a mini-freeze-point; a set of specific file revisions identified by a single label.
32.5 What is a Branch?

A Branch is a parallel line of development. A Branch can be anything
from a branch revision of a single file to any number of files. You can create Freeze-points on Branches just like on the main line of development,
and you can create Branches on Branches.
257
32

32.5.1 Policy: Always Branch Out from a Freeze-Point

A Branch should always branch out from a Freeze-point.
Source code files seldom exist in a vacuum. A file will generally only
work in a given context of other files, or, more precisely, specific file
revisions. Any work done on a Branch can only be meaningfully tested
(and later merged) in the context of the Freeze-point that the Branch originated from.
See also Workspaces, Configurations, and Branches page 263.
32.6 What is HEAD?

HEAD is a term used to refer to the newest file revision on the main
branch of development, and therefore constantly changes.
When you check out the HEAD revision of a file, what you are really
saying is: Make me a local copy of the latest available revision of this file
(on the main line of development), and who cares what the revision number is.
32.6.1 HEAD and Branches

A Branch name prefixed by HEAD_ is essentially the same as HEAD,
except that, instead of referring to the latest file revisions on the main line
of development, it refers to those on the named Branch.
32.7 What is INIT?

INIT is a term used to refer to the first checked-in file revision on the
main branch of development. Initially, therefore, INIT and HEAD are the
same.
258
33
Working with Branches:
Introduction
Overview
Situations for Using SNiFF+s Branch Support page 261
Creating a Branch Revision page 261
Working on the Branch page 262
259

33.1 Introduction
This chapter is not relevant for ClearCase users because all
Branch/Configuration-related control is delegated to ClearCase.
SNiFF+ supports the use of development Branches, or multiple parallel
lines of development. This, of course, assumes that your version control
tool itself supports Branches.
Creating Branches works for individual and multiple files (e.g. ChangeSets).
You can
260
Create Branches at any point in a files revision tree.
Create a Branch at a file revision already on a Branch.
Freeze the latest revisions of all files on a particular Branch and assign a
Freeze-point name to the set.
Compare Branch Configurations with other Configurations (either on the

main trunk or another Branch).
Merge a Branch revision of a file back into the main trunk of the files revision tree, or into another Branch.
Working with Branches: Introduction

Situations for Using SNiFF+s Branch Support
33.2 Situations for Using SNiFF+s Branch Support

You might choose to use SNiFF+s Branch support for one of the following situations:
Parallel developmentStable versions of your software system are

maintained in the main trunk of your files revision tree. Your team may
also be working on alternative or experimental development approaches,
this could be done on Branches.
Temporary fixes and/or customizationYou may be asked by a customer to develop a site-specific version of your software system. You
dont want this work to affect the main development work on the software
system. You could create a temporary Branch for the customization, and
then reintegrate this Branch with the main trunk at a later, opportune time.
Conflicting updatesA member of your team might have an exclusive

lock on a file that you also need to modify. You could do one of the following:
Break his/her exclusive lock. This really isnt a good choice.
Check out the same file revision with a concurrent lock. This results in
a local, writable copy of the file in your Workspace. After making and
testing your modifications, you check the file in as a Branch revision.
33.3 Creating a Branch Revision

The following example illustrates how you would create, and work with,
Branches on-the-fly. That is, maybe you want to modify a file, but someone else is also working on it. In such a case, you could create a Branch,
and later, when both of you are finished, merge the file revisions.
For serious Branch-work, however, please refer to Workspaces, Configurations, and Branches page 263.
In the File List

1. Highlight a file.
2. To open the Revisions window, Right-click > Revisions.
This is so that you can see what happens.
261
33

3. If the file you selected is not in bold typeface, it is not writable. You should
have a lock on a file you want to create a Branch revision for (youll see
why later).
So, if the file you selected is not shown in bold typeface,
Right-click > Lock
4. Now choose File > Check In
It does not matter if someone else has the file checked out because you
will be checking it in to a Branch.
In the Check In Dialog

1. In the Check In dialog, click the Advanced... button.
2. In the new dialogs To Branch field, enter a name for the Branch.
You can leave the Branch Point field blank. You only need to fill in this
field if you had not locked the revision you are checking in. You could also
use this field to enter either a version number, or a Configuration name to
branch out from (you can see this kind of information in the Revisions
window).
3. Click OK, and back in the Check In dialog, click Check In.
In the Revisions Window

Notice that a new Branch has been created with the name you specified
above.
33.4 Working on the Branch

When you check out files from the Branch, you select the
HEAD_<Branchname> entry in the Check Out box.
For every file you want to check in to the Branch, you have to enter the
Branch name (without the HEAD_ prefix!) in the Advanced Check In
Options as you did above, even if you originally checked out from the
Branch.
This may seem a little uncomfortable, but, remember, working like this is
recommended only for quick, on-the-fly branching. Again, for longer term,
or larger scale, branching, please refer to Workspaces, Configurations,
and Branches page 263.
262
34
Workspaces, Configurations,
and Branches
Overview
How Does a Workspace Access the Repository? page 264
Workspaces, Branches and Default Configurations page 264
Example: Default Configurations and Branch-Work page 265
Freeze HEAD page 265
Assign Default Configurations to a Workspace page 266
Default Configurations and Hierarchical Workspaces page 268
263

34.1 How Does a Workspace Access the Repository?

This chapter is not relevant for ClearCase users because all
Branch/Configuration-related control is delegated to ClearCase.
A Workspace has a Default Configuration which defines how the Repository is accessed.
Each Workspace has its own Default Configuration(s). If no Default Configuration is explicitly set for a Workspace, HEAD is used.
When you open a Project in a Workspace, SNiFF+ uses the Workspaces
Default Configuration:
for setting the default value when you choose one of the various version
control commands (e.g., check out and check in)
for updating files in a Workspace. Files are updated with respect to the
Workspaces Default Configuration
If the Default Configuration is HEAD, the most current file revisions available in the Repository are used. If another named Configuration is set,
the revisions that are elements of that Configuration are used.
34.2 Workspaces, Branches and Default Configurations

By default, a Workspace uses HEAD (see What is HEAD? page 258)
for check out/in, and for updates. However, if you are working on a
Branch, you will not be interested in HEAD, you will want to check out/in,
and update with respect to the head of the branch you are working on,
that is, HEAD_BranchName.
SNiFF+ therefore lets you change the Workspaces Default Configuration, in this case to HEAD_BranchName . Note that, you must also
always provide a base-line (or fall-back) Configuration.
The primary default should be the head of the Branch, the fall-back
should be the Freeze-point where the Branch originated.
That way, if a file does not (yet) have a Branch revision, the fall-back (a
Configuration consistent with all the originals on the Branch) is used.
This, of course, assumes you follow a clean Branch policy (see Policy:
Always Branch Out from a Freeze-Point page 258)
264

Example: Default Configurations and Branch-Work
34.3 Example: Default Configurations and Branch-Work

The best way to see how all this really works is probably by following a
step-by-step example.
34.3.1 Freeze HEAD

You are ready to release your software product, so you will freeze HEAD
in the Configuration Manager. This will allow you to return to the Release
Configuration at any time. And this will be the Workspace fall-back Configuration when you later create a Branch.
Choose Tools > Configuration Manager
In the Configuration Manager, highlight HEAD, and choose

Configurations > Freeze Revision List...
Figure 34-1
In the box that appears, enter RELEASE_1 as the Freeze-point Name.

Freezing HEAD
265
34
34.3.2 Assign Default Configurations to a Workspace

You decide that one Workspace will be dedicated to post-release bug-fixing on
a Branch.
Figure 34-2
Workspaces: Before and After
Figure 34-2 illustrates how you would set up a Workspace for Branch work.
Forward-development continues normally in MyDesk and YourDesk . That
is, in these Workspaces, the latest file revisions (HEAD) are checked out/in by
default. Updates will also synchronize with the latest file revisions in the
Repository.
The BugFixer Workspace, however, will use BRANCH_bugfix. If you try
to check out a file that does not yet have a revision on the Branch, SNiFF+ will
offer to check out the revision in the RELEASE_1 Configuration. When you
check the file back in, the default will be to BRANCH_bugfix .
Equally, when you synchronize (update) the Projects that use the BugFixer
Workspace, the latest revisions on BRANCH_bugfix are used, or, if there
are none, the elements of the RELEASE_1 Configuration.
Note that, in Figure 34-2, the Branch Configuration has the name
HEAD_BRANCH_bugfix
The HEAD_ prefix is obligatory for Branches. However, you only use it when
you create the Branch Configuration in the Workspace Manager, and when
you check out files. You do not use the prefix when you check in files.
How to...
Before re-organizing Workspaces you have to close all Projects that are open
in them. So close the necessary Projects, and then choose

Example: Default Configurations and Branch-Work

1. Highlight the Repository and Right-click > New > Configuration...
2. In the box that appears, enter the name of the fall-back Configuration,
that is the freeze-point you created earlier, RELEASE_1, and click Add.
Caution
The name you enter must be an existing freeze-point label. That is,
you must create the freeze-point in the Configuration Manager (described above).
The new Configuration appears in the Workspaces Tree, suspended from
the Repository.
3. Highlight the newly created RELEASE_1 Configuration and
Right-click > New > Configuration....
4. In the box that appears, enter the name of the Branch Configuration prefixed by HEAD_, that is, HEAD_BRANCH_bugfix, and click Add.
Remember, the HEAD_ prefix is obligatory for Branches. However, you
only use it when you create the Branch Configuration in the Workspace
Manager, and when you check out files. You do not use the prefix when
you check in files.
The new Configuration appears in the Workspaces Tree, suspended from
RELEASE_1.
5. You can now either, assign a new default to an existing Workspace, or
create a new Workspace.
To change the default Configuration of an existing Workspace, dragand-drop the Workspace onto
HEAD_BRANCH_bugfix.
When next you synchronize Projects in the Workspace, this will be
done with respect to the latest revisions on
BRANCH_bugfix, or, if these do not exist, the elements of the

RELEASE_1 Configuration.
267
34

If you want to create a new Workspace for the Branch, highlight

HEAD_BRANCH_bugfix, and
Right-click > New Workspace...
Then proceed as normal for creating new Workspaces (see Create a
New Workspace page 60).
When you first open the Projects, the latest revisions on
BRANCH_bugfix, or, if there these do not exist, the elements of the

RELEASE_1 Configuration will be used.
34.4 Default Configurations and Hierarchical Workspaces

If you use hierarchical Workspaces, dependent Workspaces inherit their
Default Configuration from the hierarchically higher Workspaces they
access.
However, Default Configurations defined for dependent Workspaces will
override inherited Default Configurations.
268
35
Overview
Integration Features page 270
How to integrate SNiFF+ and ClearCase page 271
VOBs and Views in SNiFF+ page 271
Changing Views page 271
Creating SNiFF+ Projects for ClearCase-Controlled Code page 271
Setting Workspace Root Locations page 272
Changing the config spec page 272
Synchronizing SNiFF+ Projects with View Changes page 273
Using clearmake page 273
Existing Workspaces and clearmake page 273
Setting clearmake as Default for New Workspaces page 275
269

35.1 Assumptions
Please note that this integration supports Base ClearCase, not UCM.
We assume
you have ClearCase (and SNiFF+) installed
you are familiar with basic ClearCase concepts and terms
your code is under ClearCase control; that is, the ClearCase views and
VOBS you want to use already exist
35.2 Integration Features
270
Automatic detection and presentation of available ClearCase views and

VOBs at Project creation time, as well as on-the-fly starting of views and
mounting of VOBs.
Automatic detection and handling of differences between Snapshot and

Dynamic views.
The integration allows direct access to the most commonly used ClearCase commands and tools. Context specific commands are generally
available in the expected contexts (e.g. File menu, or right-click context
menu), direct access to native ClearCase GUI elements is provided under
the Tools menu.
Features include:
Check out/in
Undo Check out
Add to Source Control
Merge Manager
Home Base/xclearcase
ClearCase Details
Version Tree Browser
History Browser
Switch View
Edit config spec
...
How to integrate SNiFF+ and ClearCase
35.3 How to integrate SNiFF+ and ClearCase

SNiFF+ automatically integrates with ClearCase when Projects are created/opened in a Workspace that accesses a ClearCase-Type Repository node (in the SNiFF+ Workspace Manager).
That is, in the Project Creation Wizard, select ClearCase as your version
control tool. When you add new Workspaces, create these under Repository nodes that use ClearCase.
35
35.4 VOBs and Views in SNiFF+

As far as version control is concerned, a SNiFF+ Workspace corresponds to (a directory within) a ClearCase view (with a specific config
spec) that accesses a given VOB or set of VOBs.
35.4.1 Changing Views

To access data in a different ClearCase view, Projects are reloaded in a
different SNiFF+ Workspace. However, this is not something you need
worry about; you can comfortably change views by choosing the
Project > Switch View... menu.
A dialog box presents a list of available views for selection. If a corresponding SNiFF+ Workspace does not yet exist, it will be automatically
created.
35.5 Creating SNiFF+ Projects for ClearCase-Controlled Code

When you create Projects/Workspaces for ClearCase controlled code,
you are asked to select from list of available ClearCase views and VOBs.
SNiFF+ will then combine these to create a view-extended path name for
the location of your Workspace Source Root.
271

35.5.1 Setting Workspace Root Locations

By default, all SNiFF+-generated files are stored in a subdirectory named
sniff_data and located under the Workspace Source Root.
However, if you use ClearCase , performance improvements can be
expected if SNiFF+-generated databases, symbol tables, etc. as well as
Build-output products are outside the Source Root, and therefore not
under ClearCase control.
SNiFF+ therefore allows you to split information storage, so that Project
Description Files and Makefiles are kept together with the source files in
t he so-call ed Project and M akefil es Location (by default in the
sniff_data subdirectory mentioned above), and the rest of the
SNiFF+-generated information and build products are maintained in a
Generated Files Location that lies outside the Source Root (an absolute
path to a location that is not under ClearCase control).
This means that you can properly version control SNiFF+ Project
Description Files and Makefiles, without the overhead of having all the
other SNiFF+ information and output products under ClearCase control.
35.6 Changing the config spec

You can change a views config spec from within SNiFF+.
To do so, choose Tools > Edit View Config Spec...
Note that changing your views config spec may result in a change in the
Project structure that you can see through the view.
Therefore, in order for the view and its corresponding SNiFF+ Workspace
to reflect the most current information as defined in the config spec,
reload the current Project. To do so, choose
Project > Reload
272
Synchronizing SNiFF+ Projects with View Changes
35.7 Synchronizing SNiFF+ Projects with View Changes

Subdirectories and files may be added/removed on disk outside of
SNiFF+. This can happen, for example, in heterogeneous development
organizations, where not all team members use SNiFF+. When you
update your ClearCase view, such modifications will be reflected on disk,
but not by SNiFF+ Projects.
SNiFF+ provides a Wizard that facilitates synchronizing SNiFF+ Projects
with on-disk changes that took place outside of SNiFF+s control.
To start the Wizard, choose Project > Synchronize > With Disk...
The file system is scanned, starting in the currently open root Projects
directory and, optionally, recursively down the tree. Various other facilities
such as inclusion/exclusion filter patterns, automatic Subproject creation
and connection, etc. are also provided.
and connection, etc. are also provided. Automatically created Subprojects are per directory and can be based on any valid SNiFF+ Project
Template. (Use the Project Templates dialog to create additional templates if necessary.)
The synchronization can also be automated, for example, after nightly
updates. Please refer to Synchronizing Projects Outside of SNiFF+
page 128 for more information in this respect.
35.8 Using clearmake

If you have the appropriate SNiFF+ Build Support license, you can use
clearmake together with SNiFF+ Build Support.
35.8.1 Existing Workspaces and clearmake

To use clearmake for Projects in existing Workspaces, choose
1. Tools > Workspace Manager
2. In the Workspace Manager, highlight the Workspace where you want to
use clearmake.
3. Choose Right-click > Workspace Properties.
273
35


1. In the tree on the left, select the Build Tool Settings Platforms node.
2. In the Make Command field, replace the existing entry with
On Unix
clearmake [other options]
On Windows
clearmake -C gnu [other options]

3. Click OK.
All Projects in the Workspace will now be built using clearmake with
whatever options you entered.
Windows Users: bash Shell for Existing Workspaces
On Windows, if you use SNiFF+ Build Support, you need to edit one of
the Build Support files in existing Workspaces:
general.incl
This is because of problems with the clearmake and the sh shell on Windows. You may also have problems because of blanks in your path to
SNIFF_DIR4.
These problem can be overcome by using the bash shell supplied in
your SNiFF+ installation directory (note that this is a customized bash).
The general.incl file is created under the Generated Files Location of each Workspace when you first attempt a Build.
In the general.incl file, insert the following lines:
SHELL = bash.exe
MAKE = clearmake
The SNiFF+ bash shell will now be called in this Workspace.
See also Note to Windows Users: bash Shell as Default for New Workspaces page 276
274
Using clearmake
35.8.2 Setting clearmake as Default for New Workspaces

To set clearmake as default for Projects in new Workspaces, you need to
change the SNiFF+ site-level Preferences. Which means you should be
the person responsible for administering Workspaces and Projects.
To edit site-level Preferences, you need write permission for the corresponding file (see below):
Choose Tools > Preferences

If you see a User tab and a Site tab, you have the necessary permission.
If not, press <F1> for context help and more information about user- and
site-level settings.
In the Preferences
1. Select the Site Level tab.
2. Select the Build Tool Settings Platforms node.
3. In the Make Command field, replace the existing entry with
On Unix
clearmake [other options]
On Windows
clearmake -C gnu [other options]

4. Click OK.
All newly created Workspaces will now use the command you entered
above.
275
35

Note to Windows Users: bash Shell as Default for New Workspaces

On Windows, if you use SNiFF+ Build Support, you need to edit one of
the supplied Build Support file templates:
template.general.incl
This is because of problems with the clearmake and the sh shell on Windows. You may also have problems because of blanks in your path to
SNIFF_DIR4.
These problem can be overcome by using the bash shell supplied in
your SNiFF+ installation directory (note that this is a customized bash).
The template.general.incl is located in
SNIFF_DIR4/config/templates/
In the template.general.incl file, insert the following line:
SHELL = bash.exe
MAKE = clearmake
The bash shell will now be called in all newly created Workspaces. See
also Windows Users: bash Shell for Existing Workspaces page 274.
276
36
Overview
Version and Compatibility Information page 278
Tell SNiFF+ to use CVS page 279
Import Code not yet under CVS Control page 279
Import Code From a CVS Repository page 282
Initial Check-In page 283
Create Additional Workspaces page 284
Initial Check-In and Repository Initialization page 281
Root Directories and the Workspace Manager page 284
Initial Check Out in New Workspace page 286
Is your Repository Clean? page 286
Initial check-out from a Clean Repository page 286
CVS/SNiFF+ Interface page 287
Synchronizing SNiFF+ Projects with Changes on Disk page 287
Other Issues page 288
Notes on Migrating from Other VCS Tools to CVS page 288
CVS Remote Repositories and Multi-Site Development page 288
Windows to UNIX Cross-Platform Development with CVS page

288
Pitfalls/Limitations page 289
277

36.1 Introduction
First of all, you have to get your code into SNiFF+, and SNiFF+ has to
know that want to use CVS for version control. The SNiFF+ CVS adaptor
then provides an integrated interface to the most important CVS functionality.
When you first import your code into SNIFF+, your code either is, or is
not, already under CVS control (checked in to a CVS Repository).
Depending on which situation applies to you, the procedure will differ
slightly.
Once you have imported your code into SNiFF+ (you only do this once),
you will need to create (at least) one Workspace for each team member
who will work on the code.
There are various strategies for going about this, as described in the section Workspace Management page 27. Here, we shall assume that
one person, a Workspace Administrator, is responsible for setting up
Workspaces.
36.1.1 Assumptions
We assume:
You are familiar with CVS.

This outline in no way replaces the CVS documentation.
CVS is already installed and configured on your system. That is:
the cvs executable is in your PATH and
the CVSROOT environment variable has been set.
You are familiar with the SNiFF+ Project and Workspace concepts.
36.1.2 Version and Compatibility Information

This chapter refers to the python-based CVS adaptor introduced in
SNiFF+ 4.0.2p1 and is not to be confused with previous adaptors.
Compared to the previous adaptor, the new one has been enhanced in
terms of performance, and now supports the typical CVS usage model
more fully.
278
SNiFF+ Versions
4.0.2p1 and higher
CVS Versions
1.11 and higher

Tell SNiFF+ to use CVS
36.2 Tell SNiFF+ to use CVS

This is a Preferences setting to make things slightly more convenient.
Start SNiFF+.
In the Welcome dialog, click Continue.
Choose Tools > Preferences...
An empty SNiFF+ Project Browser opens.
In the Preferences
In the navigation bar at the left, select the Integrations node.
In the Integrations node, from the Default CMVC Tool drop-down, select
CVS
CVS will now be offered as the initial default whenever you need to
specify a version control tool.
36.3 Import Code not yet under CVS Control

Either your files are already under CVS control (checked into a CVS
Repository), or they are not.
If your code is already under CVS control, please proceed as described
under Import Code From a CVS Repository page 282.
If your code files are not already in a CVS Repository:
Use the SNiFF+ Project Creation Wizard to import your code from a
directory as described in the various language-specific Beginners
Guides.
In the Wizard, make sure that CVS is selected as your Version Control
Tool.
If you proceeded as described under Tell SNiFF+ to use CVS page
279, CVS will already be selected by default.
279
36

Figure 36-1
Wizard CVS as Default Tool
Note that, for CVS, we recommend keeping Project Description Files

together with the source code. That is, accept the default settings in the
Wizard, see Figure 36-2 Wizard File Locations page 280.
This will help to ensure consistency if you use CVS also outside of
SNiFF+. Also, it will help to avoid problems when creating new, related
Workspaces later.
Figure 36-2
Wizard File Locations
After the Wizard completes
280
the SNiFF+ Project is created

Import Code not yet under CVS Control
the SNiFF+ Project is opened and displayed in the Project Browser
36.3.1 Initial Check-In and Repository Initialization

Your first step is to check all files in. Over and above your source files
there will generally also be Makefiles (either your own, or SNiFF+ generated ones), as well as newly created SNiFF+ Project Description Files
(PDF).
These PDFs must also be version controlled for the following reasons:
Structural and other Project information may change over time.
You will need the PDFs to initialize additional SNiFF+ Workspaces for
other team members.
PDFs, shared across the version control system, ensure the consistency
and synchronicity of all team members access to the software system.
In the Project Browser

To check in all files
In the Navigation Pane, at the left of the Project Browser, click into the
File List to ensure that it is in focus.
To select all files, choose Edit > Select All
Choose File > Check in...

In the Check In box, enter a comment, and click Check in.
Because this is an initial check-in, you will be prompted to supply Repository information.
In the Repository Dialog
From the drop-down, select the correct CVSRoot, or fill in the appropriate
fields (Location and Method).
If you have set the CVSROOT environment variable, the field will already
be initialized with this value.
Note
Do not create a CVS Repository in the same physical

directory branch as your source code location.
Do not name the directory location of your CVS Repository
CVSROOT or CVS; these are reserved names.
281
36

If the Repository is new (not yet initialized as a CVS Repository), click the
Init button.
Click OK.
The Repository will be initialized (if necessary) and all files checked in.
Once all source and SNiFF+ Project files have been checked in, the
Workspace (initially created by the Project Creation Wizard) knows all it
needs to know about the Repository.
From now on, check-out/in from/to this Workspace will automatically be
from/to this Repository. That is, it you will normally simply check in the
files with seeing this, second dialog box.
Your next step is to create more Workspaces that access this same
Repository for the other members of your team.
How to go about this is described under Create Additional Workspaces
page 284.
36.4 Import Code From a CVS Repository

If your code is not already under CVS control, please proceed as
described under Import Code not yet under CVS Control page 279.
If your code is already in a CVS repository, you can use the Project Creation Wizard to import your code directly from there.
The only things you need to look out for during Project creation are:
Before you start, create an empty directory to hold your future Workspace.
Repository source files will be checked out to this directory, so make sure
you have write permissions.
In the SNiFF+ Project Creation Wizard, make sure that CVS is selected
as your Version Control Tool.
(If you proceeded as described under Tell SNiFF+ to use CVS page
279, CVS will already be selected by default.)
282

Import Code From a CVS Repository
When you are asked for the Repository location, navigate to the Repository root directory.
Then, use the Exclude... button to deselect directories that you do not
want to create SNiFF+ Projects for.
You will, for example, not want to create a Project for the CVSROOT
directory in the Repository.
Also, you will want to exclude directories that are not related to the software system you are importing.
Note that, for CVS, we recommend keeping Project Description Files

together with the source code (default setting in the Wizard, see Figure
36-2 Wizard File Locations page 280).
This is so that, if you already have CVS modules set up, these will naturally not include the (up to this point non-existent) Generated Files
Location. It will also help avoid problems when you later create additional Workspaces for other team members.
After the Wizard completes
the SNiFF+ Project is created
your source code files are checked out to a newly created SNiFF+
Workspace
the SNiFF+ Project is opened and displayed in the Project Browser
36.4.1 Initial Check-In

Although Repository versions of your source code already exist, this will
certainly not be true for the newly generated SNiFF+ Project Description
Files (PDF).
These PDFs must also be version controlled for the following reasons:
Structural and other Project information may change over time
PDFs are needed to create additional SNiFF+ Workspaces for other team
members
PDFs, shared across the version control system, ensure the consistency
and synchronicity of all team members access to the software system.
In the Project Browser

To check in the Project Description Files
In the Navigation Pane, at the left of the Project Browser, click into the
File List to ensure that it is in focus.
To select all files, choose Edit > Select All
283
36

Choose File > Check In...

Once all the (Project) files are in the CVS Repository, you can go ahead
and create more Workspaces for the other members of your team. How
to go about this is described under Create Additional Workspaces
page 284.
36.5 Create Additional Workspaces

We assume you have completed the steps as outlined either under
Import Code not yet under CVS Control page 279 or under Import
Code From a CVS Repository page 282.
That is:
You have imported your code into SNiFF+
All source and Project Description files are in (have been checked in to) a
CVS Repository.
36.5.1 Root Directories and the Workspace Manager

Only one person needs to import code into SNiFF+ once, regardless of
how many team members will be working on that code.
However, each team member needs (at least) one personal Workspace
to work in. Each Workspace must have a root directory that will hold all
source code directories, and the person who will use it must have write
permission in the directory.
Outside SNiFF+, create empty root directories for Workspaces as needed

(these are referred to as Workspace Source Root directories).
In SNiFF+, choose Tools > Workspace Manager

The Workspace Manager opens and you should see something like
Figure 36-3 CVS Repository Node and Workspace page 285.
284

Create Additional Workspaces
Figure 36-3
CVS Repository Node and Workspace
36
To create a new Workspace that accesses the CVS Repository (originally

created by the Project Creation Wizard):
Highlight the newly created CVS Repository node
Choose Workspace > New > Workspace....
In the box that appears:
Give the Workspace a Name.
In the Source Root Location field, enter the root directory (one of the
directories you created under Root Directories and the Workspace
Manager page 284) where source code will be checked out to.
Accept the remaining defaults in the dialog, the deselected checkbox

ensures that SNiFF+ Project Description Files are stored together
with the source files. This was also the default in the Project Creation
Wizard, so if you accepted the default there, do so here; all Workspaces must be consistent in structure.
Click Add to confirm your entries and close the dialog box.
You should now see the newly created Workspace suspended from
the Repository.
285

36.6 Initial Check Out in New Workspace

Above, you created an empty Workspace.
This Workspace accesses the same CVS Repository node as that
accessed by the original Workspace (with Project) that you created using
the Wizard.
So, all you have to do is check out the files to the new Working Enviornment.
However, before continuing, consider the following: Is your Repository
Clean? page 286.
36.6.1 Is your Repository Clean?

In this context, clean means that you can isolate the Repository files
relating to the software system(s) you want to work on (that is, the files
you want to check out to a new Workspace).
In other words: either your Repository contains only these files, or the
files are grouped in defined Modules that you can check out.
If the above applies, proceed as described under Initial check-out from a

Clean Repository page 286.
If no, you can either create CVS modules (you can open the original
Project in SNiFF+ and choose Tools > Edit modules File...), or proceed
as described under First Check-Out page 61.
36.6.2 Initial check-out from a Clean Repository

Highlight the newly created Workspace.
Choose Project > Check Out...

In the dialog box that appears, enter (select) Modules if necessary.
Depending on the size of your software system, the check-out might take
some time.
When the check-out process has completed, choose

Project > Update Project Tree
You should now see the same Project Tree structure as the one
displayed in the original Workspace.
286

CVS/SNiFF+ Interface
36.7 CVS/SNiFF+ Interface

The Project, File, Tools, and Workspaces (in the Workspace Manager)
menus provide commands that interface to CVS.
(Menu commands are documented in the GUI and Menu Reference,
available online, under the Help menu).
36.8 Synchronizing SNiFF+ Projects with Changes on Disk

Subdirectories and files may be added/removed on disk outside of
SNiFF+. This can happen, for example, in heterogeneous development
organizations, where not all team members use SNiFF+. When you
update your Workspace, such modifications will be reflected on disk, but
not by SNiFF+ Projects.
SNiFF+ provides a Wizard that facilitates synchronizing SNiFF+ Projects
with on-disk changes that took place outside of SNiFF+s control.
To start the Wizard, choose Project > Synchronize > With Disk...
and connection, etc. are also provided. Automatically created Subprojects are per directory and can be based on any valid SNiFF+ Project
Template. (Use the Project Templates dialog to create additional templates if necessary.)
Synchronization can also be automated, for example, after nightly
updates. Please refer to Synchronizing Projects Outside of SNiFF+
page 128 for more information in this respect.
287
36

36.9 Other Issues

36.9.1 Notes on Migrating from Other VCS Tools to CVS
Since CVS uses RCS for its internal files, no history or configuration
information will be lost when you migrate from RCS to CVS. For in-depth
information on migrating to CVS (also from other revision control systems), please refer to the CVS Manual.
For the RCS to CVS migration with SNiFF+ specifically, there is a shell
script rcs2cvs available from SNiFF+ support.
36.9.2 CVS Remote Repositories and Multi-Site Development

If you are using a CVS pserver repository, you need to log in to the
server with a valid user name and password. To do so:
Choose Tools > Repositories...
In the box that appears, select or enter the CVSROOT and click Login.
36.9.3 Windows to UNIX Cross-Platform Development with CVS

There are two problems with Windows to UNIX cross-platform development:
1. When CVS is run on Windows, it will add a Carriage Return (CR) Character at the end of the line of every file it creates: both CVS internal files and
files managed by CVS. Most UNIX compilers do not work with the resulting CRLF line ending scheme.
2. The CVSROOT scheme required by Windows local repositories
(:local:d:\the\repository ) can be saved in the CVSRoot file
with the sources. UNIX Versions of CVS don't understand this special
form of CVSROOT and produce an error.
These problems can be solved by using a version of CVS on Windows
that has been compiled with the Cygwin kit. By compiling CVS with this
kit, it will behave more UNIX-like.
288

Other Issues
36.9.4 Pitfalls/Limitations
Both SNiFF+ and CVS keep track of the files and directories you work on.
To stay in sync, all structural changes should be done in SNiFF+.
Adding and (re-)moving in SNiFF+ will automatically update the CVS
structure.
If files are added or removed outside of SNiFF+, manually add/remove
these files form the SNiFF+ Projects.
It is not possible to use Workspace Default Configurations with the current version of the CVS Adaptor. Use CVS sticky tags instead.
36
289

290
37
Overview
Version and Compatibility information page 293

Requirements page 293
PVCS Version Manager page 293
Member Storage page 293
Access Control page 293
Parallel Development page 293
The SNIFF+ PVCS Adaptor page 294
Feature Overview page 294
Limitations and Known Issues of the Current PVCS Adaptor page

295
Setting up Projects with SNiFF+ and PVCS page 295
PVCS and Adaptor Configuration Files page 295
Non-Default Settings in the Configuration File page 296
291

37.1 Introduction
This chapter describes how to integrate INTERSOLV's PVCS Version
Manager with SNiFF+.
PVCS Version Manager is a version control system for Windows, Unix,
and OS/2.
The PVCS adaptor provided with this package can be used for both Unix
and Windows platforms. It ensures a complete mapping of SNiFF+'s version control interface to PVCS Version Manager, and it is also the missing link between the cross-platform abilities of SNiFF+ as well as PVCS.
Hence, it would be possible, for instance, to create a repository on platform A, check out a file on platform B, switch back to platform A, and
check the file in there. On both platforms, you would issue the corresponding commands from SNiFF+, with PVCS as the underlying version
control tool.
The PVCS adaptor is included in the SNiFF+ 4.x installation.
37.1.1 Assumptions
You should have a working PVCS installation on your system, and you
should be able to execute PVCS commands from your Operating System
Command Line. Although SNiFF+ helps you performing PVCS commands, you should know the PVCS concept and how to operate the
PVCS system from the command line as well.
Note that this chapter does not replace an introduction on PVCS. For
background information, please refer to the PVCS documentation.
You should also be familiar with SNiFF+ Project and Workspace concepts.
292

Version and Compatibility information
37.2 Version and Compatibility information

37.2.1 Requirements
SNiFF+ Versions
4.0.2p1 and higher
Tested PVCS Versions
6.7
Compatible PVCS versions
6.0.x, 6.5 and higher

37
37.3 PVCS Version Manager

The basic features of this version control system are described below.
37.3.1 Member Storage

PVCS simplifies access to project components: code, data files, documentation, object modules, and other binary files. Developers and administrators need not remember where each module is stored. PVCS locates
files or projects even across system boundaries. High-level support for
module sharing makes PVCS essential on heterogeneous networks.
37.3.2 Access Control

PVCS offers precise control of file locking on the LAN to prevent conflicting updates of shared files. Users can be assigned to groups that have
specific file access capabilities.
37.3.3 Parallel Development

PVCS lets developers create multiple logical views of the same physical
modules, so they can create, maintain, and test special versions of an
application. Unlimited branching offers flexible, yet safe, parallel develop-
293

ment and makes alternative versions easy to maintain. A merge facility

resolves conflicts as you merge multiple development efforts to produce
the application.
Furthermore, PVCS Version Manager comes with a graphical user interface on all platforms, however all commands can also be called from the
command line.
37.4 The SNIFF+ PVCS Adaptor

37.4.1 Feature Overview
This version of the PVCS adaptor provides the following key features:
Full access to all basic version control functions
294
Revisions of files, History, Configurations, Branches
Full support of PVCS configuration files (see PVCS and Adaptor Configuration Files page 295 for details)
Support for PVCS keyword expansion
Full support for the PVCS archive suffix rules
Support for setting a revision label to a single file or a group of files

(including SNiFF+ change sets and floating labels)
Ability to move a label from one revision to another revision for one file
Automatic reread of the configuration files after runtime changes
Full support for the PVCS ReferencedDir directive
Full repository locking ability

Setting up Projects with SNiFF+ and PVCS
37.4.2 Limitations and Known Issues of the Current PVCS Adaptor
Multiple PVCS archive suffix meta rules (include a '?' inside the extension) are not supported.
PVCS access lists, access database and the promotion model is not supported by this version of the adaptor.
37.5 Setting up Projects with SNiFF+ and PVCS

You can create new Projects in SNiFF+ using the Wizard. To do so:
In the SNiFF+ Project Browser, choose Project > New > With Wizard...
The Project Creation Wizard appears.
In the Project Creation Wizard, select PVCS as your version control tool
and follow the rest of the instructions in the Wizard.
For more information on how to create a Project in SNiFF+, please refer
to the SNiFF+ Users Guide and Reference or the language-specific
Beginners Guides.
37.6 PVCS and Adaptor Configuration Files

PVCS uses configuration files to store all settings used to control the
behavior of the PVCS commands. Multiple levels of configuration files
are possible with PVCS up to a depth of 20.
If you are using the graphical user interface of PVCS, you can set at least
a master configuration file and a project configuration file. By default,
PVCS only uses the master configuration file. If you have changed the
configuration file setting for one PVCS project, this is your project configuration file.
The PVCS adaptor of SNiFF+ can handle multiple levels of configuration
files as well, but the first include statement(s) must be entered manually
in the fixed PVCS integration configuration file.
295
37

The PVCS adaptor uses a fixed file to store all configuration settings necessary for SNiFF+. This is the master configuration file of the PVCS
adaptor and contains all settings necessary for SNiFF+:
PVCS Version 6.0
SNIFF_DIR4/config/integrations/pvcs/Pvcs60_4Sniff.cfg
contains the archive suffix rule:
".? = ??v___"
If you want to use this file, rename it to Pvcs4Sniff.cfg (after making a backup of the original!).
PVCS Version 6.5
SNIFF_DIR4/config/integrations/pvcs/Pvcs4Sniff.cfg
contains the archive suffix rule:
".? = +-arc;. = +.-arc"
Note
All archive suffix rules will be stored in this file. This file must be writable for all users who are allowed to change the archive suffix rules.
The configuration files will be read in the following order:
the default PVCS master configuration file (only PVCS 6.0)
all included configuration files
the SNiFF+ master configuration file

The settings in these configuration files will be merged in an incremental
process. That is, a setting which is only present in the master configuration file will be applied as well as a setting in the SNiFF+ master configuration file. For all settings which are in more than one configuration file,
only the setting in the last configuration file will be used. In this case, the
SNiFF+ master configuration file is the last instance for configuration settings.
37.6.1 Non-Default Settings in the Configuration File

The following settings overwrite the default settings of PVCS and
shouldn't be changed or overwritten since the correct behavior of the
adaptor is only guaranteed with these settings:
296

PVCS and Adaptor Configuration Files
QUIET
display only minimal messages
NOSIGNON
no PVCS copyright message
IGNOREPATH
use VCSDIR to specify repository directory
NODELETEWORK WRITEPROTECT
check-in doesn't remove the work files
EXPANDKEYWORDS TOUCH
keyword expansion changes the timestamp of the work file
LOGIN HOST, VCSID, UNKNOWN

use the login sources HOST, VCSID and 'No Source' (UNKNOWN)
NOSHARE
set exclusive use of archives for all operations
All other configuration settings can be overwritten or deleted from the
SNiFF+ configuration file if you are using the master and/or project configuration files. Otherwise deletion of configuration settings can disable
some functionality.
Note
Because of several problems with incorrectly configured PVCS configuration files, the SNiFF+ PVCS adaptor generates the directives
IgnorePath and ExpandKeywords Touch inside a dynamically generated temporary configration file for every repository access.
297
37

298
38
Integrating SNiFF+ with Visual
SourceSafe
Overview
Compatibility page 300
Prerequisites page 300
Setting up a SNiFF+ Project with Visual SourceSafe page 301
Checking In Files page 302
Integration Details page 303
Locking Mechanisms page 303
Branches, Change-Sets and Configurations page 303
File Descriptions page 303
299

38.1 Compatibility
This integration was developed with MS Visual SourceSafe version 6 and
SNiFF+ version 4.0.
38.2 Prerequisites
Visual Source Safe must be installed on your computer.
For SNiFF+ to integrate with Visual SourceSafe, you must set Visual
SourceSafe as your default CMVC tool, either during the SNiFF+ installation, or subsequently in the Preferences.
Once you've installed SNiFF+, you must add Visual SourceSafe to your
PATH environment variable.
To test whether Visual SourceSafe is in your path, open a shell and
enter:
ss About
You should then see version information about your SourceSafe installation.
create a valid user for Visual SourceSafe.
Open the Visual SourceSafe Admin program and create a User (if one
has not been created). If your SourceSafe Username does not resemble
your Login name, you must set the environment variable
SNIFF_VSS_USER
to the login name you would like to use within SourceSafe.
300

Setting up a SNiFF+ Project with Visual SourceSafe
38.3 Setting up a SNiFF+ Project with Visual SourceSafe

Here we will create a SNiFF+ Project (and Subprojects) with Visual
SourceSafe. We will use the SNiFF+ Project Creation Wizard to specify
the source root directory and the Repository for source code. To do so:
1. Start SNiFF+.
2. Use the SNiFF+ Project Creation Wizard to create a SNiFF+ Project
using the complex example code that comes with SNiFF+.
3. In the SNiFF+ Project Creation Wizard, select Visual SourceSafe as
your VCS Tool.
4. Assume that there is a top level SNiFF+ Project called complex, in the
Where is the Source Code? page of the Wizard, Source code root
directory field, enter
SNIFF_DIR4/examples/cpp/complex
38
5. To maintain the SNiFF+ Project structure in Visual SourceSafe Projects,

in the Repository for source code field, enter:
$/
Visual SourceSafe uses the dollar sign ($) to symbolize the root Project
in the Visual SourceSafe database.
Complex has a Subproject called complexlib which is located in a
subdirectory of Complex
complex\complexlib
301

then the path to the repository of the Subproject will be generated as follows:
$/complex/complexlib
38.4 Checking In Files

You are now ready to check in the Project files. The key point to remember here is that the files of the top-most directory (i.e. the SNiFF+ Superproject) MUST be checked in BEFORE any Subproject.
In the example, first check in the files of the complex Project and once
this is done, check in the files of the complexlib and iolib Subprojects.
302

Integration Details
38.5 Integration Details

38.5.1 Locking Mechanisms
Visual SourceSafe supports the following locking mechanisms:
Exclusive Lock, this command puts an exclusive lock on the file in the version tool. An exclusive lock means that nobody else can lock the same
version. The working file status is set to writable.
No lock, this makes the local copy read-only. No lock is set on the file.
38.5.2 Branches, Change-Sets and Configurations
SNiFF+'s version control interface provides means to create branch versions of repository files during check in or check out. These features are
not supported with Visual SourceSafe as the underlying version control
tool.
Change-Sets are modifications to a list of files. To identify Change-Sets,

SNiFF+ adds the prefix SNiFF+CS in front of a version label. ChangeSets may be up to 22 characters long and will be truncated if longer.
Labels other than Change-Sets are interpreted as Configurations.
Visual SourceSafe allows labels consisting of more than one word, however SNiFF+ does not support this feature, therefore these labels are
separated by underscores in SNiFF+, e.g. this is a label will be displayed in SNiFF+ as this_is_a_label.
38.5.3 File Descriptions

File revision descriptions which can be shown in SNiFF+ are not supported by Visual SourceSafe.
303
38

304
Part VIII
Editor and Other Integrations
Emacs Integration
SlickEdit Integration
Vim Integration
Rational Rose Integration

306
39
Emacs Integration
Overview
How the Emacs Integration Works page 308
Integrating Emacs page 309
Starting SNiFF+ page 309
Switching Emacs to SNiFF+ Mode page 310
Connecting Emacs to SNiFF+ page 310
Working with Emacs and SNiFF+ page 311
Positioning Emacs from SNiFF+ page 311
Changing Key Bindings and Sniff Menu Entries page 311
Using the Sniff Menu page 312
Switching a Non-SNiFF+ Buffer to SNiFF+ Mode page 312
Command Reference page 313
307


Note
Emacs is not supplied as part of the product package.
The following integration features are available:
Emacs can be used for all editing requests
SNiFF+ recognizes and updates all browsers when a file is saved in

Emacs
SNiFF+ commands can be issued directly from Emacs
39.2 How the Emacs Integration Works

Emacs need not be changed to work in the SNiFF+ environment. An
Emacs-Lisp configuration file supplied with the SNiFF+ distribution tells
Emacs how to:
define a SNiFF+ mode
communicate with SNiFF+
define keyboard bindings and a pull-down menu for available SNiFF+

commands
This file is called sniff-mode.el and is located in your
SNIFF_DIR4/config/integrations/emacs
directory. To use the file, simply load it into Emacs. Once the file is
loaded, a new SNiFF+ mode is available in Emacs. Then, execute the
function sniff-connect to connect Emacs to your current SNiFF+
session. SNiFF+ will then use Emacs for displaying and editing source
code. These steps will be discussed in detail in the rest of this chapter.
308
Emacs Integration
Integrating Emacs
39.3 Integrating Emacs

39.3.1 Prerequisites
SNiFF+ installed at your site
PATH must point to the following directories

SNIFF_DIR4/bin
SNIFF_DIR4/lib (on Windows only)
GNU Emacs (version 19 or later) or XEmacs (formerly Lucid Emacs)

installed at your site
The sniff-mode.el file (part of the SNiFF+ package)
39.3.2 Starting SNiFF+
39
Start SNiFF+ by typing:

sniff -s EE
at the command prompt.
If you use Emacs as your default Editor, we suggest that you do either of
the following:
On Windows
Create a shortcut to sniffstart.cmd and in its Properties > Target field, add
-s EE
or
Edit the sniffstart.cmd file in SNIFF_DIR4 by adding
-s EE
after
start sniff.exe
309

39.3.3 Switching Emacs to SNiFF+ Mode
Add the following line to your .emacs file (one line)

(load "$SNIFF_DIR4/config/integrations/emacs/
sniff-mode")
This causes Emacs to load the sniff-mode.el configuration file at
start-up.
Note
You can avoid the path specification by copying sniff-mode.el
to the directory for site-wide Emacs-Lisp files:
After you have done this, your .emacs file entry would look like this:
(load "sniff-mode")
39.3.4 Connecting Emacs to SNiFF+
To connect Emacs to a running SNiFF+ session, type:

M-x sniff-connect
Note
You could also add this command to your .emacs file.
Then, your .emacs would look like this:
(load "$SNIFF_DIR4/config/integrations/emacs/
sniff-mode")
(sniff-connect)
You can have only one Emacs-SNiFF+ connection active at a given time.
To force Emacs to disconnect from SNiFF+, type:

M-x sniff-disconnect
Emacs automatically disconnects when you end the SNiFF+ session.
310
Emacs Integration
Working with Emacs and SNiFF+
39.4 Working with Emacs and SNiFF+

Once a connection between SNiFF+ and Emacs is established, SNiFF+
uses Emacs for all requests to show or edit source code. Emacs can also
send queries to SNiFF+.
The following figure shows Emacs connected to SNiFF+. The SNiFF+
menu only appears when a file is loaded:
39.4.1 Positioning Emacs from SNiFF+

The Emacs integration offers many of the navigation features available in
the Source Editor. For example, by double-clicking on a symbol in any
SNiFF+ browser, Emacs loads the corresponding source file and positions the cursor at the appropriate location.
39
39.4.2 Changing Key Bindings and Sniff Menu Entries

The Emacs-SNiFF+ key bindings and the Sniff menu are defined in:
SNIFF_DIR4/config/integrations/emacs/sniff-mode.el
You can change the SNiFF+ key bindings as for any other Emacs key
bindings. The same is true for the Sniff menu.
311

39.4.3 Using the Sniff Menu

Most of the commands described in Command Reference page 313
are available in the Sniff menu in Emacs. The following illustration shows
the menu.
39.4.4 Switching a Non-SNiFF+ Buffer to SNiFF+ Mode

When a file is loaded in Emacs from SNiFF+, this buffer is automatically
in SNiFF+ mode. When you load a file manually (with the Emacs Load
file command), you can switch the buffer to SNiFF+ mode with the following command:
M-x sniff-mode
After the command is executed, all SNiFF+ key bindings are available.
312
Emacs Integration
Command Reference
39.5 Command Reference

All of the SNiFF+ commands that are important when editing source
code are also available in Emacs. To accomplish this, a few keys have
been bound to functions that communicate with SNiFF+. The functions
and the key bindings are defined in:
SNIFF_DIR4/config/integrations/emacs/sniff-mode.el
Generally all commands read the argument string (or symbol) from the
minibuffer, whereby the string around the point is inserted as a default.
(In Emacs nomenclature, the cursor position is called point.)
The following Emacs key bindings and corresponding SNiFF+ commands are available:
Note
For a description of the following commands, please refer to the online GUI and Menu Command Reference.
sniff-goto-symbol
Show Symbol... Shortcut: C-c C-g
sniff-browse-class
Browse Class... Shortcut: C-c C-b
sniff-hierarchy
Show <Classname> In Entire Hierarchy... Shortcut: C-c C-h
sniff-restr-hier
Show <Classname> Relatives... Shortcut: C-c C- M-h
sniff-retrieve
Retrieve in Edited File... Shortcut: C-c C-r
sniff-retrieve-proj
Retrieve In Project of Edited File...
sniff-retrieve-allprojs
Retrieve From All Projects...
sniff-retrieve-next
Retrieve In Marked Projects Shortcut: C-c C- M-r
313
39

sniff-xref-to
Refers To... Shortcut: C-c C-x
sniff-xref-by
Referred By... Shortcut: C-c C- M-x
sniff-xref-has
Refers To Components... Shortcut: C-c C-c
sniff-xref-used by
Referred By As Component... Shortcut: C-c C- M-c
sniff-reparse
Reparse...
sniff-connect
Connect
sniff-disconnect
Disconnect
314
40
Overview
Installation page 316
Working with Visual SlickEdit and SNiFF+ page 316
Starting the Integration page 316
Opening SlickEdit from SNiFF+ page 316
Using SNiFF+ from SlickEdit page 317
315

40.1 Introduction
MicroEdge Visual SlickEdit can be used for editing source code in
SNiFF+. SNiFF+ commands can be issued directly from the SlickEdit
menu, and all editing requests issued from SNiFF+ are answered by
SlickEdit.
40.1.1 Compatibility
The integration was developed for Visual SlickEdit 5.0 and SNiFF+ 4.0
and newer.
40.2 Installation
Copy sniffintegration.e and sniffcommands.e from
SNIFF_DIR4\config\integrations\slickedit\
to the macros subdirectory in your SlickEdit installation directory.
40.3 Working with Visual SlickEdit and SNiFF+

40.3.1 Starting the Integration
First, start SNiFF+.
Then, run SNIFF_DIR4\bin\sniffslickedit.exe

The sniffslickedit executable manages DDE communication
between SNiFF+ and SlickEdit.
40.3.2 Opening SlickEdit from SNiFF+

Double-click on a file or symbol name in any SNiFF+ tool, or choose one
of the Browse > Edit commands, to open SlickEdit.
316
Working with Visual SlickEdit and SNiFF+
40.3.3 Using SNiFF+ from SlickEdit
SlickEdit has an additional SNiFF+ menu with commands for executing

the most commonly used SNiFF+ functions. (When you choose a command from the SNiFF+ menu, the actual DDE command line is displayed
in the status bar.)
The SNiFF+ menu includes a command to Reparse the current file. This
command can be used after modifications to update symbol information
maintained and displayed by SNiFF+.
For details about the remaining SNiFF+ menu commands, please refer to
the SNiFF+ GUI and Menu Reference.
In addition to the SNiFF+ menu, the SlickEdit File menu has an additional
command, namely, File > Save in SNiFF+.
This command serves both to save the file, and to update the symbol
information maintained and displayed by SNiFF+.
Note that when you call SNiFF+ from SlickEdit, SNiFF+ may be hidden by
other Windows; this behavior depends on your Windows installation.
40
317

318
41
Vim Integration
Overview
How the Integration Works page 320
Preparing Vim for the Integration page 321
Preparing SNiFF+ for the Integration page 322
Making the Connection page 323
Connecting Vim to SNiFF+ page 323
Connection on Start-Up page 324
Working with Vim and SNiFF+ page 324
Key Mappings page 324
Command Reference page 325
319


This integration is based on Vim 5.x (vi improved), which is almost fully
compatible to vi but provides a variety of additional features (e.g., multiple buffers, infinite undo, command-line history, filename completion,
syntax highlighting, script language, etc.). The following integration features are available:
Vim can be used for all editing requests.
SNiFF+ recognizes and updates all browsers when a file is saved in Vim.
SNiFF+ commands can be issued directly from Vim.
41.2 How the Integration Works

You will first need to prepare Vim for the integration by downloading the
relevant files (if you havent done so already). You then need to prepare
SNiFF+ for the integration by first setting the SNIFF_DIR4 environment
variable and then by starting SNiFF+ with the External Editor argument.
Note
SNIFF_DIR4 refers to your SNiFF+ 4.x installation directory.

You will then start Vim and execute the :sniff connect command to
make the connection. These steps are discussed in detail in the rest of
this chapter.
320
Vim Integration
How the Integration Works
41.2.1 Prerequisites
SNiFF+ installed at your site.
PATH must point to

On Unix
SNIFF_DIR4/bin
On Windows
SNIFF_DIR4/bin;SNIFF_DIR4/lib.
Vim 5.x with sniff support installed at your site. You can download Vim
and the necessary files for this integration from the following Website:
ftp.home.vim.org/pub/vim
Information on Vim can be obtained from the following Website:
http://www.vim.org
the sniff.vim file (part of the SNiFF+ package).
41.2.2 Preparing Vim for the Integration

For the SNiFF+ integration to be available, vim needs to be compiled with
special flags.
On Windows
1. A pre-compiled and configured version of Vim 5.3 comes with the SNiFF+
distribution or can be downloaded from (all one line);
ftp://ftp.takefive.com/pub/SNiFF/4.0_Win/vim-win32/
vim_for_40.tgz.
2. Extract the .tgz file into your SNiFF+ 4.0 installation directory.
On Unix
You need to download original vim sources including the SNiFF+ integration and compile it at your site. You can download Vim and the files for
this integration from the following Website:
http://www.vim.org
1. Downloaded the Vim source files, e.g.,
vim-5.7-src.tar.gz
and the sources for the SNiFF+ Vim integration, e.g.,
vim-5.7-extra.tar.gz
2. Extract the above mentioned .tar.gz files to a directory where you
have write permissions.
321
41

3. Edit the Makefile in the above mentioned directory by uncommenting all

Make macros prefixed with SNIFF_.
4. Save the file.
5. Build Vim.
If Vim is already installed

1. Copy the vim executable obtained by either of the steps above into your
existing vim installation.
2. Copy SNIFF_DIR4/config/integrations/vim/sniff.vim
into your existing vim runtime environment.
3. Set the environment variables as shown later, but keep the $VIM environment variable pointing to your existing environment.
41.2.3 Preparing SNiFF+ for the Integration

1. Make sure that the environment variable SNIFF_DIR4 points to your
SNiFF+ 4.0 installation directory.
Note
Throughout this chapter, we will use SNIFF_DIR4 to refer to your
SNiFF+ 4.0 installation directory.
2. Set up your PATH to point to
On Unix
SNIFF_DIR4/bin
On Windows
SNIFF_DIR4/bin and SNIFF_DIR4/lib.
322
Vim Integration
Making the Connection
41.3 Making the Connection

Note that you can have only one Vim-SNiFF+ connection active at a
given time.
To start SNiFF+, enter

sniff -s EE
at the command prompt.
To use Vim as your default Editor in SNiFF+ on Windows
Create a Shortcut to sniffstart.cmd and in its

Properties > Target field, add -s EE
or
Edit the sniffstart.cmd file in SNIFF_DIR4 by adding -s EE

after
start sniff.exe
41
To use Vim as your default Editor in SNiFF+ on Unix

Define an alias like visniff.
41.3.2 Connecting Vim to SNiFF+

1. Start Vim in an environment where the SNIFF_DIR4 environment variable is correctly set.
2. Enter the following command in Vim:
:sniff connect
to connect Vim to your current SNiFF+ session.
The following message appears:
Connecting to SNiFF+ ... Done
323

41.3.3 Connection on Start-Up

If you want Vim to connect to SNiFF+ immediately on start-up, you need
to add the command sniff connect in your VIM initialization file.
We assume that this file is called .vimrc.
1. Check if the initialization file with the name .vimrc exists in your home
directory (~/.vimrc on Unix; %HOME%\.vimrc on Windows), if not
create it.
2. Insert the following line in the .vimrc file:
sniff connect
Vim connects to SNiFF+ immediately on start-up and will execute the
commands contained in the .vimrc file.
41.4 Working with Vim and SNiFF+

Once a connection between SNiFF+ and Vim is established, SNiFF+
uses Vim for all requests to show or edit source code. On the other hand,
you can send queries to SNiFF+ with the following Vim command:
:sniff [request[symbol]]
:sniff without arguments will display a list of all available commands.
41.4.1 Key Mappings

The key mappings are defined in the file sniff.vim. To have this file
sourced by vim:
Insert the following (one line) into the .vimrc file before the line that
contains sniff connect:
let sniff_mappings = "$SNIFF_DIR4/config/ \
integrations/vim/sniff.vim"
324
Vim Integration
Command Reference
41.5 Command Reference

For ease of use, key mappings (keyboard shortcuts) are predefined.
These allow fast queries without typing long requests. Key mappings
always act on the symbol under the current cursor position. Note that
these key mappings need to be enabled before they can be used, please
refer to Key Mappings page 324 for more information.
A Sniff menu appears in vim containing menu commands for each
request:
41
:sniff goto-symbol
Vim shows the declaration or implementation of the selected symbol. If
the selected symbol is ambiguous, a dialog opens with a list of valid
alternatives.
Shortcut: sg
Corresponding menu command: Show Symbol
:sniff browse-class
Displays the members of the selected class in the Class Browser.
Shortcut: sb
Corresponding menu command: Browse Class
:sniff hierarchy
Shows the entire class hierarchy in the Hierarchy Browser.
Shortcut: sh
Corresponding menu command: Show Class in Entire Hierarchy
325

:sniff restr-hier
Shows base and derived classes of the selected class in the Hierarchy
Browser.
Shortcut: sH
Corresponding menu command: Show Class Relatives
:sniff retrieve-next
Opens the Retriever and retrieves all occurrences of the selected string
from the Projects that are checkmarked in the Project Tree. Also all other
settings in the Retriever, except filters, are applied.
Shortcut: sR
Corresponding menu command: Retrieve
:sniff retrieve-all-projects
Opens a Retriever and retrieves all occurrences of the selected string
from all projects in the Project Tree.
Shortcut: srP
Corresponding menu command: Retrieve from All Projects
:sniff retrieve-project
from the project to which the current file belongs.
Shortcut: srp
Corresponding menu command: Retrieve from Project of Edited File
:sniff retrieve-file
from the current file.
Shortcut: srf
Corresponding menu command: Retrieve from Edited File
:sniff xref-to
Opens the Cross Referencer and shows all symbols that the selected
symbol references.
Shortcut: sxt
Corresponding menu command: Refers To
326
Vim Integration
Command Reference
:sniff xref-by
Opens a Cross Referencer and shows all symbols that are referenced by
the selected symbol. The Filter settings are used as the query parameters.
Shortcut: sxb
Corresponding menu command: Referenced By
:sniff xref-has
Opens a Cross Referencer and shows all symbols (classes and structures) that are components of the selected class. If the current selection
is a member of a class/structure, the class/structure is taken for this
query
Shortcut: sxh
Corresponding menu command: Refers To Components
:sniff xref-used-by
Opens a Cross Referencer and shows all symbols that are referenced by
the selected symbol. The Filter settings are used as the query parameters.
Shortcut: sxu
Corresponding menu command: Referenced As Component By
:sniff connect
Establishes connection with SNiFF+. Make sure that SNiFF+ is in Vim
mode.
Shortcut: sc
Corresponding menu command: Connect
:sniff disconnect
Disconnects from SNiFF+. You can reconnect at any time with :sniff
connect.
Shortcut: sq
Corresponding menu command: Disconnect
327
41

328
42
Overview
Installation page 330
Preconditions page 330
Required Steps for SNiFF+ page 330
Required Steps for Rational Rose page 331
Result page 331
Navigation from SNiFF+ to Rational Rose page 332
SNiFF+ Custom > Rational Rose Menu page 332
File List, Right-Click Context Menu page 333
Source Editor, Right-Click Context Menu page 333
Navigation from Rational Rose to SNiFF+ page 335
File Types page 336
Technical Details page 336
329

42.1 Introduction
Rational Rose is a graphical software-engineering tool which supports
the most popular OO analysis and design methods. This integration provides a bi-directional navigation between SNiFF+ and Rational Rose for
both source code that has been generated from a Rose Design and
Rose models that have been created from source code by the Rose Analyzer.
42.1.1 Compatibility
The integration has been developed for Rational Rose 98i and Rational
Rose 2000. It was tested under Microsoft Windows NT4 SP6.
42.2 Installation
42.2.1 Preconditions
Rational Rose 98i, Rational Rose 2000, or Rational Rose 2001a has to
be installed on a Microsoft Windows PC.
42.2.2 Required Steps for SNiFF+
Open a shell and change to the bin directory of the SNiFF+ installation.
Call the rosereg.exe program.
Enter the full path of the SNiFF+ installation directory.
Rosereg will write some entries for Rational Rose in the Microsoft
Windows Registry.
330
Start SNiFF+.
Choose Tools > Preferences.
In the Preferences, select the Integrations node.
Select the Rational Rose integration and click OK.

Installation
42.2.3 Required Steps for Rational Rose
Start Rational Rose.
Choose Add-Ins > Add-In Manager.
Select the Rosetosniff checkbox and apply settings.
42
42.2.4 Result
In SNiFF+, you will see the menu, Custom > Rational Rose. Additional
context menus (in Source Editor, File List, etc.) can only be seen in open
SNiFF+ Projects.
In Rational Rose you will see Tools > SNiFF+.
Note: When you use one of the above mentioned menu items, SNiFF+
will be brought into the foreground. In cases where you cannot see the
expected result in SNiFF+ (e.g. your class in the Class Browser), a dialog
may be hidden, waiting for your input. This dialog appears if the selected
symbol is ambiguous.
331

42.3 Navigation from SNiFF+ to Rational Rose

Rational Roses capabilities can be accessed with the Rational Rose
sub-menu, in various context menus, for example in Source Editor, File
List, etc.
Before using those context menu items, you have to start Rational Rose
with Custom > Rational Rose > Start Rose.
42.3.1 SNiFF+ Custom > Rational Rose Menu

The Custom > Rational Rose menu includes the following commands:
332
Start Rose
Terminate Rose
Start Rose Analyzer

Navigation from SNiFF+ to Rational Rose
42.3.2 File List, Right-Click Context Menu

The File List right-click context menu includes the following Rational
Rose commands:
Open Model in Rose

Opens a selected model in Rational Rose.
Open Deployment Diagram in Rose

Opens a selected deployment diagram in Rational Rose.
42
42.3.3 Source Editor, Right-Click Context Menu

To show a symbol in Rational Rose, first highlight it in the Source Editor.
The following menu right-click context menu commands are then available.
Show class diagram

A class diagram containing the selected class will be launched. If more
diagrams are available in Rose, the desired one can be selected through
an additional menu.
333

Show class specification

The Rational Rose class specification window will be shown.
Show processor specification

The Rational Rose processor specification window will be shown.
Show device specification

The Rational Rose device specification window will be shown.
334

Navigation from Rational Rose to SNiFF+
42.4 Navigation from Rational Rose to SNiFF+

SNiFF+s capabilities can be accessed in the Tools > SNiFF+ menu.
The following items are defined in this menu:
Browse Class
Loads the class selected in a class diagram into the SNiFF+ Content
Browser.
Edit Symbol
Loads the class selected in a class diagram into the SNiFF+ Source
Editor.
Browse Class in Relative Hierarchy

Loads the class selected in a class diagram into the SNiFF+ Hierarchy
Browser. It also shows all directly associated classes.
Browse Class in Entire Hierarchy

Loads the class selected in a class diagram into the SNiFF+ Hierarchy
Browser. It also shows all other classes.
42
335

42.5 File Types

For SNiFF+ Projects using Rational Rose, additional File Types are
defined in the Preferences. The following table shows the correlation
between Rational Rose file signatures and SNiFF+ File Types.
File Type
Signature
Description
Rose Model
*.mdl
Model Description File is the controlled unit
Rose Category
*.cat
Category File describes logical

packages
Rose Analyzer
Project
*.pjt
Project Description File for Rational Rose C++ Analyzer
Rose Re-engineered
Code
*.red
Re-engineered code from Rational Rose C++ Analyzer
42.6 Technical Details

The communication from Rational Rose to SNiFF+ is done through an
ATL COM controller, which is rosetosniff.dll . Rational Rose calls
methods by passing a dispatch pointer to it. This points to an interface
that can collect information from Rational Rose. The methods of the ATL
COM controller call the Python interpreter with rosetosniff.py to
drive SNiFF+.
The communication from SNiFF+ to Rose consists of two steps: First, the
program snifftorose.exe is called from SNiFF+ with the needed
parameters. Then, this program tries to connect to Rational Rose and
calls the specified tool.
336
Part IX
SniffAPI
SniffAPI - Concepts
SniffAPIGetting Started

338
43
SniffAPI - Concepts
Overview
Basic Idea page 340
Overall Architecture page 340
Query Interface page 341
Usage Model page 342
Scope Handling page 345
The ID Concept page 347
Basic Idea page 340
Encoding Details page 348
Data Model page 349
Completeness page 349
339

43.1 Introduction
This document provides an overview of the basic idea, the overall architecture, and the usage model of the SniffAPI.
43.2 Basic Idea

The SniffAPI provides easy access to information about software systems loaded into SNiFF+. Although the focus, both in terminology and
documentation, is on C++ and Java systems, the interface should also
work for other languages.
43.3 Overall Architecture

The SniffAPI client is implemented in Java. The illustration below provides an overview of the overall architecture of the SniffAPI. It consists of
340
an extension to SNiFF+ that extracts the information required by the client

from SNiFF+ services and exports it over
the XML-RPC inter-process communication protocol to the SniffAPI client

process.
SniffAPI - Concepts
Query Interface
the SniffAPI client side, which reads the information from the socket and
transfers it to your installed data handlers via the builder pattern. In our
sample application, the data handlers print the Project structure to the
console.
43
43.4 Query Interface

You can access information on a file, an individual Project, or a hierarchy
of Projects. All information available within this context is streamed.
SniffAPI is therefore an API to export complete parts of the symbol table;
there is no query-based mechanism for filtering.
Four different information transfer modes are supported:
Project information only; no symbols.
All information about definitions and declarations but no information about

usage (cross-reference information).
All information about definitions and declarations and short cross-reference information.
All information about definitions and declarations and long cross-reference information.
The information transfer mode is selected when the information is
requested from a SniffController instance ( getProjectData or
getFileData).
341

In the short cross-reference transfer mode, only the IDs of the referencer
and the referenced symbol and attributes describing the reference type
are transmitted. In the long cross-reference mode, enough information is
transmitted to find the referenced symbol in a symbol table.
An entire section is dedicated to the SniffAPI ID concept.
43.5 Usage Model

This section explains the usage model of the SniffAPI based on the
ProjectTreePrinter example. The complete source code of the
sample application is part of your SNiFF+ installation and can be found
in:
SNIFF_DIR4/SniffAPI/Example
The UML class diagram in the illustration below gives you an overview of
the most important classes of the sample application. The framework
classes have boxes with fine lines, and the application-specific classes
have boxes with bold lines.
342
SniffAPI - Concepts
Usage Model
We have added calling relationships (arrows) to the class diagram. The

numbers of the calling relationships indicate the corresponding code
example where you can see how the classes cooperate in detail.
43
The ProjectTreePrinter reads the absolute or relative path of the Project

file, and the Workspace Source Root path of a Project from the command line. It prints an ASCII representation of the Project tree, together
with its files and classes, to the console.
343

Example 1
As mentioned above, you integrate your software as part of a builder pattern by installing your application-specific handler objects to the default
ImplementationHandlerFactory that is managed by a SniffController object. In our example, we are interested in information on
Projects ( ProjectHandler ), files (FileHandler ), and classes
(SymbolHandler).
SniffController controller= new SniffController();
InformationHandlerFactory
factory=controller.getHandlerFactory();
factory.setProjectHandler(new
DemoProjectHandler(writer));
factory.setFileHandler(new DemoFileHandler(writer));
factory.setSymbolHandler(new
DemoSymbolHandler(writer));
Example 2
Once the factory is configured, the connection to SNiFF+ is established
and (in our example) the request to send the information for a specific
Project is sent to SNiFF+.
During the getProjectData call, the framework takes control, manages the communication with SNiFF+, and transfers the information to
the handler objects installed in the factory in step one.
int referenceAmount= SniffController.eFullReferences;
boolean recursively= true;
Boolean absolutePos= true;
try {
controller.connect(absolutePos);
}
catch( CannotConnectException e ){ ... }
try {
controller.getProjectData(sendSymbols,
referenceAmount, recursively, projectFilePath,
wePath);
}
catch(CannotAccessProjectException e ){ ... }
catch(ConnectionBrokenException e ){ ... }
controller.disconnect();
344
SniffAPI - Concepts
Scope Handling
Example 3
In the application-specific handler objects, the information is received as
data objects and used for whatever purpose needed.
public class DemoSymbolHandler extends SymbolHandler {
public void handleClass(ClassData data)
{
System.out.println("Class " + data.getName());
System.out.println("
Position " +
data.getPosition().getAbsoluteStart() + " " +
data.getPosition().getAbsoluteEnd());
if (data.isFinal())
final");
if (data.isAbstract())
abstract");
...
}
}
43
43.6 Scope Handling

Scope objects represent scopes of symbols and cross-reference information. Scopes are represented as linked lists and start with the innermost scope.
345

Example 4
The following code snippet exemplifies how a list of scopes is traversed.
void traverseScope(Scope scope) {
while (scope != null) {
printScope(scope);
scope= scope.getPrev();
if (scope != null)
contained in");
}
}
void printScope(Scope scope) {
System.out.println(
getScopeKindName(scope.getKind()
+ " scope "
+ scope.getName()
+ " in " + printPosition(scopeGetPosition()));
}
String getScopeKindName(int kind) {
switch (kind) {
case eGlobal:
return "Global";
....
}
}
346
SniffAPI - Concepts
The ID Concept
43.7 The ID Concept

43.7.1 Basic Idea
Symbol tables are graphs. In exporting symbol tables there are two
options to handle relationships which cannot be expressed by nesting.
The references representing the relationships can be transferred as
an ID (reference), or
as information that is required to find a referenced item in the symbol

table
Especially the insertion of information into a relational database
becomes considerably simpler and faster if the API provides IDs that can
be used as primary keys, and if it uses these IDs to transfer reference
information.
The references (invocation, data access,...) are the largest amount of
information transferred. References cannot be expressed using nesting.
For these reasons we introduced the ID concept. But, even with an ID
concept, clients have varying information needs regarding references.
There are therefore two ReferenceHandler types.
The SmallReferenceHandler interface is used to transfer only the

IDs of the referencer and the referenced symbol and all attributes
describing the reference itself (e.g., read/write for data references). This
makes sense, for example, when the information is stored in a relational
database. In this case the IDs and attributes suffice to write the reference
table without any need for lookup operations.
The ReferenceHandler interface is used to transfer all information
required to find the referenced symbol in a symbol table. This makes
sense, for example, if some information about references has to be collected without the requirement to build a complete symbol table.
You have to decide which cross-reference transfer mode to use when
asking for information to be transferred
(SniffController.get[Project|File]Data() ).
347
43

43.7.2 Encoding Details

All IDs of a Project form an interval [a,b] (ProjectIdRange)
-> projectId
= a
-> fileIds
= [a + 1, a + n1]
-> preprocessorIds = [a + n1 + 1, a + n2]
-> symbolIds
= [a + n1 + 1, a + n3]
-> b = max( a + n2, a + n3 )
All IDs of a Project and all it's Subprojects that have not already been
transferred also form an interval. The Subprojects are traversed depth
first to generate the IDs. The IDs of the first Subproject start with b + 1.
Subproject trees that occur several times within a Project tree are transferred only once. Their IDs are generated when they are found the first
time during the depth first traversal of the overall tree.
Every further time a Subproject is encountered, a placeholder is transferred (ProjectHandler.duplicateSubprojectLink() ).
All IDs of a Project tree form an interval
[x, y] (ProjectTreeIdRange)
N Projects with ID ranges [a1, b1] - [an, bn] result in the following interval:
x = min[a1, ..., an]
y = max[b1, ..., bn]
The ProjectIdRange and the ProjectTreeIdRange are transferred as part of the ProjectData parameter objects.
ID numbering starts at 50. Numbers below 50 are reserved for the following purposes:
348
unknown scope
global scope
file scope
5 - 13
java built-in types
20 - 41
C++ built-in types
42 - 49
reserved for later use
SniffAPI - Concepts
The ID Concept
43.7.3 Data Model

What information is transferred in detail is extensively documented in the
source code and in the generated documentation available in
SNIFF_DIR4/SniffAPI/javadocs
The illustration below shows a partial view of the data classes used by
the SniffAPI to transfer the information.
43
43.7.4 Completeness
The SniffAPI transfers all symbol information currently available in
SNiFF+'s symbol table. This information is tailored to support the browsing of large software systems and is, therefore, not complete. Certain
parts of the interface are marked with not yet supported these are
areas where we consider it probable that more information will be available in the future.
One of the reasons why we have chosen to transfer all information
through data objects is that this makes it possible to extend the interface
without breaking user code.
349

There are a lot of attributes that can be specified for C++ and Java symbols. The following table gives an overview of what kind of attributes are
supported by the language definitions and the information about which
attribute is provided by the SniffAPI.
Keyword
C/C++
auto
yes
abstract
const
yes
yes
Description
SNiFF+ 4.x
(SniffAPI)
Variable or parameter has local (automatic) extent
not supported
Mark types as abstract
Java: yes
Member functions,
variables and member variables can be
defined const.
C++: yes
C++: Pure virtual

member functions
and classes with
pure virtual member functions are
marked as abstract.
Java: all fields that

are final also have
the attribute const
explicit
yes
Constructors declared explicit will not

be considered for implicit conversions
not supported
extern
yes
Variable or function
has external linkage,
or linkage conversion of another language
not supported
Class, method cannot be derived from

or overridden. The final attribute is considered in setting the
virtual flag for Java
methods.
Java: yes
final
350
Java
yes
SniffAPI - Concepts
The ID Concept
Keyword
C/C++
friend
inline
Description
SNiFF+ 4.x
(SniffAPI)
yes
Function or class has

access to private
members.
yes
yes
Function or method is
marked as inline,
which is a suggestion
to the compiler to
generate inline code.
C++: in the case

of a member function implemented
in the class body,
the inlineMember
attribute is set
Java interface definition.
Java: yes
Non-static non const

member variables. If
declared mutable it is
legal to assign a value to this data member from a const
member function.
not supported
yes
Modifier used in the

declaration of a
method to indicate
that the method is implemented in another programming
language.
Java: yes
interface
mutable
Java
yes
yes
native
private
yes
yes
Visibility of members
in C++ and Java, visibility of inheritance in
C++.
yes, for members
protected
yes
yes
in C++ and Java.
yes, for members
public
yes
yes
in C++ and Java, visibility of inheritance in
C++, visibility of
classes in Java.
yes, for members
351
43

Keyword
C/C++
register
yes
synchronized
static
yes
transient
352
virtual
yes
volatile
yes
Java
Description
SNiFF+ 4.x
(SniffAPI)
Suggestion for the

compiler to store variables or parameters
in the CPU register.
not supported
yes
Modifier to specify
thread-safe methods
not supported
yes
Variables, functions
(visibility during linkage C/C++ only),
member functions
and variables (class
methods and variables)
yes
yes
Modifier used in the

declaration of variables.
Java: yes
Polymorphism for
functions, inheritance, enables multiple inheritance
without duplicate
members when inheriting from the
same class more
then once
yes, also set for

Java (all methods
are virtual unless
declared final or
declared in a final
class)
Indicates that a member variable (Java) or

all that can be declared const (C++)
can be modified in
the program by
something other than
statements, such as
the operating system,
the hardware, or a
concurrently executing thread
Java: yes
yes
C++: not supported
44
Overview
What You Need page 354
Directory Structure of SniffAPI page 354
Setting up JAR files for compilation of a SniffAPI client page 354
Add the JAR Files to your CLASSPATH Environment Variable page

355
Compiling the Sample Program page 356
Running the Sample Program page 356
353

44.1 What You Need
The environment variable SNIFF_DIR4 must be correctly set to the

SNiFF+ installation directory.
Java 1.2 or newer must be installed.
44.2 Directory Structure of SniffAPI

SNIFF_DIR4 contains the following SniffAPI relevant subdirectories:
SNIFF_DIR4/lib/java
JAR files of client interface
SNIFF_DIR4/SniffAPI/Source
Source code of interface of client framework
Source code of sample client ProjectTreePrinter
44.3 Setting up JAR files for compilation of a SniffAPI client

In order to compile the client sample program ProjectTreePrinter or your
own client, the Java compiler needs to know the location of the SniffAPI
interface implementation files that are packed in
SNIFF_DIR4/lib/java/sniff.jar
and also the location of the other libraries needed by the client, which are
located in the same directory.
For this reason your Java classpath must be set correctly.
354
Setting up JAR files for compilation of a SniffAPI client
44.3.1 Add the JAR Files to your CLASSPATH Environment Variable

A backslash at the end of a line, followed by an indented line, indicates
line-continuation.
Note: Do not use blanks in the CLASSPATH!
On Windows (Windows Command Prompt)
set CLASSPATH=%CLASSPATH%; \
%SNIFF_DIR4%/lib/java/sniff.jar; \
%SNIFF_DIR4%/lib/java/xmlrpc.jar; \
%SNIFF_DIR4%/lib/java/openxml-1.2.jar; \
%SNIFF_DIR4%/lib/java/xerces.jar; \
%SNIFF_DIR4%/lib/java/xml4j.jar; \
%SNIFF_DIR4%/SniffAPI/Example
On Solaris (using a sh)
CLASSPATH=${CLASSPATH}: \
${SNIFF_DIR4}/lib/java/sniff.jar: \
${SNIFF_DIR4}/lib/java/xmlrpc.jar: \
${SNIFF_DIR4}/lib/java/openxml-1.2.jar: \
${SNIFF_DIR4}/lib/java/xerces.jar: \
${SNIFF_DIR4}/lib/java/xml4j.jar: \
${SNIFF_DIR4}/SniffAPI/Example
export CLASSPATH
On Solaris (using a csh)
setenv CLASSPATH ${CLASSPATH}: \
${SNIFF_DIR4}/lib/java/sniff.jar: \
${SNIFF_DIR4}/lib/java/xmlrpc.jar: \
${SNIFF_DIR4}/lib/java/openxml-1.2.jar: \
${SNIFF_DIR4}/lib/java/xerces.jar: \
${SNIFF_DIR4}/lib/java/xml4j.jar: \
${SNIFF_DIR4}/SniffAPI/Example
355
44
44.4 Compiling the Sample Program

1. Navigate to the directory SNIFF_DIR4/SniffAPI/Example
2. Compile the sample program as follows (all one line):
javac com/windriver/sniffapi/client/clientdemo/
ProjectTreePrinter.java
44.5 Running the Sample Program

To start the sample program:
1. Start SNiFF+.
2. Navigate to the directory
and start the sample program as follows (all one line):
java com.windriver.sniffapi.client.clientdemo.
ProjectTreePrinter <ProjectPath> <WorkingEnvironmentPath>
Whereby <ProjectPath> is the absolute or relative (to the Workspaces

Generated Files Location) path to the Project file. For example:
SNIFF_DIR4/SniffAPI/Example/example.proj
On Windows: If the path to your Project contains blanks, enter the full,
absolute path enclosed in double quotes, e.g.,
"C:\Program Files\Sniff\Example\example.proj"
And <WorkspacePath> is the Workspace hierarchy as it appears in the

SNiFF+ title bar when a Project is opened in the Workspace. For Example:
example.proj - /repository/MyDesk
Above, the WorkspacePath is
/repository/MyDesk
Note the / at the beginning. Note further that MyDesk is not a file-system
location, but a Workspace name.
Running the Sample Program
44
357

358
Part X
Advanced Reference
Custom Menus
Sniffaccess
Configuring the C++ Parser
Cross-Reference Information
45
Custom Menus
Overview
Preparation page 362
Create Directory page 362
Set up a Project page 363
The Custom Menu Configuration File page 363
Menu Definition page 364
Item Definition page 365
Example: Python Dialogs page 366
Custom Menu Configuration File: EBNF Specification page 367
Configuration File page 367
Configuration File Format page 367
Actions page 368
Parameters page 369
Notes on the Keyboard Shortcut Specification page 369
361

45.1 Introduction
SNiFF+ lets you define custom menus. Custom menus can be useful for
a variety of tasks. For example, you might want to call an external application to process a selected file directly from SNiFF+. You can also use
ready-made dialogs to get information from the user.
Custom menus are defined in a special configuration file. Items defined
in this file can also be used for FIle Type right-click context menus. These
context menus are then available in the File List.
We recommend that you create a SNiFF+ Project for the custom menu
configuration file. This allows you to properly edit the file with SNiFF+
(including syntax highlighting), and to version control it (and therefore
also share it).
The configuration file itself has several examples that are fully commented. The best way to understand how custom menus work is therefore probably to look at the configuration file.
This chapter provides a general introduction to the custom menu configuration file, and a full EBNF description.
45.2 Preparation
We assume you will set up a Project as recommended above.
Before going on to set up a Project, there are a few things to do.
45.2.1 Create Directory

First, you need to create a directory, then copy the custom menu configuration file to this directory.
The name and location of this directory are not optional. They must be
exactly as stated here, otherwise SNiFF+ will not be able to find the file.
The reason for this is to avoid your custom menu file being overwritten in
the course of a future upgrade of SNiFF+.
The custom menu configuration file

SniffCustomMenus.sniff
is located in:
SNIFF_DIR4/config/tools/integrations
362
Custom Menus
The Custom Menu Configuration File
On Windows
In SNIFF_DIR4/config/Profiles/<user_name>/
create a directory called integrations
Copy SniffCustomMenus.sniff to this directory.
On Unix
In $HOME/.sniffrc
create a directory called integrations
Copy SniffCustomMenus.sniff to this directory.
45.2.2 Set up a Project
Choose Project > New > With Wizard...
In the Wizard, the source code location is the directory you created
above.
When the Wizard has run its course, the Project opens in the Project
Browser.
45.3 The Custom Menu Configuration File

45
This description is intended as an introduction.
Please refer to Custom Menu Configuration File: EBNF Specification
page 367 for more detailed information.
In the File List, double click on SniffCustomMenus.sniff.
Caution: Be very careful with the syntax! Always make sure parentheses
are closed, etc. If not, you may experience some very weird problems.
There are a number of examples in the file. When you write your own
menus, the best thing to do is copy/paste whole blocks and then modify
within the pasted block.
363

45.3.1 Menu Definition
The following is the basic menu definition.

Do not modify the definition itself. Only modify items within the array.
ExtendMenuOrToolBar (
Base : "CustomMenu"
Items : array (
-list of item identifiers
)
)
CustomMenu is internally pre-defined. This will create a top-level menu

named Custom Menu.
If you have a third-party integration that already uses a Custom Menu,
your own commands (defined in this file) will be appended.
The top level definition uses an array of item identifiers. These can be
called anything you like, but each must be enclosed in double quotes.
Each item identifier must be defined somewhere further down in the file.
This identifier can also be used to define custom right-click context
menus for File Types. That is, simply enter the identifier in the Preferences (a File Type Subcategory Setting).
The "<MENU>" item is special, and defines a submenu.

The submenu, like the normal items has an identifier.
The submenu is closed with "</>".
Each submenu will be defined somewhere further down using the
keyword Menu, the identifier (Name), and an Item , or an array of
Items.
364
Custom Menus
The Custom Menu Configuration File
45.3.2 Item Definition

Each item definition has
The keyword Item at the start.
A Name, that is, the identifier used also in the menu definition.
States
Basically, this syntactical block defines the label as you see it in the menu
(the & defines the accelerator key), and the text that appears in the
status line.
Can have a keyboard/mouse ShortCut.

If you use a shortcut that is already used elsewhere in SNiFF+, this will
not work, and an error is reported in the Log.
An associated action, AssocAction

This can be either
"|Application|ExecProcess"
or
"|Application|ExecPython"
That is, you can either run an external application, or call a Python function (SNiFF+ handles the Python environment).
Arguments and parameters are passed in the Args array.

Parameters can be passed to the Item using an Accessor.
This Accessor can be a string that is itself an Item identifier defined
elsewhere in the file. And this other item might itself use an Accessor,
and so on (Accessor recursion, see also below).
GetSelectedString and GetSelectedFile are a pre-defined

items provided by SNiFF+.
Note that GetSelectedFile always uses the "Conversion Accessor"
(an example of recursive Accessors).
Below, this is illustrated using an extract from the example
CustomShowFileAttributes
Accessor (
Item : struct (
Name : "#Project|ConvertPIPToPath"
Args : array (
Accessor ( Name : "#Project|GetSelectedFile" )
)
)
)
365
45

45.3.3 Example: Python Dialogs

Ready-made dialogs are provided as Python functions. You can see how
to call these functions in the configuration file.
Here, we will take a brief look at one of the Python submenu examples.
Note that the syntax used here is heavily abbreviated; use the configuration file for a syntactically correct version.
We assume you have set up a Project as described above, and that

SniffCustomMenus.sniff is open in the SNiFF+ editor.
To see what happens, uncomment the following lines in the menu definition (use either the toolbar button, or remove the two minus signs at the
line-beginning):
"<MENU>"
"CustomPythonDialogSubMenu"
"</>"
Save the file and press <SHIFT><CTRL><X>

This reloads the configuration file.
You should now see a Custom Menu with a Python submenu.
In the file, take a look at CustomPythonSelectFile.

This appears once in the submenu definition:
Menu (
Name : "CustomPythonDialogSubMenu"
Items : array (
CustomPythonSelectFile
And it appears again as the name of an Item.

If you look at this Item, you see, among other things, the following arguments:
"custom.CustomDialogs"
"ShowText"
"Selected file:"
Accessor (
Item : "CustomPythonFileDialog"
The first three lines, above, process the input from the Accessor item
CustomPythonFileDialog, which is also defined the file.
(The "processing" is here done by the Python function, ShowText.)
In other words, you can write any number of item definitions that do
different things using the output of, in this example,
CustomPythonFileDialog by using this Accessor.
366
Custom Menus
Custom Menu Configuration File: EBNF Specification
45.4 Custom Menu Configuration File: EBNF Specification

45.4.1 Configuration File
Name
SniffCustomMenus.sniff
Location
On Windows
or
SNIFF_DIR4/config/Profiles/<user_name>/integrations
On Unix
or
$HOME/.sniffrc/integrations
45.4.2 Configuration File Format

CustomMenuFile = { MenuExtension | SubmenuDef | Submenu |
MenuEntry | Accessor }
MenuExtension = 'ExtendMenuOrToolBar' '(' MenuExtensionSpec ')'.

MenuExtensionSpec = 'Base:' 'CustomMenu' 'Items' ':' 'array' '(' { MenuEntryID | '<MENU>' SubmenuID '</>' | Separator } ')'.
MenuEntryID = '"' character {character} '"'.
SubmenuID = '"' character {character} '"'.
Separator = '"-"'.
SubmenuDef = 'Item' '(' SubmenuDefSpec ')'.

SubmenuDefSpec = 'Name' ':' SubmenuID 'States' ':' 'ActionStates' '('
ActionStateSpec ')'.
Submenu = 'Menu' '(' SubmenuSpec ')'.

SubmenuSpec = 'Name' ':' SubmenuID 'Items' ':' 'array' '(' [ MenuItemID ]
')'.
367
45

MenuEntry = 'Item' '(' MenuEntrySpec ')'.

MenuEntrySpec = 'Name' ':' MenuEntryID [ 'States' ':' 'ActionStates' '('
ActionStateSpec ')' ] [ 'ShortCut' ':' ShortCutSpec ] [ 'AssocAction' ':'
Action 'Args' ':' 'array' '(' { ActionArgumentSpec } ')' ] [ 'Macro' ':' 'array' '('
{ MenuEntryMacroSpec } ')' ].
Accessor = MenuEntry.
ActionStateSpec = 'Default' ':' 'State' '(' ActionState ')' [ 'Disabled' ':'

'State' '(' ActionState ')' ].
ActionState = 'ShortDescription' ':' MenuEntryString [ 'Description' ':'
MenuEntryHelpText ].
MenuEntryString = '"' [Accelerator] character { [Accelerator] character
}'"'.
MenuEntryHelpText = '"' character {character} '"'.
Accelerator = '&'.
ShortCutSpec = '"' { n | s | c | b }{ character | F1 | ... | F12 | Esc | Enter | (

{ L | M | R}Click { 1 | 2 }) } '"'.
MenuEntryMacroSpec = 'struct' '(' 'Name' ':' Action [ 'Args' ':' ActionArgumentSpec ] ')'.
ActionArgumentSpec = 'array' '(' { Argument | ArgumentAccessorSpec }

')' [ 'struct' '(' ActionFlags ')' ] .
ArgumentAccessorSpec = 'Accessor' '(' ArgAccSimple | ArgAccRecursive ')'.
ArgAccSimple = 'Name' ':' Parameter.
ArgAccRecursive = 'Item' ':' 'struct' '(' 'Name' ':' Parameter 'Args' ':'
ArgumentAccessorSpec ')'.
45.4.3 Actions
Action = '|Application|ExecProcess' | '|Application|ExecPython'
Argument = ProcessArgument | PythonArgument.

ProcessArgument = '"' cmdLineArgument '"' { '"' cmdLineArgument '"' }.
PythonArgument = '"' moduleName '"' '"' functionName '"' { '"' functionArgument '"' }.
ActionFlags: [ 'Cwd' ':' Argument | ArgumentAccessorSpec ] [ 'Detached'
':' 'true' | 'false'] [ 'Blocking' ':' 'true' | 'false' ] [ 'Timeout' ':' '-1' | timeInSeconds ] | ['ShowWindow' ':' 'true' | 'false' ].
368
Custom Menus
Custom Menu Configuration File: EBNF Specification
45.4.4 Parameters
"|Application|GetIACPort" ... SNiFF+ session id and port number
"#Project|GetDefaultConfig" ... default configuration specification
"#Project|GetRepositoryRoot" ... Repository root directory
"#Project|GetWEDrive" ... Workspace drive
"#Project|GetWEDir" ... Workspace directory
"#Project|GetSelectedFiles" ... selected list of SNiFF+ file paths
"#Project|GetSelectedFile" ... first selected SNiFF+ file path
"#Project|ConvertPIPToPath" ... SNiFF+ file path(s) (Project Item Path)

argument converter
"#Project|ConvertPIPToRepositoryPath"
path(s) argument converter
"#Project|GetFileLanguage" ... file language string
"#Project|GetSelectedString" ... selected context sensitive string
...
SNiFF+
file
Repository
45.4.5 Notes on the Keyboard Shortcut Specification

The Keyboard shortcut format is case insensitive and consists of a one
character modifier and a token. The modifier is defined to be:
n...plain key (no additional key pressed)

s...<SHIFT> key
c...<CTRL> key (Windows) or <ALT> (META) key (Unix)
b...Both <SHIFT>and <CTRL> key at the same time
45
369

370
46
Sniffaccess
Overview
Introducing Sniffaccess page 372
Preparing the Environment page 372
Invoking Sniffaccess page 373
Connection Management page 374
Connecting to SNiFF+ page 375
Terminating SNiFF+ page 375
Input and Output of Data page 375
Important Data Types page 376
Examples page 381
How to Get Currently Defined Workspaces page 381
How to Get and Set Project Properties page 382
How to Add a File to a Project page 383
How to Lock a File page 384
How to Set Preferences page 385
How to Show a Specific Symbol in the Source Editor page 386
How to Change a Default Build Platform page 387
How to Use Notifications page 388
How to Generate Projects in Batch Mode page 389
Example Script for Updating Workspaces page 390
Sniffaccess Command Reference page 391
Appendix: What is Python? page 391
371

46.1 Introducing Sniffaccess

Apart from the graphical user interface, Sniffaccess is one of the means
by which SNiFF+ interacts with the outside world.
Sniffaccess is a Python module (see also Appendix: What is Python?
page 391). It extends Python with functionality to connect to SNiFF+ and
allows you to send requests to, and receive notifications from SNiFF+.
It allows the remote connection to distributed SNiFF+ sessions located at
different sites (machines).
In other words, Sniffaccess provides control integration between SNiFF+
and other programs.
Sniffaccess can be used for several purposes:
Driving SNiFF+ in batch mode. For example, this is used for unattended
updates and builds of Workspaces.
Integrating SNiFF+ with other third-party tools like CASE tools and GUI
builders.
Writing proprietary scripts for Project generation and modification with

SNiFF+.
46.2 Preparing the Environment

Make sure the following environment variables are set
372
SNIFF_DIR4 must point to your SNiFF+ installation directory

SNIFF_DIR4/bin must be in your PATH
TMP (or TEMP) must point to a valid directory
Sniffaccess
Invoking Sniffaccess
46.3 Invoking Sniffaccess

To invoke Sniffaccess in a Shell a Python interpreter and a Python script
are needed.
The Python interpreter is provided by SNiFF+ (sniffpython executable).
The Python interpreter has to be started with a Python script as a command line parameter together with any optional parameters needed to
control the scripts behavior.
Example of usage:
sniffpython MyPythonScript.py -session mySession
Example MyPythonScript.py:
from sniffaccess.Sniffaccess import *
# --- test class
class Tests:
# --- constructor
def __init__(self, aSession):
port = SA_GetPortForSession(aSession)
self.sa = Sniffaccess(port, "localhost")
# --- Check modification of Working
#
Environment
def CheckModification(self):
print self.sa.SA_IsWorkspaceModified()
# --- main entry point
if __name__ == '__main__':
try:
if sys.argv[1] == "-session":
session = sys.argv[2]
except IndexError:
print "*** Error: session missing!"
sys.exit()
test = Tests(session)
test.CheckModification()
373
46

46.4 Connection Management

There are several ways to start a SNiFF+ session. Before starting it, you
have to decide which SNiFF+ executable should be used. Either you run
SNiFF+ in batch mode, that is, without starting the graphical user interface, using the sniffs executable, or SNiFF+ in standard mode, using
the sniff executable:
1. Specify a dedicated session name for SNiFF+ at its start up and SNiFF+
will automatically choose a free port number.
Usage:
sniff -s sessionName
or
sniffs -s sessionName
2. Specify a dedicated port number for SNiFF+ at its start up.
Usage:
sniff -p dedicatedPortNumber
or
sniffs -p dedicatedPortNumber
3. Use Sniffaccess function SA_StartSniff.
Usage:
exe = "sniff"
session = "MySession"
port = SA_StartSniff(session, exe)
Note: Using the Sniffaccess function SA_StartSniff is preferred
over the other ways, because the function will wait until SNiFF+ is up and
running.
Using a session name is a better choice, since a logical name can be
managed easily. The reason is that SNiFF+ will choose a free port
number and you do not have to check for free ports. You just have to
use the logical name. In cases where you need a port number for a
specific session the function SA_GetPortForSession provides a
way to get the corresponding port. But note that session names are only
valid on a local host. They cannot be used for connections to a remote
machine. In those cases port numbers are the only way to get a proper
connection.
374
Sniffaccess
Input and Output of Data
46.4.2 Connecting to SNiFF+

You can have multiple Sniffaccess and SNiFF+ sessions running at the
same time. There are several ways to connect to a SNiFF+ session:
1. Retrieve the port number with SA_GetPortForSession, and use
this port number to connect to the session.
Usage:
session = "MySession"
exe = "sniff"
port = SA_GetPortForSession(session, exe)
sa = Sniffaccess(port)
2. Use the port number displayed in the log window of SNiFF+ to connect to
the session.
Usage:
3. Use those port number you have used to start SNiFF+.
Usage:
46.4.3 Terminating SNiFF+

Use SA_Quit to quit sniff or sniffs. The following code fragment
uses an already established connection from a Sniffaccess object.
sa.SA_Quit()
46.5 Input and Output of Data

Sniffaccess 4.x mainly uses special classes (data types) to describe
input and output data. However, not all input and output data is a class
object; in some cases Python dictionaries and arrays are used.
Note: For all examples in this section, we assume that you have already
established a connection to SNiFF+ (see Connecting to SNiFF+ page
375) using method 1.
375
46

46.5.1 Important Data Types
WorkspacePath
Describes Source Root of a Workspace.
Note: The leading slash in the path expression is important.
Example
wsPath = WorkspacePath("/rep1/Freeze/Freeze1/ws")
The parameter passed to WorkspacePath is the SNiFF+ representation of the Workspace structure (as displayed also in the titlebar of the
Project Browser).
ProjectPath
Describes the context of a SNiFF+ Project. The context is defined by a
Project Description File for the named Project, a Project Description File
for the root Project (both relative to the Workspace), and a
WorkspacePath.
(If the named Project is itself the root Project, then its Project Description File is passed twice.)
Example
wsPath = WorkspacePath("/rep1/Freeze/Freeze1/
ws","DEFAULT")
rootPdfPath ="test/complex/complex.proj"
pdfPath = "test/complex/iolib/iolib.proj"
projPath = ProjectPath(pdfPath, rootPdfPath,
str(wsPath))
sa.SA_ListDirs(projPath)
ProjectPathArray
An array of ProjectPath objects. It is sometimes necessary to
handle a collection of Projects (e.g. Subprojects).
Example
projPathArray = ProjectPathArray()
projPathArray.Add(projPath)
sa.SA_UpdateFilesOfProject(projPathArray)
ProjectItemPath
Describes a Project item (e.g. file). It is defined by a filename (including
path) and a ProjectPath.
376
Sniffaccess
Example
item = "HelloWorld.java"
projItemPath = ProjectItemPath(item, projPath)
print sa.SA_GetFileTarget(projItemPath)
ProjectItemPathArray
An array of ProjectItemPath objects. It is sometimes necessary to
handle a collection of Project items.
Example
file = "HelloWorld.java"
projItemPath = ProjectItemPath(file, str(projPath))
projItemPathArray = ProjectItemPathArray()
projItemPathArray.Add(projItemPath)
sa.SA_Lock(projItemPathArray, "HEAD")
CombindWorkspaceSource
Represents a typical Workspace. It is a combination of the classes
WorkspaceSource and WorkspaceOrganisation.
Example
objFact = ObjectFactory.ObjectFactory()
wsSrc = objFact.CreateObject("WorkspaceSource")
wsSrc.SetName("A added TestRootEnv")
wsSrc.SetOwner("dummy")
wsSrc.SetDirectory("/WS/tests")
wsOrg = objFact.CreateObject("WorkspaceOrganisation")
combWsSrc =
objFact.CreateObject("CombindWorkspaceSource")
combWsSrc.SetWorkspaceSource(WsSrc)
combWsSrc.SetWorkspaceOrganisation(wsOrg)
newID = sa.SA_AddRootWorkspace(combWsSrc)
377
46

Project
Represents a SNiFF+ Project. It is defined by a ProjectPath and an
array of Subprojects.
project = sa.SA_GetProjectTree(projPath)
# show first two levels of the tree
project.GetProjectPath().GetProject()
projects = project.GetSubProjects()
for i in range (len(projects)):
proj = projects[i]
print "+-",
proj.GetProjectPath().GetProject()
subProjects = proj.GetSubProjects()
for j in range(len(subProjects)):
subProj = subProjects[j]
print " +-",
Snurl
Describes symbol information. A Snurl is only valid (for an instant) as
long as no modifications (e.g. removing a file, or adding a new class)
were made in the Project. Therefore it doesnt make sense to permanently store a Snurl.
Example
className = "HelloWorld"
classes = sa.SA_GetClassFromName(className)
print "--- NavigateToSymbol"
if len(classes) > 0:
ret = sa.SA_NavigateToSymbol(classes[0])
else:
print "No such class!"
WorkspaceOrganisation
Describes name, directory, and build specific attributes like platform of a
Workspace.
Note: It is part of CombindWorkspaceSource.
Example
wsAttr =
sa.SA_GetWorkspaceAttributes(wsPath)
wsOrg = wsAttr.GetWorkspaceOrganisation()
print "Name ", wsOrg.GetName()
print "BuildProfile ", wsOrg.GetBuildProfile()
378
Sniffaccess
WorkspaceSource
Describes name, directory, owner, remote directory, WorkspacePath,
and ProjectPath of a Workspace.
Note: It is part of CombindWorkspaceSource.
Example
wsAttr = sa.SA_GetWorkspaceAttributes(wsPath)
wsSource = wsAttr.GetWorkspaceSource()
print "Name =", wsSource.GetName()
print "Owner = ", wsSource.GetOwner()
print "Directory = ", wsSource.GetDirectory()
WorkspaceRepository
Describes name, directory, version control tool, and version control tool
specifics for a Workspace Repository.
GenProjectAttributes
Helper class to generate Project Properties, especially used for creating
new Projects.
Describes
Project name
Project template
array of directories scan for files (scanDirs)
array of directories to create Project (createDirs)
array of directories to ignore (ignoreDirs)

Note: If the named directories in scanDirs, createDirs, and
ignoreDirs are not disjoint, the directories from createDirs
will be considered first, and then the directories from ignoreDirs.
whether
directories
(notRecursive)
should
be
recursively
whether empty directories are included in the Project tree

(removeEmpty)
whether to ignore links.
379
scanned
46

Example
dir = "/WS/autoGenProj"
#dir = "Y:/WS/autoGenProj"
projAttr = GenProjectAttributes()
projAttr.SetTemplate("default.ptmpl")
projAttr.SetRemoveEmpty(0) # do not remove
# empty projects
ignoreDirs = []
ignoreDirs.append("/WS/autoGenProj/dummy1")
ignoreDirs.append("/WS/autoGenProj/dummy2")
projAttr.SetIgnoreDirs(ignoreDirs)
sa.SA_GenerateProjects(dir, wsPath, projAttr)
380
Sniffaccess
Examples
46.6 Examples
the following section contains some useful examples and code fragments. The examples should show how Sniffaccess can be used to perform certain tasks.
46.6.1 How to Get Currently Defined Workspaces

To get all currently defined Workspaces no prerequisites are necessary.
Example
from sniffaccess.WorkspaceRepository import *
# --- start a SNiFF session
port = SA_StartSniff("MySession")
# --wss = self.s.SA_GetWorkspaces()
for i in range(len(wss)):
print "name =", wss[i].GetName(), " wsPath =",
str(wss[i].GetWorkspacePath())
print " Directory=", wss[i].GetDirectory()
if isinstance(wss[i], WorkspaceRepository):
print " VCTool=", wss[i].GetVcTool()
46
381

46.6.2 How to Get and Set Project Properties

To get and set a specific Project property, the following prerequisites are
necessary:
open Project
Project attribute name

The Project attribute name has to be one of the following values:
Attributes , BuildDir, BuildSupport , CreateLinks ,
DisplayName, etc.
Example
# --wsPath = WorkspacePath("/MyRepository/
J_HelloWorld","DEFAULT")
pdfPath = "HelloWorld.proj"
sa.SA_OpenProject(pdfPath, wsPath)
projPath = ProjectPath(pdfPath, pdfPath, str(wsPath))
print "--- GetProjectAttributes"
attr = "DisplayName"
print "DisplayName (before change) =",
sa.SA_GetProjectAttributes(projPath, attr)
print "--- SetProjectAttributes"
value = "modifiedProject.proj"
sa.SA_SetProjectAttributes(projPath, attr, value)
print "--- GetProjectAttributes"
print "DisplayName (after change) =",
sa.SA_GetProjectAttributes(projPath, attr)
# --self.s.SA_CloseProject()
382
Sniffaccess
Examples
46.6.3 How to Add a File to a Project

To add a specific file to a Project, the following prerequisites are necessary:
Open Project
File name
Example
projPath = sa.SA_OpenProject(pdfPath, wsPath)
print "--- AddFile"
projPath = ProjectPath(pdfPath, pdfPath,
str(wsPath))
file = "Y:/ws/HelloWorld/fileToAdd.java"
sa.SA_AddFile(projPath, file)
# ---
sa.SA_CloseProject()
46
383

46.6.4 How to Lock a File

To lock a specific file of a Project, the following prerequisites are necessary:
Open Project
File name
Version name of file

If version name is not supplied, HEAD will be used.
Example
sa.SA_OpenProject(pdfPath, wsPath)
print "--- Lock File"
file = "HelloWorld.java"
projItemPath = ProjectItemPath(file, str(projPath))
projItemPathArray = ProjectItemPathArray()
projItemPathArray.Add(projItemPath)
version = "HEAD"
sa.SA_Lock(projItemPathArray, version)
# --sa.SA_CloseProject()
384
Sniffaccess
Examples
46.6.5 How to Set Preferences

To set a specific preference, the following prerequisites are necessary:
Level
Either Site or User
Specification
of the following: BuildAttributes,
WSBuildAttributes, WindowSystem
One
Tools,
Types,
Item name
Depends on Specification.
Example
print "--- GetPreferences before modification"
specification = "Tools"
prefs = sa.SA_GetPreferences(specification)
undo = int(prefs['UndoLevels'])
print "UndoLevels =", undo
print "--- set UndoLevels"
undo = undo + 100
level = "User"
data = PotDict()
data['UndoLevels'] = undo
sa.SA_SetPreferences(level, specification, data)
print "--- GetPreferences after modification"
prefs = sa.SA_GetPreferences(specification)
print "UndoLevels =", undo
385
46

46.6.6 How to Show a Specific Symbol in the Source Editor

To show a specific symbol in the Source Editor, you need:
Open Project
Class name
If class name is ambiguous, SNiFF+ will pop up a dialog where you have
to select the preferred one.
Example
# --- open project
wsPath = WorkspacePath("/MyRepository/
projPathTmp = sa.SA_OpenProject(pdfPath, wsPath)
# --- navigate to symbol
className = "HelloWorld"
classes =
sa.SA_GetClassFromName(className)
if len(classes) > 0:
sa.SA_NavigateToSymbol(classes[0])
else:
print "No such class!"
386
Sniffaccess
Examples
46.6.7 How to Change a Default Build Platform

If you want to change a Workspaces Build-Platform for multiple consecutive builds, we recommend that you refer to Synchronizing Projects
Outside of SNiFF+ page 128, in particular the section on Update
Script Parameters page 131.
To change a Workspaces default Build-Platform, you need:
Workspace
Platform name
The Platform name depends on your Workspace Properties.
Example
# --print "--- GetWorkspaceAttributes (before change) ---"
wsPath = WorkspacePath("MyRepository/
print "BuildPlatform = ", wsOrg.GetBuildPlatform()
print "--- SetWorkspaceAttributes---"
oldPlatform = wsOrg.GetBuildPlatform()
if oldPlatform == "Unix":
newPlatform = "Windows"
else:
newPlatform = "Unix"
wsOrg.SetBuildPlatform(newPlatform)
wsAttr.SetWorkspaceOrganisation(wsOrg)
sa.SA_SetWorkspaceAttributes(wsAttr.GetWorkspaceId(),
wsAttr)
print "--- GetWorkspaceAttributes (after change) ---"
print "BuildPlatform = ", wsOrg.GetBuildPlatform()
387
46

46.6.8 How to Use Notifications

To use a notification, you need:
Action name
The action name has to be a known action like OpenProject,
ForceReparse, etc.
Note that Sniffaccess only supports synchronous notification. This
means that SA_WaitForNotification waits until the specified
action occurrs.
Example
print "--- Open the Workspace Manager"
print "--- Open a project from the Workspace Manager"
sa.SA_WaitForNotification("OpenProject")
print "--- Reparse the project"
sa.SA_WaitForNotification("ForceReparse")
print "--- Close the Working Envionments Tool"
sa.SA_WaitForNotification("CloseTool")
388
Sniffaccess
Examples
46.6.9 How to Generate Projects in Batch Mode

A further example how Sniffaccess can be used is illustrated in
SNIFF_DIR4/etc/genProjects.py
This script generates Projects in batch mode. A precondition is that you
must have already defined a Workspace where Projects are to be generated.
If you want the Project Description Files to be placed in sniff_data
(or a similar directory, to avoid mixing up of Project Description Files and
source files), you have to checkmark the "Use also for Project Description Files and Makefiles" item in the Workspace Properties. The rest will
be handled by the script.
Options
-ws aWorkingEnv
Refers to the Workspace where Projects are to be generated.
Enter the full hierarchy of the Workspace. The hierarchy always starts
with a slash, each layer in the hierarchy is also separated by a slash.
[-help]
Show a help message.
[-template aTemplate]
A project template (see SNIFF_DIR4/config/templates ).
[-removeEmptyProjects]
46
Remove empty projects. An empty project does not have any file, except
a Project Description File.
[-notRecursive]
Don't walk recursively through the file system tree.
{-scanDir aDirectory}
Scan for files in the given directory(s) and add them to the generated
project.
{-createDir aDirectory}
Create a project for the given directory. Note that this it does not influence where PDFs will be stored.
389

{-ignoreDir aDirectory}
Ignore this directory; don't create a Project for that directory and don't
add it to the project tree.
Examples
Creating a C/C++ Project
sniffpython genProjects.py -ws \

"/Repository/My Workspace/AutoProjectGen"
Creating a Java Project
sniffpython genProjects.py -ws \

"/Repository/My Workspace/AutoProjectGen" \
-template java.ptmpl
46.6.10 Example Script for Updating Workspaces

A further example how Sniffaccess can be used is
SNIFF_DIR4/etc/updateWS.py.
This script is used for synchronizing Projects in batch mode.
It shows use of
Command line parameters
Input/out facilities to build up a log file
Python library mail capabilities

See also Synchronizing Projects Outside of SNiFF+ page 128 for a
more detailed description.
390
Sniffaccess
Sniffaccess Command Reference
46.7 Sniffaccess Command Reference

An extensive Sniffaccess Command Reference is available online under
Help > Online Documentation > SNiFF+ Papers > Sniffaccess
The Sniffaccess Command Reference is also available in PDF:
SNIFF_DIR4/docs/sniffaccess.pdf
46.8 Appendix: What is Python?

Python is an interpreted, interactive, object-oriented programming language. It is often compared to Tcl, Perl, Scheme, and Java.
Python combines remarkable power with very clear syntax. It has modules, classes, exceptions, very high level dynamic data types, and
dynamic typing. There are interfaces to many system calls and libraries,
as well as to various windowing systems (X11, Motif, Tk, Mac, MFC).
New built-in modules are easily written in C or C++. Python is also
usable as an extension language for applications that need a programmable interface.
The Python implementation is portable: it runs on many brands of UNIX,
on Windows, DOS, OS/2, etc.
Python is copyrighted but freely usable and distributable, even for commercial use.
Resources link:
http://www.python.org
391
46

392
47
Overview
General Format of the Parser Configuration File page 395
Ignore-Rules page 396
Ignore Pattern Rules page 396
Ignore Context Rules page 396
Replace Rules page 397
Replace Pattern Rules page 397
Replace Context Rules page 397
Definition of Wordchars page 397
Parser Filter Patterns page 398
Standard Patterns page 398
From-To Patterns page 399
Pattern Modifiers page 399
Context Rules page 401
Real Contexts page 401
Real Context definitions page 402
Context Sets page 404
Predefined Contexts and Context Sets page 405
General Parser Configuration Options page 406
C++ Parser Specific Options page 406
393

394
Examples page 408
Simple Parser Filter Configuration page 408
Simple C++ Configuration page 408
C++ Configuration Using Multiple Options per Line page 409
Ignore Class Body page 410
Replacement within Class Body page 411

Introduction
47.1 Introduction
You can influence how your source code is parsed either directly in the
Project Properties dialog (for simple options)use <F1> for context help
in the Project Propertiesor using a configuration file (the location of
which must also be specified in the Project Properties).
Options such as patterns to be ignored or replaced, context definitions,
and general options such as where to send error messages can be configured.
47.2 General Format of the Parser Configuration File
The file is in plain text, lines have to end with newline (\n)like standard
Unix text filesor with carriage return, newline (\r\n) - like standard
Windows text files.
Each line may contain one or, in many cases, more configuration options.
If more than one option per line is used, each option must end with the
appropriate option separator.
Some options like define macroname text.... read the complete

line and thus cannot be followed by another option on the same line.
Options starting with '-' must be separated by whitespace characters.
Multiple parser filter rules on the same line must be separated by ';'.
In general, option-values (e.g. filenames, macro-values etc.) may not contain any whitespace characters. If whitespace characters are needed
(e.g. in c:\my files\source\), the value has to be enclosed in double
quotes: "c:\my files\source\". On the other hand, any unnecessary whitespace characters are ignored (including empty lines and trailing
blanks before the end of line characters).
Comments may be used anywhere in the file. They start with // and
extend to the end of the line.
For compatibility reasons, # is also supported as the start of a comment,

however a warning is generated (deprecated).
If an error is found, an error message is generated and the remainder of

the current line is skipped
Strings in filter rules must be enclosed in double quotes.

For compatibility reasons, unquoted strings may be accepted in some
cases, however a warning appears (deprecated).
395
47

Regular expressions in filter rules have to be enclosed in slashes or percent signs.
47.3 Ignore-Rules
You can define rules for ignoring patterns.
A pattern can, for example, define a string, or a line containing a string,
as well as a number of other things (see Parser Filter Patterns page
398)
Example
The pattern: string "foo" will match foo
The pattern: line "foo" will match a line containing foo
Ignore-rules
ignore <ignore-pattern>
ignore context <ignore-context>
To use multiple ignore rules on a single line, use ';' as separator, e.g.,
ignore string "foo" ; ignore string "bar"
47.3.1 Ignore Pattern Rules
ignore <pattern>
ignore <from-to-pattern>
Ignores the given pattern.
47.3.2 Ignore Context Rules
396
ignore context <ignore-context>

Ignores the text matched in the context of "ignore-context".
"ignore-context" may either be a real context or a context set (see
Context Rules page 401 for more information).

Replace Rules
47.4 Replace Rules

47.4.1 Replace Pattern Rules
replace <pattern> by <replacement-string>

Replaces the pattern by the given string, e.g.,
replace string "foo" by "bar"
47.4.2 Replace Context Rules
replace context <replace-context> by <replacementstring>

Replaces the text matched in context "replace-context" with the
given string, e.g.,
replace context incomment by "/* replaced comment */"
47.5 Definition of Wordchars

The definition of word character depends on the language used (e.g. is
underscore '_' a valid wordchar?). The definition of word characters is
very important to correctly find the start/end of a word.
The same word character definition is used for all filter rules. It does not
matter whether the filter rules appear before or after the word character
definition(s).
The parser filter offers some commands to define the wordchar-set:
wordchars := <charset>
Sets the word character set.
wordchars += <charset>
Adds the charset to the word character set.
wordchars -= <charset>
Removes the charset from the word character set.
<charset> must be written in flex syntax as
397
47

[<character1><character2>...]
Note
Special characters (like '\', ']', '-', newline etc.) have to be

quoted with a backslash.
Ranges (e.g., [A-Z]) are allowed, but not predefined OSdependent charsets like [[:blank:]].
47.6 Parser Filter Patterns

There are two basic types of patterns that are used in ignore rules:
'standard'-patterns (e.g., string "foo") and
'from-to'-patterns (e.g., from "foo" to "bar")

Each pattern can have one or more modifiers after the pattern definition
(see Pattern Modifiers page 399).
47.6.1 Standard Patterns

Standard patterns can be one of the following:
398
string <string> [modifiers...]

Matches the string <string>, e.g., string "foo"
line <string> [modifiers...]

Matches the whole line containing <string>, e.g., line "bar".
regex <regex> [modifiers...]

emacs_regex <regex> [modifiers...]
Match the regular expression <regex> (in emacs syntax), e.g.,
regex /fo*/ or regex %ba*/r%

Parser Filter Patterns
flex_regex <regex> [modifiers...]

Match the regular expression <regex> (in flex syntax), e.g.,
flex_regex /foo*/ or flex_regex %ba*\/r%
Note
Strings have to be enclosed in double quotes (") (e.g.,

"foo").
Regular expressions have to be enclosed either in slashes
(/) or in percent signs (%) (e.g., /a*b/ or %a*b%)
47.6.2 From-To Patterns

From-To patterns have the following format:
from <from-string> to <to-string> [modifiers...]

By default the text including the from-string and the to-string is matched.
This behavior can be altered using the exclusive modifiers.
47.6.3 Pattern Modifiers

Pattern modifiers can be:
leading
Only match at the beginning of a word.
trailing
Only match at the end of a word.
anywhere
Match anywhere in a word.
whole
Used together with the modifiers leading, trailing, or anywhere; if
a part of the word is matched with these modifiers, the whole modifier
will output the whole that was partially matched.
<default>
If none of the above modifiers are used for string matches, only whole
words are matched.
47
399

400
begin
Only match at beginning of the line.
inclusive
start-at rule in context definition: the matched text is part of the
context to be started here, that is, the matched text is rescanned by all
rules which are active in this context.
exclusive
from-to patterns: Does not change the text matched by the "from"string and the text matched by the "to"-string. The text matched by the
"to"-string is rescanned and is considered for matches by other rules.
end-at rule in context definition: The matched text is not part of the
context to be ended here. The text matched by the pattern is rescanned
in the context which is active after leaving the context to be ended with
this rule.
switch-to context rule in context definition: The matched text is not
part of the context to be ended but it is part of the context to be started,
i.e., the matched text is rescanned by all rules which are active in the
context to be started.
start-at rule in context definition: "exclusive" is not yet supported
for this type of rule.
neither inclusive nor exclusive ("delimiter" behavior)

from-to-patterns: Also replaces the text matched by the "from"string and text matched by the "to"-string.
start-at rule, end-at rule in context definition: The matched text is
replaced by "replace context" or "ignore context" if there are
such rules. But the matched text is not scanned by any other rule.
switch-to context rule in context definition: The matched text is
replaced by "replace context" or "ignore context" when these
rules apply to the context which is ended by the switch-to rule. The
matched text is not scanned by any other rule.
target_inclusive
Only valid for the switch-to context rule: The matched text is part of
the context to be started here, i.e. the matched text is rescanned by all
rules which are active in this context. Only valid if "exclusive" is also
set.
no_default
Do not match in the default context (see Real Contexts page 401
for more information about the default context).

Context Rules
<contextname>
Also match in the context 'contextname'. contextname' may be a real
context or a set. Multiple context names may be specified. The default
context is assumed implicitly except if the modifier no_default is specified (see also Context Rules page 401).
47.7 Context Rules

We distinguish between two types of contexts: The one type is a real
context, the other type is a context set. Contexts and context sets are a
way of activating or deactivating specific parser-filter-rules for some parts
of the input files.
47.7.1 Real Contexts

There is a context called "default" which is active at the beginning of
the file. All parser-filter-rules are active in this context unless they have
the modifier no_default. Other contexts can be defined by specifying
the start and end patterns, for example:
context foo := {
start at regex /class[ \n\t]*foo[ \n\t]*{/
start at string "foobar"
end at string "}"
}
Note
The context definition (for real contexts) must always be enclosed
in curly braces.
Whenever one of the "start at" patterns of the context "foo" matches
then this context is started. When one of the "end at" patterns matches
it is ended.
Only one context is active at a specific time, i.e. while context "foo"
is active, the context "default" is not active.
401
47

If, within a context "foo", the start pattern of another context ("bar") is
matched, "foo" becomes inactive, and "bar" becomes active. When the
end of the "bar" context is reached, "foo" becomes active again.
"start at"
Push the context onto the context stack.
"end at"
Pop the context from the context stack.
The context at the top of the stack is active; that is,. all patterns are
active that have this context specified as a modifier.
Multiple contexts
A filter-rule can be active in multiple contexts, just specify all the contexts as modifiers of this rule, e.g.
replace string "abc" foo bar by "xyz"

is active in the contexts "default", "foo", and "bar".
ignore string "foobar" foo no_default baz

is active in the contexts "foo" and "baz".
47.7.2 Real Context definitions

These can be:
context <context-name> := {<context-definition-body>}

Define a new context e.g.,
context incomment := {
start at string "/*"
end at string "*/"
}
402
context <context-name> += {<context-definition-body>}

Enhance an existing context definition.

Context Rules
Syntax of <context-definition>
<context-definition-body> may contain the following rules:
Note
Multiple rules (even of the same rule-type) are allowed.
start at <pattern>
start at <pattern> replace by <replacement-string>
start at <pattern> ignore
Defines the start of the context, optionally with implicit replacements/
ignore which replace/ignore the text matched by the pattern of this rule.
end at <pattern>
end at <pattern> replace by <replacement-string>
end at <pattern> ignore
Defines the end of the pattern.
escape start at <pattern>

escape end at <pattern>
Defines exceptions for the start at /end at rules. That means, a
match for the start/end is only made if the input text is matched by a
given "start/end at" pattern but is not matched by a given "escape
start/end at".
switch to <context-name> at <pattern>

switch to <context-name> at <pattern> replace
<replacement-string>
switch to <context-name> at <pattern> ignore
Switches to the context 'context-name'.
Note
context-name must be a "real" context, not a context set.
403
by
47

47.7.3 Context Sets
A context set is a simple set of contexts. It is not possible to enhance the

definition of a context set by using start-at, end-at or switch-to
rules. The only operation allowed for context sets are removal and inclusion of other contexts and context sets.
context set definitions can be:
context <context-set-name> := <context-set>

Define <context-set-name> to be the set of the given context
names.
context <context-set-name> += <context-set>

Add the contexts to the context set.
context <context-set-name> -= <context-set>

Remove the contexts from the context set.
Syntax of <context-set>
The list of contexts defining a context set must always be enclosed in
parenthesis.
<context-set> can be:
404
( )
Empty context set, not even the default context.
( <context1> <context2> ... )

A set consisting of the given contexts.
not ( )
Set of all contexts. This means all contexts defined implicitly or in the
parser-configuration file, even if the definition of the context appears after
this context set expression.
not ( <context1> <context2> ... )

A set consisting of all contexts except the ones given.

Context Rules
Using Context Sets
A context set can be used as a modifier for a rule instead of specifying all
the contexts as modifiers, for example:
ignore string "xyz" foo bar baz
is equivalent to the following construct using the context set fbb.
context fbb := ( foo bar baz )
ignore string "xyz" fbb
The definition of a context set may contain other context sets, for example:
context abc := ( foo bar )
context xyz := ( abc baz )
Then "xyz" contains "foo", "bar" and "baz".
It is possible to specify a context set that contains all contexts except

those specified:
context cde := not ( abc bar )
The context set "cde" contains all contexts except "abc", "bar".
Whereby "all contexts" here includes all contexts specified later in the
configfile and predefined contexts!
In the following definition, the context set "all" contains all contexts:
context all := not ()
47.7.4 Predefined Contexts and Context Sets

There are two predefined contexts "instring" and "incomment"; these
may also be context sets.
Due to these predefined contexts, normal filter-rules are not active during
string constants or comments.
"instring" is active inside string constants.
"incomment" is active inside comments.
405
47

47.8 General Parser Configuration Options

The following options must end either with a newline character or any
number of whitespace characters.
-e
Send errors to log
-e=filename
-e="filename"
Save errors to file filename. The errors are always appended to this
file. Therefore, we suggest that you delete this error-log file from time to
time.
-S
-C
Deprecated options, a warning is generated
47.9 C++ Parser Specific Options

The following options should not be followed by another option on the
same line because they would be interpreted as macro text.
define macroname
define macroname text....
define macroname(param1,...) text...
undef macroname
Like the #define command of the C preprocessor. Text may extend past
the end of the line, if the line ends with '\' (also as in standard C syntax).
Caution
Do not write #define macroname in the configuration file instead
of define macroname, since the '#' character denotes the start of
a comment.
406

C++ Parser Specific Options
define_predefined macroname
define_predefined macroname text....
define_predefined macroname(param1,...) text...
undef_predefined macroname
like define/undef, but denotes a predefined macro. Predefined
macros can be cleared using the -N' option (see below)
The following options must end either with a newline character or any
amount of whitespace characters and may be followed by other options
on the same line like all options that start with "-".
-Dmacroname
-Dmacroname=value
-Dmacroname="value"
-Umacroname
like standard C++ compiler semantics: -D defines a macro, -U undefines it.
-N
No predefined macros. Undefines all predefined macros like __STDC__
__cplusplus__ etc.
-Ipath
-I"path"
Append 'path' to the standard and user include paths.
Note
The standard include path is the path used by
47
#include <file.h>', the user include path is used by

'#include "file.h"'
-IClear the standard include path, i.e., all "-I-" options specified before "-I-"
are only interpreted by #include "file.h" but not by #include
<file.h>
-Lfilename
-L"filename"
Preload include file. Has the same effect as prepending '#include
"filename"' to every file the parser is going to process.
407

-Pfilename
As in -LFileName (above); no dependency information is, however,
generated for these files, nor are these files displayed in the Include
Browser.
Use e.g. for resolving macros defined in files where no direct dependency exists.
--no-error-std-include
Do not generate error messages for unfound standard includes, e.g.
#include
<stdio.h>
47.10 Examples
47.10.1 Simple Parser Filter Configuration
ignore string "foo"
replace regex /fo*/ begin by "bar"
// replace 'f' followed by any number of 'o's
// by "bar", but only at the beginning of a line
47.10.2 Simple C++ Configuration

// comment at the start of the first example
// file
# this is also a comment, but deprecated
// the empty line above is ignored
-e // send errors to log
-Dfoo
-Dmacro="value with blank"
-U__cplusplus__
-I/usr/local/include
-I/Tools/gcc/include
408

Examples
47.10.3 C++ Configuration Using Multiple Options per Line

-Dfoo -Dbar -Dfoobar=value -Dbaz -I- -I/Tools \
-Dfoobar=value define foobarbaz cout << \
"foobarbaz" << endl;
define something(x) \
if (x) { \
cout << "true"; \
} else { \
cout << "false"; \
}
define something_else(x) (x*2)
47
409

47.10.4 Ignore Class Body

//The following
class foo{
int a;
int bar() { return 1; }
};
//is converted to
class foo{
};
//context for class body of class foo
context rawFooClassBody := {
end at string "}"
}
//handle nested {} in the class body - no need to
//check for strings and comments because these are
//the predefined contexts instring and incomment
context inNestedBracesInFooClassBody := {
//Start pattern can't be declared "inclusive" here
//because this would cause an endless loop. Thus it
//is treated as delimiter. A delimiter is not
//matched by any other rule, so it has to be
// explicitely ignored.
start at string "{" rawFooClassBody \
inNestedBracesInFooClassBody no_default ignore
//End pattern can't be declared "exclusive" because
//it would be rescanned by next context and all
//nested contexts terminated immediately, so treated
//as delimiter and explicit ignore is necessary
end at string "}" ignore
}
//Define alias for the complete class body (inside and
//outside of nested braces)
context fooClassBody := ( rawFooClassBody \
inNestedBracesInFooClassBody )
410

Examples
//Ignore everything in the context alias

//"fooClassBody"
ignore regex /./ no_default fooClassBody
47.10.5 Replacement within Class Body

Please refer also the comments under Ignore Class Body page 410.
//replace "bar" by "abc" within class body of
//class foo, that is:
class foo{
int a;
int bar() { return 1; }
};
//is converted to
class foo{
int a;
int abc() { return 1; };
};
//context for class body of class foo
context rawFooClassBody := {
end at string "}"
}
//handle nested {} in the class body
context inNestedBracesInFooClassBody := {
start at string "{" rawFooClassBody \
inNestedBracesInFooClassBody no_default
end at string "}"
}
//define alias for the complete class body (inside and
//outside of nested braces)
context fooClassBody := ( rawFooClassBody \
inNestedBracesInFooClassBody )
//replace foo by bar in the context alias
//"fooClassBody"
replace string "bar" no_default fooClassBody by "abc"
411
47

412
48
Overview
Extracting Symbol Information page 414
X-Ref Information for C/C++ and Other Languages page 415
C/C++: Automatic Generation of Cross-Reference Information page

415
Setting Workspace Properties page 415
How to Force an Update of X-Ref Information page 416
Workspaces and Cross-Referencing page 416
X-Ref Database Access Control page 416
Where Locking Information is Maintained page 418
Location and Repair of X-Ref Databases page 419
Synchronizing Workspaces page 419
413

48.1 Introduction
Cross-reference (X-Ref) information describes where a certain construct
is used (referenced) and which other constructs it in turn uses (or refers
to).
SNiFF+ distinguishes between structural symbol information and symbol
usage (X-Ref) information. For non-C/C++ languages, this differentiation
is transparent to the user. For C/C++, automatic generation of X-Ref
information can be suppressed if performance becomes a problem in
very large and complex Projects.
Cross-reference information is stored in a database. In layered Workspaces, this database is shared, which means that access controls have
to be implemented to ensure consistency.
In the following, suppression and on-demand updates of X-Ref information in C/C++ Projects is described. The implications of database sharing among Workspaces are illustrated by a number of examples.
48.2 Extracting Symbol Information

All symbol information is extracted from source code files by the appropriate language-specific parser.
Parsing is triggered
during Project setup
when modified source files are saved
when files are checked in/out
by the user (menu command)
when Projects are opened if the symbol table is not available or out-ofdate
All structural symbol information is written to the symbol table, that is in
.sniff/*.symtab.V* files stored per Project directory under the
Workspace Generated Files Location.
All generated X-Ref (usage) information is written to a database and
s tore d a t th e Wo rk sp ac e Gen erate d F iles L oc atio n in th e
.sniffdb.V* directory.
414
C/C++: Automatic Generation of Cross-Reference Information
48.2.1 X-Ref Information for C/C++ and Other Languages

Because of the nature of the C/C++ programming languages, generating
X-Ref information for very large and complex Projects can demand an
appreciable time overhead. SNiFF+ therefore allows you to suppress
automatic X-Ref generation during parsing. X-Ref information will then
only be generated on demand.
In non-C/C++ languages, e.g. Java, parsing and generating symbol information is automatically done in one pass.
48.3 C/C++: Automatic Generation of Cross-Reference

Information
Automatic generation of cross-reference information can be enabled or
suppressed at Workspace level.
48.3.1 Setting Workspace Properties
In the Workspace Manager, highlight the Workspace you want to set, and
choose Right-click > Workspace Properties.
In the navigation tree, click Parsing Properties.
In Parsing Properties node, a checkbox allows you to set the parser

default behavior. You will notice that if you checkmark Always Parse XRef Information, you cannot disable pre-processing. In order achieve
more accurate cross-reference information, C/C++ code is always preprocessed when X-Ref information is generated.
If you clear the Always Parse X-Ref Information, files are not automatically parsed on saving files. This makes saving faster, but slows crossreference queries, because not all file cross-reference information will be
up-to-date.
415
48

48.3.2 How to Force an Update of X-Ref Information

If you suppress automatic generation of cross-reference information you
can force an update either
by issuing a cross-reference query, or
choose Tools > Project Manager
In the Project Manager
Highlight the Project(s) where you would like to force an update.
Choose Project > Reparse > With Cross-Reference Info.

Depending on the Projects selected, this may not be a full update.
However, it will save time when next you issue a cross-reference query,
because information is already at least partially up-to-date.
48.4 Workspaces and Cross-Referencing

X-Ref databases are maintained at Workspace level. Although only one
X-Ref database is created per Workspace, information sharing has to
work across Workspace boundaries. This implies that some sort of
mechanism for controlling Read and Write access to database files has
to implemented.
48.4.1 X-Ref Database Access Control

Note that accessing an X-Ref database effectively means opening
Projects (with symbol information) in a given Workspace, and thereby
accessing the X-Ref database for that Workspace and higher-level,
shared Workspaces.
In the following, a number of points relating to database access control
are listed, together with examples as they affect team development.
Write access is absolutely exclusive within a Workspace.

This means that if an X-Ref database is opened for writing, no other
SNIFF+ session can access the database (neither for reading, nor for
writing). In other words, Projects cannot be opened with symbol information in that Workspace by other SNiFF+ sessions.
416
Workspaces and Cross-Referencing
Example
For day-to-day development work, you will generally open Projects (with
symbol information) in your own Workspace. Because you will want any
changes you make to be reflected also in the cross-reference information, you need Write access to the X-Ref database for that Workspace.
Which is not a problem. A problem will only arises if and when another
SNiFF+ session tries to open Projects (with symbols) in that same Workspace.
Write access is hierarchically absolutely exclusive.

Write access in a higher-level Workspace also blocks all (Read and
Write) X-Ref database access in all lower-level Workspaces.
To put it another way, if Projects are opened in a parent Workspace with
Write access, no lower-level Workspace can then access the database
system of the hierarchy in any way. This means that all Workspaces
lower down in the hierarchy are blocked in terms of symbol information.
Example
What happens when a shared Workspace needs to be updated?
Updating a Workspace means, among other things, Write access to its
X-Ref database. And Write access is hierarchically absolutely exclusive, that is, all Projects open (with symbol information) in lower-level
Workspaces have to be closed. Please refer also to Write access to an
X-Ref database that is already opened in Read mode. page 418.
If a higher-level Workspace has a Write lock, it is only possible to open

Projects without symbol information (that is, without any X-Ref database
access) in lower-level Workspaces.
Multiple Read access is possible.

Any number of SNiFF+ sessions can access a given Workspaces X-Ref
database in Read mode as long as it is not already being accessed in
Write mode (see earlier).
Example
Each user may have Projects opened (with symbols) in his or her own
Workspace, that is, with Write access to the Workspaces X-Ref database. These private Workspaces may all access a common parent Workspace. All team members will therefore have Read access to the shared
Workspaces X-Ref database.
417
48

Write access to an X-Ref database that is already opened in Read mode.

Not only is Write access hierarchically absolutely exclusive (see earlier),
it also allows you to take priority over existing Read access locks. That is,
if an X-Ref database is open in Read mode for other SNiFF+ sessions,
and you attempt a Write access, you are offered a Break Lock option.
Do not use the Break Lock option, unless you are certain that this lock is
invalid. If you break a valid lock, inconsistencies are inevitable.
48.4.2 Where Locking Information is Maintained

Locking information is maintained in a subdirectory of your
Workspace Configuration Directory (set in your Preferences) called
.snifflock/. Within .snifflock/ , a subdirectory is created for
each lockable Workspace, this subdirectory takes the name of the Workspace (hierarchy) for which the locking information is maintained, prefixed by xref_ and suffixed by _DEFAULT. All current Read access
locks are stored directly in this subdirectory. Each of these subdirectories
can have another subdirectory called exclusive/. Any existing Write
access lock on the Workspace is stored in the exclusive/ subdirectory.
Lock file names have the following syntax:
lock.<machinename>.PID
If an attempt is made to access locked databases, files are created
called
try.<machinename>.PID
These files are used by SNiFF+ to identify requests for X-Ref database
access.
418
Location and Repair of X-Ref Databases
48.5 Location and Repair of X-Ref Databases

X-Ref information is stored in a subdirectory (.sniffdb.V*/) at
Workspace level. The information in the X-Ref database is cumulative.
That is, X-Ref information for every Project ever opened in a given Workspace (hierarchy) is stored in the database.
The X-Ref information for any given project will only be removed from the
database when the Project is deleted using the Delete Project command.
If, for some reason, databases are corrupted, SNiFF+ may be able to
repair them. If the databases are irreparably damaged, they can be recreated from scratch by deleting the corrupt database files and issuing a
Force Reparse command.
48.6 Synchronizing Workspaces

Hierarchically layered Workspaces should always be updated from the
top (parent) down (child) to avoid inconsistencies.
Again: Whenever a higher-level Workspace is updated, all lower-level
Workspaces accessing it should (must) be subsequently updated.
This holds especially also for cross-referencing. Apart from all other possible inconsistencies caused by out-of-sync Workspaces, cross-reference information will also be inconsistent because, for performance
reasons, internal database objects are also shared among Workspaces.
48
419

420
Part XI
Appendix
Regular Expressions in SNiFF+
Glossary

422
A
Overview
Quick Reference - Syntax page 424
Literals and Metacharacters page 426
Quantifiers: How Often to Match page 428
Position: Where To Match page 429
Nonprinting or Whitespace Characters page 431
Character Classes or Lists page 432
Choosing from a Range of Alphanumeric Characters page 432
Excluding a Character List page 432
Metacharacters inside Square Brackets page 433
Special Character Classes in SNiFF+ page 433
Groups, Alternatives and Back References page 435
423

A.1 Introduction
Basically, regular expressions are a system of matching character patterns.
Regular expressions (regex) are a powerful means to specify patterns for
filters and search strings in the various SNiFF+ tools.
The syntax in SNiFF+ conforms largely to the GNU regular expression
syntax used in the Emacs editor, with some SNiFF+ specific enhancements.
A.2 Quick Reference - Syntax
424
Regex
matches
escape
any character except newline
zero or more occurrences of preceding
at least 1 occurrence of preceding
zero or one occurrence of preceding only
beginning of line
end of line
[...]
character list
[^...]
complement of character list
!<regex>
everything except <regex>
\b<regex>
word begins with <regex>
<regex>\b
word ends with <regex>
\B<regex>
word does not begin with <regex>
<regex>\B
word does not end with <regex>
Regex
matches
\<regex>
file begins with <regex>
<regex>\
file ends with <regex>
\f
formfeed
\n
newline
\r
carriage return
\t
tab
\v
vertical tab
\s
any nonprinting character, that is,
[ \f\n\r\t\v]
\S
any printing character, that is [^ \f\n\r\t\v]
\d
any digit, that is [0-9]
\D
any non-digit [^0-9]
\w
any word constituent, that is [A-Za-z0-9_]
\W
any non-word constituent, that is [^A-Za-z0-9_]
$<regex>$
groups
\0...\9
back references to groups
\|
alternative
%s
used to reference a retrieved string in the Retriever
425

A.3 Literals and Metacharacters

Literals in regular expressions are ordinary characters that are literally
matched, that is, they match only themselves. Metacharacters are characters that are not matched literally; they are a kind of shorthand for
defined functionalities.
Expression
Matches
Does not match
b, ...
ABC
ABC
123, ...
Metacharacters: Escape with Backslash

Characters that are used as metacharacters must be preceded by a
backslash (\) to be literally matched. These are:
Backslash (\)
Period (.)
Asterisk (*)
Plus sign (+)
Question mark (?)
Square brackets ([ ... ])
Dollar sign ($)
Caret (^)
Escape Character: Backslash (\)

The backslash (\) has escape functionality. That is, a literal character
following a backslash can escape its literalness and, in combination
with the backslash, attain new functionality (if defined). Conversely, a
metacharacter following a backslash escapes its meta-meaning and is literally matched.
If a backslash-literal sequence is not defined, the backslash is ignored
and the following character is literally matched.
426
Expression
Matches
Does not match
nothing, because not followed by anything (undefined)
\, ...
Expression
Matches
Does not match
\\
\ (first \ escapes metafunctionality)
\ \, ...
\n
newline (a defined sequence)
n, \, ...
\a
a (because \a not defined)
\, ...
Do Not Match: Exclamation Point (!)

This applies only in filter fields of SNiFF+ tools: An exclamation point at
the beginning of a regular expression means match everything except
the following regex.
Note that this is not a metacharacter in the usual sense (does not have to
be escaped, unless it is in position one of the regex). Note also that this
is a SNiFF+ specific implementation and not usually part of the regular
expression syntax.
Single Character Wild Card: Period (.)

Matches any single character, except newline (\n)
Expression
Matches
Does not match
.et
get, Get, set,

2et....
got...
427

A.3.1 Quantifiers: How Often to Match

Zero or More Occurrences: Asterisk *
Note that the asterisk is not a wild card, but a quantifier. A regex followed by an asterisk (*) matches zero or more occurrences of the regex.
A period followed by an asterisk (.*) therefore matches any character
(except newline) occurring any number of times, or not at all.
One or More Occurrences: Plus Sign +

A regex followed by a plus sign (+) matches one or more occurrences of
the regex. A period followed by a plus sign (.+) therefore matches any
character (except newline) occurring at least once.
Zero or One Occurrence Only: Question Mark ?

A regex followed by a question mark (?) matches zero or one occurrence only of the regular expression. A period followed by a question
mark (?) therefore matches any character (except newline) occurring
only once or not at all.
428
Expression
Matches
Does not match
Do*Command
DCommand
myDoCommand
DoooCommand ...
DoMenuCommand
abc ...
Do+Command
DoCommand
myDoooCommands ...
DCommand
DoMenuCommand ...
Do?Command
DCommand
DoCommand
(anything else)
A.3.2 Position: Where To Match
Matches can be restricted to their position in words, lines and files.
Beginning or End of Word \b

\b followed by a regex matches only at the beginning of a word.
\b preceded by a regex matches only at the end of a word.
Not Beginning or End of Word \B

A regex preceded by \B matches everywhere except at the beginning of
a word.
A regex followed by \B matches everywhere except at the end of a word.
Expression
Matches
Does not match
\bCommand
Command
DoCommand
Command er
...
Command
DoCommand
Commander
\bCommand\b
Command (only)
(anything else)
get\B
getDate, forgetful
get, forget...
\Bget
forget, forgetful
get, getDate...
Command\b
...
Beginning of Line: caret (^)

The caret means match the following regex only if it is at the beginning
of a line. Note that the caret has a different meaning (negation) when it
is used within Character Classes or Lists page 432.
429

End of Line: Dollar Sign ($)

The dollar sign means match the preceding regex only if it is at the end
of a line.
Expression
Matches
Does not match
^void
void (only if void is
// void, avoid,
void preceded by any
the first text in the line)
characters...
)$
foo(a) (only if the )

is the last character in
the text line)
anything where ) is
followed by any characters, e.g. ;
First in file: \Accent Grave (\`)

The \ means match the following regex only if it is at the beginning of a
file.
Last in File \Accent Acute (\')

The \ means match the preceding regex only if it is at the end of a file.
430
Expression
Matches
\.*
the first line in every file (e.g. in the Retriever)
.*\
the last line on every file (e.g. in the Retriever)
A.3.3 Nonprinting or Whitespace Characters
Nonprinting characters are represented as follows in SNiFF+ regular

expressions:
Any nonprinting character \s (lower case)

This is a special character class, namely
[ \f\n\r\t\v], the listed items are:
Space <space>
Formfeed \f
Newline \n
Carriage-return \r
Tab \t
Vertical tab \v
Expression
Matches
[ \t]+$
all (unnecessary) space and tab characters at the

end of lines.
431

A.4 Character Classes or Lists

Character Classes: Enclosed by Square Brackets [...]
A character class is a list of characters, any of which can be matched.
The list can also be excluded from matches. Ranges of ASCII characters can also be specified.
Expression
Matches
Does not match
[gs]et
get, set (only)
(anything else)
A.4.1 Choosing from a Range of Alphanumeric Characters

A minus sign (-) within square brackets indicates a range of consecutive
ASCII characters. For example, [0-9] is the same as [0123456789].
Expression
Matches
Does not match
Do[A-Za-z]*Command
DoCommand
DoMyCommand
Do-Command
Do88Command
abc...
A.4.2 Excluding a Character List

If the first character in the square brackets is a caret (^), any character
except those in the square brackets will match.
432
Expression
Matches
Does not match
Do[^\s(Cc]
DoMenuCommand
DomouseCommand
Domino
Do (followed by space)
Do(
DoCommand
abc...
A.4.3 Metacharacters inside Square Brackets
To include the minus sign itself in a range, it must be the first character
(after an initial ^, if any see Excluding a Character List page 432),
e.g., Do[-A-Za-z]*Command would also match Do-Command.
If a right square bracket (]) immediately follows a left square bracket, it
does not terminate the set but is considered to be one of the characters
to match.
The caret (^) in first position negates the rest of the character class.
All other metacharacters, such as backslash (\), asterisk (*), or plus
sign (+) etc., are also matched literally if they are inside square brackets.
A.4.4 Special Character Classes in SNiFF+

Special character classes can be used in SNiFF+ as a kind of shorthand
to make writing (and reading) regular expressions easier.
Any word constituent character \w (lower case) which includes all

alphanumerics and underscore, that is, [A-Za-z0-9_]
Any non word-constituent character \W (upper case), that is,

[^A-Za-z0-9_]
Any digit \d, that is, [0-9].
Any non-digit \D, that is [^0-9].
Any nonprinting (whitespace) character \s (lower case), that is,

[ \f\n\r\t\v]. This class is described under Nonprinting or Whitespace
Characters page 431.
Any printing character \S (upper case) which is everything except

nonprinting or whitespace characters, that is, [^ \f\n\r\t\v]. See also Nonprinting or Whitespace Characters page 431.
433
Example
The following example tries to match any call of foo that takes at least one
parameter. The first expression tries to achieve this by excluding ), but
neglects the possibility of nonprinting characters, compound words and nested
parentheses. The second expression covers these eventualities and matches
the entire call up to, and including, the final closing parentheses.
Expression
Matches
Does not
match
foo([^)]+)
foo(a)
foo( )
myfoo(int a, int b, c)...
foo (a)
foo()
any foo with at

least 1 parameter
(anything else)
<foo\s*(\s*[^)\s][.\n]*])
...
In the second expression above, recall:

< beginning of word
foo three ordinary literal characters that match themselves
\s any nonprinting character
* zero or more occurrences of preceding, here \s
( an ordinary literal character that matches itself
[^)\s] anything except ) and nonprinting characters
[.\n]*] any character and newline, zero or more occurrences
) an ordinary literal character that matches itself
A.5 Groups, Alternatives and Back References
Groups enclosed in \parentheses $...$

Alternatives \pipe \|
Back References \1...\9
Groups enclosed in $...$ serve three purposes
To group an expression so that it can be treated as if it were a single character. For example, a group will be governed by a quantifier like * as if it
were a single character:
Thus, ba$na$* matches ba, bana, banana, bananana, etc.
To enclose a set of \| alternatives.

For example, my$foo\|bar$ matches either myfoo or mybar.
The alternation (\|) applies to the largest possible surrounding expressions. Only a surrounding $ ... $ grouping can limit the grouping power of
\|.
To mark a matched substring for back references. The first nine groups in
a regex can be referenced using \1 through \9.
For example, $bo)\1 will match bobo. Groups, alternation and back
references can be useful in find/change operations either for global
editing in the Retriever or in the Source Editors Find/Change dialog.
435

Examples
1. This example matches
SetupMenu or SetupStyles and

changes Setup to Update
concatenates this with Menu or Styles (whichever was matched) and
adds the substring Always at the end.
Find:
Setup\(Menu\|Styles$
Change to:
Update\1Always
Good results
Found DoSetupMenu and changed to DoUpdateMenuAlways
Found SetupStyles and changed to UpdateStylesAlways
Potential pitfall
Found SetupMenu Styles and changed
waysStyles
Remember: "The first match always wins."
436
to
UpdateMenuAl-
2. This example matches
foo(parameter1,parameter2)
and changes the parameter order. Nonprinting characters are not taken
into account, nor are nested parentheses considered.
Find:
<foo($[^,]+$, $[^,]+$
Change to:
foo(\2,\1)
Good results
Found foo(a,b) and changed to foo(b,a)
Found foo(int a,char* b) and changed to foo(char* b,int a)
Potential pitfall
Found foo(f(x,y),int b) and changed to foo(y),f(x,int b)
You could of course "fix" the regex by matching ; at the end, but that
does not solve the actual problem. As always, its safer to check before
globally changing things.
Regular expressions are cumbersome for nested parentheses of any
depth, and cannot handle arbitrary depths.
437

438
B
Glossary
Overview
SNiFF+ System Concepts page 440
Version Control Concepts page 443
Build Concepts page 447
439

B.1 SNiFF+ System Concepts
440
Browser
A Browser is a tool that is used for viewing data. SNiFF+ offers several
browsers, such as the Include Browser, the Class Browser, or the Hierarchy Browser. The information displayed in a browser can be filtered to
make it more specific.
Editor
An editor is a tool that is used for both viewing and changing data.
SNiFF+ offers a number of editors, such as the Source Editor and the
Diff-Merge tool.
File Type
In order that SNiFF+ can deal with a file correctly, it must be assigned a
File Type, based on its signature. Knowing a files type, SNiFF+ is able to
display the correct icon for the file, present the correct context menu, and
parse the files contents correctly to extract symbol information. Examples of File Types are C++ Implementation, and Java Source.
Index
An index stores references to names and other strings in such a way that
searching can be done quickly by the Retriever. An index saves time
when many searches are to be done, but generating an index for the first
time may require a little patience, and some disk space.
Information Pane
The part of the graphical user interface where the information log and
other non-browser information is displayed. You can hide the pane if you
need more space for browsers.
Navigation Pane
The part of the graphical user interface containing the file list, and symbol
lists. Using the navigation pane, you can quickly find the symbol or file
that interests you, then use browsers to examine how its used in the
source code. You can hide the pane if you need more space for
browsers.
PDF
See Project Description File.
Glossary
Preference
Preferences are the customizable attributes of SNiFF+. SNiFF+ supports
user-level and site-level preferences. Most preferences can be edited
with the Preferences dialog.
Project
A Project is used to modularize source code in a system. Each Project
may contain files, and depend on other Projects, which are called
Subprojects. Use Projects to group and organize your source code.
Project Browser
The main view to a Project; the main SNiFF+ window that holds all other
tools used to work with a Project.
Project Description File

A Project Description File is the file that describes a Project's properties,
structure and contents. A PDF is a structured ASCII file that is created,
saved and opened by SNiFF+. To save a change to a Project, the PDF
must be writable.
Source Root
Where a Workspaces source code files are stored. Project Description
Files normally refer to source code files using locations which are relative
to the Source Root, so that the same Project can be used in different
Workspaces, each with their own source code.
Symbol
A symbol is a named language construct in the source code. Examples
include classes, global functions and preprocessor macros.
Symbol Table
A Symbol Table is the information base that contains information about
the declaration, definition and use of named program elements such as
classes, methods, variables and functions of a Project. Each Project has
its own Symbol Table that is generated and maintained by the appropriate language parser. Symbol Tables are kept in memory and are
persistently stored to disk.
Template
A generic model for a Project, which can be used to create many
Projects with similar properties. For example, a C Project template may
specify that C source files and C header files are to be included in
Projects instantiated from it.
441

442
Workspace
A Workspace offers a complete source-code engineering context, which
allows a user to develop software, isolated from others. It has its own set
of properties affecting, for example, source-code parsing, and the build
system. The Workspace usually provides file-system storage for its own
copies of source code, using the Source Root, although Workspaces
which refer to source code which do not need to provide their own
storage. The Workspace also specifies where the Project Description
Files, which organize the source code, are stored, as well as other
adminstrative files generated and maintained by SNiFF+, using the
Generated Files Location. The Workspace Manager presents all the
Workspaces available to a user, and shows which Projects are present in
each one.
Workspace Hierarchy
Workspaces may be organized into a hierarchy. In such a hierarchy,
lower Workspaces depend on higher Workspaces. The lower will use the
files present in the upper, except for files which are to be modified (overridden) in the lower. On operating systems which provide symbolic links
(such as Unix), this technique can save space when large amounts of
source code are common between two Workspaces. However, on operating systems without symbolic links (such as Windows), such a technique is less useful.
Glossary
B.2 Version Control Concepts
Adaptor
An Adaptor wraps a specific CMVC tool so that SNiFF+ can use it to
implement the generic functions provided to users in the graphical user
interface. For example, both RCS and SCCS are presented to the user in
a similar way through the SNiFF+ menus, despite the fact that the
command-line interfaces to these tools are quite different.
Branch
A Branch occurs in a version tree when you create new revisions of an
element from the middle instead of the end of its history tree. This can be
useful, for example, when fixing bugs in older revisions.
Change-Set
When checking a set of files in (or even just one file), SNiFF+ allows you
to name the related changes by putting a logical label on the revision(s)
created.
Check-in
Check-in is the process of creating a new revision of a file in the Repository. In order to check a file in, you must have locked the repository file
(because otherwise another user might have checked changes in which
you would overwrite). A file check-in can be associated with a ChangeSet. SNiFF+ delegates the actual check-in operation to your underlying
CMVC tool (by means of CMVC adaptors). SNiFF+ allows you to check
multiple files in at once, linking them with a Change-Set.
Check-out
Check-out is the process of obtaining a working file in a Workspace from
a specific revision in the Repository. An exclusive check-out places a lock
in the Repository, and creates a writable working file, while a concurrent
check-out creates a writable working file without locking the Repository.
Finally, a no-lock check-out creates a read-only working file. If you check
a file out while you have a writable working copy, SNiFF+ will ask you to
confirm overwriting your existing working copy.
CMVC
Configuration Management and Version Control.
Configuration
A configuration is usually a coherent and consistent state of a system
(composed of a set of files). Typically, a configuration is a buildable state
of a system. You can freeze such a configuration by giving it a name and
443

thereby creating a virtual snapshot of the system. That is, specific revisions of files then belong to the same, named Freeze-point. See also
Freeze-Point page 444.
Configuration management
Configuration management is the process of controlling and administrating the components of configurations. Configuration management
includes the definition of Freeze-points.
Default Configuration
A Default Configuration is the Configuration of your software system that
you work on. You can set your Default Configuration when you define
your Workspace, by making it dependent on a Configuration node in the
Workspace Manager. SNiFF+ uses your Default Configuration for the
default value when you choose one of the various version control
commands, such as checking files out, and locking and unlocking revisions in the Repository. Source files are made up-to-date with respect to
the Default Configuration.
By default, the HEAD version of your software system is the Default
Configuration for your Workspaces.
Freeze-Point
A Freeze-point is a virtual snapshot of your system at a given point in
time. This configuration of file revisions, usually a stable system, is given
a name and frozen. See also Configuration page 443.
Merge
Merge is the process of combining the contents of two or more files into a
single file. Typically, the files involved in a merge are revisions of a single
Repository element. A merge can be done automatically, but often
requires manual intervention to resolve conflicts. SNiFF+s Diff-Merge
tool is a powerful editor for merging files.
HEAD
HEAD is the latest revision on the trunk or branch of a files history tree.
History
The History reflects all the different revisions of a file and is stored in the
Repository.
INIT
INIT is used by SNiFF+ as name to refer to the initial version of a file in

the Repository. The INIT version is created when a file is checked into
the Repository for the first time.
444
Glossary
Integration
Please see Adaptor.
Lock
A lock is a mechanism that controls creation of successor revisions of
elements in the Repository. SNiFF+ distinguishes between exclusive
locks (only one developer can modify a specific revision) and concurrent
locks (multiple developers can simultaneously modify the same revision).
Main branch
A main branch is the starting branch of a file's version tree. Unless otherwise specified by your default configuration, the main branch is the
default branch for CMVC operations.
Repository
A Repository contains all Repository Elements of version-controlled
Projects. The Repository is typically directly accessed only by the
managing CMVC tool, controlled by SNiFF+ through an Adaptor.
Repository Element
A Repository Element is the object in the Repository that saves the
complete history tree of a file.
Revision
A Revision is a specific version of a file. Each time a file is checked in to
the version control system, a new Revision of the file is created. The
Revision history of a file can be viewed using the Revisions tool.
State
State is a descriptive string that can added specified as property of a file
revision. Generally a house-convention is used to identify all file revisions
at the same state of development. This property is then changed when
the file reaches a new state of development. Examples could be
approved or released etc.
Update
Updating is the process of checking out all new HEAD versions of
Projects in a working environment, in order to come up-to-date with the
latest development state. Working files which are writable will not be
overwritten by an update. Updates can be done manually, or automatically
VCS
Version Control System.
445

446
Version
A file can have several versions. Likewise, a software product can have
several versions. Versions in the first sense are called Revisions in
SNiFF+, and versions in the second sense are called Configurations.
This usage helps to avoid confusion caused by the word version.
Version control
Version control is the process of managing and administrating file revisions. Most functionality is accessed through the file list in the navigation
pane.
Working File
A working file is a checked-out revision of a Repository Element, located
in a working environment. Any changes to the working file will be local,
unless the modified file is checked in. Working files are not affected by
new revisions checked into the repository by other users unless an
update is done.
Glossary
B.3 Build Concepts
Adaptor
An Adaptor wraps a specific debugger, so that SNiFF+ can provide
access to its functionality generically through the graphical user interface.
For example, an adaptor for the GNU debugger gdb allows you to step
through your codes execution and monitor variable values without having
to learn any specific command-line controls.
Build
Building is the process of creating the targets of a Project, usually by
compiling source code files, then possibly linking object files. Building is
controlled by the dependencies described in Build-Support files.
Build-Properties
When a particular file requires special settings for the tool used to build it,
this may be done using the files build properties. For example, a file may
require a specific preprocessor macro to be set, which is not relevant for
any other file in the system. Such local build-properties override more
general properties defined by the environment.
Build-Support File
A Build-Support file is a control file for the Build process, generated by
SNiFF+. It contains information about dependencies, based on SNiFF+s
knowledge of the source code, and information about which Build Tools
to use. For example, such a file may specify that A.obj is to be built if
A.cpp is newer, using the C++ compiler.
Build Tool
A Build Tool is a translator (such as a compiler) that must be used to
generate a derived file from the files it is dependent on. The precise
settings for each Build Tool are selected according to the chosen Platform.
Dependency
A dependency is a relationship between two files that implies that one file
must be updated or rebuilt when the other one changes. For example, an
object file (or a class file) is dependent on the source code file that its
compiled from. Source-level dependencies can be extracted from source
code and are typically stored in dependency files. SNiFF+ generates
dependency files that are included by Makefiles as part of its BuildSupport feature.
447

448
Derived file
A derived file is a file that can be generated (derived) from another file. A
typical example is an object file, generated from a source file through
compilation.
Make
Make is the program that reads Makefiles and drives the build process.
SNiFF+ integrates a wide range of different Make implementations.
Makefile
A Makefile is a text file read by Make programs that describes the
building of targets. A Makefile contains source-level dependencies and
build-order dependencies. As part of its Make Support feature, SNiFF+
generates Build Support Files that contain both kinds dependency information.
Platform
A Platform identifies a particular target architecture for the Build process,
for example, Windows or Linux. Each Platform specification has its own
settings for Build Tools: for the Windows Platform, the C++ compiler may
be called cl, while on Linux its name would be g++. Output for different
Platforms is normally placed in different Redirection Directories.
Redirection Directory
When a Build is performed, the results of the build are placed in a
specific Redirection Directory, based on the Platform selected by the
user. This avoids problems such as linking together code compiled for
different architectures, or accidently linking debug and optimized code
together.
Remote Build Host

SNiFF+ allows you to run the Build process on a machine (a host) other
than the one where your SNiFF+ session is executing. This may be
useful when a fast machine is available for compilations but not for interactive use, or when compilation is for a different machine architecture.
Using a remote build host, you can cause the Build to be performed
remotely.
Target
Making a target up-to-date is the aim of the build process. A target is
often an output file, such as a executable, or a library. SNiFF+ allows
multiple targets to be specified for a single Project. Building the target
means checking (transitively) all the dependencies of the target, and
using the correct Build Tool to update any out-of-date files.
Index
A
absolute project 88
how and why 89
ada
set targets and debugger 175
ada and tornado 165
ada and vwxorks 165
ada integration script 170
adaptor, create version control 252
additional includes 145
administrator, workspaces 33
analysis and browsing workspace 39
application target (java), build 159
autonomous workspace 42
B
batch mode 130
branch 257
create branch revision 261
from configuration 258
head and 258
using 261
working on 262
working with, introduction 259
build
ada projects 165
c/c++, additional includes 145
c/c++, summary of steps 140
concepts 447
custom setup 193
custom target 193
gnat 165
idl projects 187
ignore dependencies 151
inheritance of properties 241
introduction to the system 222
jar targets 181
java file 159
java idl 181
java project 159
java projects 149
jni 181
platform change in batch mode 132
project structure restrictions, c/c++ 246
project structure restrictions, java 246
remote 197
rmi 181
tool assignment 238
unattended for different platforms 132
workspace and, introduction 20
build host, remote 226
settings 74
build properties
file 75
file type for version controlling 76
file, create project for 78
inheritance, cascading and levelling 242
inheritance, file level 243
449

inheritance, project level 243

inheritance, workspace level 243
modify for workspace 74, 208
modify in preferences 207
version controlling 75
build tool 226, 227, 233
arbitrary and pre-defined field names
bits and pieces 237
command macros 234
example 228
fields in 233
file types and 247
macros in command 234
modify 205
modify, introduction 206
platform 228
settings 74, 231, 247
settings, where to modify 206
template, what for 235
build-product location 224
234
C
c++ code documentation
generate 121
introduction 120
tags recognized 123
c++ parser 393
configuration options, general 406
configure 393
c/c++ project
additional includes 145
automatic generation of cross-reference
information 415
build setup, summary of steps 140
build system and project structure 246
build tool settings, verify 146
parsing 73
set include paths 143
set targets and debugger adaptor 141, 175
change-set 257
check in 256
first 53
check out 256
first 61
class path to libraries 156
clearcase
change config spec 272
change view 271
clearmake 273
create project for 271
how to integrate 271
preparation 47
set generated files location 272
synchronize project with view changes 273
vobs and views in sniff+ 271
workspaces 47
clearmake
default for new workspace 275
existing workspace, and 273
using 273
cmvc, basic concepts and terminology 255
code documentation comments 122
code location 84
command line
sniff 130
synchronize 128
update 128
update script paramaters 131
comments, for code documentation 122
compile, file 246
compiler
c++ 228
flag for jdk 1.1.x (-c command line length) 158
java 206
concepts, glossary 439
build 447
system 440
version control 443
configuration 256
branch from 258
context menu, custom 361
context menu,context 364
create
450
Index
custom template 88
file type 106
project for build properties file 78
project for clearcase-controlled code 271
project from template 87
project with wizard 85
create file 96
creation wizard, project 49
cross-reference system 413
c/c++ vs. other languages 415
database access control 416
force update 416
location and repair of databases 419
update 416
workspace properties, set 415
workspace, and 416
workspace, synchronize 419
custom build setup 193
custom menu 361
right-click 364
custom menu configuration file 362
specification 367
custom project template 88
custom targets, enable menu 193
cvs
integrate 277
migrating to 288
pitfalls 289
remote repository and multi-site development 288
version and compatibility 278
windows to unix 288
cvvs
synchronize project with on-disk changes 287
D
database
location 419
repair 419
debug 211
and own makefiles 193
application project 212
debugger 213
java,remote vm 160
java,startup parameters 162
multiple sessions 217
remote 197
romote target vm 160
target 213
default configuration
assign to workspace 266
branch development, and 19
hierarchical workspace, and 268
default platform 209, 226
delete file from disk 96
delete project 98
derived file
signature 229
derived file type 104, 107
as intermediate product 108
directory
documenter output 121
java output classes 155
location of redirection 225
make command and redirection 224
scan project 99
workspace configuration 43
documentation
code, introduction 120
comment, description section 122
comments 122
general form and location 122
generate for c++ code 121
tag list 123
documention
output directory 121
E
emacs 307
command reference 313
connect 310
how integration works 308
integrate 309
451

key bindings, modify 311

menu entries, modify 311
position from sniff+ 311
prerequisites 309
sniff+ and 311
starting sniff+ 309
switch buffer 312
switch to sniff+ mode 310
the sniff menu 312
example
build tool 228
default configuration and branch-work
execution target, add 153
derived settings 109

manage 104
working with 103
first
265
check-in 53
check-out 61
team member 48
flag for jdk 1.1.x compiler 158
flat workspace, hierarchical vs. 31
force update, cross-reference information 416
format of parser configuration file, general 395
fortran 111
freeze head 265
field names, arbitrary and pre-defined 234

file
add from directory 99
add/remove 97
build java 159
build properties 75, 243
compilation 246
compilation, how it works 190
compile 245
create 96
create branch revision 261
create project for build properties 78
delete on disk 96
general format of parser configuration 395
move 96
move projects and 97
obsolete 99, 128
other 99
rename 96
file type 104
add 190
build tool, and 247
create new 106
custom context menu 361
custom menus 364
derived 104
generate
c++ documentation 121
include-paths 144
generated documetation, general form and location
generated files location 23
generated files, relative location 25
generated includes 229
generated target settings 238
gnat
build 165
gnat and tornado/vxworks 165
gnat integration 170
gnat integration script 170
H
head 258
branch, and 258
freeze 265
hierarchical workspace 31
do not use if 31
host settings, remote build 74
host, remote build 226
how and why absolute projects 89
452
122
Index
I
idl
add file 190
add file type 190
browsing 191
derived file types 188
file types 188
how mapped 191
interface file type 188
java compiler 184
parser mapping 191
project 187
requirements 189
symbol 191
what to do 189
ignore dependencies 151
implicit workspace selection 89
include-directives, order 237
include-paths, generate 144
includes, additional 145
includes, generated 229
inheritance of build information 241
init 258
integration
emacs 307
pvcs 291
rose 329
set version control tool 253
sourcesafe 299
version control tools 251
vim 319
integration script 170
J
jar 181, 184
java
application target, build 159
archive builder 184
build project 159
build project classes 159
build setup 149

build, summary of steps 150
compile file 159
compiler 157, 206
compiler and build tool settings, verify 157
debug remote vm 160
documentation tags 123
file, build 159
jar 184
jdk 1.1.x, command line length 158
jni 184
libraries, class path to 156
output directory 155
project 159
project build structure restrictions 246
project, build 159
promote build tool settings to workspace level
rmi 185
set output directory path 155
set source path 154
set targets and debugger adaptor 153
source path 154
switching build modes 160
tags for documentation 123, 124
java archive builder 184
java build, exclude jdk 151
java idl 181
java native interface compiler 184
jni 181, 184
L
layered workspace, do not use if 31
literals and metacharacters 426
location
generated files 24
project and makefiles 24
redirection directories 225
source code 84
source root 24
lock 256
453
158

output location
make command and redirection directory 224

make support, own 193
makefiles, using your own 193
manage
file types 104
projects 96
workspace 71
Managing 96
menu, enable for own custom targets 193
metacharacters, literals and 426
modify
build tools and settings 205
project properties 100
project structure and content 97
workspace build properties 74
move file 96
move projects and files 97
N
new
file type, create 106
platform as default 209
project from template 87
project with wizard 85
team members 63, 70
workspace 63, 69
O
obsolete files 99, 128
open
options for opening projects 93
project 62, 92
project from workspace 92
open-project options, accessing 95
options, syncProj.py 134
options, updateWs.py 131
other files 99
output directory, documenter 121
224
P
parameters
remote java debug 162
parameters, project synchronization script 134
parameters, update script 131
parser
c++ configuration file, general format of 395
c++ configuration options, general 406
configure the c++ 393
configuring c++, introduction 395
parsing, c/c++ 73
passed to super project format 229
passed to superproject format 229
paths, generated include- 144
percent sign, used in macros 234
platform 223, 231, 235
build tools and settings 232, 236
change in batch builds 132
copy 209
default 226
default, new 209
pre-defined field names, arbitrary and 234
preferences 242
file types 105
modify site-level 207
project 13
absolute 88
absolute, how and why 89
absolute,whats wrong with 88
add files 99
add/remove file 97
add/remove subprojects 98
and workspace, create 37
application 212
build 245
build ada 165
build and structure, c/c++ 246
build and structure, java 246
build c/c++ 139
454
Index
build java 159

build structure restrictions c++ 246
build structure restrictions java 246
concept, introduction 14
create for build properties 78
create from scratch 83
create in workspace 84
create only once 82
create, overview 81
create, with wizard or template? 83
creation wizard 49
delete 98
derived file types, and 189
documenting 119
for build properties file, create 78
for clearcase-controlled code, create 271
from template, create 87
inheritance of build properties 243
java 159
manage 96
move 97
open 62, 92
open from workspace 92
open, use cache, or re-read all data 94
open, with write/read-only database-access 94
open, with/without symbol information 93
opening-options 93
platform settings, verify 202
promote project build tool settings to workspace
level 147
properties 100
properties, modify 100
properties, where from 100
recent 92
remove/add file 97
remove/add subprojects 98
scan directories 99
setup, introduction 260
some advantages 14
structure and build system 246
synchronize with clearcase view 273
template 88
template, create custom 88

what it knows 16
wizard, create with 85
working with 14, 91
project and makefiles, relative location 25
properties
build, modify in workspace 208
file level build 243
project 100
target 238
version control build properties 210
workspace 73
pvcs
access control 293
adaptor 294
adaptor configuration 295
adaptor configuration files 295
assumptions 292
custom menu 295
feature overview 294
integrate 291
integrating with sniff+ 291
integrating, overview 291
introduction 292
limitations 295
member storage 293
non-default settings in configuration file 296
parallel development 293
project setup 295
requirements 293
setting up projects with sniff+ 295
version and compatibility 293
version and compatibility information 293
version manager 293
R
rational rose integration 329
read-only database access 94
redirection directory
location of 225
make command and 224
455

redirection directory location 225

regex
alternative 435
back reference 435
exclude character list 432
group 435
match at position 429
metacharacters in square brackets 433
nonprinting or whitespace characters 431
quantifiers,how often to match 428
special character classes in sniff+ 433
syntax quick reference 424
regular expression
alternative 435
back reference 435
character classes or lists 432
character range 432
class of characters 432
exclude character list 432
group 435
list of characters 432
overview 423
range of characters 432
relative project and makefiles location 25
remote
build and debug 197
build host 226
build host settings 74, 198
code, location 199
default host 201
how host finds sources 199
java 203
source location 199
remote debug
java, startup parameters 162
remove subprojects 98
rename file 96
reorganize workspace 72
repair database 419
repository 256
create node for 59, 67
repository-based tools (rcs...) 47
restrictions
c++, project build structure 246
java, project build structure 246
reverse order 237
right-click custom menu 364
right-click menu, custom 361
rmi 181
rmi stub compiler 185
rose integration 329
run 211
application project 212
custom target 193
target 212
run sniff without gui 130
S
script, ada integration 170
set
project targets and build tools 182
remote build hosts for workspace 198
remote host as default 201
version control integration 253
settings
build tool 74, 247
modify build tool template, and 205
remote build host 74
sharing or layering workspace 20
site-level preferences
build properties and 207
modify 207
site-level workspace configuration 44
sniff in batch mode 130
sniff+ pro build system, introduction 221
sniff+, version control tools and 252
SNIFF_DIR4 8
sniffaccess
connecting to 374
data input/output 375
datatypes 375
examples 381
introduction 372
456
Index
invoking 373
terminating sniff 375
sniffapi
architecture 340
compile sample program 356
concepts 339
data model 349
encoding details 348
getting started 353
id concept 347
introduction 340
jar file setup 355
query interface 341
requirements 354
run sample program 356
scope handling 345
set up jar files for client compilation
usage model 342
source code location 84
source root 22
location 24
write permission 48
sourcesafe 299
branch 303
change-set 303
check in 302
compatibility 300
configuration 303
file descriptions 303
integrate 299
locking 303
prerequisites 300
set up project with 301
start sniff in batch mode 130
startup parameters
java debug 162
subprojects, add/remove 98
subroject
add new 89
supported version control tools 252
synchronizing projects 125
outside of sniff+ 128
with file system 126

with version control system
within sniff+ 127
syncProj.py, parameters 134
system concepts 440
126
T
tags
354
123
documentation, java 124
documentation, java and c/c++ 123
target
build application 159
debug 213
properties 238
run 212
team project
preparation 46
template
create custom 88
create project from 87
terminology 439
source root, generated files location, and
repository 21
version control 256
tornado/vxworks and gnat 165
U
unattended updates 130
update
project from command line 128
update cross-reference information 416
update script parameters 131
update-order, workspace 127
updateWS.py, parameters 131
V
verify project platform settings
version control
457
202

build properties 75, 210

build properties,new file type for 76
concepts 443
create adaptor 252
set integration 253
terminology 256
tools and sniff+ 252
tools, integration of 251
tools, supported 252
vim 319
command reference 325
connect at start-up 324
connection 323
how integration works 320
key mappings 324
preparation for integration 321, 322
prerequisites 321
sniff+, and 324
starting sniff+ 323
vxworks and ada 165
W
wizard
create project with 85
project creation 49
templates and 83
workspace 17, 21, 29
administrator 33
analysis and browsing only 39
and projects, introduction 18
and repository access 264
assign default configuration 266
assign default configuration to 266
autonomous 42
branches and default configurations 264
build properties, modify 74, 208
build properties, project for 78
configuration data 42
configuration directory 43
configuration, site-level 44
configurations, and branches 263
create 38
create dependent 68
create new 60
create node for shared 67
default configuration 266
disk space,and 32
existing, and clearmake 273
first 46
flat, new team members 57
hierarchical vs. flat 31
hierarchical, caveate 31
hierarchical, new team members 65
hierarchical, not suitable 31
hierarchical, organization and coordination
hierarchical,issues 32
implicit selection 89
manage 71
name and locations 73
new 63, 69
open project from 92
organization systems 30
performance 32
properties 73
reorganizing 72
stand-alone 35, 36
stand-alone plus project 36
stand-alone without project 38
storage 18
synchronize build properties 210
teams from scratch 45
user autonomy, and 41
what for 18
write/read-only database-access 94
458
54

Users Guide Vxworks

Diunggah oleh

Informasi Dokumen

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

Users Guide Vxworks

Diunggah oleh

Hak Cipta:

Format Tersedia

SNiFF+/SNiFF+ PRO

Copyright 8/29/02 Wind River Systems, Inc.

SNiFF+/SNiFF+ PRO Users Guide and Reference, 4.1

Projects and Workspaces

SNiFF+/SNiFF+ PRO 4.1

Workspace Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29

Team Workspaces from Scratch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45

New Team Members (Hierarchical Workspace System) . .

Working with Projects

Working with Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

SNiFF+/SNiFF+ PRO 4.1

Working with Fortran . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111

SNiFF+ PRO Build/Debug: How To

C/C++ Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139

Run the GNAT Integration Script . . . . . . . . . . . . . . . . . . . . . . . . .

JAR, Java IDL, JNI, and RMI Settings . . . . . . . . . . . . . . . . . . . . . . . . . .

Custom Build Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Remote Build and Debug. . . . . . . . . . . . . . . . . . . . . . . . . .

Modifying Build Tools and Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

SNiFF+/SNiFF+ PRO 4.1

Memory View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217

SNiFF+ PRO Build System Concepts

SNiFF+ PRO Build System: Introduction . . . . . . . . . . . . . . . . . . . . . . . . .221

Version Control and Configuration Management

Integration of Version Control Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . .251

Working with Branches: Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . .

Workspaces, Configurations, and Branches . . . . . . . . . . . . . . . . . . . . .

Integrating SNiFF+ with CVS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Integrating SNiFF+ with PVCS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

SNiFF+/SNiFF+ PRO 4.1

PVCS Version Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .293

Editor and Other Integrations

Emacs Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .307

Configuring the C++ Parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

SNiFF+/SNiFF+ PRO 4.1

Parser Filter Patterns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .398

Regular Expressions in SNiFF+ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .423

SNiFF+/SNiFF+ PRO 4.1

The SNiFF+ Documentation SetGuidelines page 4

Beginners Guides page 4

Users Guide and Reference page 5

GUI and Menu Command Reference page 5

Getting Started for Tornado Teams page 5

Installation Guide, Release Notes, SNiFF+ Papers page 5

Feedback and Useful Links page 6

SNiFF+/SNiFF+ PRO 4.1

1.1 The SNiFF+ Documentation SetGuidelines

1.1.1 Beginners Guides

SNiFF+ PRO: Build and Debug Tutorial

CMVCConfiguration Management and Version Control

1.1.2 Users Guide and Reference

The Users Guide and Reference provides more in-depth information

Fundamental SNiFF+ concepts: Projects and Workspaces

Workspace and Project management

How-to guides to procedures

Technical descriptions of various subsystems (e.g. Build System)

Version Control and Configuration Management

Integrations of version control tools, editors, and other tools

Regular expression usage in SNiFF+

1.1.3 GUI and Menu Command Reference

1.1.4 Getting Started for Tornado Teams

1.1.5 Installation Guide, Release Notes, SNiFF+ Papers

SNiFF+/SNiFF+ PRO 4.1

1.2 Feedback and Useful Links