Contents | Previous | Next

# Building Programs

Source-Navigator allows you to build executable programs from the files in your project. Using Source-Navigator, you can compile your code, navigate to any errors, link your code, and, with the Insight debugger, set up a debugging session to debug your code.

### Note

The compiler, `make`, and the Insight debugger must be installed on your machine before using these features.

At the end of this chapter, there is a build tutorial for a command line-driven real estate trading game.

## The Building Process

The building process compiles and links source files, such as libraries and executable files, to produce an output binary file.

Build Process

There are four steps to building your program:

- editing your code,

- compiling your source into an intermediate format, called object files,

- linking your object files together to produce an executable application, and

- debugging your executable to find any problems.

The minimum requirements for building source code include specifying which source files should be included, the directory in which the build should be stored, linking rules, debugging, and optimization flags, and included paths.

You can edit your code using Source-Navigator. This chapter explains compiling and linking. For information about external stand alone debuggers, see either Debugger or your debugger's documentation.

## make

Source-Navigator uses a utility called `make`. `make` combines a set of rules for compiling and linking code with a tracking mechanism for determining which files must be compiled.

Source-Navigator generates a `makefile`, which `make` uses to determine which commands need to be executed in order to build your program.

## Build Targets

A build target is a conceptual object that contains information needed to compile and link a project. For example, `hello.c` is converted into `hello.o` before `hello` is built. To produce the `hello` executable, the `hello.o` object file is linked with any required libraries.

The first time you select Build Settings, the Build Targets list is empty. After you create a build target, its name appears in the list.

### Creating a New Build Target

From the Tools menu, select Build Settings to start the Build Settings dialog.

Build Settings Dialog

Enter the name of the build target in the text entry box and click the Create button. The Edit Target dialog opens.

See Editing a Target.

### Modifying Build Targets

Rename a build target by selecting the target, entering a new name, and clicking the Rename button.

### Note

Do not highlight the target name in the text box or a new target is created.

To edit an existing build target, select the target and click the Edit button.

Duplicating a build target is useful when a new target is only slightly different from an existing target. To duplicate an existing build target, select the target in the Build Targets list and click the Duplicate button.

Delete a build target by selecting it in the Build Targets list and click the Delete button. The target is removed from the listing.

### Editing a Target

In the Build Targets list, either select the target name and click the Edit button or double-click the target name. The Edit Target dialog opens.

Edit Target Dialog

#### Edit Target tabs

The Build Directory, Target Type, and Tool Chain combo-boxes are common to the tabs accessed in the Edit Target dialog.

These store information about the build target.

##### Build Directory

This is the directory where all files generated in the build process are initially stored. By default this is blank. If this is left blank, then the project directory is used. To specify the directory, either type the directory path or click the "..." button. If you click the "..." button, the Open dialog opens:

Select the directory in which to store the intermediate files. Click OK to close the dialog. The directory appears in the Build Directory field.

##### Target Type

Use this combo-box to select the type of build target to create. The options are Executable and Library.

##### Tool Chain

A tool chain is a set of compilers, debuggers, and linkers. The currently available option is GNUPro (native).

#### Source Files tab

The Source Files tab controls which source files are included in your build target. The Project Files and Target Files sections contain tree information for the selected build target.

Source Files Tab

##### Adding files

To add files to the Target Files list:

1. Select the files from the Project Files list.

2. Click the Add Files button.

   The files are copied into the Target Files list.

##### Removing files

To remove files from the Target Files section, select the files to remove and click the Clear button. To remove all of the files from the Target Files section, click the Clear All button.

##### Importing files and directories

To import files or directories into your currently active project:

1. Under Import, click either the Files or Directory button.

2. Click the files or directories you wish to add to the project. Click OK when done. The names of the added files or directory appear in the Project Files list.

#### Library Files tab

Most libraries required for building targets are linked in automatically by the compiler/linker. If you know that your target requires additional libraries, use the Library Files tab to add them to your build.

Library Files Tab

Add additional libraries by clicking the Add button. The Open dialog opens to the last directory you have looked at in this project. After you select a library and click the Open button, it appears in the library list.

To remove a library from the listing, select the library and click the Remove button. The library is removed from the build.

Libraries are linked in the order listed in the dialog. To change the order of libraries, select the library and click either the Move Up or Move Down button to change its linking order.

#### Build Rules tab

Click the Build Rules tab to configure each rule in the build target.

A rule contains information required to compile files in a project. For example, a rule to compile a C file might contain information about which compiler and flags to use, as well as what the file is called after it's compiled.

This tab lists the rules for the specified build target. Within the Build Rules tab, you can:

- disable and enable rules for the target.

- edit existing rules.

Build Rules Tab

##### Status

This column shows the currently enabled and disabled rules. To disable a rule, highlight the rule and click the Disable button. To enable a rule, highlight the rule and click the Enable button.

### Note

This button changes between Disable and Enable depending upon the state of the rule.

##### File Type

This column displays the type of file the rule acts upon.

##### Description

This column displays a description of the rule.

#### Editing a rule

To edit a rule, select the rule from the rule listing. Click the Edit Rule button. The Build Rule Settings dialog opens. The dialog title bar displays the extension for the files involved.

##### Settings tab

The Settings tab allows you to change the default settings for the rule.

Build Rule Settings with Options Selected

Debug:

This controls the debug information generated by the compiler.

Warnings:

Controls the level of warnings the compiler generates. A stricter warning ensures fewer problems with future compatibility. Set "Warnings as Errors" to make sure the compile stops any time a warning is generated.

User flags:

Enter flags not covered by the options listed in this screen. To add macros, see Defines tab.

Optimization:

Compiler optimization for the code.

Code Generation:

Processor or code control specific optimizations of settings.

Executable:

Selects the executable to use. To change the tool (such as compiler) location, either enter the location path or click the "..." button to choose the tool binary to use.

##### Includes tab

Sometimes files include other files. In C this is done with the `#include` statement. The Includes tab allows you to change the included paths for the rule.

Includes Tab

The Auto-Generated Include Paths list displays paths generated from the Source-Navigator database.

Click the Generate button to generate a list of Source-Navigator included paths. These appear in the Auto-Generated Include Paths list.

To add additional paths, click the Add button. The selected paths appear in the User Specified Include Paths list. You can delete paths by highlighting the path and clicking the Delete button.

##### Defines tab

The Defines tab enables you to view, edit, and create new macro definitions.

Defines Tab

#### Modifying macro definitions

To create a new macro, enter the name and definition in the text entry box and click the New button.

To change the current macro definition, select the macro from the Macro defines list. The macro appears in the text entry box.

Macro Created and Selected

Make the necessary modifications to the macro.

To create a new macro, click the New button. The new macro appears in the listing.

To update the macro, click the Change button. The modified macro appears in the listing.

To delete a macro, select it from the Macro defines list and click the Delete button. The macro is removed from the listing.

#### Link Rules tab

The Link Rules tab allows you to specify the program to execute and the name of the final output file.

Link Rules Tab of the Build Targets Menu

Output File:

The name of the final output file.

Linker:

Auto-detects the type of project. Click the "..." button to select another linker.

Entry Point:

This is the first function executed for the application. Default is `main()`. In Java, you must specify the name of the class that defines `main()`.

Link flags:

Displays the full link command line and allows you to add flags, but you cannot edit existing links or flags.

Debug/Execute Settings:

Controls the mode for the rule. Execute allows running the program from the Build window. Debug allows starting the Insight debugger from the Build window. See Debugging the build target for more information on debugging your program.

Command to launch Application:

This field lists the name of the binary to execute or debug. The default name is the file listed in Output File. If you changed the default output file, you also need to change the name here.

On UNIX, enter `xterm -e` before the executable name if you are debugging a console application.

Click the OK button to close the Edit Target dialog. Click the Done button to close the Build Settings dialog.

## Compiling Build Targets

After you have created and configured a build target, you must build it.

Source-Navigator can generate its own `makefiles` or work with one that you supply.

#### Internal build systems

To build your project using the Source-Navigator build system:

1. From the Tools menu in the Symbol Browser, select Build.

2. The Build window opens.

3. Select the build target from the Build Target list.

4. Click the Start button to perform the build. If you need to stop the build process for any reason, click the Stop button.

5. When Source-Navigator starts the `make` command, output from the `make` process is displayed. To step through the results, click the left or right black arrow keys in the toolbar.

6. If errors appear, the build target needs to be modified. See Modifying the Build.

   If no errors appear, the build target is compiled and ready to be executed. Click the Run button to execute the application.

#### External build systems

To build using your own `makefile`:

1. From the Tools menu in the Symbol Browser, select Build.

2. Ensure that Build Targets is set to `<External Makefile>`.

3. In the Directory field, select the directory containing the external makefile.

   If you require additional flags or a different `make` program, from the File menu, select Project Preferences and select the Others tab. Enter the additional flags or `make` program into the Build field (see Others Tab of the Preferences Dialog).

4. Click the Start button to perform the build. If you need to stop the build process for any reason, click the Stop button.

5. When Source-Navigator starts the `make` command, output from the `make` process is displayed. To step through the results, click the left or right black arrow keys in the toolbar.

6. If errors appear, the source code needs to be modified.

   If no errors appear, the build target is compiled and ready to be executed. Click the Run button to execute the application.

### Modifying the Build

If errors appear in the Build window, the source code must be modified before the build is downloaded to the target board.

Double-clicking a line with a compiler error message activates the Editor with the cursor positioned on the line of code where the error appears. Right-clicking in the output window allows you to save the build output to a file.

From the Windows menu, select Add View -> Build to add a Build window to an Editor window.

Editor-Build Window

To save and recompile the modified files, press the Start button. The Fast Save dialog box appears asking if you want to perform a fast save. Click the Yes button to save the changes and rebuild. Click the No button to discard changes and perform a rebuild. Clicking the Cancel button closes the dialog without rebuilding the program.

When the build is completed, Source-Navigator saves the executable using the name specified in the Link Rules tab. If a name is not specified, the file name will be the target name. The compiled file is saved in the build directory.

#### Build types

The Tools menu in the Build window lists the types of builds you can perform. Before selecting an option from this menu, ensure that a build target has been selected.

Tools Menu

Build

Rebuilds only the modified files. This is the same as clicking the Start button in the Build Targets window.

Force Build

Rebuilds the modified files in the project and ignores errors,

Clean Build

Removes the object files and executables.

Export Makefile

Saves your build target as a `makefile` for external use.

#### Debugging the build target

If you selected Debug from the Link Rules tab in the Edit Target dialog, you will use Insight or another debugger to debug your code.

1. From the Build window, click the Debug button.

   The Program to Debug dialog appears.

   Program to Debug Dialog Box

2. In the Program field, enter or select the application to debug.

   In the Working Directory field, enter or select the path of the project directory.

   On UNIX, in the Xterm field, enter `xterm` to have a separate debugger output console window appear. If this field is left blank, the Source-Navigator output console, specified in the Others preference tab (see Others tab), is used.

3. Click OK to debug the build target.

   The debugger launches.

   For more information on the debugger, see Debugger or your debugger's documentation.

4. Return to Source-Navigator to fix any errors and repeat the build-download-debug cycle.

##### Changing the build target from Debug to Execute

After debugging and fixing your build target, you must change the build target from debug to execute in order to run the application.

1. From the Symbol Browser window, select Tools -> Build Settings.

2. Double-click the build target to modify from the Build Targets list box.

3. Click the Link Rules tab.

4. In the Debug/Execute Settings, select Execute.

5. Click the OK button to close the Edit Target dialog.

6. Click the Done button to close the Build Settings dialog.

7. Recompile and execute your build target (see Compiling Build Targets).

#### Executing the application

Once the application compiles without errors, from the Build window, click the Run button to execute the application.

## Build Tutorial

This build tutorial is based on the `monop` demo, located in the `demos` directory. `monop` is a command line based game that you can build, edit, and play. In this tutorial, you will create two build targets and use many build and debugging features of Source-Navigator.

### Note

The monop demo is written in C. A Java demo is located in the `.../share/demos/java` folder. A C++ demo is located in the `.../share/demos/c++` folder. To learn more about these demos, read the Readme file located in each folder.

### Creating the Project

1. In the Symbol Browser, from the File menu, select New Project.

2. Create a new project called `monop.proj`.

3. Under Add Directory, click the "..." button to select the `demos/monop` folder.

4. Click OK to create the project

### Creating the monop Target

1. From the Tools menu, select Build Settings. The Build Settings dialog opens.

2. Enter `monop` as the name of the build target.

3. Click the Create button. The Edit Target dialog opens.

4. In the Build Directory field, click the "..." button and select the build directory for the `monop` project.

5. From Project Files, select the `cards.c`, `execute.c`, `getinp.c`, `houses.c`, `jail.c`, `misc.c`, `monop.c`, `morg.c`, `print.c`, `prop.c`, `rent.c`, `roll.c`, `spec.c`, and `trade.c` files.

6. Click the Add Files button to copy the files to the Target Files list.

### Note

To execute the program correctly in UNIX, click the Link Rules tab. Enter `xterm -e ./monop` in the Command to launch Application field. Click OK to close the Link Rules dialog.

7. Click OK to close the Edit Target dialog.

8. Click the Done button to close the Build Settings dialog.

The build target is created. Now you need to compile the program.

#### Debugging the monop build target

1. From the Tools menu, select Build. The Build dialog opens.

2. From the Build Targets field, select `monop`.

3. Click the Start button.

   Source-Navigator generates some errors from the build. The `lint` macro must be defined.

#### Creating the lint macro

1. From the Tools menu, select Build Settings. The Build Settings dialog appears.

2. Double-click the `monop` build target. The Edit Target dialog opens.

3. Click the Build Rules tab.

4. Because `monop` is written in C, double-click the C rule. The Build Rule Settings dialog opens.

5. Click the Defines tab. Enter `lint` in the text entry box.

6. Click the New button to create the macro.

7. Click OK to close the Build Rules Settings dialog.

8. Click OK to close the Edit Target dialog.

9. Click the Done button to close the Build Settings dialog.

#### Rebuilding the monop build target

1. From the Tools menu, select Build.

2. From the Build Targets field, select `monop`.

3. Click the Start button.

   Source-Navigator generates without errors. However, at runtime the program will not execute because the path to the cards must be defined.

#### Creating the _PATH_CARDS macro

1. From the Tools menu, select Build Settings.

2. Double-click the `monop` build target. The Edit Target dialog opens.

3. Click the Build Rules tab.

4. Double-click the C rule. The Build Rule Settings dialog opens.

5. Click the Defines tab.

6. Enter the following information in the text entry box, replacing `<project directory>` with the path to the `demos/monop` directory:

   `_PATH_CARDS="\"` `<project directory>` `/cards.pck\""`

   This tells Source-Navigator which card pack to use when running the `monop` program.

7. Click the New button to create the macro.

8. Click OK to close the Build Rules Settings dialog.

9. Click OK to close the Edit Target dialog.

10. Click the Done button to close the Build Settings dialog.

#### Performing a clean build

To ensure that the new macro is picked up at compile time, perform a clean build on the `monop` target.

1. In the Build window, from the Tools menu, select Clean Build.

   A clean build is equivalent to the command `make clean`.

2. Click the Start button to perform the build.

   Again `monop` compiles without errors, but now it links to the correct card pack.

Now you need to create another target to initialize the cards used in the `monop` game.

### Creating the initdeck Target

1. From the Tools menu, select Build Settings. The Build Settings dialog opens.

2. Enter `initdeck` as the name of the build target.

3. Click the Create button. The Edit Target dialog opens.

4. In the Build Directory field, click the "..." button and select the build directory for the `monop` project.

5. From Project Files, select the `initdeck.c` file.

6. Click the Add Files button to copy the files to the Target Files list.

### Note

To execute the program correctly in UNIX, click the Link Rules tab. Enter `xterm -e ./monop` in the Command to launch Application field. Click OK to close the Link Rules dialog.

7. Click OK to close the Edit Target dialog.

8. Click the Done button to close the Build Settings dialog.

The build target is created. Now you need to compile the program.

#### Debugging the initdeck build target

1. From the Tools menu, select Build. The Build dialog opens.

2. From the Build Targets field, select `initdeck`.

3. Click the Start button.

   Source-Navigator generates some errors from the build. The `lint` and `_PATH_CARDS` macros must be defined.

#### Creating the lint and _PATH_CARDS macros

1. From the Tools menu, select Build Settings. The Build Settings dialog appears.

2. Double-click the `initdeck` build target. The Edit Target dialog opens.

3. Click the Build Rules tab.

4. Because `initdeck` is written in C, double-click the C rule. The Build Rule Settings dialog opens.

5. Click the Defines tab. Enter `lint` in the text entry box.

6. Click the New button to create the macro.

7. Enter the following information in the text entry box, replacing `<project directory>` with the path to the `demos/monop` directory:

   `_PATH_CARDS="\"` `<project directory>` `/cards.pck\""`

   This tells Source-Navigator which card pack to use when running the `monop` program.

8. Click the New button to create the macro.

9. Click OK to close the Build Rules Settings dialog. Click OK to close the Edit Target dialog. Click the Done button to close the Build Settings dialog.

10. Open a console window and copy the `card.inp` files, located in the `demos/monop` directory, into the build directory.

#### Performing a clean build

To ensure that the macros are picked up at compile time, perform a clean build on the `initdeck` target.

1. In the Build window, from the Tools menu, select Clean Build.

2. Click the Start button to perform the build.

   This time `initdeck` compiles and links without errors. `initdeck` is the name of the working executable.

3. Click the Run button to run `initdeck`, which creates the cards used in the game.

   A console window opens to build the cards and closes after the build is complete.

4. From the Build Targets field, select `monop`.

5. Click the Run button.

   A console window opens and `monop` runs automatically. Enter the number of players and their names. Press the `?` key to list the playing options.

Contents | Previous | Next