Using CodeWarrior Pro

This document is a tutorial which will help you with the basic use of CodeWarrior. The handout contains two very short C programs which you may type in, compile, link, run, and print. If you enter these two programs and get everything to work, you will learn the minimum necessary about CodeWarrior to do programming assignments for EECS 280.

This handout assumes that you have mastered basic use of the Macintosh computer. If you have not, please read the ITD handout Macintosh Basic Skills or consult the Apple Macintosh user manuals. The CodwWarrior IDE also runs on, and is avalable on, Intel Pentium machines running under Windows; this writeup assumes the Macintosh environment in its description. The Wintel environment should be very similar, except for the command key shortcuts which are described.

CodeWarrior

The CodeWarrior IDE should be in the load set (i.e., resident) on most campus machines, both Macintoshes and Wintels. If you find a machine which does not have the CodeWarrior IDE resident, then you can copy it down from the ITD or CAEN applications server; this is a very slow process, so it is much better to find a machine which has the IDE already on the local hard disk. Once you are through using CodeWarrior, be sure to save your current source and project files on floppy disks or in your AFS/IFS file space; for safety, you should keep two copies of your current project folder, each copy on a separate disk. After saving copies of your current project folder, you should then delete the project folder from the local hard disk; otherwise, your project solution is still there for the next person who uses the machine!

Creating a Project in CodeWarrior

To create a new project in CodeWarrior:

1. first, find the CodeWarrior IDE application in the Metrowerks CodeWarrior folders and launch the IDE by double clicking it;
   
2. select New Project from the File menu (or type shift-command-N);
   
3. in the New Project window, check the Create Folder check box if you wish the IDE to create a new project folder for you - if you already have a project folder, then uncheck this box;
   
4. in the project stationery list, click the arrow to the left of the MacOS entry - then click the arrow to the left of the C/C++ entry;
   
5. to create a project for a C program, double click on the "ANSI C Console PPC" entry - to create a project for a C++ program, double click on the "ANSI C++ Console PPC" entry;
   
6. if you checked the Create Folder check box, then in the next window you must type in the name of the project file to be created (use a name that identifies the project) and you must navigate to the folder on the disk in which you want the new project folder to be created; you should place a special suffix on the project name which you type (for example, use proj0.µ (µ is typed as option-M)) so the project file is easy to find - in this case, CodeWarrior will remove the suffix to get the name of the project folder (i.e., typing proj0.µ will create a project folder named proj0 which contains a project file named proj0.µ); if you type a project file name with no suffix, then the IDE creates a folder of the name you give and places a project file with the same name inside that folder;
   
7. if you did not check the Create Folder check box, then you get a window in which you must give a name for the project file, and then you must navigate to the project folder in which you want that project file to be stored - in this case, the project folder must already exist and it should not contain a project file already; the name of the project file should have a suffix (such as .µ) which makes it easy to find in the project folder;
   
8. you now get a project window indicating that the project is ready for you to use; if you click the arrow next to the Sources entry, you will see that there is a source file named HelloWorld.c (for a C project) or HelloWorld.cp (for a C++ project) included in the project;
   
9. to be sure that the project is properly set up, select Run from the Project menu (or press command-R) - the test program in HelloWorld.c or HelloWorld.cp will be compiled, linked, and run - you should now see output from the program that starts off as "Hello World, this is CodeWarrior!....." - choose Quit from the File menu to terminate the program run and get back to the CodeWarrior IDE.
   

Restarting an Already Existing Project

Entering your Source Program and Compiling It

1. to create a new source file select New from the File menu (or press command-N); you will next see an edit window in which you may type your source code; use Save in the File menu (or type command-S) to save the current status of your source code; you may use all of the standard Macintosh edit operations in this edit window (cut, copy, paste, etc.); when you first save the source file, you must give it a name which ends with the suffix .c (if it is C source code) or with the suffix .cp or .cpp (if it is C++ source code) - we recommend that you use the project name for this (i.e., name the source file project0.c); if you wish a printed copy of your source file, select Print from the File menu (or type command-P); when you wish to close the source file window, select Close from the File menu (or type command-W);
   
2. to add the source file to the project, select Add Window from the Project menu while the source file edit window is the frontmost active window; this adds the source file in the front most edit window to the project; you must add your source file to the project before you can compile and run your program; the Add Window command will not be available unless you have saved your source code in a file with an appropriate file name suffix;
   
3. if you need to add other files to your project (other source code files or library files), select Add Files from the File menu; now navigate through the file system in the usual way selecting whatever other files you need; note that text files can be added only if the file is a source file and the name is suffixed properly; if you need to remove a file from the project, select the file in the project window (by single clicking on the name) and then select Remove Files from the Project menu (or type option-Delete); if you have created the project correctly, you should not have to add any files to it other than the source files which you create;
   
4. to check the syntax of your source code, select Check Syntax from the Project menu (or type command-;); if there are errors in your source code, an error window will appear with the error comments; to correct an error, double click on the error comment, which takes you to the source code which caused the error, then edit the source code;
   
5. if you wish to see the preprocessed source code, select Preprocess from the Project menu - this shows in a new window your source code as it comes out of the C preprocessor; if you wish to see the assembler language version of your source code, select Disassemble from the Project menu - this lists in a new window the assembler language version of your program; you may close either window by selecting Close from the File menu (or by typing command-W);
   
6. to compile and link your entire project, select Make from the Project menu (or type command-M); this causes your source code to be compiled and any library files needed to be added to the project; if there are errors in the compilation, you will next see an error window with each of the error statements; double click on an error statement to get to the part of the source code which caused the error comment; after all of the source code errors are corrected in your source code, save the source file and re-make the project; if the make is successful, then an application file is placed in your project folder; if you wish to compile the source code in the active edit window but not link the project, then select Compile from the Project menu (or type command-K); if you select Bring Up To Date in the Project menu (or type command-U), then all files in the project are compiled, if needed, but not linked;
   
7. to run your program, select Run from the Project menu (or type command-R); if the project is not completely up to date, this command first brings the project up to date; then the resulting application file is launched and executed; when the program has finished execution, select Quit from the File menu (or type command-Q) to return to the CodeWarrior environment.

As a practice in using the CodeWarrior environment, create a new C project, then type in the following source code and add the source file to the project:

     /* 
      * Program Hello World
      * Prints "Hello World" COUNT times 
      */
     #include <stdio.h>
     #define COUNT 10
     int
     main(void)
           {
               int i;
               for (i = 0; i < COUNT; i++)
                    printf("Hello World!\n");
               return 0;
            }
     

1. if you get an error message that "main" is defined more than once, then you forgot to remove the HelloWorld.c file from your project when you added your new source file - you cannot have two source files with a main function in each;
   
2. if you get an error message that "main" is undefined or missing, then you probably forgot to add your source file to the project (or, possibly, you spelled main incorrectly!);
   
3. if you get a variety of link error messages about missing functions, then most likely you selected the wrong project type in creating the project, forgot to put the #include directive in your source code, incorrectly spelled the function name in your source code, or did not set up CodeWarrior correctly on your local hard disk;
   
4. if you get link error messages stating that CodeWarrior could not find certain libraries, then it is quite likely that your CodeWarrior environment is not properly set up on your local hard disk; CodeWarrior looks for all of its components starting in the directory in which the compiler is stored, so if you have put things in different places than CodeWarrior expects these link error messages result.
   

Using the CodeWarrior Editor

You may open multiple edit windows in CodeWarrior, although things begin to get confusing when many windows are open! You can move easily from one window to another either by clicking in the desired window, if you can see it, or by selecting the desired window by name from the Window menu (or by typing the command equivalent assigned to that window). You may use the split bar on either the vertical scroll bar (at the top just above the scrolling arrow) or on the horizontal scroll bar (on the left end just to the left of the scrolling arrow) to split the edit window into multiple panes, both vertically and horizontally, for viewing multiple parts of a file in the same edit window. This allows for easier cut/copy/paste operations from one part of a source file to another, especially when the two source segments are too far apart to get into one edit window at the same time. You may also use the Macontosh Drag and Drop feature. Simply select a segment of text, then mouse down on it, then move it using the mouse to the new location for the text, which may be in a different part of the same file or in a different file. When the selected text segment is where you want it to be, release the mouse button and the text is placed there in the file.

At the top left of the edit window there are five icons. If you click on the leftmost icon (which is contains a script h)), you will see a pop-up menu containing an alphabetical list of all of the interface files included in the source file in this edit window. At the top of this pop-up menu is a Touch command which allows you to touch this file; a touched file will be compiled at the next make, even if it has not changed. If you select one of the interface files from the pop-up menu, then a new edit window opens with the selected interface file in it. You can also open an interface file by selecting the file name in the source code edit window, then choosing the Open Selection command from the File menu. In addition, if you press command-tab, CodeWarrior switches from a source file edit window to an interface file edit window, or vice versa; for this command to work, the two files must have the same name other than the file name extension (e. g., project0.c and project0.h).

If you click on the second icon from the left at the top of an edit window (the button labelled with two curly braces {}), you will see a pop-up menu containing a list of all of the function names defined in the source file in this edit window; the functions are listed in the same order as they occur in the source file. If you option-click on this icon, then the function list is in alphabetical order. One function name will have a check mark to the left of its name; this is the function containing the current insertion point. If you select one of the function names in the pop-up menu, then the edit window moves to that function in the source code, but leaves the insertion point wherever it happens to be. If you hold down the Shift key while selecting a function from this list, then the function is displayed in the edit window, and the entire function is selected (which is useful for a copy/paste sequence).

If you mouse down on the fourth icon from the left at the top of the edit window (the one with the icon of document on it), you will see selections which allow you to convert the text file in the edit window between UNIX, DOS, and Macintosh text file formats; these commands change the line endings in the text file in the edit window. This is useful if you are reading files from another operating system, or if you wish to move the text file in the edit window to another operating system. When you save a file in an edit window, it is saved in the format selected in this pop-up menu.

The third and fifth icons at the top of the edit window are not described here. The third one allows the user to set mark points within the source file for quick access, while the fifth one is used when software version control is being used in the project.

Finally, if you command-click or option-click on the file name at the top of an edit window, you will see a pop-up menu which contains the full pathname of this file, from the disk name (at the bottom of the pop-up menu) to the file name (at the top of the pop-up menu).

If you are running on a Macintosh with a color monitor, and the colors are set on in the monitors control panel, then you will see the source code in an edit window in four colors. All comments will be displayed in red, all keywords will be displayed in blue, all strings will be displayed in green, and the rest of the text will be displayed in black. Once you get used to this colorful display, you will find it makes the source code much easier to scan by eye. The colors used, and many other aspects of the editor, may be changed in the editor preferences. Select the Preferences command in the Edit window, then click on Editor Settings in the preferences window.

By default, the editor uses the Monaco font, size 9, in an edit window; this can be changed in the editor preferences. It is best to use either the Monaco or the Courier fonts for program listings, since these are mono-width fonts. Use tabs to properly indent the source code as shown in the text and source code handouts for this course (see also the course pack). The editor autoindents each line as you type; each time you hit return, the next line is indented to the same indentation as the previous line. You can then backspace or tab if you wish to change the indentation of the new line. If you type option-return, the new line is not indented. Again, much of this behavior can be controlled or changed via the editor preferences; the auto-indentation feature can be turned off or on in the Fonts & Tabs preferences window.

In addition to the usual editing functions, the Edit menu also provides some other useful functions. If you place the insertion point in a line of text, or select a block of text, then choose the Balance command from the Edit window (or type command-B), the editor will search in either direction from the insertion point to balance parentheses, square brackets, or curly brackets. Once a balanced match has been found, selecting Balance again will match the next bigger balanced portion of the text. This allows a quick check of the bracketing of a C program, which is useful when strange compiler errors start occurring! If you select a block of text, then it can be shifted either right or left in the source file by choosing either the Shift Right (command-]) or Shift Left (command-[) command in the Edit window. Each shift is by one tab size in the specified direction.

Finally, here are a few techniques and short cuts supported by the CodeWarrior editor:

• a single click positions the insertion point at the cursor
  
• the arrow keys move the insertion point one character at a time or one line at a time
  
• to move the insertion point word by word, hold down the option key and use the Left or Right Arrow key
  
• to move the insertion point to the beginning or end of the current line, hold down the command key and hit the Left or Right Arrow key
  
• to move the insertion point up or down by one page, hold down the option key and use the Up or Down Arrow key
  
• to move the insertion point to the beginning of the file, hold down the comand key and use the Up Arrow key
  
• to move the insertion point to the end of the file, hold down the command key and use the Down Arrow key
  
• a double click selects the word at the cursor
  
• a triple click selects the line at the cursor
  
• to select text word by word, double click on the first word and hold down the mouse button while moving the cursor to the last word in the selection, or
  
• to select text word by word, position the cursor and hold down the shift and option keys while using the Left or Right Arrow key
  
• to select text line by line, triple click on the first line and hold down the mouse button while moving the cursor to the last line in the selection
  
• to select text character by character, position the cursor and hold down the shift key while using the Left or Right Arrow key
  
• to select text to the beginning or end of the current line, position the insertion point, hold down the shift and command keys, and hit the Left or Right Arrow key
  
• to scroll the edit window one page up, hit the Page Up key
  
• to scroll the edit window one page down, hit the Page Down key
  
• to scroll the edit window to the beginning of the file, hit the Home key
  
• to scroll the edit window to the end of the file, hit the End key
  
• to scroll the edit window to the insertion point, hit either the Left Arrow key or the Right Arrow key
  
• hit the Delete key to delete the selected text or the character in front of the insertion point
  
• hit the Forward Delete (del) key to delete the character after the insertion point
  
• hit command-Delete to delete from the insertion point to the end of the file
  

Using the Project Window

• to select a single file or group, single click the name;
  
• to deselect a single file or group, command-click its name;
  
• to select a consecutive list of files or groups, select the first one in the list, then shift-click the last one in the list;
  
• to select a non-consecutive list of files or groups, command-click each file name or group name.
  

In the project window, the File column gives the names of the group/segments and the source and library files in the project. If you option-click on a file name in this column, a pop-up menu appears which gives a variety of operations which may be performed on this file (such as find its directory path, remove it, compile it, etc.). To the left of each source file name, there will be a check mark if the file needs to be compiled during the next make of the project. You may click in this column to turn the check mark on or off; this is the same as touching the file (see later). The Code and Data columns of the project window give the object size of the code and data in each file; these numbers show only after the project has been made at least once. The last column, headed with the "bug" icon, is the Generate SYM Info column; this column contains a dot (€) if debugger symbol information is to be generated when this file is compiled; this information is needed by the runtime debugger. Normally the dot is set by default each time you add a source file to the project; the setting can be reversed by clicking on the dot. If you plan to use the CodeWarrior debugger with this project, then your source files should specify the generation of symbol information. If you option-click on any dot, then symbol information generation is turned off for all source files in the project; if you option-click in a blank space in this column, then symbol information generation is turned on for all source files in the project. On the far right of each line in the project window is another triangle. If you mouse down on this triangle, a pop-up menu apears. The first item in the pop-up menu is the Touch command; if you select this command, then this source file will be compiled in the next make of the project. The rest of the pop-up menu is an alphabetical list of the interface files included in this source code file; this list is only available if the source file has been compiled at least once. If you choose a file name in this list, then the source of the selected file opens in a new edit window. You can close the project window by

• clicking its close box (upper left corner)
  
• selecting Close from the File menu (or typing command-W) when the project window is the foremost or only window
  

Compiling and Linking a Project

Check Syntax (command-;)
This command does a syntax check of the source file in the current edit window or the source file(s) selected in the project window. If any syntax errors are found, then a message window appears on the screen containing the pertinent syntax error messages. Note that this command, unlike the others, does not actually compile the source code - it just checks the syntax of the source code.
Compile (command-K)
This command compiles either the source file in the currently active edit window or the selected source file(s) in the project window. The source file in the active edit window cannot be compiled unless it has been saved with a proper suffix and it has been added to the project. If any compiler errors are discovered, a message window appears on the screen containing the pertinent compiler error messages.
Bring Up To Date (command-U)
This command brings the project up to date; every new (added), modified, or touched file in the project is compiled. As each source file or library file is compiled, the file name is highlighted in the project window. The data size and code size for each file is added to, or updated in, the project window. If any compiler errors are discovered, a message window appears on the screen containing the pertinent compiler error messages.
Make (command-M)
This command brings the project up to date; every new (added), modified, or touched file in the project is compiled. As each source file or library file is compiled, the file name is highlighted in the project window. If any compiler errors are discovered, a message window appears on the screen containing the pertinent compiler error messages. If no compiler errors are discovered, then the object files in the project are linked; if any link errors are discovered, then a message window appears on the screen containing the pertinent link error messages. If no link errors are discovered, then a project application file is created in the project folder. If all of the files in the project have already been compiled, then this command simply links the compiled source code files.
Run (command-R)
If the project is not up to date, then this command first does a make of the project. If the make is successful, then the project application is run; if not, then a message window appears with the pertinent error messages. If the Enable Debugging option has been selected in the Project menu when the run command is given, then a SYM file is created in the project folder and the CodeWarrior debugger loads first and controls the running of the program.

NOTE: there is also a Precompile command in the Project menu - do not use this command!

When compiler or linker errors are detected, the error messages are presented on the screen in a message window. There are two kinds of messages which may be presented in a message window:

Errors
Error messages are marked by a red stop sign icon with a hand icon to the left of the message; these may be either compiler or linker error messages. In either case, the program cannot be run until the errors are corrected.
Warnings
Warning messages are marked by a yellow yield sign icon to the left of the message; these may come either from the compiler or the linker. A warning message means that something unusual has been found, but the application object program was created anyway. However, running the application may be dangerous to the health of your Macintosh! It is best to treat warnings the same as errors and change the code to get rid of them.

At the top of the message window are the two icons for error messages and warning messages. The first (leftmost) icon is the error message icon; to the right of the icon is the total count of error messages. The second icon is the warning message icon; to the right of the icon is a total count of warnings. If you click on either icon, then the messages of that type are removed from the message window; clicking on the icon again brings back the messages of that type. The message window can be closed either by clicking its close box or by selecting Close from the File menu (or typing command-W). The message window can then be reopened by selecting the Errors & Warnings Window command from the Window menu (or typing command-I); this will also make the message window the active window, even if it was not closed at the time. If the message window is the active window, then it may be saved using the Save A Copy As command or printed using the Print command (or typing command-P).

Next in the message window is the message pane. This pane contains a complete list of all of the error and warning messages generated by the last compile or make of the project. Each error message has an icon to its left which indicates the type of message it is. You can select a message in this window by single clicking on it. When you do that, the source code which gave rise to this message is shown in the bottom pane of the message window. You may edit the source code in this pane to correct the error which caused the message. At the top right of the message window are two arrows - one an up arrow and one a down arrow. You may select the next (or previous) message in the message window by clicking on one of these buttons.

If you wish instead to return to the actual source code, in an edit window, which caused a message, do one of the following:

• select a message (by clicking on it), then hit the return key;
  
• double click the message
  

For linker errors and warnings, things are a bit different with the message window. The window can be navigated using the up/down arrow keys or the scroll bar. However, you cannot double click a linker message to get a source code edit window, because linker errors are caused by problems in the object code of the project. The most likely sources of linker errors are a missing library file, a misspelled function name, a missing include statement, or (on a 68K project) a segment too large (more than 32K bytes.

Running the Project

From the desktop, you may open the project folder and double click the project application; this runs the application without launching CodeWarrior. The runtime behavior of the program is exactly the same, except that when you terminate execution control returns to the desktop instead of to CodeWarrior.

When the Hello program runs, a new window appears on the screen, the console. This window acts as the input and output of the program. The printf function writes to this window, and the scanf function reads from this window. You may print this window or save it in a file in the usual Macintosh way. When the program has finished execution, you may return to CodeWarrior by selecting Quit in the File menu or by typing command-Q.

Hitting the PANIC Button

Quitting CodeWarrior

If the Computer Just Goes Dead

If Previously OK Projects Get Weird

Redirecting Standard I/O for Data Input and Result Output

The I/O functions scanf, printf, gets, puts, etc., all read or write the standard I/O. CodeWarrior C allows the user to conveniently use a Macintosh dialog box to choose the source of the standard input and the destination of the standard output when the program is run (each and every time). To do this, you must add some specific code to your program.

In order to redirect standard I/O when the program runs, three things must be done:

1. include the header file console.h in the source code;
   
2. add parameters to the main function; and
   
3. call the ccommand function to allow the user to redirect standard I/O during program execution.
   

     /* 
      * Program Hello World
      * A very simple C program which reads an integer n and prints
      *  "Hello World"  n times
      */
     #include <stdio.h>
     #include <console.h>
     int
     main(int argc, char ** argv)
            {     
               int i, n;
               argc = ccommand(&argv);
               printf("Enter the value of n: ");
               scanf("%i", &n);
               for (i = 1;   i <= n;  i++)
                    printf("Hello World!\n");
               return 0;
           }
     

1. where the standard input comes from (keyboard (console) or file); in the lower left half of the dialog box, click on File to get a window which allows the selection of an input file; otherwise, standard input comes from the keyboard;
   
2. where the standard output goes (screen or file); in the lower right half of the dialog box, click on File to get a window which allows you to create and name an output file and designate what folder to put the new file in; otherwise, standard output goes to the console window;
   
3. the command line (we ignore this; the information is accessed through argc and argv in true UNIX fashion).
   

     /* 
      * Program Hello World
      * A very simple C program which reads an integer n and prints
      *  "Hello World"  n times
      */
     #include <stdio.h>
     #include <console.h>
     int
     main(int argc, char ** argv)
       {
           int i, n;
           argc = ccommand(&argv);
           fprintf(stderr, "Enter the value of n:  ");
           scanf("%i", &n);
           printf("For n = %d, we have:\n", n);
           for (i=0; i<n; i++)
                printf("   Hello, World!\n");
           return 0;
      }
     

For More Information about CodeWarrior