Version 4.0


Copyright © 1997-1998 by Cygnus Solutions Inc.

Copyright © 1992-1996 by multiX Software GmbH.

Source-Navigator is a trademark of Cygnus Solutions.

Certain portions of this product are copyrighted as follows:

Copyright © 1996 Michael I. Schwartz.

Copyright © 1993-1997 The Regents of the University of California and Sun Microsystems, Inc.


Certain portions of this product are copyrighted as follows:

Copyright © 1993 AT&T Bell Laboratories

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that the copyright notice and warranty disclaimer appear in supporting documentation, and that the names of AT&T Bell Laboratories any of their entities not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. AT&T disclaims all warranties with regard to this software, including all implied warranties of merchantability and fitness. In no event shall AT&T be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortuous action, arising out of or in connection with the use or performance of this software.

RCS is copyrighted by Walter Tichy and Paul Eggert. Distributed under license by the Free Software Foundation, Inc.

CVS is copyrighted by Signum Support AB and distributed under "GNU General Public License."



Part # 300-400-1010020-01

Cygnus Solutions
1325 Chesapeake Terrace
Sunnyvale, CA 94089
Phone: +1 408 542 9600
Fax: +1 408 542 9699


Cygnus-multiX GmbH
Zettachring 2
D-70567 Stuttgart
Phone: +49 711 728 7426
Fax: +49 711 728 7427


Electronic access:


Foreword 9

Introduction 13

What Source-Navigator Does 13

Managing Projects with Source-Navigator 13

Navigational Tools 14

About this Guide 15

Document Conventions 15

Using the Mouse 16

Keyboard Accelerators and Shortcuts 16

Obtaining Technical Support 17

Creating a Project 19

Starting a New Project 19

Starting a Project Using Auto-Create 19

Starting a Project Using the Project Editor 21

Working with Projects 25

Opening a Project 25

Using the Project Editor 26

Adding Files to a Project 27

Adding Directories to a Project 28

Adding the Files from Another Project 28

Using Views 29

Closing Projects 30

Deleting Projects 30

Importing Directories into a Project 30

The Project Preferences Dialog 31

General Project Preferences 32

Using Source-Navigator 43

Using the Symbol Browser Toolbar 43

Browser Buttons 43

List Filter Buttons 44

The Extended Toolbar 45

Menus 46

History Menu 47

Windows Menu 47

General Window Features 48

Adding a Browser/Navigator to an Existing Window 48

Reusing Windows 49

Preserving Context Between Windows 50

Adjusting Window Column Size 50

Using Filters 51

Symbol Selectors 51

Pattern Box 52

Symbol and Type Abbreviations 53

Symbol Browser 55

Column Filters 57

Editor 59

The Editor Window 60

Symbol Accelerator Compound Box 61

View History 61

Search Menu 62

Using emacs as Your Editor 67

Cross-Referencer 69

Cross-Reference Details 71

Cross-Referencer Preferences 74

Class Browser 79

Class Name 80

Member List 80

Inheritance Tree 81

Member List Filter Dialog 81

Scope Selector 83

Class Browser Accelerator Keys 83

Class Hierarchy Browser 85

Using the Class Hierarchy Browser 85

Tools Menu 86

Class/Hierarchy Preferences 87

Accelerator Keys 89

Include Browser 91

Reducing Displayed Information 92

Include Preferences 93

Retriever 97

Retriever with Cross-Referencer 99

Grep 101

GNU Regular Expressions 103

Debugger 107

Starting the Debugger 108

Debugging the Application 109

Debugger Menu 110

Breakpoints 111

Stack 112


Compile & Make 113

Using the Make System 113

Integrating Other Compilation Tools 114

Version Control Systems 115

Using Version Control 115

Checking in a File 116

Checking Out a File 117

Discarding Changes to a File 118

Show Differences 118

Version Control Preferences 118

List of Figures and Tables

Figure 1-1 New Project Window 21

Figure 1-2 The Symbol Browser Window 24

Figure 2-1 The Project Editor Window 27

Figure 2-2 The Project Tab of the Preferences Dialog 32

Figure 2-3 Parser Tab of the Preferences Dialog 36

Table 2-1 File Types and Associated Filename Extensions 37

Figure 2-4 Others Tab of the Preferences Dialog 40

Figure 2-5 Colors & Fonts Tab of the Preferences Dialog 42

Figure 3-1 The Default Toolbar 43

Figure 3-2 File and Text Management Toolbar Buttons 45

Figure 3-3 Pattern Searching Toolbar Buttons 46

Figure 3-4 The History Menu 47

Figure 3-5 The Windows Menu 47

Table 3-1 Pattern Interpretation of Special Characters 52

Figure 3-6 Symbol Browser Showing Filter Results 53

Figure 3-7 Abbreviations Panel 54

Figure 4-1 Symbol Browser Window 55

Figure 4-2 Symbol Browser with Exclusive and Classes Selected 56

Figure 4-3 Symbol Browser Right Button Menu 57

Figure 5-1 Editor Window 60

Figure 5-2 Edit Tab of the Preferences Dialog 64

Figure 6-1 Cross-Reference Window 70

Figure 6-2 Symbol Accelerator Pulldown Menu 71

Figure 6-3 Cross-Reference Window, Right Mouse Button Down 72

Figure 6-4 Cross-Reference Window Showing Details By Window 73

Figure 6-5 Editor Showing Referencing of Symbol 74

Figure 6-6 Cross-Referencer Tab of the Preferences Dialog 75

Figure 7-1 Class Browser Window 80

Figure 8-1 Class Hierarchy Browser Window 86

Figure 8-2 Class Hierarchy Tab of the Preferences Dialog 87

Table 8-1 Class Hierarchy Browser Accelerator Keys 89

Figure 9-1 Include Browser Window 92

Figure 9-2 Include Browser Window, Right Mouse Button Down 93

Figure 9-3 Include Tab of the Preferences Dialog 94

Figure 10-1 Retriever Window 98

Figure 10-2 Retriever Window showing search results 98

Figure 11-1 The Grep/Editor Window 102

Figure 11-2 Sample Grep Search Results 103

Table 11-1 Regular Expression Repetition Operators  105

Figure 12-1 Debugging with Source-Navigator 108

Figure 12-2 Program to Debug Dialog Box 109

Figure 12-3 Toolbar Buttons for the Debugger 110

Figure 12-4 Breakpoint Window 111

Figure 12-5 Showing the current trace 112

Figure 13-1 Make Process Window 113

Figure 14-1 Version Control Window 116

Figure 14-2 Check-in dialog box 117

Figure 14-3 Check out dialog box 117

Figure 14-4 Showing Differences 118

Figure 14-5 Version Conrol Tab of the Preferences Dialog 119



-- by Michael Tiemann, author of GNU C++

The challenge of software comprehension has grown considerably since I started programming in 1986. Back then, I could write 2,000 lines of code on a good weekend, and build fully functional systems of 20,000 to 70,000 lines of code in a matter of weeks or months.

When I downloaded GCC version 1.0 in 1987, it supported two UNIX machines (the Vax and the Sun3) and weighed in at about 110,000 lines of code. In two week's time, I understood the code well enough to generate code for the Sequent Balance 8000 (an 8-way NS32032 UNIX-like machine). For me, GCC was easy to understand, and with that understanding, easy to modify to do new and exciting things.

Today, GCC weighs in at over 750,000 lines of code, supports C, C++, Java and other languages, supports over 100 variants of 30 CPU architectures, and has grown in complexity to the point that no single person can understand all of it. The code comprehension techniques I used ten years ago simply do not scale to today's software comprehension challenges, yet the need to do new and exciting things is as strong as ever.

Ten years ago, I wouldn't think twice about writing 10,000 lines of code if it needed to be written. Today, good engineering is as much about reusing existing code as it is about writing new code. Indeed, for a system of reasonable complexity to work with any degree of consistency, it is required that common functionality must come from common implementations. But how does one find common implementations in a code base that's over 500,000 lines of code? What about in 5,000,000 lines of code?

The old tools, find , grep , ctags , etc., are problematic for several reasons. Their interfaces are cumbersome. They don't maintain state from one invocation to the next, so it takes as much time and effort to ask a second question as it does to ask the first. And finally, they work only at the text level, not at the level of program symbols, structures, and organization. This is a critical shortcoming, as they report many false matches, and not nearly enough of the symbol relationship information to be useful.

Source-Navigator was designed to put programmers back in control of their source code by giving them the power to define what they see and what to ignore, to hide the irrelevant details that make it so difficult to focus on the details that actually matter.

Source-Navigator's Symbol Browser provides the overview that answers the question "what have I got in this project?". By grouping all the functions, global variables, classes, methods, filenames, etc., into separate views, the Symbol Browser makes it very easy to take inventory on large projects. Each inventory can be sorted by symbol name, type, filename, and each can be filtered so that only symbols that match a certain set of properties are listed. For programs that use names carefully, an amazing amount of structure can be deduced merely by selecting or combining the categories of interest and filtering and/or sorting the results.

From the global view of the Symbol Browser, you can move quickly to the specifics by selecting the symbol of interest and then launching the browser of interest. Machines have gotten a lot faster, but it's still time consuming (if not impossible) to use tools such as find and grep to identify all the places where a global variable is used, and how that variable is used (read from, written to, passed to a function, etc). With Source-Navigator, this information is two mouse clicks away (select, launch), and for the Source-Navigator browsers that show relationships (cross-references, class hierarchies, include files), each mouse click can expand the view by as many additional levels as you specify. Thus, if you are looking at an undocumented global variable, you are two mouse clicks away from seeing who uses it and how, and probably 3 or 4 clicks away from understanding the complete context in which the variable is used. (Once you do figure it all out, finish the job by writing comments for the next person who needs to read the code!)

Browsing through class hierarchies, include file relationships, class definitions, and the like, is an excellent way to build a mental framework of how software is organized. As this organization comes into focus, the next task is to understand how things are implemented. Source-Navigator is unique in its ability to enable one browser to act as the navigator for a second browser. For example, a cross-reference browser can be used to drive an editor, so that you can follow cross references in the source code without losing the context of the cross-reference information. Similarly, a class hierarchy browser can be used to drive a class browser to show class definitions without losing the context of the overall class hierarchy. The ability to combine and relate any two browsers lets programmers maintain global context while working at the implementation level, and vice versa! An editor browser can drive a cross-reference browser so that as you step through your source code, you can see all the cross references that relate to each symbol on every line of source code. This immensely powerful feature gives you a rich understanding of unfamiliar code much more quickly than any other tool I know, and it is the only one that supports both top-down and bottom-up source code comprehension using the same interface.

The most important tasks for code comprehension remain the same as they did ten years ago; back then, most software was small and simple enough that these tasks could be performed with the hardware we were born with. Source-Navigator reduces the complexity of today's software by letting you specify what you want to see and what you want to ignore, and how to organize details in context.

You can dynamically (and instantly) change these criteria so that at all times you are looking at what you need to see, what you need to understand, without a whole lot of extra detail. With this tool, we can continue to do new and exciting things, which is what programming is all about.




What Source-Navigator Does

The Source-Navigator 4.0 source code comprehension tool extracts information from existing C, C++, Java, Tcl, [incr tcl] , FORTRAN, Cobol, and assembly programs and uses this information to build project databases. The database represents internal program structures and relationships between program components. Source-Navigator graphical tools then use this database to query symbols and relationships between components.

As parsers scan through the source code, they extract information such as the locations of function declarations and the contents of class declarations and store the extracted information into a project database.

In addition to the languages supported in the standard distribution, you can use the Source-Navigator Software Development Kit (SDK) to add new parsers to extend Source-Navigator functionality to other languages.

Managing Projects with Source-Navigator

A Source-Navigator project is a file containing references to source code files. A project describes where files are located and how to operate on them. Once a project is defined developers can:

Navigational Tools

All Source-Navigator tools are organized around a project database that holds all project-specific objects. The name and location of the project files, symbols extracted from the source, and the relationships between symbols reside in the project database. File structure may not be pertinent when visualizing code relationships, so Source-Navigator allows you to view and understand software structure regardless of which file contains what information.

The Symbol Browser, Editor, and the Cross-Referencer are the basic tools for working with source code in a project.

About this Guide

This guide serves as a reference to Source-Navigator menus, tools, and functionality.

Document Conventions

Source-Navigator's documentation uses the following general conventions:

Menu names and their submenus are separated by an arrow (->). For example, File -> Open means select the File menu and choose Open from its submenu.

Paths are written in UNIX notation (forward slashes) throughout; .../libexec means the Source-Navigator install directory, subdirectory libexec .

Using the Mouse

The following are conventions for using the mouse with Source-Navigator:


Place the cursor on a specified object, and press the left-mouse button. Double-click means to click the left-mouse button twice in rapid succession without moving the mouse.


Depress and hold the Ctrl key simultaneously clicking with the left-mouse button on selection.


Depress and hold the Shift key simultaneously clicking with the left-mouse button.


Place the cursor on a specific object, and click the right-mouse button.

Select Text

Click and drag cursor through text (or code) to be selected. Selected text is highlighted.

Select Entries

Clicking a line selects it. To indicate the end of the selection, hold down the Shift key and click the desired line. This function is enabled in the Project Editor and file selection boxes.

Show the number of items in symbol lists.

Click the center-mouse button or press Meta +right-mouse button (UNIX); press Alt +Right Mouse (Windows).

Keyboard Accelerators and Shortcuts

You can use the keyboard to activate many of the functions displayed on the toolbar and in the menus.


For Windows NT:

Obtaining Technical Support

Cygnus provides support by email, phone, or fax.


Toll free: 800-CYGNUS-1
Main line: +1 408 542 9600
FAX: +1 408 542 9700


Bug reports:


Creating a Project

In this chapter you will learn how to create a project , or project file, which is a database table consisting of the highest-level project information. The project file describes all project-specific files, symbols, and references to other database files.

Starting a New Project

The first time you start Source-Navigator, the Source-Navigator Projects window lists the demo projects installed when you first installed Source-Navigator; if you chose not to install the demo projects, the window will be empty. After you create projects, their names are listed in the window at start-up.

Starting a Project Using Auto-Create

Auto-Create is a quick way to start a new project if all your source files live in a single directory (or a small number of directories) and if you want all the files from that directory in your project. If you want to create a project that contains selected files from several directories, see "Starting a Project Using the Project Editor" on page 21 .

To start a new project using Auto-Create, follow these steps:

  1. In the Source-Navigator Projects window, click New Project... .
  1. The Auto-Create dialog box will appear.
  1. To use source files from the listed directory, click Yes . If you would like to add other directories, click more and use the " ... " button to choose additional directories. All files in those directories will become part of your project.
  2. The parser begins scanning the specified files, extracting information about symbols, such as function names and class names. The extracted symbols are loaded into the built-in high-performance database.
  3. You can watch the progress of the extraction process:

Starting a Project Using the Project Editor

To start a project that contains a list of files that don't correspond neatly to a single directory, click Project Editor from the Auto-Create dialog. The Source-Navigator New Project window will appear.


New Project Window

  1. In the Project File text box you will see a directory; this will become your project directory . From now on every non-absolute file name will be relative to this directory. If you would like to choose a different directory, click the " ... " button.
  2. The project directory's name with the .proj file extension is the default; you may change the name of the project file in the Project File text field, but you must use the .proj file extension if you're working in Windows and you want Source-Navigator to launch when you double-click on your project name.
  3. If the project's source code resides in a read-only data system, you will be unable to create the project and database files in that directory. You must choose a writeable directory for the project file and the database files.
  4. To change the location of the project file, give the absolute pathname to a directory in the Project File text field; to change the location of the database files, see "General Project Preferences" on page 32 .
  5. Click OK to continue. For details on project settings and preferences, see "The Project Preferences Dialog" on page 31 .
  6. The Project files window lists all the directories and file names that make up the project.
  7. To permanently remove files and directories from the project, select a file or directory and click the Unload button.
  8. Note: Clicking the Unload button does not delete the files themselves, it just removes them from your project database.
  9. Click OK to set up the new project. The parser begins scanning the specified files, extracting information about symbols, such as function names and class names. The extracted symbols are loaded into Source-Navigator's high-performance database.


The Symbol Browser Window

Congratulations--you just created your first Source-Navigator project!

Now that your project is up and running, you may repeat the above steps to create other projects or keep reading for details about how to customize and use your current project.


Working with Projects

In this chapter you will learn how to customize and work with your newly created project.

Opening a Project

When you open an existing project, Source-Navigator allocates the necessary file and memory resources (see page 32 for details). These resources are necessary to update the database and to reflect changes in project files or in the project configuration.

To open an existing project:

  1. From the Source-Navigator Projects window, either select the project name and click Open or double-click on the project name in the window.

Using the Project Editor

The Project Editor enables you to organize different versions of a source file for a project. You use it to create and change views and to hide, re-select, and unload files.


The Project Editor Window

Adding Files to a Project

To add source files to a project, select Add Files... from the Project Editor window. The Open dialog will appear.


Clicking on Files of Type at the bottom of the window brings up a menu from which you can choose files based on the file extensions shown in the menu; All files (*) is chosen by default. Select source files to be added to the project and click Open .

Click Unload to remove (not delete) unneeded files from the project.

Adding Directories to a Project

The Add directory... button allows you to add entire directories and their contents to your project.

Select the directory you want to add and click OK ; you may add as many directories as you wish, but you must add them one at a time.

Adding the Files from Another Project

The Add Project... button allows you to import all the files from another Source-Navigator project into your current project.


This is the same Open dialog as when you clicked on Add Files... , except that Project files (*.proj) is chosen by default from the Files of Type menu. To see all files in the directory, choose All files (*) .

When you're finished working with the Project Editor, click OK .

Using Views

Views show a partial set of project files. For example, one view might be set to show only database-specific files from a project, while another one shows the GUI components in the project. You may hide files in one view, and then reinstate these hidden files into other views.

Creating Views

Enter the name of the new view in the View text entry box and click OK . This creates the new view and closes the Project Editor. The next time you open the Project Editor, this view will be the default view in the View Selection box.

Views and Multi-User Support

New views into the project can benefit workgroups sharing a common database. Source-Navigator makes sharing a project over the network seamless.

To open a project as a second user, simply use the Add Project... button. Source-Navigator will prompt you with the proper options, and based on permissions you will be able to read and write to the project.

Selecting Another View

To select an existing view, click the downward arrow to the right of the View text entry box. This will pop down a list of views you can choose from.

Removing Files from a View

To remove files from a view, but not from your project, select the files from the Project Editor window and click Hide . Click OK to close the Project Editor. This removes the files from your view, but does not delete them from your file system.

Closing Projects

To close a project, select Close Project from the File menu. Closing a project:

Deleting Projects

To delete a project, select File -> Delete Current Project (from the Symbol Browser) or File -> Project -> Delete Current Project (from one of the other browsers). The project file and other project database files will be deleted. All source files and directories remain unchanged.

Importing Directories into a Project

As an alternative to selecting source code directories for the new project, you can collect directory names into a separate file and import this file into Source-Navigator. (On UNIX, you could use the find command to generate this list.)

To import directories, start Source-Navigator with the import option:

snavigator -import filename

The project directory is the current working directory, and the file filename must contain directory names or filenames, one per line. (The Source-Navigator Include Browser uses the directory names.) A sample file for import follows:


The Project Preferences Dialog

Use the Project Preferences dialog to specify project-specific parameters. Select Project Preferences from the File menu, and enter your changes in the dialog. After changing any parameters in this dialog, click OK to update the project with the current settings.

Note: default values may be transferred from the previously created project, some options take effect only in new windows, and some options only take effect the next time the project is opened.


The Project Tab of the Preferences Dialog

General Project Preferences

Descriptions of the general Project Preferences tabs are included in this section; the following are discussed in their relevant chapters.

Edit : see Chapter 5, "Editor", on page 59 .

Class/Hierarchy : see Chapter 8, "Class Hierarchy Browser", on page 85 .

Xref : see Chapter 6, "Cross-Referencer", on page 69 .

Include : see Chapter 9, "Include Browser", on page 91 .

Version Control : see Chapter 14, "Version Control Systems", on page 115 .

Project Tab

In the Project box you can set:

  • Read-only project
    Select this if the project should be read-only. Default is off.
  • Refresh on Startup
    Select this when files are likely to be changed without Source-Navigator's knowledge and when you want to be sure that your database is in sync with your source when you start.
  • Default is on; this could cause delays when opening your project, so for large source bases that are relatively stable, or where network latency is a problem, set this to off and choose Tools -> Refresh Project to resync the database with the source.

Under Database you will find:

  • Database directory name
    Source-Navigator creates all database files under this directory. If the directory already exists, you will need read and write permissions for it; if you're creating a new directory, you will need permission to create it.
  • The file system for this directory must contain free disk space equal to the size of the source base without cross-references, and up to about ten times the size of the source code if you choose to generate cross-references. If you don't have the necessary permissions (for example, if it is a read-only file system), or if there is insufficient free disk space in your first choice of location, you may create your project directory in another location on your network by entering a directory name with its absolute path.
  • Permission These buttons control the read-write permissions for your project: the first set controls access for the creator of the file, the second set for the group, and the third for "others" i.e. everyone else on the network.
  • Build comment database
    Select this if you would like to store comment strings in the database.
  • Database cache size

Note: Caches improve performance by using memory (fast) instead of disk (slow) where possible. Larger caches increase the likelihood that data will be found in memory rather than on disk. Overallocating caches has the opposite effect, however: the operating system will swap the cache to disk, and the system will get dramatically slower. The cache defaults are generous for most projects; don't increase them without a reason.

  • Enter the database cache size (in kilobytes) or accept the default value. Source-Navigator creates the project database (in the background) with the specified cache size. Increasing this amount speeds up project creation and data access, but requires that more memory be allocated to Source-Navigator.
  • The recommended maximum is the amount of free RAM on a quiet system divided by 16, up to a maximum of 4 Mb. The total of this amount plus the amount allocated to the cross-reference database cache should not exceed one quarter of the total memory.
  • For more details about this parameter, look under dbopen in the "Database API" chapter of the Source-Navigator Programmer's Reference Guide .
  • Xreference (Cross-Reference) database cache size
    Enter the Cross-reference database cache size in kilobytes or accept the default value. Source-Navigator creates the project cross-reference database with this cache size. Increasing this amount speeds up cross-reference creation and data access but requires that more memory be allocated to Source-Navigator.
  • The recommended maximum size is the amount of system memory divided by 32, up to 8 Mb. The total of this amount plus the amount allocated to the database cache should not exceed one quarter of the total memory.
  • For more details about this parameter, look under dbopen in the "Database API" chapter of the Source-Navigator Programmer's Reference Guide .

The Window box contains:

  • Split windows: These buttons control where new views appear when you add a view to an existing window ( Windows -> Add view ).
  • Select Horizontal to have new views appear to the right of the current view; select Vertical to have new views appear below the current view.
  • New windows
    Selecting Are Reusable causes new information to appear in the current window; deselecting it causes a new window to appear when you choose a new symbol, tool, or view.
  • Selecting Keep Context causes new tool windows to be opened to the same symbol context as the current window; deselecting it causes a new tool to be empty when opened.
  • Set S-N window size to
    This setting controls the size of newly-created Source-Navigator windows. You may resize the windows after they're created.
  • File dialog box This setting allows you to choose between the Source-Navigator file chooser and the native file chooser.

Parser Tab


Parser Tab of the Preferences Dialog

Source-Navigator uses plug-in parsers to parse multiple languages and calls the correct plug-in based on file extensions. Source-Navigator is pre-configured for the most commonly used file types; these can be changed and new plug-in parsers can be added. For more information on adding parsers, please see the "Adding Parsers" chapter of the Source-Navigator Programmer's Reference Guide .

File Types and Associated Filename Extensions

Parse source files as

File Extensions

PowerPC 601 assembly

*.asm *.[sS]


*.[hHcC] *.[ch]xx *.[ch]pp *.cc *.hh *.[CH]XX *.[CH]PP *.CC *.HH


*.cbl *.cob


*.for *.FOR




*.[ly] *[IMm]akefile

Tcl, [incr Tcl]

*.tcl *.itcl *.itk *.tk

After each of the languages is an "External Editor" box; you may type in the executable (shell) command for an external editor, or you may click on the "..." button to browse. If you leave the box blank, Source-Navigator will use its built-in editor.

Macro Processing

Macros add an interesting wrinkle to the task of source code analysis, and there is no single right way to handle them. By default, Source-Navigator treats them as opaque symbols, and aside from recording where they are defined, it ignores them completely. This behavior not only makes Source-Navigator's parsing substantially faster than true compilation, but it also preserves the layer of source code abstraction that is presented in the Editor. This behavior is particularly useful when maintaining software that must run on multiple platforms, and you would like to see all of the impacts that a change might have, regardless of a macro's platform definition.

For some projects and/or tasks, this layer of abstraction is a true barrier to code comprehension. For these cases, you can direct Source-Navigator to define and expand macros in one of four ways:

define is used to insert a symbol into Source-Navigator's preprocessor namespace. If you define FOO (or #define FOO , the leading # is optional), then conditionals that test #ifdef/#ifndef will be scanned according to the #ifdef/#ifndef test. FOO will be replaced with the empty string.

define can also be used to give a symbol a value (such as define FOO BAR ). This will not only inject the symbol into the namespace, but will cause Source-Navigator to scan BAR whenever it sees the FOO macro. This is particularly useful for DEFUN or PROTO macros that are used to bridge between K&R and ANSI C but which otherwise are not interesting at the source code comprehension level. It is also useful when macros test numerical results, such as #if (X >= Y) or #if X .

define macros can take arguments, just as in C and C++, and they can expand recursively, (i.e., FOO might expand to BAR (5) which might then expand to mumble (5, 5, 0) ; in this case Source-Navigator would only see mumble (5, 5, 0) ).

replace is just like define , except that the symbol is not injected into the namespace. Thus, if you want to expand macros, but not have conditional code compiled away, use replace .

The macro processor does not support include , token concatenation, ANSI stringification, or other pre-processor directives. These may be implemented in a future release.

Source-Navigator lets you use more than one macro file in a project. You can specify a macro in one file, and then delete it from the preprocessor namespace using delete in a second macro file.

  • undef

undef doesn't do any substitution, it just affects the evaluation of #if , #ifdef , and #ifndef statements.

Defining and Using Macro Files

As explained above, Source-Navigator parses, but does not interpret, macro definitions in your project files. It only interprets macro definitions from files you specify explicitly in the parser preferences of your project. Because multiple files may be specified, you may want to organize your macro files according to global, per-user, and per-project divisions. This order is important, because the last definition for the macro will be used.

Macro files are ascii files and every non-blank line is a macro directive. Leading blanks and # characters are stripped, and if the first character of a line is a ' , the line is treated as a comment. The macro file can contain continuation lines, for example:

define ABC\

Otherwise, the directives are interpreted as documented above.

Others Tab


Others Tab of the Preferences Dialog

  • Make command
    Type in the executable (shell) command to start your make system.
  • HTML viewer
    For UNIX platforms, enter the HTML viewer that will display online help. Select Help  -> HTML to open the viewer, which must be included in your path.
  • For the Windows NT platform, the default HTML browser starts automatically.

In the Bug reports box you can set:

  • Report bugs via
    On UNIX, select EMail to use /usr/ucb/Mail . On Windows or UNIX, select WWW to bring up your default browser (on Windows) or a currently running HTML browser (on UNIX).
  • Mailhost On UNIX, enter the name of your mailhost.
  • Local host Enter your local IP address.

From the Printer box you can set:

  • ASCII Print Command
    Enter the settings you use when printing a source file from a UNIX command line or a DOS shell.
  • Print Command
    Type in the print command appropriate for your UNIX system. For example, BSD-inspired systems use lpr , whereas Sys V systems use lp . In Windows, Source-Navigator uses the Registry to decide how to print.

The GNU Debugger command box contains a text field where you should enter the executable (shell) command to start the GNU Debugger.

In the Retriever box:

  • Don't display the warning dialog for multiple matches
    Select this if you don't want to be warned when the Retriever finds more than one symbol with the name you're searching for.

Colors & Fonts Tab


Colors & Fonts Tab of the Preferences Dialog

Source-Navigator assigns a different default color to each component of your source code. If you would like to customize these colors, or choose different fonts, bring up the Colors & Fonts tab view, select the component you'd like to customize, and modify the entry in the text fields on the right. To set RGB (Red-Green-Blue) values, click the corresponding "..." button to bring up the Choose Color dialog box.

You may want to change colors from their default settings if they don't show up well on your laptop or CRT display, or if your code colorization conventions don't match Source-Navigator's default colors.


Using Source-Navigator

This chapter describes how to use the most common features of Source-Navigator.

Using the Symbol Browser Toolbar

Source-Navigator tool icons are located under the Symbol Browser's main menu bar. To find out what a tool does, move the cursor over it; a description of the tool will pop up in a text box. The toolbar is shown in its default configuration in Figure 3-1 .


The Default Toolbar

Browser Buttons

With the toolbar, you can access many of the Source-Navigator browsers you will use most often. However, you can add or remove toolbar buttons and menus. For more information see the "Customization" chapter of the Source-Navigator Programmer's Reference Guide .

Toolbar buttons provide quick access to the following Source-Navigator functions:

Class Hierarchy Browser Button

Select this button to start the Class Hierarchy Browser. For more information on this tool, see Chapter 8 on page 85 .


Class Browser Button

This button starts the Class Browser. For details on how to use this tool, see Chapter 7 on page 79 .


Cross-Referencer Button

To start the Cross-Reference Browser, select this button. Details can be found in Chapter 6 on page 69 .


Include Browser Button

Select this button to start the Include Browser. For details, see Chapter 9 on page 91 .



List Filter Buttons

In large projects, function names, methods, or other symbol types may add up to thousands of symbols. The filter searches for specific symbols in the symbol database; use the List Filter buttons to restrict searches by symbol type.

Filter by Classes, Methods, Functions, Project Files

Select these buttons to restrict the symbol list in the Symbol Browser to classes, methods, functions, or project files respectively.

For details on how to filter for other symbols, see "Using Filters" on page 51 and Chapter 4, "Symbol Browser", on page 55 .

The Extended Toolbar

The Extended Toolbar Buttons box from the Edit Tab of the Preferences Dialog (see page 32 ) adds several new tool buttons to the toolbar.

File and Text Management

Select these buttons to manage your files and text.

File and Text Management Toolbar Buttons

Pattern Searching

Select these buttons to search the window or the project database for the desired symbol.


Pattern Searching Toolbar Buttons


The File , Edit , Search , and Tools menus appear in all windows, though they are context-sensitive; the options available from the menus change depending upon which tool you're using. The History and Windows menus, however, are more general and offer the same options within each tool.

History Menu

The History menu enables you to repeat queries and restore previous states of each browser.

The History Menu

Windows Menu

The Windows menu lists the project's tools, enabling you to start a new instance of a tool ( Windows -> New ), add that tool to your current window ( Windows -> Add View ), or change to a currently running instance of a tool ( Windows -> Views ).

The Windows Menu

General Window Features

You may reuse Source-Navigator windows and adjust the window column size. The status line shows information such as the number of lines of source code in the Editor window and the current directory.

Adding a Browser/Navigator to an Existing Window

If you find yourself often using two of Source-Navigator's tools simultaneously, you can combine them into one window. This keeps you from constantly switching between windows, and allows you to see both tools at the same time.

For instance, if you have a class open in the Class Hierarchy Browser


and you'd like to bring up an editor to see the same class, but you'd like to continue to see the class hierarchy, just select Windows -> Add View -> Editor , and an editor will appear in the same window. Depending upon your settings in the Preferences Dialog (see page 31 ), the new editor will either appear at the bottom of the window (if you chose Horizontal),


or on the right side of the window (if you chose Vertical). As you click on symbols in the hierarchy, those symbols appear in the editor.


Reusing Windows

When you select Reuse in a window's status line, the window's contents will be overwritten. With Reuse deselected, a new window will be created to display the new view.


For example, with Reuse deselected, double-clicking a symbol to display its symbol definition creates a new editor window. Your previous Editor window remains unchanged. Reuse is selected by default.

Preserving Context Between Windows


Selecting the Context button from the status line preserves the context of a selected symbol when switching between tools. If Context is unselected, the new tool will open to the default or empty condition.

For example, if you have a particular class selected in the Editor, that same class will be displayed when you change to the Class Browser. When not selected, the Class Browser will open with whatever was previously displayed. Context is selected by default.

Adjusting Window Column Size

The column dividers allow you to adjust the width of columns on the screen. You can adjust the size of a column by moving your cursor over the divider until the left-right arrows appear, then clicking and dragging the column divider to the desired position.


Using Filters

Source-Navigator provides several ways to filter the symbols displayed in the Symbol Browser and in other tools: by using the List Filter buttons (see page 44 ), by using the Symbol Selectors from the View menu (see below), by using Column Filters (see page 57 ), and by using the Symbol Accelerator Compound Box (see page 61 ).

Symbol Selectors


While the List Filter buttons allow you to search by classes, methods, functions, and project files, the Symbol Selector provides a more complete list of search choices.

If the Exclusive box is selected, then you may choose one symbol type to search for; if it's unselected, you may combine symbol types for more complex searches.

Pattern Box

Several Source-Navigator windows contain text entry boxes that allow you to narrow your search for a particular text pattern in that window.


The Pattern box allows you to search the text inside the files for a particular pattern. Patterns are not case sensitive.

Pattern Interpretation of Special Characters

Special Character

Interpretation in Filter or Pattern Boxes


Matches any sequence of zero or more characters.


Matches a single character.


Matches any single character in chars . If chars contains a sequence of the form c-x , any character between c and x inclusive will match.


Matches the ? character exactly, avoiding special interpretation of the character. Also applies to the following characters: [ , ] , * , ? , and \ .

For example, *.[hc] matches all strings with the *.C , *.H , *.c , *.h extensions; [0-9]* matches all symbols beginning with a number.

So, with Agent* in the filter text box, and Classes , Methods , and Files chosen from the View menu, you would see the results shown in Figure 3-6 .


Symbol Browser Showing Filter Results

To clear the text box for another search, type Ctrl+U .

Symbol and Type Abbreviations

Source-Navigator uses the following abbreviations, which are also defined online in the Help menu (Help -> Abbreviations) .


Abbreviations Panel


Symbol Browser

The Symbol Browser window is displayed when you first create or open a project. It is the main window for navigating among the Source-Navigator symbols. The Symbol Browser shows high-level information about the project, such as files, definitions, functions, variables, or classes/methods.


Symbol Browser Window

Each symbol in the Symbol list box is hyperlinked to the Editor, which is described in Chapter 5, "Editor" . A double-click on a symbol starts the Editor, which displays the symbol in its context in the source file. Depending on your settings in the Preferences dialog (see "Class/Hierarchy Preferences" on page 87 ), the cursor is positioned on the location where the symbol is found, declared, or defined.

The Symbol list box displays different kinds of project symbols, depending on which type of symbol you select from the Symbol-type selector (accessed through the View menu). If the Exclusive box is selected, then only one type of symbol will be displayed at a time. If Exclusive is unselected, then clicking additional symbol-type selectors adds those symbols to the existing contents of the symbol list box.


Symbol Browser with Exclusive and Classes Selected

To find out the number of symbols matching your selection, right-click over the symbol list; from the popup menu you may sort the symbol list by column, and hide columns to simplify the display.


Symbol Browser Right Button Menu

For faster searching you can use the toolbar buttons to browse project files, functions, methods, and classes. For more information on the toolbar see "Using the Symbol Browser Toolbar" on page 43 .

Column Filters

Column filters override all other filter preferences, and allow you to constrain the contents of a list view by filtering by a certain pattern. They are available in any window where information is presented in columns, such as the Symbol Browser, Class Browser, and Retriever windows.

Right-click on the column header, and it'll be replaced by a filter box.


Type in a pattern and hit Enter , and the list will display all symbols matching your pattern.




Source-Navigator allows you to edit source files with its built-in Editor, or with an external editor that you select in the Edit tab of the Project Preferences dialog box (see "Editor Preferences" on page 63 ). Instructions for using emacs as your external editor are given on page 67 ; if you intend to use another external editor, see the "Customization" chapter in the Source-Navigator Programmer's Reference Guide .

To open the Editor, double-click a symbol in the Symbol Browser (or other Source-Navigator tool) window (symbols in tool windows are hyperlinked to the Editor).

The Editor Window


Editor Window

The Editor displays the contents of a project source file and allows you to edit it. When you save a modified source file, the project, symbol, and cross-reference databases are updated without recompilation and changes are reflected in all Source-Navigator tools. Standard mouse operations are supported in the Editor:

You can use the Find box in the toolbar to find text. Simply type the text into the box and hit Return ; the next instance of the text will be found. To find a previously used pattern, use the arrow box to pop down a list of previous patterns. Select one with the mouse, and the next instance of that pattern will be found.

Symbol Accelerator Compound Box

The Symbol Accelerator compound box in the toolbar allows you to quickly navigate through your source code. This accelerator, when the Editor is open, will list all of the symbols in either the open file or within the entire project. When other tools are open, the Symbol Accelerator will list the components relative to the tool.

For instance, in the Class Browser, it will list only classes in the file or in the project.

Notice that the Symbol Accelerator text field in the toolbar will display the component that is referenced as the Editor's cursor moves through the file.

View History

Source-Navigator can provide complex information in a number of intuitive ways. As you navigate through a project, you may want to return to the view of a relationship that you were previously investigating. Source-Navigator stores a view history of your journey through the project. The left and right arrows in the toolbar act like Previous and Next buttons in popular Web browsers.

For more detailed history, the History menu allows you to view a list of previous views on a per-tool basis. This lets you jump directly to the view you want, rather than paging through previous views.

Search Menu

The Search menu is context-sensitive; different options are available depending upon the tool you're using. The following are available within the Editor.

Find Dialog

To find a specific string or pattern in the text file, select Find from the Search menu.


Type your string or pattern into the text box, and hit Search ; you can hit Search multiple times to find more instances of the string. Deselect Ignore case if you want a case-sensitive search. Deselect Forward if you wish to search backward. When Regular expression is selected, the pattern is treated as a regular expression, and hitting Search will find the next match for the regular expression.

Replace Dialog

The Replace dialog is similar to the Find dialog.

The Ignore case , Regular expression , and Forward buttons behave the same. Search finds the next instance of the pattern, Replace replaces the current pattern with the pattern in the Replace pattern box.

Find Declaration, Implementation

If a symbol is selected in the Editor, selecting Find Declaration will switch to the location of the declaration of the symbol, and Find Implementation will switch to the location of the implementation of the symbol.


Grep brings up a miniature version of the Grep tool (see Chapter 11 on page 101 ). Select the expression you want to search for, and select Grep from the Search menu. Source-Navigator will automatically search for your text in all project files.

Go To Menu

When you want to go to a specific line in the file, select Search -> Go To -> Go To Line... . This will allow you to type in the line number you wish to go to. Set Mark allows you to set a place in the file you wish to come back to later. Go To Mark will jump back to the last mark you set.

Editor Preferences

Choose File -> Project -> Project Preferences to change the settings in the Editor.


Edit Tab of the Preferences Dialog

In the Format box you'll find:

  • Tab Stop A group of this many spaces will be inserted as a tab character.
  • Inserted Tab Width
    In the built-in editor, pressing the tab key will insert this many spaces.
    Note: If Tab Stop and Inserted Tab Width have the same value, pressing the tab key will add a tab to the source.
  • Auto indent width
    Enter the number of spaces that the built-in editor should indent ( Edit -> Indent ) or outdent ( Edit -> Outdent ) when reformatting source code.
  • Wrap by This controls where the editor breaks a line that is longer than the width of the window.

The Work box contains:

  • Create *.bak Files
    If selected, the editor creates backup files.
  • Bracket match delay
    Sets the amount of time (in milliseconds) that matching brackets should be highlighted.
  • Right mouse supports:
    If edit menu is selected, you can access some functions, such as Undo , Delete , Cut , Copy , and Paste through a right-mouse pop-up menu.
  • If Scrolling is selected, you can scroll the text in the editor using the right-mouse button.
  • Output file translation:
    End of lines of source files may be represented differently on different platforms.
  • Choose cr (new line) if you're on a UNIX system, crlf (carriage-return-linefeed) on Windows, and lf (linefeed) if you're looking at Macintosh source code. The default auto translation mode automatically handles common cases.
  • Extended toolbar buttons
    Selecting this box adds several new tool buttons to the Symbol Browser toolbar. For more information about these buttons, see "The Extended Toolbar" on page 45 .
  • External Editor Insert the command line for your favorite editor in this text box. Source-Navigator can set the position of the cursor in the editor if the editor can be configured by command line options. The following substitutions can be performed on the command line by Source-Navigator before it is executed:
  • %f

    file name


    line number


    column number


    project directory


    Tcl interpreter

Common Editor Configurations


  • On UNIX, vi is not a GUI application, and therefore must be invoked from a command line shell. This is done with the following command:
  • xterm -T %f -e vi +%l %f
  • The modifications you make and save will be stored into the database only after the external editor terminates.
  • Windows NT can execute DOS executables without launching a shell, so the command line for a DOS version of vi would be:
  • vi +%1 %f


  • On Windows, you can invoke notepad by entering the following command:
  • notepad %f


  • Starting a new emacs session : To start a new emacs session whenever you view source code, enter emacs or the name of the executable file of emacs. For example, enter nemacs or xemacs , without any parameters. The strings " emacs " must be found in the command because the changes you make and save will be stored into the database immediately (without terminating emacs).
  • Using a current emacs session : For instructions on how to configure Source-Navigator to communicate with a currently running emacs session, see the next section.

For information on customizing your key bindings, see the "Customization" chapter of the Source-Navigator Programmer's Reference Guide .

Using emacs as Your Editor

Source-Navigator supports GNU emacs 19.34 and xemacs 19.14; other versions may also work, although these have not been tested.

When you use emacs as your editor, Source-Navigator displays files in an emacs window. Whenever emacs saves a file, Source-Navigator updates the database. Multiple Source-Navigator projects can share a single emacs editing session.

You can use emacs with Source-Navigator in one of two ways:

To start a new emacs process:

Enter emacs (or the name of your program with the string emacs ) as the Editor command parameter in the Project settings dialog box ( Project menu -> Preferences ).

To communicate with an already running emacs process:

  1. Modify your emacs startup file so that gnuserv utility, which is provided in your Source-Navigator distribution, is loaded. This involves adding the following two lines to your emacs startup file (usually ~/.emacs ):
  2. (load "/usr/cygnus/snavigator/emacs/lisp/gnuserv")
  3. See your emacs documentation for additional information.
  4. In the Project settings dialog box, set your editor to gnuclient .
  5. When you start a new emacs session, Source-Navigator can now request that the running emacs session bring up files for editing. Source-Navigator also rescans the files when you finish editing.


If you are currently using the emacsclient utility, you need to use gnuclient instead.

If you use xemacs , the gnuserv package is included; see your xemacs documentation for instructions on loading it.

The Source-Navigator search function replaces the find-tag command ( Meta-period ) when you search for a symbol. Because the other tag commands are not yet available inside Source-Navigator, you need to use the equivalent emacs commands, if available.




The Cross - Referencer creates tree diagrams that show essential relationships within the project's symbol database, such as the function-call hierarchy tree. You can traverse up and down the hierarchy tree, as well as expand or restrict the tree. You can select items in the hierarchy and display their Refers-to and Referred-by relationships; these relationships are based on the "point-of-view" of the selected symbol.

A Refers-to relationship is one where the selected symbol "points to" another symbol; that symbol, in turn, is Referred-by the selected symbol.

Source-Navigator creates the cross-reference information in the background, so you can work in other views. During this process, the Cross-Referencer tool button is disabled (grayed-out). After the database is built, the Cross-Referencer tool can be opened.

Although you can always start the Cross-Referencer by choosing it from the Windows -> New menu, you may want to start the Cross-Referencer so that it focuses on a specific symbol. To do this, select a symbol in the Symbol Browser or Editor, and then click the Cross-Referencer tool button or choose the Xref tab.

The selected symbol becomes the root symbol in the Root box at the top left of the Cross-Referencer window. The references that Refer-to the root symbol are indicated by blue arrows, and those that are Referred-by are indicated by red arrows. You can traverse the hierarchy tree by selecting references and clicking the right-pointing hand tool ( Refers-to ) and left-pointing one ( Referred-by ) as shown in Figure 6-1 .


Cross-Reference Window

The Remove Subnodes tool allows you to remove the display of subnodes from the hierarchy tree.

If you start the Cross-Referencer without selecting a symbol, references are not shown until you either enter the target symbol name in the Symbol Accelerator text entry box, or select the symbol type from the Symbol Accelerator compound box (see Figure 6-2 ), and then select one of the members of the list.

The Symbol Accelerator is a local interface to the Symbol Browser. As such, it allows you to define the type of symbols for cross-referencing and to select symbols based on pattern matching.


Symbol Accelerator Pulldown Menu

Double-clicking a symbol in the Cross-Referencer window starts the Editor, with the specific symbol in context in the source file. The cross-reference information is stored in the database, and is kept current by the Editor.

Cross-Reference Details

Holding down the right mouse button on a symbol in the cross-reference window brings up a menu that allows you to filter the list of symbols you're working with, as well as to gather new information about the symbols you're interested in.


Cross-Reference Window, Right Mouse Button Down

Choosing Details By brings up a window that shows where each symbol in the list is referenced.


Cross-Reference Window Showing Details By Window

Clicking on the column headers allows you to sort the focusing on that column, either alphabetically, by line number, by class, etc. The Pattern text entry box in the window allows you to use a string to filter the list.

Symbols that occur multiple times are listed; when you click on a symbol and then add the Editor to the window ( Windows -> Add View -> Editor ) the Editor will show where that symbol is referenced.


Editor Showing Referencing of Symbol

Cross-Referencer Preferences

Preference settings for the Cross-Referencer window are located in the Xref tab of the Preferences dialog. To find this window, select File -> Project Preferences from the Symbol Browser, or Edit -> Preferences from the Cross-Referencer.


Cross-Referencer Tab of the Preferences Dialog

The Cross-referencing box contains:

Under Layout you'll find:


Class Browser

For projects developed using object oriented languages, the Class Browser enables you to browse class hierarchies, access levels, and member types. The Class Browser displays the list of class members of a particular class, based on your selections from the Class/Hierarchy Tab of the Preferences dialog ( see page 87 ).

For traditional languages such as C, Cobol, and FORTAN, the Class Browser enables you to see the members of structures and common blocks.


Class Browser Window

You can start the Class Browser by double-clicking on a class, by selecting a class and clicking the Class Browser tool button, or by choosing Class from the Windows -> New menu.

Class Name

You can enter the class name into the Symbol Accelerator text entry box ( emacs-style tab completion is also supported). If you press Enter and the name matches a valid class name, the information for the appropriate class will be loaded. For more information on the Symbol Accelerator, see page 61 ).

Member List

The symbols displayed in the member list are controlled by the pulldown menus and inheritance tree. Access levels and attributes are indicated by icons; for the key to these icons please see the Abbreviations panel ( Help -> Abbreviations ) or see Figure 3-7 on page 54 .

Inheritance Tree

The inheritance tree shows the relationship of the browsed class and its base classes.

The check boxes before the class names determine whether or not members of a class are included in the member list. Use the mouse to manipulate these check boxes:

Member List Filter Dialog

Click on the Filter button to bring up this dialog box. The symbols displayed by the Member List are included based on these settings.


Scope Selector

The Scope Selector menu filters the member list depending on the accessibility of the members.

Class Browser Accelerator Keys

These accelerator keys are available for use with the Class Browser.

Key Combinations


Meta +I (UNIX)
Alt +I (Windows)

Starts the Editor for the implementation of the currently marked symbol.

Meta +D (UNIX)
Alt +D (Windows)

Starts the Editor for the definition of the currently marked symbol (you may also press the Enter/Return key if the symbol you want is highlighted).



Class Hierarchy Browser

Inheritance , which is a type of relationship between objects, allows one object to share behavior with one or more other objects (sharing with more than one is known as multiple inheritance ). Inheritance provides the basic mechanism for the reuse of code. The Class Hierarchy Browser helps you to understand class hierarchy trees, which in turn helps you to reuse existing code.

You can start the Class Hierarchy Browser by choosing Windows -> New -> Hierarchy , by clicking the Class Hierarchy toolbar button (see "Class Hierarchy Browser Button" on page 44 ), or by choosing the Hierarchy tab in the Editor.

Using the Class Hierarchy Browser

The Class Hierarchy Browser can display the entire class hierarchy, including the superclasses and subclasses of a selected class (see Figure 8-1 ).


Class Hierarchy Browser Window

Tools Menu

The Tools -> Hierarchy menu contains the following items, which control how the class hierarchies are displayed.

Class/Hierarchy Preferences

Many of the settings that control how the Class Hierarchy window displays information are located in the Class/Hierarchy Tab of the Preferences dialog. To find this window, select File -> Project Preferences from the Symbol Browser, or Edit -> Preferences from the Class Hierarchy Browser, and choose the tab listed Class/Hierarchy .


Class Hierarchy Tab of the Preferences Dialog

In the Class box you will find:

Under Hierarchy Layout you will find:

Accelerator Keys

These accelerator keys are available with the Class Hierarchy Browser.

Class Hierarchy Browser Accelerator Keys

Key Combinations


Meta +B (UNIX)

Alt +B (Windows)

Starts the Class Browser for the marked class.



Include Browser

Some programming languages provide a facility for including other source files. In C/C++ this is achieved by using the #include preprocessor directive. The I nclude Browser lets you display Includes and Included from relationships of source files in the same window.

Start the Include Browser by choosing Include Browser from the Windows -> New menu.


Include Browser Window

To see further relationships, after selecting a file in the left pane of the Include Browser window, use the right and left pointing-hand tool icons to show files included by the selected file (blue connection lines), and files that include the selected file (red connection lines), respectively.

To determine the number of levels shown for a query, enter an integer value in the Level text entry box. The change takes effect with the next query.

Reducing Displayed Information

Holding down the right mouse button on a symbol in the Include Browser window brings up a menu that allows you to show or hide include information.


Include Browser Window, Right Mouse Button Down

This is useful when the Include Browser is displaying more information than you need, and you'd like to hide all relationships but the particular one you're interested in.

Include Preferences

You'll find preference settings for the Include Browser window in the Include tab of the Preferences dialog. To find this window, select File -> Project Preferences from the Symbol Browser, or Edit -> Preferences from the Include Browser.


Include Tab of the Preferences Dialog

The Layout box contains:

In the Include directories box you can choose which directories to search for include files. Using the set of directories shown in Figure 9-3 , for example, if <stdio.h> is a reference then Source-Navigator will first look for the file /usr/include/stdio.h , then for ./stdio.h , etc. The first file found is the one used by the Include Browser.




Retriever is optimized for speed, and allows you to search for text patterns in the names of symbols in the database. To search for text patterns in source files, use Source-Navigator's Grep tool (see Chapter 11 on page 101 ).

To find a symbol, enter its search pattern surrounded by asterisks (for example *agent* ) in the Pattern text box, and click Search . The * , ? , [ , and ] wildcard characters are supported.


Retriever Window

The retriever displays all the symbols it found with the pattern you're searching for (see Figure 10-2 ).


Retriever Window showing search results

Double-clicking an item in the list will open the Editor showing the symbol in context in the source code.

For more information on reusing windows for multiple searches, see "Reusing Windows" on page 49 .

Retriever with Cross-Referencer

If you're looking at a unique symbol in the Editor and you click the Xref tab to see its cross-references, the Xref window will appear.

However, if you're looking at a symbol that is not unique (there's more than one symbol with that name in the database) the Retriever will tell you that it's found multiple matches and ask you to choose the correct one to display.

If youdon't want to see this warning in the future but want to go straight to the retriever dialog, click the box in the dialog or choose the equivalent box from the Others tab of the Project Preferences dialog (see page 40 ).

Double-click on the symbol for which you'd like Xref information, and the Xref window will appear.




Source-Navigator's Grep 1 tool allows you to search for text patterns in source files throughout the project. It is more powerful than using grep on the command line because

Start the Grep tool by choosing Grep/Editor from the Windows -> New menu. This will open a Grep/Editor split window (for more information on split windows, see "Adding a Browser/Navigator to an Existing Window" on page 48 ).


The Grep/Editor Window

In the Pattern text box, enter a regular expression then click Search . For more information on regular expressions, see "GNU Regular Expressions" on page 103 .

You can use the Files filter to limit your search; for example, entering *.cc restricts the search to only C files. For a list of file extensions and their associated languages see Table 2-1 on page 37 .

Figure 11-2 shows the results of a sample Grep search.


Sample Grep Search Results

Clicking on an item in the Grep results list displays the appropriate file in the Editor, with the cursor positioned at the selected line.

GNU Regular Expressions

A GNU regular expression 2 is a pattern that describes a set of strings. Regular expressions are constructed analogously to arithmetic expressions: various operators combine to form smaller expressions.

The fundamental building blocks are the regular expressions that match a single character. Most characters, including all letters and digits, are regular expressions that match themselves. Any metacharacter with special meaning may be quoted by preceding it with a backslash.

A list of characters enclosed by [ and ] matches any single character in that list; if the first character of the list is the caret ^ , then it matches any character not in the list. For example, the regular expression [0123456789] matches any single digit.

A range of ASCII characters may be specified by giving the first and last characters, separated by a hyphen. Certain named classes of characters are predefined. Their names are self explanatory, and they are [:alnum:] , [:alpha:] , [:cntrl:] , [:digit:] , [:graph:] , [:lower:] , [:print:] , [:punct:] , [:space:] , [:upper:] , and [:xdigit:] . For example, [[:alnum:]] means [0-9A-Za-z] , except the latter form is dependent upon the ASCII character encoding, whereas the former is portable. The brackets in these class names are part of the symbolic names, and must be included in addition to the brackets delimiting the bracket list. Most metacharacters lose their special meaning inside lists. To include a literal ] , place it first in the list. Similarly, to include a literal ^ , place it anywhere but first. To include a literal - , place it last.

The period matches any single character. The symbol \w is a synonym for [[:alnum:]] , and \W is a synonym for [^[:alnum]] .

The caret ^ and the dollar sign $ are metacharacters that respectively match the empty string at the beginning and end of a line. The symbols \< and \> respectively match the empty string at the beginning and end of a word. The symbol \b matches the empty string at the beginning or end of a word, and \B matches the empty string provided it is not at the beginning or end of a word.

A regular expression matching a single character may be followed by one of several repetition operators:


Regular Expression Repetition Operators 




The preceding item is optional and matched at most once.


The preceding item will be matched zero or more times.


The preceding item will be matched one or more times.


The preceding item is matched exactly n times.


The preceding item is matched n or more times.


The preceding item is optional and is matched at most m times.


The preceding item is matched at least n times, but not more than m times.

Two regular expressions may be concatenated; the resulting regular expression matches any string formed by concatenating two substrings that respectively match the concatenated subexpressions.

Two regular expressions may be joined by the infix operator | ; the resulting regular expression matches any string matching either subexpression.

Repetition takes precedence over concatenation, which in turn takes precedence over alternation. A whole subexpression may be enclosed in parentheses to override these precedence rules.

The backreference \n , where n is a single digit, matches the substring previously matched by the n th parenthesized subexpression of the regular expression.

In basic regular expressions the metacharacters ? , + , { , | , ( , and ) lose their special meaning; instead use the backslashed versions \? , \+ , \{ , \| , \( , and \) .



Source-Navigator has has a graphical front-end to the GNU debugger, gdb .

This interface helps you to graphically visualize data structures and memory, and it allows you to set, enable, and disable breakpoints and watchpoints, thereby augmenting Source-Navigator's static analysis capabilities with a powerful tool for dynamic code analysis. The gdb interface has been fully integrated with the rest of Source-Navigator's browsers, so that double-clicking on a symbol in a data display, for example, will take you instantly to that symbol's definition.

Note that by default, Source-Navigator does not store information about local variables, so clicking on a local variable will not have any effect. To add local variable information to the project database, see page 75 .

You don't have to be familiar with gdb to use Source-Navigator's debugger interface.


Debugging with Source-Navigator

Starting the Debugger

Choose Tools -> Debug -> Go to start the Debugger. In the Program to Debug dialog box, choose the application you want to debug, and enter a working directory and application input parameters.

If your application uses stdin or stdout , you will need to set the xterm parameter. By default, this is xterm , but for Windows NT, you will want to use cmd.exe . If your program does not use stdin or stdout , you do not need to set this parameter.


Program to Debug Dialog Box

The entries are saved in the project database, and used as the default values the next time you use the Debugger.

To initialize the debugger session click OK . A breakpoint to the main() function is set automatically.

Debugging the Application

You can control your application using toolbar buttons, Debugger menu items, or keyboard shortcuts.


Toolbar Buttons for the Debugger

Debugger Menu


To set a breakpoint to the current editor position, use the Tools  -> Debug -> Add breakpoint menu item of the editor.

Choose this menu entry to show, enable, disable, or delete breakpoints.

Breakpoint Window


Activate View -> Stack to show the current stack trace.

Showing the current trace



Compile & Make

Although Source-Navigator has no internal compiler or build systems, it can interface with external make and compiler systems. Once an external system is configured, you can start a compile or make a project. Source-Navigator can interpret the output of the compiler or build system.

Using the Make System


Make Process Window

The command you enter in the text box changes the shell command executed by the Tools -> Make menu item. Click Start to perform the make.

When Source-Navigator starts the make command, the make process is displayed. Double-clicking a line with a compiler error message activates the Editor with the cursor positioned on the code line where the error appears.

Integrating Other Compilation Tools

Source-Navigator supports most command line-driven compilers that can produce error output that includes the filename and line number where an error has occurred. For more information, see the "Customization" chapter in the Source-Navigator Programmer's Reference Guide .



Version Control Systems

Source-Navigator provides a graphical user interface to several external version control systems that perform the version control tasks. The Source-Navigator version control system allows you to manage version control tasks on a project level. With version control you can organize your development to manage versions, version history, labels, and related documents.

Version control systems use locks to prevent the same files from being modified by two developers simultaneously. If a lock is used in revising a file, no one can modify the file until it is unlocked. Locking and unlocking can be controlled by checking in or checking out versions.

For more information, see the "Integrating with Version Control Systems" chapter of the Source-Navigator Programmer's Reference Guide .

Using Version Control

The following version control systems have been integrated with Source-Navigator: RCS, CVS, SCCS, and ClearCase. When creating a project, you must specify the correct version control system being used to manage the body of source code you wish to analyze. You make your selection in the Version Control tab of the Preferences dialog (see page 118 ).

To start version control, choose Edit -> Revision Control (see Figure 14-1 ).

Version Control Window

Checking in a File

You can check in all or selected project files in your version control system. When you check in, you can enter descriptive text of the changes and a version or version number. Using the left-mouse button, select one of more files to check in. With these files highlighted, choose Edit -> Revision Control -> Check in . The Check in dialog box is displayed.


Check-in dialog box

If you check in with With lock selected in this dialog box, others may not use your version in write mode.

This is useful if you are continuously working on a particular file, but wish to register checkpoints in your work without giving other developers the opportunity to make modifications to that file.

Checking Out a File

Versions of a file can be checked out for modification either locked or unlocked. Checking out with With lock selected in the Check out dialog box prevents other users from checking out the same version in write mode. A file that will be displayed but not modified may be checked out without lock.

Check out dialog box

Discarding Changes to a File

Working files can be reverted to the repository version with discard .

Show Differences

The Diff tool highlights differences between the current version of a file (the one you have checked out) and another one that you select from the list of available version numbers.


Showing Differences

Version Control Preferences

Use the Version Control tab of the Preferences dialog to tell Source-Navigator what source code control system you're running. You can access this tab by selecting File -> Project -> Project Preferences from the Symbol Browser, or Edit -> Preferences from the Version Control window.


Version Conrol Tab of the Preferences Dialog

Select your external version control system for the project. The options are RCS, CVS, SCCS, and ClearCase.





symbol and type 53

accelerator keys

Class Browser 83

Class Hierarchy Browser 89

general 16

Auto-Create dialog box 20



Class Browser 83


adding for debugging 111

disabling 107


checking in files 116

checking out files 117

Class Browser 79

accelerator keys 83

baseclass 83

filtering by access level 83

member list filter dialog 81

scope selector 83

starting 80

subclass 83

window 80

Class Hierarchy Browser 85

accelerator keys 89

starting 85

Tools menu 86

window 86

class name

filtering by access level 83

searching 80

ClearCase 115

columns, resizing 50


external system 113


document 15

keyboard 16

creating a new project 19


data, created in background 69

databases 23

defining symbols for 71

generating 23

Cross-Referencer 14, 69

selecting symbols 71

starting 69

tree diagrams 69

window 69, 70

CVS 115



gdb 107

global variables 112

menu 110

starting 108

dialog box

Auto-Create 20

Diff tool 118


importing into project 30

removing from project 22

discarding files 118

document conventions 15


Editor 14, 56, 59, 103, 114

extended toolbar 45

opening 59

window 60


and find-tag command 68

starting a new process 67

tab completion supported 80

using as editor 67

using with a running process 68

versions supported 67

emacsclient utility 68


file extensions 36


adding to a project 27

removing from project 22

unloading 22


by access level 83

patterns 52

special characters 52

toolbar buttons 44


column 57

symbol accelerator 61


gdb debugger 107

GNU regular expression 103

GNU regular expressions 103

gnuclient 68


search example 102

tool 101


hierarchy tree

diagram 69

function call 69

limiting 86

traversing 70

History menu 47


Include Browser 91

relationships 91

starting 91

window 92


defined 85

multiple 85

tree 81


keyboard accelerator keys

Class Browser 83

Class Hierarchy Browser 89

general 16


list filter buttons 44

locking files 115


macros 37

define 38

defining 39

delete 38

replace 38


external system 113

make command 114

make process window 113

member list filter dialog 81


Debugger 110

History 47

Windows 47

multi-user views 29


new project

creating 19

window 21


parser 20, 23

setting options 36

patterns 52

special characters 52


project 31

preserving context 50

Program to Debug dialog box 109


creating new 19

database 14

defined 13, 19

directory 22

file 19

managing 13

preferences 31

Project Editor

window 27

Project files window 22


RCS 115

regular expressions 103

Retriever 97

searching patterns 97

window 98

reusing windows 49


SCCS 115

Scope Selector menu

Class Browser 83


patterns 97

symbol names 97

text patterns 101

stack trace

showing current 112

status line 48

subclass 85

Class Browser 83


in hierarchy tree 70

superclass 85

symbol accelerator compound box 61

Symbol Browser 14, 55

window 23

Symbol list box 56

symbol selector 71


searching for 97


technical support 17

text patterns

searching in source code 101

toolbar 43

extended 45

list filter buttons 44

Tools menu 86


unlocking files 115


version control 115

checking in files 116

checking out files 117

ClearCase 115

CVS 115

diff tool 118

discarding files 118

locking, unlocking files 115

managing on project basis 115

RCS 115

SCCS 115

starting 116

supported external systems 115

version differences 118

window 116

View menu

adding breakpoint 111

showing current stack trace 112


creating 29

multi-user 29

removing files 30

selecting 30



disabling 107


Project Editor 27


Class Browser 80

Class Hierarchy 86

Cross-Referencer 69, 70

Editor 60

Include Browser 92

Make Process 113

New Project 21

Retriever 98

reusing 49

Symbol Browser 23

Version Control 116

Windows menu 47

1. " G eneral R egular E x p ression".

2. Richard Stallman and Karl Berry wrote the GNU regex backtracking matcher. Copyright (C) 1989, 1991 Free Software Foundation, Inc., 675 Massachusetts Avenue, Cambridge, MA 02139, USA.