Version Control on Mac OS X, Part 2

The first article of this series introduced you to the basics of version control, discussed some examples of using it on projects, and outlined what version control systems are available under Mac OS X. In this article, you'll get a chance to apply this knowledge by using one of the most popular version control systems, Concurrent Versions System (CVS), on a sample project under Project Builder. Specifically, you will learn how to set up CVS for remote access, import a project into CVS, and use CVS commands from within Project Builder. Before continuing, make sure you have read the first article of this series and "In Sync with CVS," by James Duncan Davidson. In addition, make sure you install the Apple developer tools, freely available from Apples developer site.

The Apple developer tools come with an IDE called Project Builder, which includes a development environment to edit, build, debug, and run Mac OS X applications. Project Builder does not include the main development tools (compiler, linker, version control, etc.) as part of the program. Instead, it uses UNIX development tools such as gcc, g++, gdb, and CVS. In a sense, Project Builder is evolutionary; it continues the line of IDE-based development environments for the Macintosh, but breaks with tradition by using external UNIX-based tools for implementing its development tasks. This strikes a nice balance by providing a modern interface for application development while leveraging the strengths of the UNIX tool set.

Project Builder supports access to CVS through its GUI. As you learned in the first article, CVS is by no means the only version control system for Mac OS X. However, it is one of the most popular systems from the UNIX world to find its way to Mac OS X, and is supported by Project Builder. For these reasons, as well as its popularity in the open source community, it makes a good choice for version control under Mac OS X.

Setting Up CVS

There are two ways to set up CVS -- for local access and for remote access. Local access means that the CVS repository is located on your development machine. With remote access, the repository resides on a machine on the network and you develop on any machine you wish, connecting to the repository over the network.

Though both methods have their advantages and disadvantages, I prefer remote access. These days, networks are ubiquitous, so I can keep my repository in one place and access it from many locations. Another good reason for choosing remote access is for use on projects with a geographically distributed development team. For example, envision the following: you and some friends want to develop a new editor for Mac OS X. Each person lives in a different part of the country. A requirement of the project is that members need to access and update each others work at any time. Since CVS is designed to work over the network, one developer sets up a CVS repository on a single, networked machine. The other developers configure their environment to remotely access the repository over the network. Now all developers have access to CVS as though the repository were accessible within their file system.

The following steps show you how to set up CVS for remote access. To do this, you will need two machines connected to the network; one that holds the CVS repository and one for development. Lets call the machine that holds the repository the "CVS remote host" and the development machine the "CVS client host."

The first step is to set up the CVS remote host. For this example, I will assume the host name of the CVS remote host is "cvshost.somedomain.edu," the username is "omalley," and the CVS repository is located in /Users/omalley/cvs-repository.

1. If necessary, create an account for yourself and others that will access to the repository.
2. Open System Preferences (located in /Applications), click on the Sharing icon, and click on the Remote Login checkbox. This runs the SSH daemon, enabling you to connect to the machine over SSH.
3. Open the Terminal application (located in /Applications/Utilities) and create a directory called cvs-repository, which will hold the CVS repository for your projects. Place this directory on a disk partition that is large enough to handle the anticipated file storage requirements. Try to be overly conservative when estimating your disk requirement. For this example, place the repository in your home directory.
   % mkdir ~/cvs-repository
4. Run the CVS initialization command to set up the repository. You only need to run this command once, before anyone uses the new repository.
   % cvs d /Users/omalley/cvs-repository init
5. Update the cvswrapper file, located in /Users/omalley/cvs-repository/CVSROOT, to properly handle binary files and bundles. To do this, see "In Sync with CVS" and Apples Project Builder documentation.

Now that the repository is ready, you can set up the CVS client host. To do this, perform the following steps on the CVS client host.

1. Generate your SSH keypair files, using the same password as your user account on the CVS remote host.

   
   % ssh-keygen -t rsa
   Generating public/private rsa key pair.
   Enter file in which to save the key (/Users/omalley/.ssh/id_rsa): 
   Enter passphrase (empty for no passphrase): 
   Enter same passphrase again: 
   Your identification has been saved in /Users/omalley/.ssh/id_rsa.
   Your public key has been saved in /Users/omalley/.ssh/id_rsa.pub.
   The key fingerprint is:
   1a:61:41:ad:a2:f2:e3:4b:d9:bd:49:af:c5:5e:46:66 omalley@G4.local.
   

2. Add your public key to the CVS remote hosts authorized_keys2 file. The following example assumes you do not have a ~/.ssh directory or an authorized_keys2 file on the CVS remote host.

   
   % scp ~/.ssh/id_rsa.pub omalley@cvshost.somedomain.edu:
   The authenticity of host cvshost.somedomain.edu (123.123.12.3)' 
   can't be established.
   RSA key fingerprint is 
   1a:61:41:ad:a2:f2:e3:4b:d9:bd:49:af:c5:5e:46:66.
   Are you sure you want to continue connecting (yes/no)? yes
   Warning: Permanently added 'cvshost.somedomain.edu,123.123.12.3' 
   (RSA) to the list of known hosts.
   omalley@cvshost.somedomain.edus password: 
   id_rsa.pub           100% 
   |*******************************************|   227       00:00    
   % ssh cvshost.somedomain.edu
   omalley@ cvshost.somedomain.edus password: 
   Last login: Mon Jul 28 20:40:10 2003 from bgp786711bgs.na
   Welcome to Darwin!
   % mkdir .ssh
   % cat id_rsa.pub > ~/.ssh/authorized_keys2 
   % rm id_rsa.pub
   % exit
   

3. Add the following lines to your ~/.cshrc file on the client host:

   
   setenv CVS_RSH ssh
   setenv CVSEDITOR emacs
   setenv CVSROOT :ext:omalley@ 
   cvshost.somedomain.edu:/Users/omalley/cvs-repository
   eval `ssh-agent`
   ssh-add
   

4. Add the following lines to your ~/.logout file on the client host. This prevents multiple ssh-agents from building up on your system by killing the process when you exit the shell.

   
   eval `ssh-agent -k`
   sleep 1
   

5. Create a directory called ~/MacOSX on the client host, create a file called ~/MacOSX/environment.plist, and add the following lines to the file:

   
   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist SYSTEM
   "file://localhost/System/Library/DTDs/PropertyList.dtd">
   <plist version="0.9">
   <dict>
           <key>CVS_RSH</key>
           <string>/usr/bin/ssh</string>
   </dict>
   </plist>
   

Log out of and back into the active account for the settings to take effect.

To Test your Configuration

1. Open a new shell in the Terminal and when prompted, enter the same passphrase (password) as you did when creating your SSH keypair files.
2. Check out CVSROOT into a temporary directory:

   
   % cd ~/tmp
   % cvs co CVSROOT .
   cvs server: Updating CVSROOT
   U CVSROOT/checkoutlist
   U CVSROOT/commitinfo
   U CVSROOT/config
   U CVSROOT/cvswrappers
   U CVSROOT/editinfo
   U CVSROOT/loginfo
   U CVSROOT/modules
   U CVSROOT/notify
   U CVSROOT/rcsinfo
   U CVSROOT/taginfo
   U CVSROOT/verifymsg
   cvs server: Updating .
   cvs server: Updating CVSROOT