• 4 — Source Browsing
• Adding Source Browser Information to a Project
• Changing Project Settings
• The BSCMAKE Tool
• The Source Browser Window
• Definitions and References
• File Outline
• Base Classes and Members
• Derived Classes and Members
• Call Graph
• Callers Graph
• Summary

4 — Source Browsing

In addition to the ClassWizard, the Source Browser is yet another invaluable development tool in Visual C++. This tool enables you to quickly locate definitions and references of symbols and to explore the relationship between symbols.

Adding Source Browser Information to a Project

The Source Browser tool requires the presence of a browser information file in your project. To add browser information, you must change your project settings; alternatively, you can also invoke the BSCMAKE utility manually.

Changing Project Settings

If you attempt to use source browsing features when no browser information file exists, the Developer Studio warns you of this and offers the option of rebuilding your project with browser information. You can also specify browser information in the Project Settings dialog (Figure 4.1). Select the Settings command from the Build menu to invoke this dialog, and select the Browse Info tab.

Figure 4.1. Adding browse information to a project.

To add browse information to your project, make sure the Build browse info file checkbox is set. Note that you can apply this setting selectively; for example, you can specify that browse information be added to your project's Debug build, but not to its Release version.

In this dialog, you can also specify additional command-line settings for the bscmake.exe utility.

The BSCMAKE Tool

The BSCMAKE tool, bscmake.exe, is the utility that creates browse information (BSC) files. This file is generated from source browser (SBR) files that are created during the link process. BSCMAKE employs a few tricks to improve its efficiency; for example, when it is finished processing an SBR file, it resets that file's length to zero, thus indicating that the file has no new information. This way, BSCMAKE can perform an incremental build of the browse information file during subsequent invocations. You can prevent BSCMAKE from implementing this behavior by specifying the /n command-line switch; when run with this switch, BSCMAKE performs a full build of the browse information file and does not truncate SBR files.

The bscmake.exe utility has several command-line options that can be used to improve its performance and limit the size of the BSC file. These options all begin with /E. For example, /Ei can be used to exclude the contents of specified include files from the build; /Er can be used to exclude specific symbols (the name of the include file or symbol to be excluded must be specified on the command line; if you wish to specify multiple filenames, enclose them in parenthesis). Other /E options include /El (exclude local symbols), /Em (exclude symbols in macro bodies), /Es (exclude include files specified with an absolute path either explicitly or through the INCLUDE environment variable).

BSCMAKE by default does not include unreferenced symbols in the browse information file. To include unreferenced symbols, specify the /Iu command-line option. Note that this option has no effect if the compiler generated packed SBR files, which do not contain unreferenced symbols.

To prevent BSCMAKE from repeatedly processing a header file that appears in several source files with preprocessor settings, use the /S option; this option forces BSCMAKE to ignore repeated occurrences of the header files specified on the command line.

BSCMAKE uses the base name of the first SBR file on its command line as the base name for its output file. To specify another output filename, use the /o command-line option.

The following example performs a full rebuild of a source information file. It also prevents BSCMAKE from processing two header files repeatedly:

bscmake /n /S (myhd1.h myhd2.h) /o myproj.bsc mysrc1.sbr mysrc2.sbr

The Source Browser Window

The features of the Source Browser can be accessed through the Source Browser window. This window is invoked through the Browse command in the Tools menu. This command presents the Browse dialog (Figure 4.2), where you can enter the symbol you wish to look up and specify the type of browse information that you wish to see. If a symbol is presently highlighted in Class View or in an editor window, the symbol will appear as a default in the Identifier field of this dialog.

Figure 4.2. The Browse dialog.

Note that you can use the asterisk as a wildcard character when specifying the symbol in this dialog.

You can also invoke the Source Browser window from within Class View in the Project Workspace window. Position the cursor over a symbol (class name, member function name, member variable name, or global symbol) and right-click to invoke the popup menu. Depending on the symbol's type, the popup menu will contain several commands (for example., the Base classes or Called by commands) that take you directly to the Source Browser window. Another shortcut available in these popup menus (and also popup menus in source editor windows) can take you directly to a symbol's declaration, definition, or references; this capability is a shortcut to a key Source Browser functionality.

Definitions and References

Depending on how you invoke it, the Source Browser can provide several views on your application's source code. The first of these views is the Definitions and References window (Figure 4.3).

Figure 4.3. Source Browser: Definitions and References.

In this window, all definitions and references of the specified symbols are shown. Selecting a definition or reference and double-clicking on it opens the appropriate source (or header) file and positions the cursor directly over the selected definition or reference. Thus, the source browser can be used as an efficient source navigation tool.

File Outline

The File Outline window (Figure 4.4) provides a unique view on a source or header file. This window lists all classes, functions, variables, macros, and types defined in the specified file.

Figure 4.4. Source Browser: File Outline.

This window also contains a series of buttons that can be used to filter out unwanted symbols. You can specify which types of symbols you wish to see listed by clicking the appropriate button in the window's toolbar.

The type of a symbol is displayed in the form of a lowercase letter in the left pane of the File Outline window. For example, a lowercase f means that the symbol is a function. Next to this letter, an uppercase letter on gray background specifies whether the symbol is virtual (for example, a virtual member function) or static.

Base Classes and Members

The Base Classes and Members window (Figure 4.5) is a three-pane window where you can browse the base classes of a specific class; it also shows the selected class's member functions and variables and the definitions and references for those.

Figure 4.5. Source Browser: Base Classes and Members.

In the combo boxes in this window's toolbar, you can specify what combination of virtual, static, nonvirtual, and nonstatic functions you wish to see listed; and also, what combination of static and nonstatic data you wish to see appear.

In the pane displaying class members, the type of a member is marked by the lowercase letter f (function) or d (data). Another, uppercase letter on a gray background shows whether the member is declared as virtual or static.

Derived Classes and Members

The Derived Classes and Members window (Figure 4.6) enables you to browse classes derived from a specific class. The appearance and behavior of this window are similar to that of the Base Classes and Members window.

Figure 4.6. Source Browser: Derived Classes and Members.

This window is also a very useful tool for familiarizing yourself with the structure of the Microsoft Foundation Classes. For example, as shown in Figure 4.6, you can browse the entire hierarchy CObject-derived classes, exploring their members and their relationships.

Call Graph

The Call Graph window (Figure 4.7) shows a hierarchical view of functions called by the specified function.

Figure 4.7. Source Browser: Call Graph.

Callers Graph

The Callers Graph window (Figure 4.8) shows the hierarchy of functions that call the specified function.

Figure 4.8. Source Browser: Callers Graph.

Summary

The Source Browser is an invaluable reference tool component of Visual C++.

Using the Source Browser requires that your project be built with source browser information added. You can select this option in the Project Settings dialog (Browse Info tab). The tool used to build browser information (BSC files) is the bscmake.exe utility.

The Source Browser window, invoked through the Browse command in the Tools menu or through various popup menus, presents six different views on your application's source.

The Definitions and References window lists all definitions and references for selected symbols. If you double-click on a definition or reference, the appropriate source or header file is opened with the cursor positioned at the location of the selected definition or reference.

The File Outline window presents a view of all symbols declared or defined in a specified source or header file. Toolbar buttons let you control what type of symbols you wish to see listed.

The Base Classes and Members window is where you browse the base classes of a specific class. The Derived Classes and Member window is where you do the same for classes derived from the specified class.

The Call Graph and Callers Graph windows can be used to list the functions called by a specific function or the functions that call a specific function.