Perforce 2007.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). The Perforce SCC Plug-in is installed when you install Perforce on Windows, and is based on the Microsoft Source Code Control (SCC) API and has been tested with Microsoft Visual C++, Visual Basic, and Visual Studio .NET. For details about supported versions of each IDE, refer to the release notes for the plug-ins.

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

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:

http://www.perforce.com/perforce/technical.html

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 Introducing Perforce.


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.

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.

Configuring Perforce preferences for Visual Studio IDEs

To configure Perforce preferences, display the settings control panel by choosing the corresponding menu entry:

Visual Studio .NET: Tools > Options > Source Control >SCC Provider and click Advanced...
Visual Basic 6.0: Tools > Perforce > Options and click Advanced...
Visual C++ 6.0: Tools > Options, scroll right and click the Source Control tab and click Advanced...

The following sections describe the Perforce settings you can configure on each tab.

General tab

Option
Description

Date format

Specifies whether dates are displayed using the operating system format or the Perforce format.

Log options:

Log All

Logs all commands sent to the Perforce server. To log only user-initiated commands, disable this option.

Enable logging to file

Specifies the name, location and maximum size of the log file.

Enable diff2 on file-to-file drag and drop

Enables you to diff files in the depot using drag and drop. To prevent inadvertently launching a diff (if you never use drag-and-drop diffing), disable this feature.

Warn before reverting files

Displays a dialog enabling you to change your mind before reverting files. When you revert an open file, any changes you made are discarded.

Option	Description
Date format	Specifies whether dates are displayed using the operating system format or the Perforce format.
Log options:
Log All	Logs all commands sent to the Perforce server. To log only user-initiated commands, disable this option.
Enable logging to file	Specifies the name, location and maximum size of the log file.
Enable diff2 on file-to-file drag and drop	Enables you to diff files in the depot using drag and drop. To prevent inadvertently launching a diff (if you never use drag-and-drop diffing), disable this feature.
Warn before reverting files	Displays a dialog enabling you to change your mind before reverting files. When you revert an open file, any changes you made are discarded.

Connection tab

Option
Description

When binding a project to source control

Specifies how you want to configure the Perforce server and workspace associated with the solution.

Show the Perforce connection dialog: enables you to specify the settings manually.

Bind to the workspace that matches your Perforce environment settings: uses the settings in effect when you add the project ("global" settings).

If you are adding a solution that contains a large number of projects, choose Bind to the workspace that matches your Perforce environment settings and configure the `P4PORT` and `P4CLIENT` settings to specify the server and workspace. If you choose Show the Perforce connection dialog, you must manually enter settings for each project in the solution.

When connecting to a server

Show Remember Password dialog

For 2003.2 server and below: if enabled, the plug-in displays a "Remember Password" dialog when prompting you for your password. If disabled, the plug-in prompts you every time the Perforce server requires your password.

Show Login Expiration dialog

For 2004.2 server and above: Enables/disables display of login-related dialogs. Perforce servers that are running in a high security mode can set a session time limit. After the session expires, you are prompted to log in when you attempt another Perforce operation.

Unicode servers

Set encoding for all connections

Specifies encoding used on client machine when connecting to a Perforce Server that is running in Unicode mode. DO NOT SET unless you know for sure that your server is running in Unicode mode.

Option	Description
When binding a project to source control	Specifies how you want to configure the Perforce server and workspace associated with the solution. Show the Perforce connection dialog: enables you to specify the settings manually. Bind to the workspace that matches your Perforce environment settings: uses the settings in effect when you add the project ("global" settings). If you are adding a solution that contains a large number of projects, choose Bind to the workspace that matches your Perforce environment settings and configure the `P4PORT` and `P4CLIENT` settings to specify the server and workspace. If you choose Show the Perforce connection dialog, you must manually enter settings for each project in the solution.
When connecting to a server
Show Remember Password dialog	For 2003.2 server and below: if enabled, the plug-in displays a "Remember Password" dialog when prompting you for your password. If disabled, the plug-in prompts you every time the Perforce server requires your password.
Show Login Expiration dialog	For 2004.2 server and above: Enables/disables display of login-related dialogs. Perforce servers that are running in a high security mode can set a session time limit. After the session expires, you are prompted to log in when you attempt another Perforce operation.
Unicode servers
Set encoding for all connections	Specifies encoding used on client machine when connecting to a Perforce Server that is running in Unicode mode. DO NOT SET unless you know for sure that your server is running in Unicode mode.

Diff tab

Option
Description

Default diff application

Enables you to select the application that is used to diff your files. Optionally enables you to configure different applications for specific file types.

Option	Description
Default diff application	Enables you to select the application that is used to diff your files. Optionally enables you to configure different applications for specific file types.

Merge tab

Option
Description

Default merge application

Enables you to select the application that is used to perform three-way merges when you resolve files.

Option	Description
Default merge application	Enables you to select the application that is used to perform three-way merges when you resolve files.

Version tab

This tab displays version information about the Perforce SCC Plug-in.

Font tab

This tab enables you to configure the font used by Perforce merge and Time-lapse View utilities.

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 Perforce Command-Line Interface (P4) program. Note that P4SCC does not observe settings in Perforce config files. For details about client workspaces and views, refer to Introducing Perforce.

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:

Server host and port

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`

User name: your Perforce user name.
Password: (optional) your Perforce user password.
Client workspace: the name of the client specification describing the workspace where you work on local copies of project files.

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:

Add the files to a Perforce changelist by issuing a command such as Add to Source Control.
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

To perform administrative tasks, you need to use the p4 command line client. For details about performing these tasks, see the Perforce Adminstrator's Guide.

Tasks that require you to work outside the IDE include:

Modifying a client view or user password: you can create a client specification or user through the Connection dialog when adding a project to source control, but to modify it subsequently, you must use another Perforce client program (the p4 command line, P4Win, or P4V).
Creating branches and labels: these and other administrative tasks must be done using the p4 command. Refer to Introducing Perforce for basics.

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.