Contents
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.
Permission is hereby granted, without written agreement and without license or royalty fees, to use, copy, modify, and distribute this software and its documentation for any purpose, provided that the above copyright notice and the following two paragraphs appear in all copies of this software. IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS
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."
USA:
Cygnus Solutions
1325 Chesapeake Terrace
Sunnyvale, CA 94089
Phone: +1 408 542 9600
Fax: +1 408 542 9699
Europe:
Cygnus-multiX GmbH
Zettachring 2
D-70567 Stuttgart
Germany
Phone: +49 711 728 7426
Fax: +49 711 728 7427
Electronic access:
http://www.cygnus.com
Email: sn-support@cygnus.com
sales@cygnus.com
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-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.
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.
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:
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.
This guide serves as a reference to Source-Navigator menus, tools, and functionality.
Source-Navigator's documentation uses the following general conventions:
Plain Typewriter Font
Denotes code fragments, contents of files, and command names; also indicates directory, file, and project names where they appear in body text.
Italic Typewriter Font
Represents a variable for which an actual value should be substituted.
Bold Typewriter Font
Indicates command lines, options, and text output generated by Source-Navigator.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
.
The following are conventions for using the mouse with Source-Navigator:
You can use the keyboard to activate many of the functions displayed on the toolbar and in the menus.
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.
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.
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:
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.
.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. 
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.
In this chapter you will learn how to customize and work with your newly created 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.
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.
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.
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.
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 .
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.
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.
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.
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.
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:
chk.h
chk.c
hello.h
/usr/joe/src/main.c
/usr/joe/src/read.c
/home/andrea/tcp/call.c
/usr/local/include
/tmp
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
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 .
In the Project box you can set:
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.
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 .
|
|
|
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.
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
doesn't do any substitution, it just affects the evaluation of
#if
,
#ifdef
, and
#ifndef
statements.
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\
\
5
Otherwise, the directives are interpreted as documented above.
Others Tab of the Preferences Dialog
In the Bug reports box you can set:
/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).From the Printer box you can set:
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.
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.
This chapter describes how to use the most common features of Source-Navigator.
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 .
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:
Select this button to start the Class Hierarchy Browser. For more information on this tool, see
Chapter 8 on page 85
.
This button starts the Class Browser. For details on how to use this tool, see
Chapter 7 on page 79
.
To start the Cross-Reference Browser, select this button. Details can be found in
Chapter 6 on page 69
.
Select this button to start the Include Browser. For details, see
Chapter 9 on page 91
.
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.
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 Buttons box from the Edit Tab of the Preferences Dialog (see page 32 ) adds several new tool buttons to the toolbar.
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.
The History menu enables you to repeat queries and restore previous states of each browser.
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 ).
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.
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.
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.
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.
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.
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 ).
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.
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.
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
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.
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 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 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.
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.
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.
The Search menu is context-sensitive; different options are available depending upon the tool you're using. The following are available within the Editor.
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.
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.
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.
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.
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:
*.bak
Files
xterm -T %f -e vi +%l %f
vi +%1 %f
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).For information on customizing your key bindings, see the "Customization" chapter of the Source-Navigator Programmer's Reference Guide .
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:
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
).
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
):
(load "/usr/cygnus/snavigator/emacs/lisp/gnuserv")
(server-start)
emacs
documentation for additional information.
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 .
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.
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
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:
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.
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.
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 ).
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 .
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:
Click on the Filter button to bring up this dialog box. The symbols displayed by the Member List are included based on these settings.
The Scope Selector menu filters the member list depending on the accessibility of the members.
These accelerator keys are available for use with the Class 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.
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
The Tools -> Hierarchy menu contains the following items, which control how the class hierarchies are displayed.
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:
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.
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.
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.
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
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.
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 .
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 ).
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.
Clicking on an item in the Grep results list displays the appropriate file in the Editor, with the cursor positioned at the selected line.
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:
|
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
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.
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.
You can control your application using toolbar buttons, Debugger menu items, or keyboard shortcuts.
Toolbar Buttons for the Debugger
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.
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.
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 .
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 .
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 ).
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.
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.
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.
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.
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.
