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
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.
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,
, 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
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,
, 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.
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.
Plain Typewriter FontDenotes code fragments, contents of files, and command names; also indicates directory, file, and project names where they appear in body text.
Italic Typewriter FontRepresents a variable for which an actual value should be substituted.
Bold Typewriter FontIndicates command lines, options, and text output generated by Source-Navigator.
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 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.
.projfile extension is the default; you may change the name of the project file in the Project File text field, but you must use the
.projfile extension if you're working in Windows and you want Source-Navigator to launch when you double-click on your project name.
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.
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 .
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 (*) .
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.
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.)
The project directory is the current working directory, and the file
must contain directory names or filenames, one per line. (The Source-Navigator Include Browser uses the directory names.) A sample file for import follows:
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.
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 .
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.
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.
is used to insert a symbol into Source-Navigator's preprocessor namespace. If you
, the leading
is optional), then conditionals that test
will be scanned according to the
will be replaced with the empty string.
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
whenever it sees the
macro. This is particularly useful for
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)
macros can take arguments, just as in C and C++, and they can expand recursively, (i.e.,
might expand to
which might then expand to
mumble (5, 5, 0)
; in this case Source-Navigator would only see
mumble (5, 5, 0)
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:
/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).
lpr, whereas Sys V systems use
lp. In Windows, Source-Navigator uses the Registry to decide how to print.
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.
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 .
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.
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 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 ).
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.
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),
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 ).
in the filter text box, and
chosen from the
menu, you would see the results shown in
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.
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.
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 .
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.
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.
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 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.
xterm -T %f -e vi +%l %f
vi +%1 %f
emacsor the name of the executable file of emacs. For example, enter
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).
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.
gnuservutility, which is provided in your Source-Navigator distribution, is loaded. This involves adding the following two lines to your emacs startup file (usually
emacsdocumentation for additional information.
emacssession, Source-Navigator can now request that the running
emacssession bring up files for editing. Source-Navigator also rescans the files when you finish editing.
The Source-Navigator search function replaces the
) when you search for a symbol. Because the other tag commands are not yet available inside Source-Navigator, you need to use the equivalent
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.
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 .
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.
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.
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.
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.
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 ).
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 .
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 ).
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 .
Some programming languages provide a facility for including other source files. In C/C++ this is achieved by using the
preprocessor directive. The
lets you display
relationships of source files in the same 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.
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.
box you can choose which directories to search for include files. Using the set of directories shown in
, for example, if
is a reference then Source-Navigator will first look for the file
, then for
, 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 ).
The retriever displays all the symbols it found with the pattern you're searching for (see Figure 10-2 ).
For more information on reusing windows for multiple searches, see "Reusing Windows" on page 49 .
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 ).
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
filter to limit your search; for example, entering
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.
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  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 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.
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 .
If your application uses
, you will need to set the
parameter. By default, this is
, but for Windows NT, you will want to use
. If your program does not use
, you do not need to set this parameter.
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.
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.
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.
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.
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.