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 SCC Plug-in: based on the Microsoft Source Code Control (SCC) API and has been tested with the following IDEs:
- Microsoft Visual C++, Visual Basic, and Visual Studio .NET
- TogetherSoft Together
- Perforce CodeWarrior Plug-in: supports Metrowerks CodeWarrior for Macintosh and Windows, and is based on their proprietary API.
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
|
- 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
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:
- 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 the Perforce User's Guide for details.
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.
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