jon parise // friday, june 22, 2018

Source Management with Perforce

Jon Parise <jon@csh.rit.edu>

Introduction

About a year ago, a few of us here at RIT's Computer Science House began discussing solutions for source code management. The House has accumulated a good deal of legacy source code from various projects over the past twenty-odd years of its existence, and we decided it would be a good idea to centralize everything in a central code repository. The repository needed to be accessible via the network, support multiple users, and offer client software for a wide range of hardware and software platforms.

It seemed as though CVS (from Cyclic Software) would be the obvious solution. Having worked with CVS in the past, I was already familiar with its organization and functional metaphors. It fulfilled all of our needs, and it was freely available. CVS support is also plentiful among popular development tools, and there are numerous third-party add-ons available. In addition, countless public software projects (including all of the BSD source trees, Mozilla, GNOME, etc.) are managed using CVS.

It therefore may be surprising to hear that we didn't end up choosing CVS as our source code management solution.

Enter Perforce

A large number of House members are loyal BeOS users and developers. We learned that Be, Inc. was using a commercial software solution to manage their (probably unwieldy) source trees. The product was named Perforce, produced by the company of the same name. We thus decided it was worth investigating, if simply out of pure curiosity. Like most, we had never heard of Perforce.

Perforce, being a commercial product, was undoubtedly going to be out of our price range, or so we though until we discovered this paragraph:

Bona fide organizations developing freely available software (e.g. products distributed under the Berkeley or GNU copyrights) may be eligible to obtain Perforce servers for FreeBSD or Linux gratis. This includes upgrades but not support. Execution of a Perforce License Agreement for Free Software Development is required. Contact us for more information.

(http://www.perforce.com/perforce/price.html)

We contacted Perforce, explained to them how we fit the above requirements, and they bestowed upon us a free server license with support for two hundred client users. Note that while the above only mentions FreeBSD that the server software runs perfectly well under OpenBSD. I have not personally tried it under NetBSD or BSDI, but I don't see a reason why it wouldn't run under those platforms as well.

There is an evaluation version of the server that is freely downloadable from the Perforce site. It supports a maximum of two client users, but aside from that, it is fully functional. Once you've received a license key, your evaluation installation will be upgraded to the full version, and your configuration will remain intact.

The Basics

The following is a rather informal attempt to familiarize the reader with the basic workings of the Perforce system. This is not intended as a tutorial. In-depth tutorials and user documentation are available in numerous formats on the Perforce web site.

For those already familiar with CVS, the basic Perforce operations will straight-forward. Beware not to attempt to bend all of the Perforce functions to their CVS counterparts. They are two entirely different paradigms. The basic functionality, however, is very similar.

Perforce follows a client / server model. The source repository is located on and maintained by the server, along with various accounting mechanisms such as user management, system logging, and permissions control. The server also has various duties such as maintaining versions and tracking changelists.

Perforce uses the concepts of depots and clientviews to describe the relationship between the server and client environments. Depots describe a section of the whole repository. A depot is generally created for each project managed by the server. Clientviews are user-defined views into the repository. They can be composed of one or more depots, or smaller selections of them, allowing a tremendous deal of flexibility. Each user can have one or more clientviews defined, and switching between them, akin to switching between workspaces, is as easy as changing the value of an environmental variable.

All operations between the client and server are performed using a commandline program named 'p4'. Graphical clients are also available for various platforms, but the commandline interface is standard. Commands are issued using the form 'p4 command [arguments]'. Detailed help is available simply by issuing the command 'p4 help [topic]'.

Users add, edit, and remove local files using the commands 'p4 add', 'p4 edit', and 'p4 remove'. These actions are recorded in a changelog. Like CVS, no local change is committed to the repository until the user actively submits the current changelist (using 'p4 submit'). Local files are synchronized with those on the remote repository using the command 'p4 sync'.

Establishing a Server

Setting up a server is a relatively simple task. Create a directory in which the Perforce server will store its file. This includes both the system's configuration files and the source repository. In this example, we'll assume the directory you've created is /perforce. Next, create a new user ('perforce', in this example) and give that user ownership over the /perforce directory. Then, start the server process. I use the following command:


    su perforce -c '/usr/local/sbin/p4d -p 1818 -r /perforce'

This will start the server on port 1818 with the Perforce root directory set to /perforce.

Assuming the server process started cleanly, you can proceed to configure the system through the 'p4' client tool. Begin by creating yourself a Perforce user account using the command 'p4 user'. Once your have a user defined, you'll want to explore the following commands:


    p4 info                     Reports server information
    p4 depot [depotname]        Creates new source depots
    p4 protect                  Sets protection (permission) rules

All of the above is explained in far greater detail in the Perforce documentation.

Additional Notes

The Perforce system is quite extensible. A client API package (complete with static libraries, header files, and sample source code) is freely available from the Perforce site. There are also hooks for running scripts (for reporting or validation) at various submission stages.

There is a wealth of contributed software available on the Perforce site, including graphical clients, source browsing scripts, CVS and RCS to Perforce conversion scripts, and additional merge and diff tools. Perforce has even developed a module for the Apache web server (called WebKeeper) that effectively puts the entire document tree under source control.

Conclusion

We at Computer Science House are clearly impressed with the capabilities Perforce has to offer. While we'll probably never use some of the more advanced features in our smaller, more manageable projects, it is clear that larger software firms will surely benefit from Perforce's advanced source management competency.