Quick Guide to Perforce

Introduction

Perforce can be used for free if you only need two users (login) and two client workspaces (computer). You can switch users through the Win4 client (User | View Users, select a user, and select User | Switch to...), and clients (ClientSpec | View Client Specs,

In Perforce jargon, a "client" is a user profile, which includes an "owner" (user), a "host" (computer from which the user will connect to the p4d server), and a "workspace" (a directory on his computer where files will be checked out from the depot). When used in evaluation mode, a Perforce server only allows up to two clients.

P4d is the server daemon. It creates a bunch of db.* files when started. The client application is either p4 (command line-based), or p4win (GUI-based; No graphical client is available for Linux.) Files are kept in a depot on the server where Perforce is running. A server can handle more than one depot, and client workspaces can be located in remote networks. Perforce recommends against replicating a depot on another, remote Perforce server, because it increases the risk of merging conflicts. (From online documentation) Performance can be increased for remote users by using restrictive client views and access permissions so that each user is accessing only the depots and subdirectories s/he is working on.

Windows users at network-bound sites will be more efficient using the Perforce p4 command line interface rather than the P4win GUI, because the current release of  P4win makes frequent behind-the-scenes data update requests from the server.

Support for accesing remote depots

The Perforce remote depot support allows you to access files from a venus:1666 depot while you are connected to mars:1666 as your local server. For instance, you could define a remote depot called "//venus" with a mapping to the venus:1666 "//depot2" path.  Once you've done this, you can use p4 commands to refer to files in the //venus path. E.g., p4 diff2 //venus/elm2.1/... //depot/elm2.1/... diffs all the files in the venus:1666 //depot2/elm2.1 path with their counterparts in the mars:1666 //depot/elm2.1 path.

When you access files in the //venus path, p4 is not communicating directly with the venus:1666 server. Instead, your p4 (or P4win) program communicates with the mars:1666 server, which in turn communicates with the venus:1666 server.

Limitation: Access is read only, Servers must be running the same 'p4d' versions, NT servers and Unix servers are incompatible, No metadata access, label and client names are those on the local server (Files in a remote depot may be accessed by label name or client name, but the local server's label and client specifications will be used in these cases), One-sided integration records, Remote access can seriously degrade local performance

Conclusion: Use remote depots to share code, read-only, with remote sites that do not need to make any change to the code. If they do, they'll have to connect to the original server where live data live.

Perforce for Windows

As a first test, we'll install both the server and the client on the same NT host:

  1. Download and install perforce.exe from http://www.perforce.com. Make sure that the perforce.exe that you download does contain both the server and the client for NT.
  2. Select Perforce Administrator Install (Typical)
  3. The default port on which the server listens is 1666. Choose your favorite text editor. If you installed perforce.exe as the local administrator, the Perforce server (p4d) will also be installed as an NT service, started after the install, and marked to start automatically at boot time.

    The username is the NT user account with which you are connected while installing this copy of Perforce
     
  4. Create a client workspace, ie. any directory where files will be copied when they're checked out from the Perforce repository (located in c:\Program Files\Perforce\depot\). Let's use C:\p4client\
  5. Put a couple of files in that new directory so we can test adding files to the Perforce repository
  6. Start up the Windows client P4Win from the Start | Program group
  7. ClientSpec | Edit: Root=C:\p4client. Click on Update
  8. ChangeList | View Pending Changelists
  9. Launch Windows Explorer, and drag-n-drop the test files you put in c:\p4client into P4Win's Pending Changelists pane on the right hand-side
  10. Click on OK in the pop-up dialog.
  11. In the Pending Perforce Changelists tree, click on the Pending Changelists to view the test files you just added
  12. Right-click on the Default tree item, and select Submit in the pop-up menu
  13. Add a dummy description (eg. "Original files"), and click on Submit. The files have been added to Perforce's repository ("depot"), and can be viewed in the Client View of Perforce Depot tree on the left hand-side
  14. To remove files from the Depot, select them in the Perforce Depot tree, right-click, and choose Open for Delete (No such item now! Must check files out in client workspace, and delete them?)
  15. To view these test files in read-only mode (ie. they are not checked out, and hence, should not be edited since Perforce won't handle the changes), just double-click on any file in the Perforce Depot tree
  16. To check out and edit one or several files, select them in the Depot tree, right-click, and select Open for Edit
  17. In the right-hand Pending Changelists section, right-click on ONE file, select Edit Using in the pop-up menu, and select Associated Editor (to use the default editor that you selected when installing Perforce), or Other editor
  18. Once you are through working on the test files that you checked out from the Depot, go back to P4Win, right-click on the Default section in the Pending Perforce Changelists, and choose Submit
  19. To view changes made on files in the depot, select Changelist | View submitted changelists
  20. Double-clicking on any item in the Changelist shows which operations were performed that time
  21. To branch a file...
  22. To view what changes were made between two revisions of a file, right-click on the file in the Perforce Depot tree, select Revision History...
  23. In the Revision History dialog, select the two revisions that you want to compare, and click on Diff Revs

P4d on Linux and P4Win on NT

[root@mylinux administrator]# ./p4d -h
Usage:
 
    p4d [ options ]
    p4d -j? [ -z ] [ args ... ]
 
        The first form starts the Perforce server.
        The second form performs checkpoint/journaling operations.
 
    Server options:
        -d              run as a daemon (fork first, then run)
        -f              run as single-threaded server
        -i              run for inetd (socket on stdin/stdout)
        -q              suppress startup messages
        -s              run as an NT service (or invoke as p4s)
        -xu             run database upgrades and quit
 
    Checkpointing options:
        -jc [ prefix ]  checkpoint, then save and truncate journal
        -jd [ file ]    checkpoint without saving/truncating journal
        -jj [ prefix ]  save and truncate journal
        -jr file        restore incrementally from file
        -z              gzip checkpoint/journals
 
    General Options:
        -h -?           print this message
        -V              print server version
 
        -J journal      set journal file (default $P4JOURNAL, 'journal')
        -L log          set error log (default $P4LOG, stderr)
        -p port         set listen port (default $P4PORT, 1666)
        -r root         set server root directory (default $P4ROOT)
        -v level        debug modes (default $P4DEBUG)

 

Tech Notes

While the Client workspace (eg. C:\P4CLIENT in the example above) holds files while they're checked out, Perforce keeps the File Depot in its depot\ sub-directory (eg. d:\Program Files\Perforce\depot\). Perforce seems to use RCS as its file format, and files are kept in the depot even after having been marked as deleted through the Perforce client, probably to protect the innocents.

When checking a file out, it is not automatically extracted from the depot into the client workspace, so if you removed files from the client workspace...

TO TRY

Temp stuff

Typically each engineer user has his or her own dedicated client  workspace, and may also use other special-purpose or project  workspaces.  The client workspace specification defines a view, or  subset, of files from the repository that are of interest to the user.  The workspace itself contains physical copies of the files in its view.

The Perforce Server comprises three main sub-components:  a  request handler, a data manager and a file librarian.  The  request handler acts as an executive, sequencing actions to  carry out client requests and managing communication with  the client.  The data manager implements optimized database  services based on the Berkeley DB database package,  customized for multi-user support.  It maintains a meta-database describing the status and history of versioned files in  the depot and transactions against the depot.  The librarian is a highly efficient file archiver that stores  repository files on disk local to the server. It writes  text file versions in an RCS-compatible, reverse-delta format;  binary file versions are stored in a standard compressed format.

WebKeeper module, which uses the Perforce API to enable an Apache HTTP web server to act as a Perforce client and request versioned files directly from a Perforce server.

P4FTP allows FTP clients, including Dreamweaver, Netscape, and Internet Explorer, to access Perforce depot files via FTP.  It can be installed in addition to or instead of an FTP server on Unix or Windows NT/2000.

Perfbrowse - Web/Perforce Browser: This simple depot browser is implemented in Perl 4 and runs as a CGI script on your web server. It allows you to browse your Perforce depot using a normal web browser.

P4DB - Web/Perforce Browser: Another way to browse your Perforce depot via the Web is withP4DB. Lots of features; provides some nice reporting and cross-referencing. Contributed by Fredric Fredriksson of MYDATA Automation.

Change Tracking

Perforce provides a primitive change tracking system. Change requests are "jobs," and the developer can link many changelists to one job or one changelist to many jobs.

However, Perforce needs a much better change tracking tool before it can be considered a change management system. Fortunately, a "Defect Tracking Integration" is due for release in March 2001, and by the time you read this, the integrations to TeamShare's TeamTrack (see Dana Cline's "Tracking Bugs on the Web," Nov. 1999) and Mozilla's (www.mozilla.org) Bugzilla should be available. (The beta copies of these integrations are available at www.ravenbrook.com.) During integration, the change information is copied from the Perforce job record to the change tracking tool record, and vice versa. It purportedly integrates the benefits of Perforce's configuration management, especially changelists, with the benefits of a change tracking tool.  P4DTI.

Username = NT User

When booting, client = "<NT hostname> has not been defined"

When creating first client, owner = Fred is defined when installing the application?

To edit a user, switch to it first

To add files to depot, must be located in workspace, then click on Submit

Why no edit from remote host?

To uninstall Perforce, run install EXE

Q&A

How to undelete a file that is marked as To Delete in the Changelist?

What's the difference between a user, a client, and an owner?

Guess a client is an instance of Perforce that is installed on a given computer, while a user is an account defined in the Perforce server

Resources