Chapter 5
Metrowerks CodeWarrior
This chapter describes how to perform Perforce source code control tasks in the CodeWarrior environment. Note that the Perforce CodeWarrior Plug-in supports Perforce features directly, but the Perforce SCC Plug-in maps Perforce features to generic functions (for example, "check-in.") For details about managing your code using features such as resolve and integrate, refer to the Introducing Perforce.
Note
|
The highest available version of the CodeWarrior plug-in is version 2005.1.
|
Configuring CodeWarrior with Perforce
The instructions in this section apply to CodeWarrior for Macintosh and for Windows. Although Windows CodeWarrior screens differ in appearance from Macintosh screens, they are identical in content. Note that, on Macintosh the VCS menu is represented by this icon in the menu bar: 
Warnings!
|
- Do not use global version control settings (settings you make when no project is open). Conflicts between project-level and global settings cause problems for CodeWarrior.
- Do not change file read/write settings manually. Perforce manages these settings and uses them to track the status of files.
|
To configure the Perforce CodeWarrior Plug-in, perform the following steps.
- Launch CodeWarrior.
- Open the project for which you want to specify version control settings.
- Choose Edit > Version Control Settings...
CodeWarrior displays the VCS Settings dialog as shown in the following figure.
- Check Use Version Control and choose Perforce as the method.
If Perforce is not listed in the Method popup menu, the Perforce CodeWarrior Plug-in is not installed correctly. Verify that you copied the plug-in files to the Perforce CodeWarrior plug-in directory as described in "Configuring CodeWarrior with Perforce" on page 43.
- Specify login settings. In the Username field, type the Perforce user name (the P4USER value) of the owner of the client workspace where you want to store this project.
Note
|
With the CodeWarrior plug-in, you cannot configure individual projects using a Perforce config file. (For details about Perforce config files, refer to the P4 User's Guide.)
|
- If the specified Perforce user has a password, set the Login Settings checkboxes as follows:
To be asked for your password
|
Always show login dialog
|
Remember password
|
|---|
|
Never
|
Off
|
On
|
|
Once
|
Off
|
Off
|
|
Always
|
On
|
Off
|
Recommendation: to minimize the number of times you have to log in, turn off the checkbox Always show login dialog, turn on Remember password, and leave the Password field blank.
The Connect on open checkbox determines whether you are asked to login when the project starts up or when you perform the first Perforce operation.
Note
|
When configuring settings for a secure server, leave the Version Control Settings password field blank and check Remember password to ensure the correct sequence of events during authentication.
If you're using Perforce's ticket-based authentication and you fail to login (due to an incorrectly-specified password), any subsequent operations you attempt will fail. In this situation, choose VCS>Disconnect and log in again.
|
For each project, you must set the Local Path field, which is used for two purposes:
- the current working directory for files specified using relative paths in the VCS menu's Command... menu item
- the directory used as the root for all of the VCS menu's Recursive commands
The Database path field is not used by the CodeWarrior plug-in.
To specify Local Path on the VCS Setup pane:
- Click Choose. CodeWarrior displays a folder browser dialog.
- Specify Local Path (for details, refer to CodeWarrior on-line help).
- Browse to the desired folder and click OK.
To configure the settings required for CodeWarrior to interact with the Perforce Server, perform the following steps.
- Click Perforce Setup in the left pane of the VCS Settings dialog.
The Perforce Setup pane is displayed as shown in the following figure. 
Set P4PORT and P4CLIENT to the Perforce server port and client workspace name, respectively.
Set other preferences as desired. The following table describes the options.
Checkbox
|
Effect
|
|---|
|
Show all
information
messages
|
Specifies whether some Perforce operations display a dialog containing messages about the results of the operation.
|
|
Always show
job lists
|
Specifies whether job lists are always displayed on the Submit form, or only when there are jobs already linked to the changelist.
|
- Click Save to save your settings.
The VCS menu
Scope of menu options
To perform source control operations, you choose options from the VCS menu or one of its submenus, according to the set of files you want to operate on.
To operate on...
|
Choose commands from this menu
|
|---|
|
Files and folders selected in the IDE project window
|
VCS
|
|
The project file itself
|
VCS > Project
|
|
All files and folders in the path specified in the Local Path field on the VCS Settings pane
|
VCS > Recursive
|
To run a recursive operation on a file subtree on Macintosh computers, hold down the Shift key while choosing the operation.VCS menu commands operate on the files and folders selected in the IDE project window.
Warning!
|
Be careful when performing a recursive sync operation. Depending on your client view, you can inadvertently download the entire contents of the depot to your client computer, possibly hundreds or thousands of files. To avoid this problem, ensure that your client workspace is mapped to a specific directory in the depot. For details about client views, refer to Introducing Perforce.
|
To issue Perforce commands other than those on the VCS menu, choose VCS>Command... or issue P4 commands at the operating system command line prompt.
Simple versus advanced menu options
There are two types of menu options: simple and advanced. You can configure CodeWarrior to display simple, advanced, or both sets of options. The following table describes the menu settings.
Option
|
Description
|
Example
|
Advantages & Disadvantages
|
|---|
|
Simple
|
Only the basic menu options are displayed.
|
The VCS menu contains Sync but not Sync...
|
Advantage: shorter menus.
Disadvantage: advanced operations such as p4 sync -f can't be performed directly from the VCS menu.
|
|
Advanced
|
For menu options that have both a basic and advanced version, the advanced version is displayed
|
The VCS menu contains Sync... but not Sync
|
Advantage: the plug-in displays dialogs for most of the commands, allowing more advanced options to be specified for each command, such as being able to change a file's type before you Add it to Perforce.
Disadvantage: the dialogues are always displayed, adding steps to most VCS commands.
|
|
Both
|
For menu options that have both a basic and advanced version, both versions are displayed.
|
The VCS menu contains both Sync and Sync...
|
Advantage: you can choose between the simple and advanced form of the commands
Disadvantage: the VCS menu size doubles.
|
To view the advanced options on Macintosh platforms, press the Option key. Some of the menu selections appear with ellipses after them. For example, instead of Sync, the menu item becomes Sync... To choose an advanced option, press the Option key.
On Windows platforms, enable the advanced menu options by choosing Advanced or Both in the Amount of Menu Detail field on the VCS Settings > Perforce Settings pane. To configure the display of advanced menu options:
- Choose Edit > Version Control Settings... The VCS Settings dialog is displayed.
- In the left pane, click Perforce Settings. The Perforce Settings pane is displayed.
- In the Amount of Menu Detail field, choose the level of menu options you want displayed by default.
VCS menu commands
The VCS menu commands work as follows:
- A plain command (for example, Sync) performs the specified operation using defaults (for example, sync to the head revision).
- A command followed by an ellipsis (for example Sync... or Sync Subtree...) displays a dialog where you can specify command options.
- A command followed by "Subtree" performs the specified operation recursively (on the files in a selected folder plus its subfolders).
The following table describes the commands that the Perforce CodeWarrior Plug-In adds to CodeWarrior in the VCS menu and its submenus.
Menu
Command
|
Description
|
|---|
|
About
|
Display information about your current Perforce configuration.
|
|
Add
|
Add the selected files to the depot.
To add files recursively, select all the files and folders in the project window and choose Add. To add the project file, use the Project>Add submenu.
|
|
Command...
|
Enables you to run any Perforce command. File name arguments specified using relative pathnames are interpreted by Perforce using the database path specified in the Version Control Settings preferences panel.
To use the Perforce * and ? wildcards, specify file names using depot syntax. The Perforce ... wildcard works with both local and depot syntax. For details about wildcards and depot and local syntax, refer to Introducing Perforce.
To specify files or directories with spaces in their names, use quotes around the entire file argument; for example:
p4 changes "//depot/a b c"
The Command... menu item does not support:
|
|
Connect and
Disconnect
|
Irrelevant for plug-in users. The CodeWarrior VCS API requires use of this menu option, but Perforce has no corresponding feature.
|
|
Delete
|
Marks the selected files for deletion from the depot. Files are deleted when you submit the changelist in which they are marked.
After you delete files from the depot, delete them from the CodeWarrior project using the Project>Remove Selected Items menu item.
To delete a CodeWarrior project, use the Project>Delete submenu.
|
|
Diff
|
Diffs the revision in the client workspace against the revision last synced from the depot, using the CodeWarrior diff utility.
|
|
Edit
|
Opens the selected files for edit in the client workspace.
|
|
Filelog
|
Displays the revision history of the selected files.
|
|
Have
|
Lists the revision numbers of the selected files that were last synced to the client workspace.
|
|
Opened
|
Lists all open files in the current client workspace.
|
|
Opened -a
|
Lists all files opened in all client workspaces.
|
|
Properties
|
Displays Perforce information about the selected files.
|
|
Resolve
|
For files scheduled for resolve, displays a dialog enabling you to select and perform the desired type of resolve. (For interactive resolves, you must use a full-featured Perforce client application such as P4V or the p4 command-line interface.)
Refer to Introducing Perforce for information about resolving files.
|
|
Revert
|
Reverts the selected files to the revision last synced from the depot.
|
|
Submit
|
Displays the submission dialog for the default pending changelist. If you have open files selected in the CodeWarrior project, those files are selected in the changelist. In the recursive submit dialog, all open files under {localpath} are selected in the changelist.
To submit a numbered changelist, use the Command... menu item. If a Submit of the default pending changelist fails, Perforce assigns a number to changelist and you must use Command... to submit it.
All jobs linked to the default pending changelist are displayed in the Submit dialog.
To specify whether CodeWarrior displays an empty job list in the Submit dialog, enable the Always Show Job List checkbox in the Perforce Settings preferences panel. To add jobs to any changelist, use the resulting job list.
|
|
Sync
|
Copies revisions of the selected files from the depot to the client workspace, if not already copied.
To get all files from the depot for the first time, use Recursive>Sync, then add the files to your project using CodeWarrior's Project>Add Files... command.
To retrieve specific revisions, use the advanced Sync... command.
|
|
Synchronize Status | Selection
|
Refreshes the version control status displayed on the icons for each file in the project or for selected files. Execute this command after you perform an operation outside of CodeWarrior that affects the status of files in a CodeWarrior project.
|
Basic SCM tasks
This section describes how to perform the following tasks:
Adding a project to the depot
To add all of the source files in a CodeWarrior project to version control, perform the following steps:
- With the project open, choose Edit >Select All.
All of the project files, including source files and other resource files, are highlighted.
- Choose VCS>Add.
For each source file that was added to the default pending changelist, CodeWarrior displays a message similar to the following:
- //depot/CW/cw-test100/cw-test100/hello.cpp#1 - opened for add
- Choose VCS>Submit.
The P4 Submit Form dialog is displayed.
- Enter your comments and click OK.
CodeWarrior displays messages similar to the following:.
Change 6426 created with 1 open file(s).
Submitting change 6426.
Locking 1 files ...
add //depot/CW/cw-test100/cw-test100/hello.cpp#1
Change 6426 submitted.
|
Include the project file under version control, especially if multiple developers are working on the same project. Although the project file does not appear in the CodeWarrior project window, it does reside in the file system. Leave the project file checked out, so it can be modified automatically by the IDE if project resources change.
To add the project file to version control, perform the following steps.
- Choose VCS>Project>Add.
- Choose VCS>Project>Submit, enter your comment on the submit form and click OK.
- Choose VCS>Project>Edit.
Tip: export the project file in XML format and maintain the XML file under Perforce control, to enable you to diff versions of the file to see how it has changed.
To verify that source files are under Perforce control, edit a file that is not checked out. If the file is under Perforce control, CodeWarrior prompts you to check it out, make it writable, or cancel the operation.
Checking files out
Files that are not checked out are designated by a crossed-out pencil icon, indicating that they are write-protected.
To check a file out of the depot so you can change it, click the file and choose VCS>Edit. If you want to change its file type, choose VCS>Edit... and specify the desired file type in the P4 Edit Options dialog.
Checking files in
In the project window, files marked by a pencil icon are open for edit. 
After editing the open files, save them to your local directory and check the files into version control. To save the files on your local directory, choose File>Save; however, saving does not update the depot.
To check files into the depot, perform the following steps.
- Select the files you want to check in.
- Choose VCS>Submit.
The P4 Submit Form dialog is displayed, containing a list of the selected files. (Note that the Submit menu option is enabled only when files are selected, but Recursive>Submit is always enabled.)
- Check the files you want to check in.
- Enter your comments in the Comments field and click OK.
CodeWarrior displays a message similar to the following:
Change 6429 created with 1 open file(s).
Submitting change 6429.
Locking 1 files ...
edit //depot/CW/cw-test100/cw-test100/hello.cpp#2
Change 6429 submitted.
|
Diffing files
The Perforce diff utility P4Diff allows you to compare the contents of two text files. On Macintosh, you can diff Macintosh TEXT files and files stored in the depot using the apple file type with the -t option.
P4Diff enables you to compare a file that is open for edit with another version residing in the depot. You can use this capability to review changes before checking a file into version control, or compare your file with a previously submitted version of the file in case of a conflict.
To diff a file:
- In the Project window, click the file you want to compare.
- Choose the menu option VCS>Diff...
The Perforce Diff Options is displayed.
- Specify desired diff options by clicking the corresponding radio button. By default, Perforce compares the open file with the version previously acquired from the depot. You can also compare any two previous file versions residing in the depot by entering the two version numbers.
- Click OK.
The Perforce Diff window appears with the file differences highlighted.
Reverting files
To discard any changes you have made to a file after checking it out, right-click the file and choose VCS>Revert. The head revision from the depot is copied to your client workspace, overwriting any changes you have made. In Perforce, the file is removed from the default pending changelist.
Deleting files
To delete files from the depot:
- Click the files and choose VCS>Delete.
The VCS Messages dialog displays a message indicating that the files are opened for delete. Using Perforce, you can verify that the file is in the default pending changelist, opened for delete.
- Choose VCS>Submit.
The P4 Submit Form is displayed.
- Check the files you want to delete, enter comments and click OK.
The VCS Messages dialog is displayed, indicating that the changelist has been submitted.
Working with CodeWarrior files
How file status is displayed
The following table describes how CodeWarrior indicates file status.
File status
|
Icon appears as
|
VCS menu appears as
|
|---|
|
Files are recognized by CodeWarrior but not by Perforce
|
Gray lock
|
Add command is enabled, most others are inactive.
|
|
Files have been added to a changelist but not submitted to Perforce
|
Pencil (indicating the file is writable)
|
Most commands, including Submit, are enabled.
|
|
Files have been successfully submitted to Perforce
|
Pencil with slash (indicating the file is not writable)
|
Check in
|
To display results for all Perforce commands, enable the Show all information messages option in the VCS Settings dialog. CodeWarrior displays the results of each command in its own window (labeled VCS Message Window). By default, results are displayed only when there is no visual change in the Project window.
Location of project files
The Project window has tabs for Files, Link Order and Targets. If you click the Files tab, the window displays source files and libraries, organized into collapsible lists or groups. The groups do not necessarily represent the actual file structure.
To view the location of a file, click and hold on a specific file until the pop-up menu appears, then choose File Path. The file's location on your local directory is displayed hierarchically.
The window does not display the project file (.mcp file), although this file resides in the project directory.
Choosing Perforce file types when adding files
Macintosh TEXT files are always stored as Perforce text files (without resource forks) so the files can be diffed, resolved, and edited on platforms other than Macintosh. For non-TEXT files, the file's extension, Finder type, and Creator are looked up in the Internet mappings database. If the database contains an entry mapping the file type, Perforce uses the Mac default format specified. If the database does not contain an entry, Perforce store the file using its apple file type.
When adding files to the depot, check the files' Perforce type before submitting the files, to ensure that correct file types are assigned. To see the Perforce types of open files, use the Opened menu item. To override the file's default Perforce type when adding the file to Perforce, hold down the Option key when choosing the Add menu item, and select the file's type in the resulting dialog.
When you add portable binary files (for example, .gif files) to a Perforce depot, store them using the Perforce binary format, to avoid complications that otherwise might occur when the file is synced to a non-Macintosh computer.
Please send comments and questions about this manual to
manual@perforce.com.
Copyright 2001-2005 Perforce Software. All rights reserved.
Last updated: 12/22/05