Perforce For Home
By FB2
Monday, February 02, 2004
Version Control on the Home Desktop
Programming (and tinkering with other people's programs) is something most of us enjoy to do at home. Mostly we just code small scripts, utilities, little databases, or blog engine No.500. Eventually, either we lose some important piece of code we wrote for our enjoyment, or the importance of version control or configuration management is something we learned to appreciate at work, so we start to look for ways to have a proper code repository for ourselves.
There are many free solutions available for the home hacker.
- The most widely used and obvious choice is CVS. It's free; there are many free resources, like books, articles, and tutorials available. It runs on most platforms, you can install a CVS server on Linux, Windows, even MacOS X. For Windows, there's even a nice installer wizard.
- One of the popular alternatives is Subversion, which aims to replace CVS, inheriting all the nice things, and adding all the features CVS users are dreaming about - like support for atomic(transactional) batch commits, proper directory operations, renames. However, Subversion is far from being a mature product, and installation is not as trivial as CVS.
- There's also a new version control system for the Real Cool Linux People, called Arch. It's gaining some positive buzz in blogs recently, but it's for Unix People only, so I can't really use it.
There's a nice article at onlamp.com about some up-and-coming version control systems, with some more free options.
At work, we use a mixture of systems, primarily based on the clients' requirements. We used Rational ClearCase, Synergy, Visual SourceSafe and CVS on one or more projects. Maybe I even missed out one or two VCSes. Synergy is basically a shame of software development, and I hope I never have to use it again. All the other tools did the job, but we always had the easiest time on any project with CVS. It has the best tool support. Every possible IDE or enterprise development tool is integrated with it. There are multiple choices for the client, including command line and a wide assortment of GUI tools. Because of the limited number of features, every usage pattern, potential problem, and possible workaround is documented. It has multiple web front-ends. Basically over the years I've become efficient with it, I know how to carry out my tasks, and I know who to call if I have a problem I can't solve for myself.
I've also grown pretty bored with it. Just as I feel I have to change my Windows theme from time to time, and I'm keep on switching browsers and media players, if I have to use something on a daily basis, it will become boring.
When I received my new home PC, I decided I'm not going to set up CVS on it, which was my home VCS during the last year or so. For a while I was toying with the idea of installing Subversion, but after reading some pretty negative comments about the installation problems, and the general state and direction of the project, I was reluctant to go through the pains to install it. During the last few years, I've been hearing mostly positive comments about a commercial product, called Perforce. I've heard from some friends about it, and some of our clients also use it, with satisfying results. Most people claimed that one of the biggest benefits is that it's as easy as CVS, without the limitations.
I wanted to find out if they had an evaluation version available, just to satisfy my curiosity. I did not really expect a downloadable version, as typically the "big" commercial vendors provide persuasive salesmen instead of downloadables. I was in for a surprise.
Get your own copy
It seems that the good folks at Perforce Software Inc. would like you to try their system. Furthermore, you don't have to sell your soul for a copy.
To download a version for your Operating System, go to their Software Download page. If you're a Windows user, like me, you only need to download the Windows Installer .
While you're there, grab the most important docs:
The links above refer to the specific (latest available) version of Perforce. It's possible that Perforce was updated since the publication of the article. Please check the following address for the latest versions:
http://www.perforce.com/perforce/technical.html
The downloadable version contains an unlicensed edition, which allows you to run the software with no time restrictions. With this version, you can use Perforce with two client PCs, and two users. Here's how they define this "unlicensed" version:
You may use software downloaded from Perforce for any purpose you want and for as long as you like. The Perforce Server supports only two users and two client workspaces unless used with a Perforce License. We will be happy to issue you a free Evaluation License to remove the user/workspace restrictions for a limited time.
This is just what I need for now. I want to use Perforce on my home desktop, and on my laptop, so the 2 client license is just enough for me. If I want to put my wife's documents under version control, I will have to go to a different solution, as the $750 user license would be way too much for home use, but let's worry about that when it becomes absolutely necessary...
Put your Configuration Manager hat on
Now that we downloaded the software and manual, let's install it! I wanted to avoid any possible misconfiguration, so I just ran the Windows Installer wizard, and I always selected the default options. I was briefly pondering about the root location for the repository, but I decided that the default Program Files/Perforce location is as good as any. In a "production" environment this would certainly be on a dedicated partition. Now that we have the Perforce Server and the Client installed, let's define the basic terminology. Every CM tool I ever tried had its own word for every possible entity and operation in the system. One of the reasons could be that they want to differentiate their product, so they look for words and metaphors which sound fresh, new, and sophisticated. Maybe they just want the opportunity to sell consulting services, to train you on these new metaphors.
This is my interpretation of the terminology used in Perforce, read the User Manual for the "official" glossary.
| Perforce | CVS equivalent | Brief Explanation |
| Depot | CVSROOT | A central repository typically used to contain the files related to a specific project. It can contain multiple modules, as a CVS root can have modules. |
| Client | no equivalent | A Client is basically a name for your workspace configuration. By default it's the host/machine name of your development PC. |
| Client Owner | User | The Client Owner is the Perforce user who creates the client, or the named user set in the specification. By default it's the logged in PC user. Note that the default installation of the Perforce Server is quite liberal: you don't have to explicitly create a new user. It is created dynamically when the new user connects to the server. |
| Client Workspace | Local Copy | A directory on your development (client) PC, where you work on the local copies of the files contained in the repository |
| Synchronization | cvs update | Applying the changes in the server repository to your local copy, or getting the initial copy from the repository |
| Submit | cvs commit | Applying the changes in your local client workspace to the central repository |
| Change List | no equivalent | A list of changes in your local workspace, like modified, added, files, which can be grouped together. For example you might want to "commit" only a subset of the changes, for example only the file changes related to a specific bug fix |
| Client Spec | partially the CVSROOT env. variable | A set of attributes, which will be used on your client PC to describe to the P4 Client, what servers, depots, ports should be used. It also describes the location of the directories on the Client PC, where the local copies of the files will be maintained. |
Basic Perforce workflows
I will now describe some simple tasks I had to carry out to put some of my home projects under revision control, using Perforce. Note that I strongly advise anyone approaching Perforce, to read at least the User Manual. There are a lot of helpful hints, and troubleshooting ideas, this article is just the crystallization of what I've gathered from reading the documentation, and trying to figure things out for myself.
Throughout the examples, I will use the P4 command line client.
1. Creating a new Depot
The first thing I would recommend to do is the creation of a new repository (depot) on the server. This will contain all of our projects. Here's the command, which I executed on the machine, which acts as the P4 Server:
p4 depot Work
Wooo, what's going on here? If you have some experience with CVS, you won't be shocked, but basically P4 pops up a text document in our favorite text editor. This is the "User Interface" of the command line client. If an operation requires further data, it will display a text form. Your job is to read the instructions on the top of the form, and then fill in your answer into the form fields. If a form field expects just a single value, then you can enter your response after the label and the ":" sign. If it can be a list of values, for example a list of files, then you have to enter every element in a new line, starting with a tab.
Here's my form for the Depot creation:
As you can see, P4 actually filled in the form for me. I only have to approve it by closing the editor window. In a later example, you will see the "Submit" form, where the developer must fill in some fields, before P4 accepts it. If you need more information about a particular command, you can just execute the command with the first parameter being help. In our case it would be "p4 help depot". If you mess up the order, and accidentally you try to get help by typing "p4 depot help", you will have a new Depot called "help". Use the "p4 depot -d help" command to get rid of it. I needed to do it, too...
2. Configuring the local workspace
After we have a new, clean Server depot for us, we will need to properly configure the Client PCs. You can do that, by running the following command on the client PC:
p4 client
Here's the form displayed by P4 on my laptop:
It is very important to get this form right, as this will configure the way our P4 client accesses the server, and this will define the local folders, which need to be mapped to server directories. It took me a while to figure out all the correct settings. Very likely you will only have to change Root and View in your client spec form.
- Root setting: that's the Parent folder of your project folders, on your local clients.
- View setting: This setting allows you to map directories on the server Depot to your local file system. This is an enumeration, you can map multiple folders. In my example, I map two projects on the local "c:\work" directory, specified as the Root directory, to two separate directories in the Depot.
-
- The right side of the View setting is the path of the client side files
- The left side of the View setting is the path of the files to be mapped, relative to the root of the Depot.
- the "\..." path element means all files, folders, and subfolders within a directory
So, on my local file system, I have a directory: "c:\work\attache". I store one of my toy coding project's files. Also, I have a directory, "c:\work\city" for a different project. I've mapped these directories to be synchronized with the "city" and "attache" directories of the server Depot.
3. Adding your files
Ok, this will be easy. You can add any file with the "p4 add" command. You don't have to add directories, just the files.
p4 add *.java
Note that now you're just scheduling these files to be added to the repository, you'll need to submit your change list to get the files in the Depot.
4. Submitting your change list
When you've completed your changes/additions/bugfixes in your local workspace, you will need to submit your changes to the server.
p4 submit
P4 will display the "Submit" form for us. We basically have to describe the nature of the changes (for example "I fixed all the bugs") in the description field, and then we can submit our changes. Note that if you worked with CVS for a long time, probably you will automatically enter the comments on the top of the form, which is the "CVS way". In P4, you have to navigate to the correct form field. Below the form fields, you will see the list of changed files, and the type of the change. You have the option to remove certain files from the list. This allows you for example to submit changes only for a specific bugfix, while keeping the changed files related to a different bugfix "checked out".
Unless there was a conflict, which is unlikely, because we just created the repository, the new files will be added to our Depot. The files we've just added to the Depot will be flagged as read-only. If we want to update them, we will have to notify the P4 server about our intention.
p4 edit somefile.txt
The Perforce manual describes the way you can edit your files if you're not connected to the server, but apparently P4 really prefers to work in an on-line mode, as a client-server application. CVS stores some local information about the files you've updated from your server. That's why you have all those CVS directories, when you check out something from a CVS server. Perforce stores these settings and state information on the server.
5. Synching the other PC
One of the reasons I've installed Perforce is to make sure that I can work on my home projects on my laptop, and on the desktop PC. I configured my laptop to access the Perforce server, then I created the Depot, and as a last step, I've imported the relevant projects from my laptop's hard drive. Now it's time to get the project files to the other PC. Basically I had to do the same configuration steps. I've configured the client spec, to make sure that I have access to the Perforce server, and I've mapped the proper server directories to my local workspace. Because the files are already in the repository, I just have to synchronize my local workspace with the server.
p4 sync
After the sync process, I have the same project files on the desktop PC. If I want to edit something, I just have to use "p4 edit", and I can also add new files to the repository. If I start to change the same file on both PCs, Perforce has quite sophisticated merge mechanism, which will allow me to consolidate the changes.
See? That was easy!
I think these basic concepts are enough to give you a kick start. The documentation is certainly good enough to help you through the advanced topics, like branching, and merging.
Perforce has some basic features which could allow you to maintain your task list, it has sophisticated reporting capabilities, and API hooks for customization and scripting.
A lot of tools and IDEs have plugins for Perforce, so if you prefer to work with the VCS from within your development tool, you should certainly look around for existing solutions.
Personally I prefer to use the command line client. When I'm working with a VCS system, I have to be in a quite different mind set from the normal coding activities. I have to be careful about what I submit into the repository, and I have to make sure I will not break the build, or disable someone else's already submitted work, so I really have to pay attention to the configuration management workflow. Working outside the coding IDE gives me a "visual clue" to make this context switch in my brain.
By the way, Open Source projects may be eligible for free Perforce licenses, but then they have to give "read" access to Perforce Software Inc. to the project repository, and they have to renew the license on a yearly basis. Both of these seem to be pretty strong requirements, but you'd probably provide anonymous CVS access to your project anyway, and if you don't get a new license for some reason or another after a year, you still have the option to migrate your project to something else.