Perforce 2003.2 Using IDE Plug-ins
<< Previous Chapter
About This Manual
Table of Contents
Index
Perforce on the Web
Next Chapter >>
Microsoft Visual C++

Chapter 1
Basic Concepts

About IDEs and plug-ins

Perforce plug-ins enable you to perform basic Perforce software configuration management (SCM) tasks from within integrated development environments (IDEs). Perforce offers two IDE plug-ins:

Perforce also offers plug-ins for other development tools. See our Web site for details.

The Perforce SCC Plug-in is installed when you install Perforce on Windows. To obtain the Perforce CodeWarrior Plug-in, go to the Perforce downloads web page.

The SCC and Perforce CodeWarrior Plug-ins offer similar functionality but have different user interfaces. For details about supported versions of each IDE, refer to the release notes for the plug-ins.

Note that the terminology for SCM tasks varies depending on which development environment you are using. The following table compares some common terms.

IDE with SCM plug-in
Other commonly used terms
Corresponding Perforce command

Add to source control/Perforce

Add

p4 add

Check out

Edit

p4 edit

Check in

Submit

p4 submit

Show differences

Diff

p4 diff

Get latest version

Sync, Refresh

p4 sync

Show history

Filelog

p4 filelog

Undo checkout

Revert

p4 revert

Remove from source control

Delete

p4 delete

About Perforce

Perforce is an SCM system that is based on a client/server architecture. The main repository (the depot) resides on a central server while the files you work on reside in a workspace on your local machine. You can place some or all of the files in your workspace under source control. When you perform SCM tasks, the files remain in your workspace, and Perforce reads or writes them as required. For example, when you submit a change, Perforce reads the edited files in your workspace and updates the information in the database accordingly. When you issue a Get latest version or refresh command, Perforce transfers files from the depot to your workspace.

The most current revision of the file in the depot is called the head revision. Perforce allows you to check out the head revision or any previous revision of a file. To enforce the IDEs' check-in and check-out procedure, Perforce controls the read-write permissions of files. When files are checked out for edit, their permissions are set to read-write. When files are not checked out, Perforce sets them to read-only.

Perforce submits changed files in groups called changelists. Perforce keeps track of a project's revision history as a sequence of changelists. This approach allows you to reconstruct a project in your workspace as it appeared at any point in its history. Perforce makes changes atomically, meaning that when you submit changes to a group of files, either all of the changed files are accepted simultaneously or none of them are. If conflicts result from multiple users working on the same files, these conflicts must be resolved before Perforce will accept the changes.

Perforce offers a command-line client (P4), a native Windows GUI (P4Win), a cross-platform GUI (P4V) and a Web-based interface (P4Web). For detailed information about Perforce, refer to the user documentation available on the web at:

Most IDEs are project-based: they manage a group of files according to the project to which the files belong. However, Perforce manages files with no provisions for specific IDEs' project structure. You must determine which files you need to place into your Perforce depot, depending on the conventions of your IDE and your group development practices.

Tracking changes

When files are added to source control, deleted from source control, or checked out for edit, Perforce adds them to a changelist. The changelist contains the file names, revision numbers, and operations to be performed. Any edits you make to checked out files are kept in your local client workspace until you send the changelist to the depot with a check in or submit command.

The Perforce server tracks changelists by numbering them sequentially. Changelist numbers are displayed in a results window after a change has been submitted.

Handling conflicts

The ability to detect and resolve conflicts is important in team development, when multiple developers are working on the same files. For example, suppose two programmers copy the same file from the depot into their workspaces and each programmer edits the file differently. When the first programmer submits his version of the file to the depot, the file becomes the head revision. When the second programmer tries to submit her changes to the depot, Perforce determines that her changes are based on a previous revision and does not allow the file to be checked in. If the second file were accepted without question, the first programmer's changes would be overwritten.

When Perforce detects a conflict, it requires you to choose the changes to be checked in. When resolving file conflicts, you can use a merge utility to display the differences between two text files, to help you determine how to resolve the conflict. For more details, see the Perforce Command Reference.

File types

Perforce automatically detects whether files placed under source control are text or binary files and stores them accordingly on the server machine. By default, text files are stored in reverse delta format, and binary files are stored in their entirety. The following table lists recommended Perforce file types and attributes for common file types. For details about Perforce file types, refer to the Perforce User's Guide For a list of common file types, see http://www.icdatamaster.com.

File Type
Perforce file type
Description

.asp

text

Active server page file

.avi

binary+F

Video for Windows file

.bmp

binary

Windows bitmap file

.btr

binary

Btrieve database file

.cnf

text

Conference link file

.css

text

Cascading style sheet file

.doc

binary

Microsoft Word document

.dot

binary

Microsoft Word template

.exp

binary+w

Export file (Microsoft Visual C++)

.gif

binary+F

GIF graphic file

.htm

text

HTML file

.html

text

HTML file

.ico

binary

Icon file

.inc

text

Active Server include file

.ini

text+w

Initial application settings file

.jpg

binary

JPEG graphic file

.js

text

JavaScript language source code file

.lib

binary+w

Library file (several programming languages)

.log

text+w

Log file

.mpg

binary+F

MPEG video file

.pdf

binary

Adobe PDF file

.pdm

text+w

Sybase Power Designer file

.ppt

binary

Microsoft Powerpoint file

.xls

binary+w

Microsoft Excel file

.zip

binary+F

ZIP compressed archive file

Note

The Perforce apple file type stores Macintosh files in the depot as a single file containing both the data and resource forks. Pre-2000.1 versions of Perforce stored Macintosh file forks as separate files in the depot. If your depots contain Macintosh files stored in this manner, upgrade the existing files to use the apple format. If you do not convert existing files after you upgrade, Perforce continues to store them using its two-file approach. For details, see "Working with CodeWarrior files" on page 52

Configuring IDEs with plug-ins

Regardless of the IDE you use, you must define a client view, add files to the Perforce depot, and configure your source control settings and preferences. The following sections provide details about these tasks.

Defining the client workspace and view

To set up the Perforce SCM environment, you define a client workspace (a directory on the client machine that contains the project files) and a client view (a mapping of the depot to your client computer). The files in your IDE projects must reside under the client workspace root (the highest-level directory of your client workspace). Your files can be put under source control only if they are located in the client workspace. You can specify a directory that already contains files, or an empty directory for a project you intend to create. You can also populate your client workspace with files from the depot which are currently under version control.

To create a client workspace and view, you must use the p4 command line client program. Note that P4SCC does not observe settings in Perforce config files. For details about client workspaces and views, refer to the Perforce User's Guide.

Add a project to source control

To add a project to source control, you specify the Perforce settings required to connect to the server where you want to store the project. You must specify the following settings:

This setting specifies the name of the host on which the server is running and the port on which the server is listening, using the following format:

IDE and Perforce host location
Required Settings
Examples

Same machine

Only port number is required

1666
1818

Different machines

Host name (or IP address) and port are required

myhost:1818
mydomain.com:2550
10.0.0.5:1666

Adding files to the depot

After you specify the settings for the server where you want to store project files, you can add the files. The exact commands required to add files to the depot depend on the IDE in which you are working. Typically you perform two steps:

  1. Add the files to a Perforce changelist by issuing a command such as Add to Source Control.

  2. Submit the changelist by issuing a command such as Check In or Submit.

Files are added when the Check In or Submit is completed.

Basic SCM tasks

The plug-ins enable you to perform the following basic SCM tasks from within your IDE:

Task
Description
Perforce activity

Add files to the depot

After you add files to your project, you add them to the depot.

Files are opened for add in a pending changelist.

Retrieve files

Get a copy of a file from the depot.

Files are synced to your computer.

Check files out

Get the latest version from the depot for editing.

Files are opened for edit in a pending changelist.

Check files in

Put your edited files in the depot as the most recent revisions.

A pending changelist is submitted.

Diff files

Compare a file with a previous revision to see what's changed.

The Perforce diff utility is launched to display differences between two versions of a file.

Revert files

Discard changes you've made to your local copy of a depot file.

The head revision is synced to your client workspace and removed from its pending changelist.

Delete files

Remove a file from a project and from the depot.

Files are opened for delete in a pending changelist.

When to go outside the IDE

Perforce plug-ins support a basic set of SCM tasks. To perform administrative tasks, you need to use the p4 command line client. For details about performing these tasks, see the Perforce User's Guide.

Tasks that require you to work outside the IDE include:

If you do perform Perforce SCM tasks outside the IDE, be sure to refresh the IDE display afterwards, to ensure that file status is updated and displayed correctly.


Perforce 2003.2 Using IDE Plug-ins
<< Previous Chapter
About This Manual
Table of Contents
Index
Perforce on the Web
Next Chapter >>
Microsoft Visual C++
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