3. Working with Projects



This chapter introduces the CodeWarrior project manager and shows how to set up, configure and work with projects.


Projects Overview

A project is a collection of files that the compiler and linker use to create an executable piece of computer code. Some examples of executable code include an application, library, or shared library.

Project files also contain options that affect the project you're working with. There are a wide variety of options that control many aspects of the IDE, such as code optimization, the browser, compiler warnings, and much more.

This chapter discusses many of the basic tasks involving projects, such as creating, opening, adding files to projects, and saving projects. It also describes operations such as moving files in the project window, marking files for debugging, and dividing the project window into segments or groups of files.

The topics in this chapter are:


Creating a Project

This section discusses how to create a new project in CodeWarrior.

These are the types of projects you can create in CodeWarrior by choosing New Project from the File menu.


Empty Project

Choose New Project from the File menu. When presented with the project stationery dialog, click Empty Project and click Create to continue.

You are next asked to name and save the project. After doing so, you will have an empty project with no source files in it.

The option Empty Project is useful if you are making a project from scratch that does not require the standard libraries included in a C, C++, or Java project.


C or C++ Project

Choose New Project from the File menu. When presented with the project stationery dialog, click the twist down triangle next to
C-C++, and choose one of the prebuilt stationery projects.

After highlighting the type of project you want to start from, click Create to continue.

You are next asked to name and save the project. After doing so, you will have a basic project containing a placeholder HelloWorld source file, and libraries necessary for compiling for the target platform you chose.


Java Project

Choose New Project from the File menu. When presented with the project stationery dialog, click the twist down triangle next to
Java, and choose the prebuilt stationery for an applet or an application.

After highlighting the type of project you want to start from, click Create to continue.

You are next asked to name and save the project. After doing so, you will have a basic project containing a placeholder HelloWorld source file, and libraries necessary for compiling for the target platform you chose.


Custom Project

Before creating a new project, you can configure the project so that they will be saved for use when you create future projects.

Briefly, the procedure for doing this is to launch the BeIDE, then choose the Settings command under the Window Menu. You see a dialog as shown in Figure 7.1. To learn how to change these settings, refer to "Configuring IDE Options Overview." You can also set project settings in the same way. See "Project Settings Panels."

After changing your settings, you can create a new project, using the New Project command under the File Menu. You can choose one of the stationery choices listed above (C or C++ Project, Java Project) to start your project, or you can start with an Empty Project.

Now that you have configured your options and opened a new project window, you can save your project. To save your project, choose the Save A Copy As command from the File Menu in the Project window.

Now we want to add this custom project to the Stationery list. Let's assume we're making a new C++ stationery project.

Navigate to the Stationery folder (in the Metrowerks folder), and go in the C_C++ folder. Now you can make a new folder for your custom project. The name you give this folder will appear in the stationery dialog box the next time you choose New Project from the File menu.

If at any time you decide that you want to use different project settings, you just create a new stationery project. First configure your options, then open a new project, and finally save your new stationery project to the appropriate folder in the stationery folder.


TIP:

We suggest naming your project with the suffix ".proj".This makes your project easier to identify on your hard disk and obeys the conventional naming that CodeWarrior expects from a project file. In the event the file type is lost on a project file (using gzip for example), CodeWarrior can still identify the file as a project file and open it correctly.

Opening an Existing Project

There are two ways you can open a project file from within CodeWarrior. This section tells you how to open your projects so you can work on them.

The topics in this section are:


Using the Open Command

Information on how to open a project file is discussed in "Opening Files with the File Menu".


Using the Recent Projects List

You can have only one project open at a time in CodeWarrior. Opening or creating an additional project closes the first one, saving all of the closed project's information and settings.

The last few projects you have opened and closed are available from the Recent Projects submenu in the Window Menu (Figure 3.1). To switch back to a previously opened project, just choose a project from this list.

Figure 3.1 The recent projects list



Choosing an item from this submenu closes the open project and opens the newly selected project.

To reopen a previously opened project, just choose a different project from the Recent Projects.

CodeWarrior adds projects to this list when you close them. When you quit the CodeWarrior session altogether, the Recent Projects is cleared, and CodeWarrior automatically saves state information and settings.


Saving a Project

CodeWarrior automatically updates and saves your project when you do certain actions. This section discusses these actions that cause the project file to get saved.

The topics in this section discuss how to:

You never have to manually save your project unless you want to create a copy of it. See "Backing Up Files" for a description of how to create a backup copy of a project.


Items Saved with Your Project

When CodeWarrior automatically saves your project, it saves the following information:


NOTE:

CodeWarrior stores your source file's object code in the (Objects) folder located in the same folder as your project.

Saving a Copy of Your Project

CodeWarrior lets you save a copy of the project. To read about using this feature, see the discussion in "Backing Up Files"


Closing a Project

After you have been working with your project for awhile, you may want to close it to work on another project, or to quit the CodeWarrior application to work on something else. To read about how to close your project, see "Closing All Files"


Guided Tour of the Project Window

The project window displays the project you are working on, shows the project's files and segmentation for each file. It also shows the object code and data sizes. See Figure 3.2 for a good look at the project window.

For more on debugging information, see "Controlling Debugging in a Project."


Navigating the Project Window

To navigate the project window, use the scroll bars on the right side of the window, or the Up and Down Arrow keys on your keyboard. If your Project window contains many files, use the Home and End keys to jump from the first file in the first group (Home Key) to the last file in the last group (End Key).

Use the Page Up and Page Down keys to scroll your project window one page up or one page down.


Project Window User Interface Items

This section will take you on a tour of the various user interface items that you can use to alter your project view or project settings. The project window contains many pop-up menus and columns that indicate segmentation/grouping, access path, and header information. This section briefly describes these pop-up menus and columns.

The topics in this section are:

Figure 3.2 The Project window





Group Organization

Each CodeWarrior project is visually divided into different groups of files. Files are moved between groups, groups can be collapsed and other groups expanded using the disclosure triangle, and entire groups can be moved around in the window. Figure 3.2 shows an example of file groups in the project window.

While this file grouping capability is useful from an organizational standpoint, it also has significance for some particular targets you may be building. For example, some targets need the group facility to produce segments at link time required by the target architecture. For more discussion about groups see "Managing Files in a Project."


File Column

The File Column of the project window, shown in Figure 3.2, shows which files are in your project and the names of the groups or groups which contain those files. Files can be added, moved around, opened, or removed.

Double-clicking on a file name in the File Column opens the file in an editor window. The exception to this is binary files (such as library files) which cannot be opened into an editor window. For information on opening files from the File Column, see "Opening Files from the Project Window."

For information on adding, moving, or removing files, see "Managing Files in a Project."


Code Column

The Code Column of the project window, shown in Figure 3.2, shows the size, in bytes or kilobytes, of the compiled executable object code for a corresponding file. If zero is displayed, it means that your file has not yet been compiled.

The Code values do not necessarily reflect the amount of object code that will be added to the final binary file. The linker may not use all a project file's object code. Instead, the linker only uses the parts that are referenced by other files in the project.

For more information on how the linker works, see "Compiling and Linking a Project."


Data Column

The Data Column of the project window, shown in Figure 3.2, shows the size, in bytes or kilobytes, of the non-executable data area for a corresponding file. If zero is displayed, it means that your file has not yet been compiled, or that the file does not contain a data section in its source code.

The Data values do not necessarily reflect the amount of data that will be added to the final binary file. The linker does not use all a project file's data. Instead, the linker only uses the parts that are referenced by other files in the project.

For more information on how the linker works, see "Compiling and Linking a Project."


Interface File Pop-up

The Interface File Pop-up in the project window, shown in Figure 4.4, allows you to see and open interfaces and header files for your project source files.

For more information about opening interfaces and header files, see "Interface Files Pop-up Menu."



Group File Pop-up

The Group File Pop-up of the project window, shown in Figure 3.2, allows you to easily see which files are in a group without fully expanding the group. You can also open a file from this pop-up. This pop-up distinguishes itself from an Interface File Pop-up since it is in the same row as the name of a Group.

For more information about opening files this way, see "Opening Files from the Project Window."


Managing Files in a Project

Groups of files in a CodeWarrior project are a convenient way to organize files sharing a common purpose. For example, all files that involve playing sound could be put in one group named "Sound" in your project.

This section discusses aspects of adding, moving, naming, organizing, viewing, marking for compilation, and removing files from your project. The topics are:


About Groups and Segments

Groups allow you to organize your source code files into logical categories to help you keep track of where you put your files. On some targets, groups serve the additional purpose of keeping code in segments that the linker will create.


Selecting Files and Groups

From the project window you can select one or several files and groups to open, compile, check syntax, remove from the project, or move to a different group.

When a group is selected, all of the files within the group are selected, regardless of whether or not one of its source code files are included in the selection. For example, the project in Figure 3.3 has one group title selected. If you executed the Check Syntax command, the operation is performed on all of the files in that group.

Figure 3.3 Selecting groups in a project window





Selection by mouse-clicking

To select a single file or group in the project window, click its name.

To select a consecutive list of files or groups, select the first file or group in the list by clicking its filename, then Shift-click the last file or group to be selected. All files and group names between the select click and the Shift-click are selected.

To select a non-consecutive group of files or groups, Alt-click each filename or group.


Selection by keyboard

Type the first few characters of the file name you want to select and CodeWarrior selects the file as soon as the characters identify the file closest to your entry.

Use the Backspace key if you make a typo.

Press Enter to open the file.


Expanding and Collapsing Groups

Groups display files in collapsible lists. Each group is identified by a group disclosure triangle.

To expand a group and view its files, click on the disclosure triangle to the left of the desired group. To close a group and view only its name, click the disclosure triangle again (Figure 3.4).

Use Alt-Right Arrow to expand a group.

Use Alt-Left Arrow to collapse a group.

Figure 3.4 Expanding and collapsing groups




Adding Files

This section tells how to add files to your CodeWarrior project.

When adding a file to a project, Access Paths to the file or files automatically get set in the project. The Message Window informs you whenever a new access path is added.

For more information about Access Paths see "Access Paths."

For more information about the Message Window, see "Guided Tour of the Message Window."

Here are the topics you will learn about in this section:


Where Files Appear

Files are always added after the currently selected item in the project window, or at the bottom of the project window if there is nothing selected. To put a new file or files in a particular location, always select the item above that location before performing the Add Files or 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.Add to Project command.

If a group is selected, regardless of whether or not the group is expanded or collapsed, the files that are added are placed at the start of the selected group. To learn about how to select a file or group of files, see "Selecting Files and Groups."

Of course, you can always move a file or group of files to a new location after adding to the project. To see how to move files and groups around in the project window, see "Moving Files and Groups."


Using the Add Files Command

The Add Files command on the Project Menu opens a dialog box you can use to add files to your project from many locations. Use this command to add source code files, libraries, or a shared library.

This command opens a dialog box that can be used to add files to your project from many locations (Figure 3.5). Only text files will be displayed in the dialog file list. To examine and configure possible extensions for file names, refer to "Setting a File Extension."

Figure 3.5 Adding multiple files to a project



Select the file you want to add, then click the Add button. Repeat this action for all the files you want to add. When finished, click the Done button to close the dialog.

To add several files from the same directory in the Add Files dialog, select a file using the mouse, then Shift-click on additional files to choose them, or just click and drag the mouse to choose multiple files. When all the files you want are selected press the Add button.


Using Drag and Drop

When you drag and drop files or folders onto the CodeWarrior Project window, they will be added to the project.

To add files to your project using this method, first select the files or folders you want to add to the project. If you don't know how to select files, see "Selecting Files and Groups."

To complete the add operation, drag your selection onto the project window.

When dragging the selected files onto the project window, CodeWarrior verifies that the files can be added to the project. When dragging a folder, CodeWarrior always highlights the folder. It willperform a check to make sure that the folder, or one of its subfolders, contains at least one source code file or library before adding the folder to the project.

If the project window is highlighted, releasing the mouse adds the selected files and the contents of the selected folders to the project, appending them to the group which the cursor is in. To add files to a new group, release the mouse when the cursor is over the blank space after the last group.

The new files will be added after the selected item in the project window, so activate that window and select the item before dragging for best results.

CodeWarrior does not allow the dragging of entire volumes (such as your hard disk) onto the project window because adding files from an entire hard disk would probably take too long.

Although CodeWarrior supports dragging and dropping files into the project window, you cannot drag files out of the project window. To remove files from the project window, see "Removing Files and Groups."


Using the Add to Project Command

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.Add to Project command adds the file associated with the active window to the project. You typically do this when you've opened a new file for editing, then decided that you would like to add it to the currently-open project window.

To use 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.Add to Project command, select a location in the project window. Then, open a file and select 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.Add to Project command from the editing window's Project Menu.


NOTE:

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.Add to Project command is enabled when the active window is a text file, the file is not yet in the project, it has already been saved, and it has a permissible filename extension (see "Target"). 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.Add to Project command is dimmed otherwise.

Moving Files and Groups

To move one or more files or groups, select the files or groups to be moved. Selecting a group selects all of its files regardless of whether or not its files are visually selected in the project window. If you need help selecting files and groups, see "Selecting Files and Groups."

Next, drag the selected files or groups to their new location in the project.

A focus bar (an underline) indicates where the selected files will be moved when the mouse is released.

Whether you are moving files or groups depends on your selection. For example, if your selection consists of files then the focus bar is shown on each line, under both groups and files.

If your selection includes at least one group, then the underline is shown only under other groups as you move the mouse in the project window. This enables you to rearrange groups.

Finally, release the mouse button when the underline is positioned after the desired file or group position.

When a file is underlined and the mouse is released, the selected files are placed in the same group, following this file. When a group is underlined, the selected files are placed at the end of this group.


Creating Groups

To create a new group, select a file(s) you want to put in the new group, then choose New Group from the Project Menu. A new group is automatically created.

The new group will have a name like "New Group." For information on how to change this name, see "Renaming Groups."


Figure 3.6 The project window after creating a new group




Removing Files and Groups

To remove one or more files or groups, first select the files or groups to be removed. Note that selecting a group selects all of its files regardless of whether or not its files are visually selected in the project window.


WARNING!

This command can't be undone. If you mistakenly remove a group, you must re-add its files using either 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.Add to Project or Add Files commands under the Project Menu.

When you remove a group from your project, all of the files that are in that group are removed from the project. If there is only one group in your project, you won't be able to delete the group, since CodeWarrior requires at least one group in a project.


Renaming Groups

To rename a group, select the group to be renamed by clicking on it then press the Enter key. You may also use the arrow keys to navigate to the group, then hit the Enter key. Also, double-clicking on a group name will open the rename dialog box.

When you have done this, a dialog box appears containing a standard name dialog (Figure 3.7).

Figure 3.7 Changing a group name





Type the new name in the name box and click OK.

The name of the group is changed in the project window.

If you have selected more than one group, the same dialog opens for the next group selected, enabling you to change its name as well.


Controlling Debugging in a Project

Your program will probably not run correctly the first time you build it. In order to debug it, you need to enable debug information for your project and the files you are concerned with. This section tells you how to do this.

The topics in this section are:


Activating Debugging for a Project

To enable debugging for a project, you need to set certain options in the "Configuring IDE Options Overview". Refer to "PPC Project Panel" and "Project Settings Panels" for a discussion of how to do this. If Generate SYM File is enabled, you can select the Enable Debugger command from the Project Menu and all the necessary configuration will be done for you automatically.


Adding Preprocessor Symbols to a Project

Sometimes you may want to add your own symbol definitions to your project so that they are automatically included at the beginning of each source code file when you build your project.

An example of this using the C or C++ language would be:


  #define GLOBAL_DEBUG

Maybe you want to define this symbol when building development versions of your code, but want to undefine it before shipping your final product.

To do this, you would create a precompiled header and insert this symbol definition into the header. See "Using Precompiled or Preprocessed Headers" for more information on how to do this.

Also see the CodeWarrior C/C++/Assemb;y Language Reference manual for more information about this topic.





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