# 8.

Compiling and Linking

This chapter discusses how to control compilation, linking and running a CodeWarrior project.

## Compiling and Linking Projects Overview

The information in this chapter assumes you have already created a project, added the necessary files, grouped these files, and set the project's options. To learn more about how to do these things, refer to other chapters in this book, including `"Projects Overview,"` `"Working with Files Overview,"` `"Source Code Editor Overview,"` and `"Configuring IDE Options Overview."`

You should also be familiar with features such as moving files in the project window, the project window's columns, and pop-up windows. To learn more about how to do these things, refer to `"Projects Overview,"`

This chapter discusses how to compile and link a project to produce your code, and how to correct common compiler and linker errors using the Message window. It does not describe in detail the various types of programs CodeWarrior can create. For that information, please see the CodeWarrior Targeting manual appropriate for your platform. A table describing which guide to refer to is shown in `"Where to Go From Here."`

The topics in this chapter are:

- `Choosing a compiler`
- `Compiling and Linking a Project`
- `Using Precompiled or Preprocessed Headers`
- `Preprocessing Source Code (C/C++ only)`
- `Disassembling Source Code`
- `Guided Tour of the Message Window`
- `Using the Message Window`
- `Running Shell Scripts from the IDE`

## Choosing a compiler

When you create source code files, you are using a certain programming language such as C, C++, Pascal, or another language. These languages have naming conventions for the files. For example, in the C language, a source code file ends with a .c suffix and a header file ends with a .h suffix.

This section describes how to assign a file suffix to a compiler for a given language in the CodeWarrior IDE.

### Understanding Plugin Compilers

The CodeWarrior IDE is designed to allow compilation of many different programming languages. In order to make the product modular to accept many different languages, plugin compilers are used.

Plugins are basically small loadable code modules that allow the IDE to have many different compilers at its disposal. For example, there are plugin compilers for C, C++, Pascal, Java, and assembly language.

### Setting a File Extension

To associate a plugin compiler with a given file, you set the `Target` options. For a description of how to configure these options to set a compiler for your source code files, refer to `"Target."`

## Compiling and Linking a Project

The CodeWarrior IDE provides many different ways to build a project. When you build a project, you compile and link it.

All compiling and linking commands are available from the Project Menu. Depending on your project type, a few of these commands may be disabled or renamed. For example, you cannot Run a plug-in, but you can Make it. Also, a compiling or linking command may be dimmed because CodeWarrior is busy executing another command or the project is being debugged.

### Compiling Files

You can tell CodeWarrior to compile a single file, or compile certain files in your project. Of course, CodeWarrior can also compile all files in your project.

The Compile command on the `Project Menu` is dimmed when:

- There is no open project.
- The active Editor window does not have a source code filename extension.
- The active window's source code file is not included in your project.
- The binary file, such as the application you created from the project, is running under the CodeWarrior debugger.
- An application created from the project is running.

A status line displaying the total number of files to be compiled and the number of the file being compiled is also provided at the bottom of the project window.

#### Figure 8.1 Compiler progress

#### Compiling One File

To compile a single file in your project, select that file in your Project window and choose `Compile` from the `Project Menu`. To learn how to select several files in your project, refer to `"Selecting Files and Groups."`

Alternatively, you can open the file in the CodeWarrior Editor, make the window the active window, and choose `Compile` from the `Project Menu`.

#### Compiling Selected Files

You may select numerous files in your project for compilation, by selecting the files in the Project window and then choosing `Compile` from the `Project Menu`. To learn how to select several files in your project, refer to `"Selecting Files and Groups."`

### Updating a Project

When you have many newly added or modified files in your project, you can use the `Bring Up To Date` command on the `Project Menu` to compile all the files that need recompiling. The Project window message area displays information on the compilation process, as shown in `Figure 8.1`.

When using this command, the linker will not be invoked, so your project will not have its output binary produced. This command only runs the compiler.

### Making a Project

When you are ready to produce your binary file, such as an application, library, or shared library, you use the `Make` command on the `Project Menu`. This command builds the selected project type by updating the newly added or modified files, then linking the project, copying resource files, and executing any postlink source files.

The results of a successful build depend on the selected project type. For example, if the project type is an application, the `Make` command builds an application and saves it in the same folder as your project. Table 8.1 lists each project type and what is built when the `Make` command is executed.

#### Table 8.1 Results of successful build

Project Type | Target | Make Creates
--- | --- | ---
Application | BeOS | BeOS application
Library | BeOS | BeOS Library
Shared Library | BeOS | BeOS Shared Library

Once all the modified files have been compiled successfully, CodeWarrior links the project to produce your output binary. If the project has already been compiled using `Bring Up To Date` or another command, then the `Make` command only links the compiled source code files together.

### Enabling Debugging

When the `Enable Debugger` option is checked in the `Project Menu`, choosing the Debug command lets the CodeWarrior Debugger launch and debug your project. When you choose `Disable Debugger` from the `Project Menu`, choosing the `Run` command runs your project normally.

To learn about how to configure your project so that files in the project have debugging information generated for them, refer to `"Controlling Debugging in a Project."`

To learn more about running your project, refer to `"Running a Project."`

### Running a Project

When you choose the `Run` command from the `Project Menu`, CodeWarrior compiles and links (if necessary), and creates a stand-alone application, then launches that application.

When compiling and linking is successful, CodeWarrior saves a new application in the same folder as the open project. It is named according to options you set. If you would like to change these options, refer to `"Project Settings Panels."`

If the current project is for a library, shared library,or plugin, the Run command is not available.

### Debugging a Project

To debug your project, there are basically two steps you need to do. Of course, you must already have your project compiled and linked with debugging information generated. To learn how to enable debugging for your project, refer to `"Enabling Debugging."`

The second step is for you to start the debugger with your compiled application as the debug target. You can do this by selecting the `Debug` command from the `Project Menu`. If the `Debug` command is not in the menu, you do not have debugging enabled for your project. Refer to `"Enabling Debugging"` to learn how to remedy this.

Once you have selected the Debug command, CodeWarrior compiles and links your project, creates a debugging information file , and then opens that debug information file with the CodeWarrior Debugger.

If the `Debug` command is dimmed, make sure the proper options for debugging are configured, as detailed in `"Enabling Debugging"`. Also, make sure that Metrowerks Debugger application is on your hard disk. If `Debug` is still dimmed, you are probably attempting to run a project whose project type cannot be run, such as a shared library or library.

### NOTE:

The Debug command does not open any application that you may need to debug your project. If you're debugging aCodeWarrior Plug-in or any other project that requires an application, you must launch the application on your own before you choose Debug.

Once you are in the Metrowerks Debugger, you need to refer to the CodeWarrior Debugger Manual for information on how to use it.

### Generating a Link Map

Metrowerks C/C++ compilers let you create a link map file that contains function and class section information on the generated object code.

Metrowerks Pascal compilers let you create a make map file that contains a list of dependencies and the compilation order.

### Removing Objects

When you compile your project in CodeWarrior, a `.o` file is created. There are a few different commands available if you want your project file to consume less memory on the hard disk, or you want to remove all object code and start compilation over again.

#### Removing Object Code

In some cases, you may wish to remove all the object code from the project and restart the compiling and linking process. To remove a project's binaries, select the `Remove Objects` command from the `Project Menu`.

When `Remove Objects` is chosen, it resets the Code and Data size of each file in the project window to zero.

#### Remove Objects & Compact command

When the Option key is held down, choosing `Remove Objects` removes all binaries from the project and compacts it to consume the minimum amount of space on your hard disk.

Compacting the project removes all object code and debugging information stored in the project file and retains only the information about which files belong to the project and project-specific option settings.

## Using Precompiled or Preprocessed Headers

Source code files in a project typically use many header files (".h" or ".hpp" files). Often, the same header file is included in many files, forcing the compiler to (inefficiently) read the same header files many times during the compilation process.

To shorten the time spent compiling and recompiling a header file, use `Precompile` on the `Project Menu`. A precompiled header file takes the compiler significantly less time to process than an ordinary, uncompiled header file.

For instance, a precompiled header file that contains the most frequently used headers in your project could be made into one precompiled header file. Instead of having to compile the same thousands of lines of header files for each source file in your project, the compiler only has to load one precompiled header file.

### NOTE:

You can only include one precompiled header in a source file. Including more than one precompiled header will result in an error.

### TIP:

CodeWarrior frequently changes the precompiled header format when implementing new features in CodeWarrior updates. Therefore precompiled header formats are often incompatible between CodeWarrior updates. After installing a new CodeWarrior update, you usually need to precompile your precompiled headers to use the new format. See "Automatic updating" on page 172 for more information on updating precompiled headers.

The topics in this section are:

- `Creating Precompiled Headers`
- `Defining Symbols For C/C++`

### Creating Precompiled Headers

To precompile a header file, you must have a project open. The preferences from this project are used when precompiling. A file to be precompiled does not have to be a header file (".h" or ".hpp"), but it must meet these requirements:

- The source file must be a text file. You cannot precompile libraries or other files.
- The file does not have to be in a project, although a project must be open to precompile.
- It must not contain any statements that generate data or code. However, C++ source code can contain inline functions and constant variable declarations (`const`).
- Precompiled header files for different targets are not interchangeable. For example, to generate a precompiled header to use with BeOS compilers, you must use a BeOS compiler.
- A source file can include one precompiled header file using the `#include` directive.

#### Figure 8.2 Saving a precompiled header

#### Precompile command

To precompile a file, choose `Precompile` from the `Project Menu`. The progress of this operation is displayed in the Project window message area. If compiler errors are detected, a Message window appears.

To learn more about the Message window and correcting compiler errors, consult `"Correcting Compiler Errors and Warnings."`

#### Automatic updating

During a `Make` or `Bring Up To Date` operation, CodeWarrior automatically updates a precompiled header file if its source has been modified.

If CodeWarrior encounters a `.pch` or `.pch++` file in the project that was modified since it was last precompiled, CodeWarrior precompiles it again to ensure that the resulting precompiled header is up to date.

To create a precompiled header file that is automatically updated, open the project that will use the precompiled header. Then create a source code file that will be used as the precompiled header's source file.

To read about the requirements for a precompiled header source file, refer to `"Creating Precompiled Headers"`.

Save the source file with a .pch or .pch++ filename extension.

Now add the source file to the open project with the `The` `Project Menu` `lets you add and remove files and libraries from your project. It also lets you compile, build, and link your project. All of these commands are covered in this section.`

Whenever the `.pch` or `.pch++` file is modified, the CodeWarrior project manager will automatically update it by precompiling it.

To include the precompiled header in a project source code file, add this line as the first `#include` directive in the file:

    #include "name"

Alternatively, you may also specify the use of a precompiled header file in your project settings. To learn about how to do this, refer to `"C/C++ Language."`

### NOTE:

Do not use the `.pch` or `.pch++` source file in `#include` directives; use the name of the resulting precompiled header file. Although using the `.pch` or `.pch++` file is legal and will not affect the final binary, you won't be taking advantage of the precompiled header's speed.

### Defining Symbols For C/C++

To automatically update and add predefined symbols and other preprocessor directives, you can create a precompiled header file, add it to your project, and place its name in the appropriate C/C++ Language Panel option.

First, open your project and create a new source code file with the `New Text` command on the `File Menu`.

This new text file will contain your preprocessor directives. You'll use this file as a precompiled header file that you will add to your project.

Choose `Settings` from the `Window Menu`, and select the `C/C++ Language`.

If there is a filename in the Prefix File box, Copy it into the Clipboard, then click OK to close the dialog box.

In the new Editor window, paste the filename used in Prefix File in an `#include` directive. Make sure this is the first directive in the file.

For example, if the Prefix file is MyHeaders, then the first directive in the editor window is

#include <MyHeaders>

Type in all your own `#define`, `#include`, and other preprocessor directives.

Save this file with a `.pch` or `.pch++` filename extension.

If this is a C header, use `.pch`. If this is a C++ header, use `.pch++`. For example, save this file as "MyPrecomp.pch".

Choose `Project Menu` from the Project Menu to add this precompiled header source file to your project.

Choose `Settings` from the `Window Menu`, and select the `C/C++ Language`.

In the Prefix File field, enter your precompiled file's name, in this example "MyPrecomp". Click OK to save your changes.

Whenever your project is built, the CodeWarrior project manager updates your precompiled header and automatically includes it in each source code file.

## Preprocessing Source Code (C/C++ only)

The C/C++ preprocessor prepares source code for the C/C++ compiler. It interprets directives beginning with the "#" symbol (such as #define and #ifdef), removes extra spaces and blank lines, and removes comments (/**/ and //). You might want to preprocess a file if you want to see what the code looks like just before compilation.

For example, Figure 8.3 shows a source code file before using the `Preprocess` command on the Project Menu.

#### Figure 8.3 Source code before Preprocess

Open a file that you want to preprocess, or select a file in your currently-open Project window. To preprocess afile, select the `Preprocess` command on the Project Menu. The results of the `Preprocess` command are stored in a new file named after the source code file that was preprocessed and beginning with the "#" character (Figure 8.4).

To save the contents of the new window, choose one of the save commands in the File Menu.

#### Figure 8.4 Preprocessor output

## Disassembling Source Code

If you wanted to see the code that would be generated for your file you could disassemble the file. Disassembling is useful if you want to know the machine level calls that are being made when your source code is executed. In addition, the disassembled code can be a model for writing your own assembly routines.

There are two ways to disassemble a source code file using the CodeWarrior IDE:

- `Using the Disassemble Command`
- `Using the option Machine Code (x86 only)`

### Using the Disassemble Command

The `Disassemble` command on the Project Menu disassembles the compiled source code file selected in the project window and displays its assembly-language code in a new window. The title of the new window consists of the name of the source code file with the extension ".dump" (Figure 8.5).

#### Figure 8.5 Disassembling a selected source code file

To save the contents of the ".dump" window, choose one of the save commands in the File Menu.

If the file being disassembled has not been compiled, the disassemble command will compile the file before disassembling it.

### Using the option Machine Code (x86 only)

When the option Machine Code is enabled in the x86 CodeGen settings panel, the compiler will generate a `.asm` file each time your source file is compiled. This `.asm` file is generated at the same location as your source file.

For further information on the Machine Code option, see `"Machine Code Listing."`

## Guided Tour of the Message Window

The Message window is used to display messages about events that have occurred when compiling, linking, or searching files. There are a number of elements in the window that are useful for accomplishing certain tasks, such as navigating to error locations and scrolling to see all messages for a project.

The topics in this section include:

- `Error Check Box`
- `Warning Check Box`
- `Notes Check Box`

#### Figure 8.6 The CodeWarrior Message Window

### Error Check Box

The Error check box in the Message window, shown in Figure 8.6, toggles the view of error messages on and off. This is useful if you have changed the view of the window to something else and want to get back to viewing the error messages.

To learn more about seeing error messages in the Message window, refer to `"Seeing Errors and Warnings."`

### Warning Check Box

The Warning check box in the Message window, shown in `Figure 8.6`, toggles the view of warning messages on and off

To learn more about seeing error messages in the Message window, refer to `"Seeing Errors and Warnings."`

### Notes Check Box

The Notes check box in the Message window, shown in `Figure 8.6`, toggles the view of note messages on and off

To learn more about seeing note messages in the Message window, refer to `"Seeing Errors and Warnings."`

### Message List Pane

The Message List Pane, shown in `Figure 8.6`, allows you to view your messages.

To learn more about seeing messages in the Message window, refer to `"Seeing Errors and Warnings."`

## Using the Message Window

While compiling your project, CodeWarrior may detect a syntax error or other type of compiler error in one of your project's source code files. If this happens, the Message window displays the total number of errors and warnings, as well as information about each one.

In this section, you will learn how to interpret, navigate, and use the information that appears in the Message window. The topics in this section include:

- `Seeing Errors and Warnings`
- `Stepping Through Messages`
- `Correcting Compiler Errors and Warnings`
- `Correcting Linker Errors`
- `Saving the Message Window`
- `Locating Errors in Modified Files`

### Seeing Errors and Warnings

The Message window displays several types of messages:

Select this | To display this
--- | ---
| Errors | Either compiler or linker errors. Both types of errors prevent the compiler and linker from creating a final binary.
| Warnings | Either compiler or linker warnings. Neither type prevents CodeWarrior from creating a binary. However, they indicate potential problems during runtime. You can specify which conditions lead to warning messages or you can upgrade all warnings to errors.
| Notes | All other types of messages issued in the Message window. For example, results of a batch find are notes messages.

To close the Message window, click its close box or select Close in the File Menu while the Message window is the active window. If you close the message window and want to see it again, choose the `Message Window` command from the Window Menu to reopen it.

To see only error messages in the `Message List Pane`, click on the `Error Check Box` and turn off the `Warning Check Box`.

To see only warnings in the `Message List Pane`, click the `Warning Check Box` and turn off the `Error Check Box`.

To see both errors and warnings in the `Message List Pane`, click both buttons. Notes do not appear in the Errors & Warnings window.

You'll also see other types of messages from time to time in a Message window, such as:

- During `Project Menu` or `Add Files` when a file being added does not reside on an existing access path.
- During linking when a project contains conflicting resources.
- During a Find when the `Batch Checkbox` is selected in the Find dialog box.

### Stepping Through Messages

When the compiler finds errors during a build, or the CodeWarrior search engine finds text you asked it to look for when `Using Batch Searches`, you'll see the message window.

#### Figure 8.7 Errors and Warnings Message Window

To step through the list of messages, click on a message and use the up and down arrows to navigate the list. Hit the Enter key to open an Editing window at the chosen error. In addition, you can use Command-Option-Down Arrow and Command-Option-Up Arrow shortcuts to navigate the message list.

### Correcting Compiler Errors and Warnings

When an error occurs during compilation, the Message window will show you the error message in the `"Message List Pane"`. The location in the source code that the message refers to will allow you to navigate to the spot in your source code where the message refers to, and inspect or correct your code. You can do this easily by selecting the message in the Message List Pane and then hitting the Enter key.

For a complete list of compiler errors and their possible causes, consult CW Error Reference.

#### Figure 8.8 Source Code Error Location

#### Opening the File for the Corresponding Message

To open a source code file that corresponds to a given message, select the message in the `"Message List Pane"` and press Enter. You may also double-click the message in the `"Message List Pane"` to open the relevant file.

### Correcting Linker Errors

If the linker encounters any errors while linking your project, the Message window appears indicating these errors (Figure 8.9). This window can be scrolled through using the scroll bar or arrow keys.

To learn about how to scroll through messages in the Message window, refer to `"Using the Message Window."` To learn about changing the view of messages in the Message window, refer to `"Seeing Errors and Warnings."`

#### Figure 8.9 Linker errors message window

Since Linker errors are a result of problems in the object code, CodeWarrior cannot show their corresponding errors in the project's source code files.

Linker errors are usually the result of one of the following circumstances:

- Your project is missing the necessary libraries. Linker error messages of this type occur when the project is missing a library.
- You have misspelled the name of a library routine. This means that the routine that the Linker is searching for does not exist. Check the name of the routine to make sure it is spelled correctly.

### Saving the Message Window

To save the contents of the Message window, just follow these steps.

First, make the message window active. To accomplish this, either click on the deactivated message window, or select `"Message Window"` from the Window Menu.

Next, select the `"Open File"` command from the File Menu.

The `"Save A Copy As"` command will display the following dialog (Figure 8.10)

#### Figure 8.10 Saving the Message window

Specify the name andthe location, then click Save. A text file will be saved containing all the errors, warnings, and messages listed in the message window.

### Locating Errors in Modified Files

If an error is corrected or the source code is changed, the compiler may not be able to find other errors in the source code file. This may result in an alert telling the user that the position of the error could not be found. When this happens, recompile your project to update the list of errors in the Message window.

## Running Shell Scripts from the IDE

Shell scripts can be run from the IDE as part of the build process. Therefore, the IDE has the ability to use shell commands to work with a CodeWarrior project.

These steps explain how to run a shell script from the IDE:

1. Get a script.

Here's a sample script which will copy an application (MyApplication) and it's .`xMAP` file to the directory `/boot/Apps.` When the script is finished, it will beep.

    cp MyApplication MyApplication.xMAP /boot/Apps/

    /bin/beep

Type a shell script for your project, and save it to your hard drive as `samplescript.sh`

### NOTE:

You can name a script with whatever extension you like the best. Metrowerks uses `.sh` as a standard naming convention for shell scripts.

2. Add this script to your project.

Drag the script file to one of your groups in the project window.

3. Make sure the IDE recognizes the script.

Choose the menu item `Settings` from the `Window` menu in the project window, and click the settings panel Target from the list on the left.

We want to tell the IDE a few things what scripts look like, what tool should be used with a script, and when the IDE should execute this script.

a. Tell the IDE the extension of the file you want it to recognize.

In the Extension edit field, type the extension "`sh"`, without the quotes.

b. Tell the IDE which tool to use with this extension.

Click the Tool Name pop-up menu, and choose `sh` as the tool to use with this extension.

c. Tell the IDE when it should execute this script.

Click the Flags pop-up menu, and choose the stage for executing your script. For this example, choose Postlink Stage because we want this script to copy the files after the link has been completed.

4. Run the script.

Choose `Make` from the `Project` menu to compile your project and run the script.

Visit the Metrowerks website at: http://www.metrowerks.com
For assistance contact Metrowerks Technical Support at: support@metrowerks.com
Copyright © 1998, Metrowerks Corp. All rights reserved.
Last updated: February 15, 1998
* Chris Magnuson * John Roseborough