Michael Vandegriend - mav@ee.ualberta.ca

Software and ASIC team projects require many different files including source code files, compiler files, and documentation files. Keeping track of these files becomes a challenging task when several different people are working with the same set of files. Without proper file management, two people can modify the same version of a file, which creates two different versions, one of which will be lost if both versions are saved to the same file name. Other problems may arise if changes are made to a working file, only to find that the changes don't work, and the original version cannot be recovered to reverse the damage. The best method to prevent these problems is to use some sort of version control system to keep an archive of the different versions of the file. While there are many different version control systems, the Revision Control System (RCS) has many useful features, is easy to use, and is readily available for UNIX. The CEB 531 lab has RCS already installed, and it is available for free from the Free Software Foundation.

In order to allow multiple people to access the same files, common, or shared, directories must be created. The CEB 531 workstations use Andrew File System (AFS), which allows users to create access lists specifying who can read, write, and execute their files. The process for creating a common directory is described in another Student Application Note at http://www.ee.ualberta.ca/~elliott/ee552/studentAppNotes/98f/unix/Account_sharing/acountshare.htm. Note that to give another user access to a specific directory, that user must have read access to all higher directories, including your home directory.

RCS keeps track of the different versions of a file by storing the differences between each version. Users must first register the original version of a file with RCS, a process known as checking in the file. Once a file is checked in, it becomes read only. To make changes to a RCS file, a user must check the file out, which 'locks' the file so that only the user can changes to the file. Locking the file prevents two people from simultaneously modifying the file, which could result in two completely different versions of the same file, or one user's work being overwritten by the other. After updating a file, the user must check the file back into RCS, which creates a new version of the file, and releases the lock so other people can then check it out for other modifications. Each revision of a file registered with RCS is given a number so that it can be referenced.

The following procedure describes the setup and basic operations of RCS.

1. Go to your working directory. This directory has the files you want to register with RCS.

2. Create a subdirectory named RCS.

3. Register your file, say project.vhd, using the 'check in', ci, command.

The file project.vhd is now registered with RCS and is labeled with revision number 1.1. The initial registering will remove the file from your current directory; however, the file can be recovered using the 'check out', co, command as described below.

4. To retrieve the latest version of the file for viewing (the file will be read only) use the co command

5. To check out and lock a file for editing use:

6. To check in a file, thereby archiving the new version and allowing others to edit the file use:

7. To recover a past version of a file, the easiest method is to check out the file by revision number.

These commands will allow you to perform basic version control.

RCS has many useful features to make project file management much easier. Note that many files can exist under a single RCS directory. To execute commands with all of these files, replace the filename in commands with RCS/*.

A RCS header containing the filename and revision number can be displayed in a RCS file. This header is created using $ID$ in a comment, which in VHDL looks like

When a file is check in the $ID$ string is expanded to include the filename and revision number. Although the header is not necessary, it should be included to identify which files are under RCS control.

The owner of the RCS directory can control who can check out files for editing. To permit people to modify a file use

where bill, ted, and sally are the user names. The -e option will revoke the ability to edit a file as in

RCS stores the version history of a file, which can be displayed using the rlog command. This command also displays the current status of the file, including who, if anyone, has locked the file and is editing it. To display the entire history and status of the file use

To check who has locked the file use

To discover the differences between two versions of a RCS file, use the rcsdiff command. Finding the difference between the current version and the previous version is done with

To find the difference between two versions use

To access one RCS directory from multiple directories, the symbolic link can be used. From the desired directory, execute the command

where username is your user name and project/source is the directory containing the RCS subdirectory. This command creates a new entry of RCS@ in your directory, which is a link to the real RCS directory. All RCS functions that could be performed in the original directory can now be performed in the new directory.

The symbolic link can be used for single files or other directories.

RCS proved crucial to finishing my portion of the Voice Controlled Remote Control project. On one occasion, I accidentally deleted one of my VHDL source code files, which is irreversible when using the rm command. Having the previous version of the file archived in RCS allowed me to quickly recover from my loss. On another occasion I made changes to working code to improve it. However, after drastically changing the file, I found out that nothing worked, but I was able to recover my working version since it was stored in RCS.

Professional ASIC design teams use RCS to manage their project files. On my last work term, I worked with a team designing a telecommunications ASIC with over 1 million gates. The team used RCS and symbolic links to manage its many different files.

Horspool, R. The Berkeley Unix Environment, 2nd ed. Prentice-Hall, Scarborough, 1992.