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, whereas the Perforce SCC Plug-in maps Perforce features to generic functions like "check-in". For details about managing your code using Perforce, and especially about using advanced features such as resolve and integrate, refer to the Perforce User's Guide.
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 Perforce User's Guide.)
|
Installing the CodeWarrior Plug-in
To obtain the Perforce CodeWarrior Plug-in, go to the Perforce downloads web page (http://www.perforce.com/perforce/downloads/macosxppc.html) and browse to the page for your Windows platform. After you download the file, copy it to the appropriate CodeWarrior directory, as follows:
- Metrowerks CodeWarrior x.x:Metrowerks CodeWarrior:CodeWarrior Plugins
- Metrowerks CodeWarrior x.x/Metrowerks CodeWarrior/CodeWarrior Plugins
Configuring CodeWarrior with Perforce
The instructions in this section apply to CodeWarrior for Macintosh and for Windows. The screen captures are for Macintosh. Although Windows screens differ in appearance from Macintosh screens, they are identical in content.
Warning!
|
To avoid conflicts between project-level and global settings, which cause problems for CodeWarrior, always enter settings with a project open, and be sure to enter settings for each project. 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.
|
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 extracted the plug-in to the Perforce CodeWarrior Plug-in directory.
- Specify login settings. In the Username field, type the Perforce user name (the P4USER value) for the client workspace you want to link to this project.
- If you use a password, set the Login Settings checkboxes as follows:
To be asked for your password...
|
Set "Always Show Login Dialog" to...
|
Set "Remember Password" to...
|
---|
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.
- 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.
For each project, you must specify its working directories. In CodeWarrior, the database path is the current working directory for files specified using relative paths in the VCS menu's Command... menu item, and local path is the directory used as root for all of the VCS menu's Recursive commands. The local path must be set to the client workspace root or a directory under the client workspace root.
To specify project directories, open the project and perform the following steps.
- Specify the Database Path.
- Choose "Project relative" and enter the project root.
- Click Choose. CodeWarrior displays the Change an Existing Path dialog. Browse to the desired folder and click OK.
- To specify the Local Path, enter the client workspace root or click Choose, browse to the client workspace root, and click OK.
The VCS menu
To perform source control operations, you choose options from the VCS menu. Most of the commands in this menu have the same name and functionality as the corresponding Perforce command. To issue Perforce commands other than those on the VCS menu, choose VCS>Command... or issue P4 commands in MPW.
On Macintosh, the VCS menu is displayed as the following icon in the toolbar:
The VCS menu options appear as shown in the following figure.
The Project and Recursive menu selections enable you to specify the set of files to which you want the command to apply. The following table summarizes these options.
Menu selection
|
Command applies to
|
---|
VCS
|
All files that you select in the project window.
|
VCS > Project
|
Only the current project file.
|
VCS > Recursive
|
All the files under the {localpath} directory that are mapped to files in the depot using the client view. Recursive commands act like p4 command {localpath}/...
Recursive commands act on the project file if the project file is under {localpath}.
Note: To run a recursive operation on a file subtree on Macintosh computers, hold down the Shift key while choosing the operation.
|
The {localpath} identifier refers to the value of the Local Path directory as set in the VCS Settings dialog. Most of the Recursive submenu items act on all the files under this directory, even when these files are not in the project.
Warning!
|
Be careful when performing a recursive sync operation. Depending on your client mapping, 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 limited and specific directory on the depot.
|
The Perforce CodeWarrior Plug-in has advanced options for many menu items. When you choose an advanced menu item, CodeWarrior displays dialogs that enable you to specify additional options before the operation is executed.
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 Macintosh, no setup steps are required to enable the advanced options. On Windows platforms, the advanced option is enabled by specifying either Advanced or Both in the Amount of Menu Detail field during setup.
The following table describes the menu options.
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 configure the display of advanced menu options:
- Choose Edit > Version Control Settings...
- In the Amount of Menu Detail field, specify either Advanced or Both.
The Perforce CodeWarrior Plug-in identifies file status by placing an icon next to each file in the project window. In addition, the VCS menu is context-sensitive: if you highlight a file, the menu selections are enabled or disabled depending on file status.
VCS menu commands
The VCS menu contains selections for Project and Recursive commands. Project commands operate on the project file, as opposed to source files. Recursive commands operate on all files in the directory set as the Local Path in the VCS options menu. You can display the recursive subtree of a Perforce operation on Macintosh computers by holding down the Shift key.
To display advanced menu options on Macintosh, hold down the Option key and click the menu item. To display advanced menu options in Windows, specify Advanced or Both in the VCS setup window.
The following table describes the version control commands that the Perforce CodeWarrior Plug-In adds to CodeWarrior.
Menu Command
|
Description
|
Option Key or Advanced Menu Action
|
Related P4 Command
|
---|
Synchronize Status
|
Synchronizes the CodeWarrior file status with the Perforce file status. Refreshes the version control system icons for each file in the project. Execute this command after you perform an operation outside of CodeWarrior that affects the status of files in a CodeWarrior project.
|
None
|
None
|
Sync
|
Copies the head 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, enable advanced menus and use the Sync... command.
|
Enables you to enter revision specifications and other p4 sync options.
|
sync
|
Edit
|
Opens the selected files for edit in the client workspace.
|
Opens the files for edit and enables you to change the file types.
|
edit
|
Revert
|
Reverts the selected files to the revision last synced from the depot.
|
None
|
revert
|
Filelog
|
Displays the revision history of the selected files.
|
Displays the full description of each changelist.
|
filelog
|
Have
(recursive)
|
Lists the revision numbers of the selected files that were last synced to the client workspace.
|
None
|
have
|
Diff
|
Diffs the revision as edited on the client workspace against the revision last synced from the depot, using the CodeWarrior diff utility.
|
Enables you to select the diff style, and to force the diff.
|
diff
|
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
|
Enables you to set the file's Perforce file type.
|
add
|
Delete
|
Deletes the selected files from the depot.
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.
|
None
|
delete
|
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.
|
None
|
submit
|
Resolve
|
For files scheduled for resolve, displays a dialog enabling you to select and perform the desired type of resolve.
Refer to the Perforce User's Guide for detailed information about resolving files using Perforce.
|
None
|
resolve
|
Opened
(Recursive submenu)
|
Displays the list of all open files in the current client workspace.
|
Enables you to view a list of all open files in all client workspaces.
|
opened
|
Connect and Disconnect
|
Irrelevant for plug-in users.
The VCS API requires use of this menu option, but Perforce has no corresponding feature.
|
None
|
None
|
About
|
Display information about your current Perforce configuration.
|
None
|
info
|
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.
All Perforce special characters and wildcards are supported. 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 currently support:
|
None
|
None
|
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, the VCS Messages dialog displays a message similar to the following:
- //depot/projectdir/filename.c#1 - was added
- Highlight the open files
- Choose VCS>Submit.
The P4 Submit Form dialog is displayed.
- Enter your comments and click OK.
The VCS Messages dialog displays a message similar to the following:
- //depot/projectdir/filename.c#1 - was submitted
Using Perforce, you can verify that the files are listed in the default pending changelist as opened for add.
Although the project file does not appear in the CodeWarrior project window, it does reside in the file system. Include the project file under version control, especially if multiple developers are working on the same project. 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.
- Choose VCS>Project>Edit.
Note that CodeWarrior displays a project icon in the lower left.
Tip: you can store the project file in XML format, which enables you to diff versions of the file to see how it's changed.
To verify that source files are under Perforce control, attempt to edit files that are not checked out. If the files are under Perforce control, CodeWarrior prompts you to check it out, remove the lock, 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.
- Check the files you want to check in.
- Enter your comments in the Comments field and click OK.
In the VCS Messages dialog, a message similar to the following appears:.
Change 5059 created with 3 open file(s). Submitting change 5059. Locking 3 files ... edit //depot/Demo3/DataEnvironment1.Dsr#2 edit //depot/Demo3/DataReport1.Dsr#2 edit //depot/Demo3/frmDataEnv.frm#2 Change 5059 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 files:
- 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
|
Most commands, including Submit, are enabled.
|
Files have been successfully submitted to Perforce.
|
Pencil with slash
|
Check in
|
To display results for all Perforce commands, enable the Display 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 menuitem. To override the file's default Perforce type when adding the file to Perforce, hold down the Option key when choosing the Add menuitem, 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 when the file is synced to a non-Macintosh computer.
Specifying default file types
When you add files (other than text files) from a Macintosh client to a Perforce depot, Perforce determines the file type by examining the Macintosh client's Internet mappings database. The factors that determine how a Macintosh file is stored are as follows:
- File name extension
- Finder type
- Creator
The following figure shows the Internet dialog with File Mappings selected at the left. The right pane shows file extensions mapped to Macintosh applications.
The following table lists standard mappings for Perforce.
Macintosh file type
|
Perforce file type
|
---|
Macintosh
|
apple
|
Plain text
|
text
|
Binary data
|
binary
|
If the Internet mappings database does not contain an entry for a file type, Perforce stores it using the apple file type.
To change the default Perforce file type for all files of a particular combination of file extension, Mac file type, and Mac creator:
- Open the Internet control panel and click the Advanced tab. (If the Advanced tab is not visible, choose Edit>User mode and set the mode to Advanced).
- Click the File Mapping icon at the left of the Advanced tab dialog.
- Scroll through the mappings list, looking for your extension, Mac file type, and Mac creator combination. If the combination you're looking for does not exist, you can add it by clicking Add... and entering the file extension, Mac type, and creator in the Change Mapping dialog.
- Click Show Advanced Options.
- On the right side of the Advanced Options dialog, choose the correct default format for this particular file type. The Macintosh format maps to the Perforce apple file type, Plain Text maps to text, and Binary Data maps to binary.
- Save your changes and close the Internet control panel.
Please send comments and questions about this manual to
manual@perforce.com.
Copyright 2001-2004 Perforce Software. All rights reserved.
Last updated: 02/26/04