|
|
|
Chapter 1
Perforce Concepts
|
|
Perforce facilitates the sharing of files among multiple users. It is a software configuration management tool, but software configuration management (SCM) has been defined in many different ways, depending on who's giving the definition. SCM has been described as providing version control, file sharing, release management, defect tracking, build management, and a few other things. It's worth looking at exactly what Perforce does and doesn't do:
- Perforce offers version control: multiple revisions of the same file are stored, and older revisions are always accessible.
- Perforce provides facilities for concurrent development; multiple users can edit their own copies of the same file.
- Some release management facilities are offered; Perforce will track which revisions of which files are part of a particular release.
- Bugs and system improvement requests can be tracked from entry to fix; this is known as defect tracking.
- Perforce supplies some lifecycle management functionality; files can be kept in release branches, development branches, or in any sort of needed file set.
- Change review functionality is provided by Perforce; this allows users to be notified by email when particular files are changed.
- Although a build management tool is not built into Perforce, we do offer a companion freeware product called Jam - Make(1) Redux. Jam and Perforce meet at the file system; source files managed by Perforce are easily built by Jam.
Perforce excels at all file management functions. Although Perforce was built to manage source files, it can manage any sort of on-line documents. It can be used to store revisions of a manual, to manage Web pages, or to store old versions of operating system administration files. Its branching functionality, which allows copies of files to evolve separately from the files they were copied from, is unparalleled in the industry. And Perforce is extremely fast.
Note
|
You don't need to read the rest of this chapter if you don't want to. All the material discussed here is also covered in the `how-to' chapters, which comprise the rest of the manual. This chapter is provided as a guide to what Perforce does, without the details of how to do it.
|
|
Perforce Architecture
|
|
Perforce has a client/server architecture, in which many computers, called clients, are connected to one central machine, the server. Each user works on a client; at their command, files they've been editing are transferred to and from the server. The clients communicate with the server via TCP/IP.
The Perforce clients may be distributed around a local area network, wide area network, dialup network, or any combination of these. There can also be Perforce clients on the same host as the server.
Two programs do the bulk of Perforce's work:
- The p4d program is run on the Perforce server. It manages the shared file repository, and keeps track of users, clients, protections, and other Perforce metadata.
- p4d must be run on a UNIX or Windows/NT host.
- The p4 program is run on each Perforce client. It sends the users' requests to the p4d server program for processing, and communicates with p4d via TCP/IP.
- p4 client programs can be run on many platforms, including UNIX, Windows, VMS, Macintosh, BeOS, and Next hosts.
This manual assumes that either you or a system administrator has already installed both p4 and p4d. You'll find instructions for this in our System Administrator's Guide, available at our Web site.
|
Moving Files Between the Clients and the Server
|
|
Users create, edit, and delete files in their own directories on the clients; these directories are called client workspaces. Perforce commands are used to move files to and from a shared file repository on the server known as the depot. Perforce users can retrieve files from the depot into their own client workspaces, where they can be read, edited, and resubmitted to the depot for other users to access. When a new revision of a file is stored in the depot, the old revisions are kept, and are still accessible.
Files that have been edited within a client workspace are sent to the depot via a changelist, which is a list of files, and instructions that tell the depot what to do with those files. For example, one file might have been changed in the client workspace, another added, and another deleted. These file changes might be sent to the depot in a single changelist, which is processed atomically: either all the changes are made to the depot at once, or none of them are. This allows problem fixes that span multiple files to be updated in the depot at exactly the same time.
Each client workspace has its own client view, which determines which files in the depot can be accessed by that client workspace. One client workspace might be able to access all the files in the depot; another client workspace might access only a single file. The Perforce server is responsible for tracking the state of the client workspace; Perforce knows which files a client workspace has, where they are, and which files have write permission turned on.
Chapters 3 and 4 teach the basics of using Perforce.
|
File Conflicts
|
|
When two users edit the same file, it is possible for their changes to conflict. For example, suppose two users copy the same file from the depot into their workspaces, and each edits his copy of the file in different ways. The first user sends his version of the file back to the depot; subsequently, the second user tries to do the same thing. If Perforce were to unquestioningly accept the second user's file into the depot, the first user's changes would not be included in the latest revision of the file (known as the head revision).
When a file conflict is detected, Perforce allows the user experiencing the conflict to perform a resolve of the conflicting files. The resolve process allows the user to decide what needs to be done: should his file overwrite the other user's? Should his own file be thrown away? Or should the two conflicting files be merged into one? At the user's request, Perforce will perform a three-way merge between the two conflicting files and the single file that both were based on. This process generates a merge file from the conflicting files: the merge file contains all the changes from both conflicting versions, and this file can be edited and then submitted to the depot.
To learn how to resolve file conflicts, please see chapter 5.
|
Labeling Groups of Files
|
|
It is often useful to mark a particular set of file revisions for later access. For examples, the release engineers might want to keep a list of all the file revisions that comprise a particular release of their program. This list of files can be assigned a single mnemonic name, like release2.0.1; this name is a label for the user-determined list of files. At any subsequent time, the label can be used to copy the old file revisions into a client workspace.
You'll learn about labels in chapter 8.
|
Branching Files
|
|
Thus far, it has been assumed that all changes of files happen linearly. But this is not always the case: suppose that one source file needs to evolve in two separate directions; perhaps one set of upcoming changes will allow the program to run under VMS, and another set will make it a Mac program. Clearly, two separately evolving copies of the same files are necessary.
Perforce's Inter-File BranchingTM mechanism allows any set of files to be copied within the depot. By default, the new file set, or codeline, evolves separately from the original files, but changes in either codeline can be propagated to the other.
We're particularly proud of Perforce's branching mechanism. Most SCM systems allow some form of branching, but Perforce's is particularly flexible and elegant.
The mechanism of Inter-File Branching is covered in chapter 9.
|
Job Tracking
|
|
A Job is a generic term for a plain-text description of some change that needs to be made to the source code. A job might be a bug description, like "the system crashes when I press return", or it might be a system improvement request, like "please make the program run faster."
Whereas a job represents work that is intended to be performed, a changelist represents work actually done. Perforce's job tracking mechanism allows jobs to be linked to the changelists that implement the work requested by the job. A job can later be looked up to determine if and when it was fixed, which file revisions implemented the fix, and who fixed it. The fields contained in your system's jobs can be defined by the Perforce system administrator.
Perforce's job tracking mechanism does not implement all functionality normally supplied by full-scale defect tracking systems. Its simple functionality can be used as is, or it can be integrated with a full-scale job tracking system with a scripting language like Perl or Python.
To read more about jobs, please see chapter 10.
|
Change Review, Daemons, and Triggers
|
|
Perforce's change review mechanism allows users to receive email notifying them when particular files have been updated in the depot. The files that a particular user receives notification on is determined by that user. Change review is implemented by an external Perl program, or daemon, and can be recoded by a knowledgeable user, allowing change review functionality to be customized.
External scripts can be run automatically by Perforce whenever changelists are submitted. These scripts, called triggers, allow files to be validated before they're submitted to the depot.
We discuss change review from the user's perspective in chapter 6. To learn how to set up the change review daemon, or how to write your own daemons, you'll need to consult our System Administrator's Guide.
|
Protections
|
|
Perforce provides a protection scheme to prevent unauthorized or inadvertent access to the depot. The protection mechanism determines exactly which Perforce commands are allowed to be run by any particular client.
Permissions can be granted or denied based on users' usernames and IP addresses, or can be granted or denied to entire groups of users. Since Perforce usernames are easily changed, protections at the user level provide safety, not security. Protections at the IP address level are as secure as the host itself.
We discuss protections in our System Administrator's Guide.
|
|
|
|
Please send comments and questions about this manual to
[email protected].
Copyright 1997, 1998, 1999, 2000 Perforce Software. All rights reserved.
Last updated: 02/16/00
|