Introduction to Sun WorkShop

Chapter 5

Browsing Source Code

Sun WorkShop uses pattern search and source browsing modes in the Browsing window to browse your C, C++, Fortran 77, and Fortran 95 source code. Pattern search mode allows you to search your source code for any text string, including text embedded within comments. Source browsing mode allows you to find all occurrences of any program-defined symbol in your code by searching in a database that is created when you ask Sun WorkShop to generate source browsing information at the time you create or edit your project, compile your code with a source browsing option, or create a tags database. You then view the occurrences or matches to your query with their surrounding source code in the Browsing window match pane.

You can also graph the function and subroutine relationships in your program, and if your source code is written in C++, you can browse and graph the classes defined in your program.

For step-by-step instructions and more information about browsing, see the Browsing Source Code section of the online help (you can access the online help through the Help menu or Help button in any Sun WorkShop window).

Using Pattern Search Mode

Pattern search searches for any text string (including text embedded in your comments) in the current directory or in the directories imported in the sb_init file (for more information about sb_init and searching multiple directories, see "Searching Multiple Directories" in the Browsing Source Code section of the online help).

Use pattern search when you:

• Want to do a quick search for a text string
• Do not have a source browsing database in the directory you want to search
• Do not want to graphically view function call relationships or class hierarchies
• Do not want to examine the data or member functions of a class

Pattern search uses grep syntax and searches all source code lines for a match to the string you type in the Pattern text box of the Browsing window (see FIGURE 5-1). For more information, see "Searching for a Pattern" in the Browsing Source Code section of the online help.

FIGURE 5-1   Browsing Window in Pattern Search Mode

Pattern Search Special Characters

Although you can type in the Pattern text box a pattern exactly as it appears in the code, you can also use special characters (wildcard characters) to specify a pattern. You can use the special characters in TABLE 5-1 in the Pattern text box in the Browsing window.

TABLE 5-1   Pattern Search Special Characters

Character	Meaning	Example
Period (.)	Matches any character.	l.nes matches all occurrences of lanes or lines.
Asterisk (*)	Matches zero or more occurrences of the preceding character.	file.*() matches any string that contains file followed by zero or more characters and (), such as traffic_file_close() and file_save_popup. *file matches only strings that begin with file.
Caret (^)	Constrains the search to match the beginning of a line.	^tr* finds all lines that begin with traffic, truck, or any other string beginning with tr.
Dollar sign ($)	Constrains the search to match the end of a line.	lanes$ finds all the lines that end with the string lanes.
Backslash left angle bracket (\<)	Matches the start of a word.	\<get finds get_foobar, but not widget.
Backslash right angle bracket (\>)	Matches the end of a word.	\<String\> finds String *foo, but not XmStringCreate().

Surrounding an expression with a caret and a dollar sign constrains the search to match the entire line.

For more information, see "Special Characters in Pattern Search and Source Browsing Modes" in the Browsing Source Code section of the online help.

Multiple Directory Searches

Pattern searching uses the directories listed in the sb_init text file to search source files in multiple directories. For step-by-step instructions, see "Searching Multiple Directories" in the Browsing Source Code section of the online help.

Using Source Browsing Mode

In source browsing mode, Sun WorkShop responds to queries by searching in a database that contains information about the source files you are browsing. Use source browsing mode when you:

• Have a source browsing database
• Want to search for language elements such as functions, classes, structs, unions, or records or their usage, definitions, or assignments
• Want to graphically view function call relationships or class hierarchies
• Want to examine the data or member functions of a class

FIGURE 5-2 shows the Browsing window in Source Browsing mode.

FIGURE 5-2   Browsing Window in Source Browsing Mode

Source Browsing Databases

Sun WorkShop obtains its browsing information from a database that describes the static structure of your program. How the browser functions depends upon the database it accesses. The following are the browser database choices available:

• No database. You must use pattern search mode instead of source browsing mode. For more information, see "Searching for a Pattern" in the Browsing Source Code section of the online help.
• Compiler-generated browser database. This database provides full browser functionality. Source browsing mode responds to queries by searching through this database.

  One of the selections you can make when you are creating or editing a project is for Sun WorkShop to generate the database when it compiles your code or you can generate the database by adding the appropriate source browser option to your makefile and building your source files. For step-by-step instructions, see "Generating a Browser Database" in the Browsing Source Code section of the online help.

• Tags-generated database. This database provides a way to browse source files without compilation, allows queries on functions and global variables, and displays function calls (graphing features not available). A tags database recognizes only global definitions for variables, types, and functions and collects information on function calls. Function calls for C++ members are recognized only when members are called explicitly.

  For step-by-step instructions, see "Creating a Tags Database" in the Browsing Source Code section of the online help.

Source Browsing Special Characters

Although you can type a name or function in the Match text box exactly as it appears in your source code, you can also use special characters (wildcard characters) to specify a set of character strings.

You can use the special characters in TABLE 5-2 in the Match text box in the Browsing window.

TABLE 5-2   Source Browsing Special Characters

Character	Meaning	Example
Period (.)	Matches any character.	.ehicle matches all occurrences of vehicle or Vehicle.
Asterisk (*)	Matches zero or more occurrences of the preceding character.	vehi.* matches any string that begins with veh, such as vehicle_length(). vehi* matches veh., but not vehicle_length().

For more information, see "Special Characters in Pattern Search and Source Browsing Modes" in the Browsing Source Code section of the online help.

Multiple Directory Browsing

For all projects except a user makefile project: When you create or edit your project, if you ask Sun WorkShop to generate source browsing information during compilation, Sun WorkShop merges all the browsing directories for you. Then when you search in pattern search mode or source browsing mode, all the source directories in your project are automatically searched. For more information, see "Creating a New Project" and "Editing a Project" in the Working With Projects section of the online help.

For a user makefile project: If you keep your source files in several directories, you will most likely run the compiler in each of these directories. By default, the compiler generates a separate source browsing database in each directory. Since Sun WorkShop browses only one database at a time, it searches only that part of your application located in the current directory. You can override this default behavior by importing databases. For step-by-step instructions for how to import databases, see "Browsing Multiple Directories" in the Browsing Source Code section of the online help.

Relating Browsing and Graphing

FIGURE 5-3 shows how the Browsing window, the Call Graph window, the Class Graph window, and the Class Browser window interrelate.

FIGURE 5-3   How Browsing, the Graphers, and the Class Browser Interrelate

Graphing Functions

Using the Call Graph window, you can graphically inspect the relationships of the functions in programs using ANSI C, C++, and Fortran. You can display the functions that either call or are called by one or more selected functions. The Call Graph window provides a graphic representation of the call relationship of functions and subroutines. For step-by-step instructions and more information, see "Graphing a Function Call" in the Browsing Source Code section of the online help.

You must have a source browsing database to view function relationships (see Source Browsing Databases).

---

Note – You can graph virtual functions, but Sun WorkShop cannot determine the actual function that would be called. For example, if main calls b::d(), a virtual function that could actually call b1::d() or b2::d(), Sun WorkShop cannot tell which function is called. The graph shows main calling b::d(), but no connection between main and b1::d() or main and b2::d().

---

To change the colors used for node background, graph pane background, node border, node text, and arrows between nodes in the Call Graph window, edit the WORKSHOP resource file (see Call Graph and Class Graph Window Colors). Any color changes you make apply to both the Call Graph and Class Graph windows.

FIGURE 5-4 shows the Call Graph window.

FIGURE 5-4   Call Graph Window

Graphing Classes

Using the Class Graph window, you can graphically inspect the inheritance structure of classes in C++ programs. The Class Graph window provides a graphic representation of class hierarchies. For step-by-step instructions and more information, see "Graphing a Class Hierarchy" in the Browsing Source Code section of the online help.

To change the colors used for node background, graph pane background, node border, node text, and arrows between nodes in the Class Graph window, edit the WORKSHOP resource file (see Call Graph and Class Graph Window Colors). Any color changes you make apply to both the Class Graph and Call Graph windows.

FIGURE 5-5 shows the Class Graph window.

FIGURE 5-5   Class Graph Window

Browsing Classes

Using the Class Browser, you can:

• Browse a class. You can show the class list and data function members and view class interfaces and relationships.
• Examine class relationships. You can select a class and examine its base, derived, and friend classes, and you can browse classes, structs, and unions referenced in the current class.
• Graph a class. You can graph the class hierarchy of a class selected in the Class Browser window.
• Show the source of a class. You can show the source of a particular class in an editor window.

You can view information about classes and their member and friend functions in the Class Browser window. By navigating through the classes in the source code and libraries, you can understand how the classes were defined and used.

When you open the Class Browser window (see FIGURE 5-6), the Browser list contains all classes of the type Class or Struct in the current source browser database. Using the two check boxes to the right of the Browser list, you can show all types, only classes and structs, or only the unions.

For step-by-step instructions and more information, see "Browsing a Class" in the Browsing Source Code section of the online help.

FIGURE 5-6   Class Browser Window

Exiting Browsing

To quit the current browsing process and close all browsing windows, choose Browse Exit Browsing in the Browsing window. If you want to close the Browsing windows without killing the current browse process, choose Browse Close.