3    A Guided Tour of FUSE

This chapter shows how FUSE tools can help you perform tasks and solve problems on a typical software development project. For detailed information about a specific FUSE tool, refer to either the tool-specific chapter in this manual or the online Help.

3.1    Start FUSE with a Specific Environment

Suppose you have written code for an application and you are ready to build it. Go to the directory that contains the source files for your application and invoke FUSE with the fuse command. By invoking FUSE this way, the project context and thus any tools you start during the session will be configured to this working directory automatically. Alternatively, you could use Common Desktop Environment (CDE) icons in the Application Manager to start FUSE and individual tools (see Section Section 2.1.2).

When you start FUSE from the command line, the Control Panel appears:

Like most FUSE tools, the Control Panel has a transcript area and an information area. The transcript area in the Control Panel lists all open projects and the names of the tools started in those projects. In other tools, the transcript area lists data pertinent to that tool (such as source code text in the Editor, the results of a build in the Builder, or program errors in the Ladebug Debugger).

The information area at the bottom of the window displays operation status and a one-line quick help on the tool's menu items.

3.2    Create a Makefile

From the Control Panel, start the Builder by choosing Tools: Builder. Because this is the first time you are building the application and there is no makefile, the Builder displays an information dialog box indicating that it was unable to find a makefile. Click on OK. The Project Manager dialog box comes up, which you can use to change the working directory, specify a path for a makefile, or create a makefile.

To create the makefile for your application, click on the Create... button. In the Create Makefile dialog box, enter the names of the makefile and the target (the executable). Use *.c (appropriate for this example) to list source files that make up your application, and specify flags for linking and compilation (use -g for debug).

When you click OK in the Create Makefile and Project Manager dialog boxes, t he Builder creates the makefile and configures the Builder to your makefile. To display a graph of your makefile that shows the dependencies between files, choose Graph: Display Graph. The Builder parses the makefile and displays the graph. Include file dependencies are not listed but can be added, as described in Section Section 3.2.1.

The Builder dependency graph uses colors to indicate file status:

• White: up-to-date source file

• Red: out-of-date source file

• Orange: newer source file

• Yellow: selected target

Shapes in the dependency graph represent file type:

• Oval: source file

• Rectangle: intermediate file

• Diamond: target

You can display node names and dependencies in the information area by dragging the mouse over a node or line in the graph. This is useful when the graph is large.

3.2.1    Analyze Dependencies in the Makefile

The Builder can automatically add to the makefile and graph the dependencies on include files (choose Execution: Build Dependencies). You can use filters to eliminate certain dependencies from the graph. For example, use the regular expression ^/ to filter out pathnames that begin with / (for example, /usr/include/stdio.h).

Note the dependency on types.h that appears in the following graph:

Now you can start a build by clicking on the Start Build button. If you want to collect static analysis data for use by the browsing tools (Cross-Referencer, Call Graph Browser, C++ Class Browser), you also need to click on the Generate Static Analysis Data toggle button before you start the build.

The results of running gnumake appear in the transcript area. (If you like, you can tell the Builder to use another make utility instead of gnumake; choose Execution: Execution Control.)

Use the Diagnostics buttons (First, Next, Previous, Last) to navigate the error messages in the transcript area. When you use one of these buttons to select a message in the transcript area, the Builder invokes the Editor, which, in turn, displays the source code associated with the message. (You can also scroll through the transcript area and double click on messages to display the associated source code.)

3.2.2    View Annotated Source Code in the Editor

All lines associated with errors are annotated in the Editor with colored icons. Other annotations are used to represent lesser errors. When you select a message in the Builder, the source line associated with that message is annotated with a colored icon.

The Builder and Editor windows are synchronized: if you navigate to another message in the Builder transcript area, the Editor automatically repositions the source code to the associated line and annotates it as the currently selected message.

After fixing errors, you can start a new build from the Editor by choosing Utilities: Compile Default... or Utilities: Compile File... options.

3.3    Set Up and Start the Debugger

After you get a clean build, you can try running the application. If, when you run it, your application produces a segmentation fault and a core file, you can invoke the Debugger (Digital Ladebug for Digital UNIX Systems) from the Tools menu in the Editor, the Builder, or the Control Panel.

When the Debugger starts, it displays the Run New Program dialog box. The Working Directory defaults to the project directory. Specify the program to run and, optionally, the name of the core file, debugging options, and program arguments (if any). Then click on OK.

3.3.1    Display Call Stack Information

After you start the program, the Debugger displays the source code and indicates the line in your code that was executing when the problem occurred. You can use the Call Stack menu to show the call stack and the function in which the fault occurred.

3.3.2    Run the Program with Breakpoints

Now you decide to set some breakpoints before continuing to debug your application. You can set breakpoints from the Editor, in the Debugger, or from the communications pane at the bottom of the Debugger window.

To set a breakpoint in the Debugger, click on a toggle button in the breakpoint area to the left of the source code line.

After setting breakpoints, you can run the application by choosing File: Run Same Program. Enter arguments that you want to pass to the program in the Arguments: field, then press Return (or click on OK).

To see the contents of a variable, select the identifier in the source code display and click on the Print button.

3.4    Find a Search Pattern in Source Code Files

As part of the coding and debugging process, you often have to examine source files. The Search tool makes it easy to find occurrences of regular expressions in text files. Search is integrated with the Editor, giving you a powerful and efficient means to locate character sequences in files (not just program source files) and to view the locations in context.After starting a search for a string in the Search tool, you can display the source code for an occurrence by double clicking on the line in the search results display. The code is displayed in the editor and annotated with a colored icon.

3.5    Create a Source Code Library

Suppose you have found and fixed all the problems with your application. Now you want to store the application files in a code library. Choose Tools: Code Manager from any tool to start the Code Manager.

Because you have not yet created any code libraries, you'll first see an informational box that gives you a choice of specifying existing libraries to open or creating a new library. To create a new library, click on the Create Library button in the informational box and enter the pathname of the library and working directory in the Project Manager dialog box. Use the Tool Type: options box to specify either RCS or SCCS as the library manager, then click on the Create... button.

This creates the library and FUSE adds the library path to the Libraries to Open list for the current project. If you save the current project, opening the project during a future session would automatically open this library when you started the Code Manager.

3.5.1    Insert Files into the Library

To insert files into the library, choose Commands: Insert New... from the Code Manager. The Insert Files dialog box appears. If you enter *.c in the File Pattern: field, the Selected Files list is filtered to display only C source files. If you want, you can fill in the Comment field and provide the name of a Descriptive File (such as README) that you want to associate with files in the library. Click on OK to insert the selected files into the library.

3.5.2    Check Files Out of and Into the Library

The Code Manager keeps a revision history of each file in the library. A new revision is created whenever you check in a file. You can view the revision history for a file by double clicking on its name in the Code Manager display area.

Use the buttons below the display area to obtain additional information about each revision (for example, who worked on the revision, when it was worked on, or comments that were logged when the file was checked in).

The Code Manager allows you to execute commands before or after a Code Manager operation by specifying preprocessing or postprocessing commands. The results of pre- and postprocessing are displayed in the transcript area. For example, you can see the operation name (%OP) and the name and version of the file (%FNV) on which the operation is performed as preprocessing information in the transcript area.

To specify pre- or postprocessing commands, choose Library: Set Pre/Post Processing Strings... in the Code Manager. This command invokes the Project Manager dialog box.

After specifying this preprocessing option in the Pre-processing Command field, click on OK.

When you check out a file (without a lock), the checkout operation and the name and version of the file are reported.

3.6    Compare Revisions of Files

You can graphically display the differences between two files, or between a file you have checked out and a previous revision, using the FUSE Compare tool. The Compare tool can also merge files and revisions interactively.

If you select only one revision in the Code Manager, the Compare tool compares the revision you selected to the file of the same name residing in your current working directory. To specify the revision you want to compare to the checked-out file, you can:

• Select the revision in the Code Manager and choose Commands: Compare...

• Invoke the Compare tool directly and choose File: Compare...

You can review the differences (by using the Next Diff and Prev Diff buttons) or scroll through them using scroll bars that synchronize the Compare display window.

3.6.1    Annotate Differences in the Editor

When you double click on a difference line for the file in your working directory, the Editor displays the associated source code. To annotate lines in the source code that are associated with differences reported in Compare, choose Edit: Annotate Left or Edit: Annotate Right in the Compare window. Source code lines are marked with a left or right angle bracket, depending on whether the differences came from the file on the left or the right side of the Compare window.

3.6.2    Merge Revisions of Files

When you are working in an environment where multiple users are checking in and checking out files in a source code library, there might be instances when you want to merge two different revisions of the same file. Additionally, you might want to merge the differences of two files (with different file names) that originated from the same file.

You can merge files from either the Code Manager or the Compare tool. Use the Code Manager when you want to merge two revisions of the same file; use Compare when you want to merge the differences of two files with different file names.

To start a merge operation:

1. Invoke the Code Manager, select the two revisions of the same file, and then choose Merge/Checkout... from the Commands menu.

2. Invoke the Compare tool, choose Merge from the File menu, and then choose the two files with different file names and the ancestor file (the file from which the two files originated).

Use the Pick Left, Pick Right, Next Conflict, Prev Conflict, Next Diff, and Prev Diff buttons to view the differences and conflicts found between the two files and then choose the ones you want to incorporate into the merged version of the files.

3.7    Generate Memory Analysis Data

To analyze memory leaks and errors in your program, use the Heap Analyzer. Configure the Heap Analyzer with your target executable using the Project Manager.

Analyzing memory leaks and errors with the Heap Analyzer is done in two steps. First you generate the memory analysis data by running your instrumented application. Then you can analyze the resulting data.

To generate memory analysis data, choose Generate Data in the Action: options box, specify arguments (if required), and then click on Run.

3.7.1    Display Memory Analysis Data

After the memory analysis data has been generated, you are ready to analyze the data. In the Action: options box, choose Show Data. In the Show: options box, choose the type of data you want to display (memory leaks or different types of memory errors). In the As: options box, choose the display format (Histogram, 2-level Histogram, and so on). Then click on Apply.

3.8    Generate Profiling Data

To analyze the performance of your program, use the Profiler. The Profiler inherits the target executable setting for the project. You can check the default target for the project by choosing Projects: Show/Modify... in the Control Panel. Enter the pathname for the target executable in the Target Executable field if necessary.

Analyzing performance with the Profiler is done in two steps. First you generate the profiling data by running your instrumented application. Then you can analyze the resulting data.

To generate profiling data, choose Generate Data in the Action: options box, specify arguments (if required), and then click on Run.

3.8.1    Display Profiling Data

After the profiling data has been generated, you are ready to analyze the data. In the Action: options box, choose Show Data.

To find out which functions you are executing most frequently and display this information as a histogram, click on Apply. By default, the Show: options box is set to Functions by CPU Cycles and the As: options box is set to Histogram.

This graph lists the functions in the application and the percentage of the execution cycles spent in each function. The percentages are also shown graphically by bars in the histogram and are sorted in descending order.

3.8.2    Pinpoint a Hotspot in Profiling Data

You can view profiling data in more detail by choosing the Lines by CPU Cycles and then double clicking on a function. For example, suppose you want to examine the data for the copy_file function. Choose Lines by CPU Cycles in the Show: option box. Choose the 2-level Histogram from the As: options box and double click on that function to see the histogram. This display tells which lines of code in the copy_file function are consuming the most cycles.

To see the source code associated with a line in the histogram, click MB2 on that line. The source is displayed in the Editor, annotated with a colored icon.

3.9    View Search Result, Memory Analysis Data, and Profiling Data

When you use the Search tool, the Heap Analyzer, or the Profiler, the resulting data can be viewed in the tool's main window display area. Additionally, these tools also allow you to view the resulting data in the Program Visualizer, which provides a graphical view of the data.

3.10    Locate Declarations by Name and Classification

In contrast to the Profiler, which is a dynamic analysis tool that supplies performance and coverage information as your application runs, FUSE also offers static analysis browsing tools. These tools (Cross-Referencer, Call Graph Browser, C++ Class Browser) use a database created by scanning the source code for your application during a previous build.

The Cross-Referencer allows you to locate occurrences of program symbols (declarations, references, assignments, functions, and calls). The most common use of the Cross-Referencer is to search for declarations by name.

For example, to search for all the declarations that begin with max, you could use the expression ^max in the Name: field, and choose Expression from the associated option box. (The Cross-Referencer lets you specify any regular expression supported by the egrep command.) Click on Issue Query to begin the search.

The results of the query are displayed in the lower half of the Cross-Referencer window. When you click on a symbol in the first column, the line numbers for the selection are displayed in the second column.

To display the source code associated with a symbol, double click on the symbol in the first column. The Editor appears and the associated source code is annotated with a colored icon.

You can constrain a query by specifying additional filter information in the top half of the Cross-Referencer window. At any time during a Cross-Referencer session, you can recall the information associated with a previously issued query to refine it further, if necessary, and reissue it.

3.11    Analyze Routine Call Relationships

The Call Graph Browser is a static analysis tool that lets you view and analyze call and containment relationships in your application. Containment relationships present a hierarchical view of an application (that is, where various functions, files, and subdirectories are contained). For example, file foo.c is contained in a directory named bar.

You can use the main window to display a graph of functions and their call relationships in your application as nodes connected by arrows. You can also view the containment hierarchy by selecting a specific node and choosing Selection: Show Contained. When the files of an application are distributed over several directories, the initial call graph will show call relationships at the directory level.

The three small views below the main call graph let you view specific Called By and Calls relationships. The center view shows the selected node. The left view shows the node at the caller end of the selected arrow. The right view shows the node at the callee end of the selected arrow. You display these views by dragging MB1 over the relationship arc of specific nodes.

The transcript area below the small views displays information about the selected node. For example, in the following figure the function read_command_line has been selected (and is displayed in the center small view) and the transcript area shows the calling relationships (the functions it is called by and the functions it calls).

You can display the source code associated with information in the graph or transcript:

• From the graph, you have two choices:

  • Select the node and then choose Selection: Edit.

  • Double click on a node whose type is function.

• From the transcript: Select the item.

The Editor appears and the associated source code is annotated with a colored icon.

3.12    Analyze Calls Between Source Files

You can use the Call Graph Browser to analyze calls between source files.

The nodes are rectangles instead of ovals because they represent the files in the application, not the functions. The arrows, however, still represent call relationships. This layout gives you some immediate insight into the design and implementation of the application.

When the file buildtable.c was selected in the call graph, the transcript area displayed the names of the functions defined in the file.

To view the contains relationships, that is, the functions within a file, you must first expand the file. Then select Selection: Show Contains.

3.13    Display the Class Hierarchy for a C++ Program

The C++ Class Browser is an optional tool available with the DEC FUSE Support for C++ license. This tool displays the class hierarchy for a C++ program and lets you bring the source code for selected classes and members into the Editor.

In the figure that follows, the Mammal class has been selected and detailed member information for that class is displayed in the Member Information pane.

In the area directly below the graph, the Base Classes menu lists the immediate classes that Mammal inherits from. The Derived Classes menu lists the immediate classes that inherit from the Mammal class. You can make a class the current class by clicking on it in the Base Classes or Derived Classes tear-off menu lists. This allows you to traverse the hierarchy from these menu lists, as well as from the graph.

To help you locate classes more easily, you can enter the name directly in the Class field or click on the Browse... button to display the Class List dialog box. From here, you can browse the entire class hierarchy by name or filter it using a regular expression.

Colors are used in the class graph to represent relationships. The class currently selected in the graph is yellow. A blue border indicates a derived class that inherits without redefinition a member function selected in the Member Information pane. A red border indicates a class that defines the member function selected in the Member Information pane.

Double clicking on a node in the graph displays the associated source code in the FUSE Editor. If you click MB3 on an item in the Members column, you can choose to edit the definition or declaration or set a breakpoint for that item.

In this example, choosing Edit Declaration from the MB3 pop-up menu on the Mammal(const class Mammal(&)) line in the Member Information pane displays the annotated code in the FUSE Editor.

You can apply various filters to the content of the Member Information pane, by either setting the toggle buttons beside the pane or using the filter dialog box after clicking on the Member Selection button. This dialog box lets you enter a regular expression in the Pattern Filter field to filter members by name.

3.14    Port Your Application

If you wrote your application to run on a platform other than a Digital UNIX Alpha system, you can use the Porting Assistant to identify the source code that might not compile or run on Digital UNIX Alpha systems.

The Porting Assistant is closely integrated with the FUSE Builder and editors. After running code checks on your source code, you can use the Builder to see the results of the code check operation.

After you run checks in the Porting Assistant, you can use either the FUSE Editor or one of the supported Emacs editors to review any diagnostic messages and associated code. To get help on a diagnostic message, choose Help on Diagnostic from the Diagnostics menu.