4    Builder

This chapter provides an overview of the Builder's features and capabilities. For more detailed information on how to use this tool, choose Help: On Builder. You can print Help topics using the HyperHelp Viewer.

The FUSE Builder allows you to build applications quickly and consistently. The Builder supports all make utilities, including, but not limited to, Ultrix make, POSIX make, and gnumake. For detailed information about a specific utility, see your system documentation, or choose either the On Make(1u), On Make(1p), or On Gnumake option from the Help menu.

Figure Figure 4-1 shows the Builder main window.

Figure 4-1:  Builder Main Window

Key elements are the major window panes running from the top to the bottom of the window:

Configuration area

Displays basic information about the current build session such as the current project and build directory.

Graphic display area

Displays a graphical representation of the currently selected makefile. You can turn on and turn off the graph display. By default, the graph is turned off.

Controls area

Lets you set up the parameters for a build and start the compilation process.

Transcript area

Displays all error, warning, and status messages associated with the compilation of a makefile.

Information area

Displays information messages and Quick Help on menu items when you press and hold MB1 on the item.

4.1    Summary of Features

The Builder lets you do the following:

• Build (compile) all or part of your program including static analysis data for use by the C++ Class Browser, Call Graph Browser, and Cross-Referencer

• Build parts of a program in parallel:

  • Build locally in parallel

  • Distribute parallel builds across a LAN

• Build any type of file target, including source files, executables, and object files

• Allocate build processing across more than one system (distributed builds)

• Review transcripts of builds

• Track errors in a build

• Analyze information about files (including file name and update status) and file dependencies using the makefile graph

• Create simple makefiles (makefiles that do not call in other makefiles and that do not require complicated building instructions)

• Print the makefile graph

• Specify remote hosts and monitor build progress

• Provide integration with the Porting Assistant and the editors

4.2    Requirements for Using the Builder

To use the Builder for program building:

• Check that all include, source, and object files are available. Check that all disks containing these files are mounted and are available. If these files are not in standard directories (for example,/usr/include,/user/ar), make sure you specify the nonstandard directories in the makefile.

• Check that the compilers for the languages you use are installed.

If you are working with unsupported languages, you can still use the Builder to create, edit, and build files. However, interaction between the Builder and the FUSE Editor is compromised; the FUSE Editor cannot annotate compilation errors generated by a build that involves files coded in an unsupported language.

4.3    Starting the Builder

You can start the Builder in several ways:

• Use the command line.

• If you have CDE installed, use the Builder icon.

• Use the FUSE Control Panel once FUSE is running.

• Use the Tools menu from most FUSE tools.

When you start the Builder, it searches for a file named makefile or Makefile in the working directory. If a makefile cannot be found, the Builder displays an informational message and displays the Builder main window. You can configure Builder properties for the current project to use a makefile (in the working directory) with a different name, or a makefile that may exist in a directory other than the working directory (see Section Section 4.4).

4.3.1    Use the Command Line

You can start the Builder from the command line using the following command:

% fusebuild [-f path] [-cwd] [-Xt-Options]

See Appendix Appendix D and the specific reference pages for the command syntax and options.

If the Control Panel is not running, it starts automatically as a minimized icon. If FUSE is already running, the Builder is placed in the current project.

4.3.2    Use the Builder Icon from CDE

When you have CDE installed, FUSE provides a FUSE application group icon and icons for the individual tools that make up the FUSE environment.

To invoke the tool:

1. Double click on the Application Manager icon in the CDE Front Panel to display the application group icons.

2. Double click on the Application Manager icon in the CDE Front Panel to display the application group icons.

3. Double click on the FUSE application group icon to display the icons in the FUSE application group.

4.3.3    Use the FUSE Control Panel

To start the Builder from the FUSE Control Panel, choose Builder from the Tools menu. Like all tools, the Builder inherits its configuration data from the project settings. If these settings are already specified, the Builder main window appears. Otherwise, you will be prompted by an informational box to set project properties for the Builder. See Section Section 4.4 for more information on setting properties for the Builder. See Section Section 9.4 for more information on working with projects.

4.3.4    Use the Tools Menu from Most FUSE Tools

Most FUSE tools have a Tools menu. To start the Builder, select Builder from the Tools menu.

4.4    Setting Project Properties for the Builder

By default, the Builder uses the working directory as the build directory and uses a makefile in the working directory.

To set up the Builder to use a build directory different from the working directory, or a different makefile in the working directory, or a makefile that exists in a directory other than the working directory, choose Projects: Show/Modify... from the Control Panel. In the resulting Project Manager dialog box, click on the Settings Category options box at the top and choose Builder. This brings up the Project Manager dialog box shown in Figure Figure 4-2.

Figure 4-2:  Project Manager Dialog Box

The Project Manager displays the following information:

• Build Directory: Optionally, enter the pathname for the build directory. The pathname can be either absolute or relative to the working directory for the project. The Builder looks in the build directory for files or directories used in the makefile. Any relative pathnames used by the makefile must be relative to this build directory.

• Makefile: If you do not enter a makefile name in this field, the Builder looks first for a file named makefile or Makefile in the build directory (if there is one) or in the working directory for the project. If you used a different name for the makefile or if you want to use a makefile that is not in the working directory, enter its path. Click on the Create... or Modify... buttons to create or edit a makefile.

• Make Engine: When executing local sequential builds, you can choose any make engine, including ULTRIX make, POSIX make, and gnumake. To perform a local parallel or distributed build, you must use gnumake.

• Build and Compile Commands: The Builder provides defaults for these two fields, but you can choose your own.

For more information (including information on syntax for the build and compile commands), click on the Help button on the dialog box to bring up the online Help topic Set Builder Properties for a Project.

4.5    Using the Makefile Graph Display

The Builder makefile graph provides a graphical representation of the currently selected makefile. The graph lets you use the Builder main window to view a graph of the file, select targets in the makefile for building, and view a transcript of the build operation and any errors that it reports.

Use the makefile graph to become familiar with a new program, analyze changes you make to the build procedure, and select build targets. The makefile graph provides a graphical view of the relationships among files as defined in a makefile.

By default, the makefile graph display is turned off. When you turn on the graph, the Builder searches first for the makefile specified when you configured the Builder. If the Builder does not find that makefile, it searches the working directory for the file named makefile or Makefile. If the Builder finds a makefile, it parses it and then displays the makefile graph in the Builder main window display area. If it does not find a makefile, it displays a pentagon symbol.

The makefile graph uses shapes and colors (or gray scale), and line patterns and widths to provide information about file category, update status, and dependency relationships. See the online Help for an explanation of what each color and shape represents.

Note

If a makefile is recursive (that is, it calls another makefile), the makefile graph displays only those nodes in the second makefile that are directly referenced by the calling command.

4.5.1    Turning the Makefile Graph Off and On

Before the Builder displays a makefile graph, it must first parse the makefile. Depending on the complexity of the makefile, the parsing could take a few minutes. Therefore, by default, the Builder does not display a makefile graph. If you want the Builder to display a graph of the currently selected makefile, choose Show Graph from the Graph menu. When the graph is turned on, the Show Graph option has a check mark beside it. Click on the option again to turn off the graph.

Note

The graph is turned off if you choose Other as the make engine.

To change the default settings of the Builder so that the makefile graph is automatically displayed when you start the Builder, do the following:

If you change the graph settings during your Builder session but do not save the new settings before exiting the Builder as described in steps 2 and 3, a dialog box is displayed when you exit the Builder asking if you want to save your settings.

4.5.2    Using the Mouse for Viewing Information in the Makefile Graph

Table Table 4-1 lists the mouse actions you can use to display information about the makefile graph.

Table 4-1:  Makefile Graph Mouse Actions

Use this mouse action...	To...
Press and hold MB1 and drag the pointer across a node or line	Display the file name or dependency in the information area of the Builder main window.
Press MB1 on the node.	Select a node, display its dependency graph, and make it the current build target.
Double click on a source file node.	Display the file in an editor.
Position the pointer over the node and press MB3.	See the dependency graph for single node (without selecting it).
Press MB3 on a selected node.	Clear the selection and display the top-level graph.

In the case of a particularly complex graph, you may want to reduce the information in the graph and change the graph layout. Use the Builder Graph menu to adjust the layout and filter information.

When a build operation starts, check the transcript. For a successful build, the transcript lists no errors and the Error buttons remain grayed out. The makefile graph is updated to show that all nodes that are part of the target's dependency are up-to-date. If a build is unsuccessful, the transcript lists the errors and the First error button is enabled. The makefile graph reflects only intermediate targets that were successfully built.

To facilitate your interpretation of the file graph, you can click on the zoom buttons located below the graph. These buttons allow you to increase or reduce the size of graph objects, or redraw the graph so that all object labels are visible.

Figure Figure 4-3 shows a typical makefile graph.

Figure 4-3:  Builder Makefile Graph

Compare the graph with the following example, which is the makefile from which the graph was generated. The example contains callouts that clarify the relationship between makefile entries and their graphical representations.

 
SRCS = count.c fileops.c misc.c    (1)
 OBJS = count.o fileops.o misc.o   (2)    
 CFLAGS = -g 
 all: count    (3)
 count: $(OBJS)     cc -non_shared -o count $(OBJS)    (4)
 clean:     rm -f count $(OBJS) core *~                (5) 
 depend:    @cat < /dev/null > makedep             (6)
      @for i in ${SRCS}; do \                   
                   ($(CC) -M $(INCLUDES)  $$i >> makedep); done      
      @echo `/^# DO NOT DELETE THIS LINE/+1,$$d' > eddep      
      @echo `$$r makedep' >> eddep      
      @echo `w' >> eddep
      @$(RM) -f makefile      
      @$(CP) Makefile makefile      
      @chmod 644 makefile      
      @ed - makefile < eddep      
      @$(RM) -f eddep makedep      
      @echo `# DEPENDENCIES MUST END AT END OF FILE' >> makefile
      @echo `# IF YOU PUT STUFF HERE IT WILL GO AWAY' >> makefile
      @echo `# see make depend above' >> makefile      
      # DO NOT DELETE THIS LINE -- make depend uses it

1. Source (.c) files for the executable, count. Each source file is represented on the graph by a rounded rectangle.

2. Object files on which the count executable directly depends. These are intermediate files and are represented on the graph by rounded rectangles.

3. The all node on the graph represents a final build target for the entire count application and is represented on the graph as a diamond. As the first target specified in the makefile, all is also the default build target for the Builder.

4. Build command for the count executable file that counts the number of times each letter of the alphabet appears in a specified file. The count executable file is represented on the graph as a hexagon because it is a makefile target that is an intermediate file in terms of file dependency relationships.

5. Makefile targets used for deleting program files from the Builder working directory. The clean option removes intermediate program files.

6. A makefile target that creates the dependencies of all the sources in the SRCS list from the relative include files. The depend option is represented on the graph by a diamond; it does not depend on other options nor is it a dependency for other options.

4.6    Executing a Local Build

There are two types of local build:

• Local sequential processes each object sequentially at the local host.

• Local parallel executes parallel processing of objects at the local host.

To execute a local build:

Note

If you select make to perform the build, the Builder cannot annotate any error messages resulting from the compilation that refer to the relative pathnames of files.

4.7    Executing a Distributed Build

A distributed build executes parallel processing of objects at the remote host(s) specified in the host configuration file. To execute a distributed parallel build:

Note

The Builder executes all makefile commands in the shell. Observe shell syntax rules when entering commands.

Figure 4-4:  Edit Host Configuration Dialog Box

4.8    Generating Static Analysis Data with the Build

The browser tools (Call Graph Browser, Cross-Referencer, and C++ Class Browser) rely on a database that is generated using a set of static analysis data files. The Builder can create the static analysis data files as part of its build process. In order to use any of the browser tools, you must generate the static analysis data files as part of the build.

To generate static analysis data, follow these steps:

1. Use the Project Manager to specify a data directory. This data directory is the location where FUSE places the directory tree (project_name.data) that contains the database and static analysis data files. If you don't specify a data directory, the working directory will be used.

2. Use the Project Manager (Browser Tools Settings Category) to specify information about your environment, such as files to ignore during a scan, and whether or not to compress the database. This lets you customize how you want the static analysis database to be populated after the scanning process.

3. Build your target, including static analysis data.

4. Open a browser tool, for example, the C++ Class Browser, whose data display relies on the generated database.

See the online Help topic Generating Static Analysis Data as Part of the Build for details on these steps.

4.9    Creating a Makefile

The Builder provides support to create a simple makefile. In addition, the Builder provides support to create simple KAP-specific and Motif-specific makefiles. To create a more complex makefile that uses numerous source and data files and even calls in other makefiles, it is advisable to load the basic makefile into a FUSE Editor buffer and enter the instructions manually.

Choose Create Makefile... from the Makefile menu. The Builder displays the Create Makefile dialog box, shown in Figure Figure 4-5. The only fields that you must complete are:

• Makefile Name: The name assigned to the makefile. This is the makefile that is loaded during the configuration phase (see Section Section 4.4).

• Target: The name of the target that the Builder creates by building the makefile.

• Directory: The pathname of the directory in which you want the Builder to create the makefile.

This dialog box has a toggle button that appears only if you brought the dialog box up from the Builder. You can choose to use this newly created makefile as your project makefile.

If you brought the dialog box up from within the Project Manager, the newly created makefile becomes the project makefile by default.

Figure 4-5:  Create Makefile Dialog Box

See the online Help for more information about these and the other fields in the Create Makefile dialog box.

4.10    Tailoring Makefiles

The Create Makefile... option offers substantial support for generating a simple makefile, but it assumes certain default states that may be undesirable. The following solutions allow you to personalize your makefile to override these states.

4.10.1    Dependencies on System Include Files

Dependencies on system include files (/usr/include/*.h) rarely undergo modification. For this reason, when the Builder processes the depend target of a makefile generated with the Create Makefile... option it automatically excludes these dependencies from the makefile and does not display them in the makefile graph.If you prefer to have dependencies on system include files in the makefile and shown in the graph, remove the following lines from the depend target in the makefile:

@grep -v "\.o[   ]*/usr/include" makedep > makedep1
@mv makedep1 makedep

4.10.2    Dependencies on RCS and SCCS in gnumake

By default, if the gnumake utility is unable to locate specified sources in the working directory, it automatically checks them out of the RCS or SCCS libraries without displaying a message to inform the user that it has done so. This situation may be undesirable for a number of reasons.

To disable the automatic checkout option, enter the following lines in your makefile:

%:: RCS/%,v%:: SCCS/s.%%:: %,v%:: s.%

The effects of this modification are:

• gnumake no longer extracts files from the source management library.

• The Builder does not display dependencies on RCS or SCCS files (unless you enter a rule in the makefile that requests it to do so).

4.10.3    Demangling Output from the Linker when Using C++

The C++ language allows you to overload function names. To make these names unique for the linker (ld), the compiler encodes them using a process called mangling. Error output by the linker may include these mangled names. For example, in the following error output from ld, the function init(void) has been mangled into init__Xv:

ld:
Error: Undefined:
init_Xv

To decode these names, you can pipe the error output from the linker through the demangle utility. If you are using the Bourne shell (/bin/sh), the default used by make and gnumake, pipe ld errors through demangle as follows:

$(LD) -o $@ $(LDFLAGS) $(OBJS) $(LIBRARIES) 2>1 | demangle

If you are using the C shell (/bin/csh), pipe ld errors through demangle as follows:

$(LD) -o $@ $(LDFLAGS) $(OBJS) $(LIBRARIES) | demangle

4.11    Tracking and Correcting Build Errors

All error and warning messages resulting from a build are displayed in the transcript area. The following is an example of some output that could be displayed in the transcript area:

ccom: Warning: count1.c, line 95: illegal combination of
pointer and integer      
      s = i;   
   -------^
ccom: Error: count1.c, line 97: a undefined      
      a = 5;    
   ----^
*** Error code 1

The subsequent interaction between the Builder and the FUSE Editor following completion of a build is consistent with the behavior described in the following scenarios:

• The editor is already reading a buffer.

  The editor leaves the current buffer unchanged. It annotates any files responsible for compilation errors by placing a colored icon in the annotation area next to the line in question.

  To open an annotated file, choose the Open... option in the File menu of the FUSE Editor. Alternatively, you can double click on an error/warning message in the Builder transcript area; the editor loads the source code of the file associated with the error message into a buffer, and displays a colored icon in the annotation area next to the selected message.

• The editor is not running.

  To start a new instance of the FUSE Editor, double click on an error/warning message in the Builder transcript area. The editor loads the source code of the file associated with the error message into a buffer, and displays a colored icon in the annotation area next to the selected message.

• The editor is running, but no specific buffer is open.

  The editor loads and displays a new buffer containing the source code of the first file that generated an error or warning message. It annotates the buffer by placing a colored icon in the annotation area next to the line responsible for each compilation error.

The Builder does not detect linker errors, such as unresolved function references that arise when multiple object files are linked to form a single executable file. Check to make sure that objects and libraries are specified correctly in the makefile.

4.11.1    Navigating and Filtering Porting Assistant Diagnostic Messages

If you perform a build from within the Porting Assistant, the Porting Assistant automatically starts the Builder and displays diagnostic messages in the Builder's transcript area. Use the First, Next, Previous, and Last buttons in the Builder main window to move the transcript window's focus to the appropriate message and display the code associated with the message in the default editor. Choose Filter... on the Builder's Buffer menu to filter out specific diagnostic messages.See Chapter Chapter 17 for additional information about navigating and filtering Porting Assistant diagnostic messages.