Development Tools
*****************

Here are some tools that you might find useful while developing code.

Tags
====

Tags are an index to the functions and global variables declared in a program.  Many editors, including Emacs and vi, can use them.  The Makefile in pintos/src produces Emacs-style tags with the command make TAGS or vi-style tags with make tags.

In Emacs, use M-. to follow a tag in the current window, C-x 4 . in a new window, or C-x 5 . in a new frame.  If your cursor is on a symbol name for any of those commands, it becomes the default target.  If a tag name has multiple definitions, M-0 M-. jumps to the next one.  To jump back to where you were before you followed the last tag, use M-*.

CVS
===

CVS is a version-control system.  That is, you can use it to keep track of multiple versions of files.  The idea is that you do some work on your code and test it, then check it into the version-control system.  If you decide that the work you've done since your last check-in is no good, you can easily revert to the last checked-in version.  Furthermore, you can retrieve any old version of your code as of some given day and time.  The version control logs tell you who made changes and when.

CVS is not the best version control system out there, but it's free, it's fairly easy to use, and it's already available on the Leland machines you're using for the projects.

For more information, visit the CVS home page.

Setting Up CVS
--------------

To set up CVS for use with Pintos on the Leland machines, start by choosing one group member as the keeper of the CVS repository. Everyone in the group will be able to use the CVS repository, but the keeper will actually create the repository, keep its files in his or her home directory, and maintain permissions for its contents.

The keeper has to perform several steps to set up the repository. First, create a new AFS group for the repository by executing pts creategroup KEEPER:pintos-cvs, where KEEPER is the keeper's Leland username.  Then, add each group member to the new group by repeatedly using the command pts adduser -user USERNAME -group KEEPER:pintos-cvs, where USERNAME is the name of a group member.  After the group is created and its members added, pts membership KEEPER:pintos-cvs should report that each group member is a member of the KEEPER:pintos-cvs group.

The keeper now creates the repository directory and gives the group members access to it.  We will assume that the repository will be in a directory called cvs in the keeper's home directory.  First create this directory with mkdir $HOME/cvs, then give group members access to it with fs setacl -dir $HOME/cvs -acl KEEPER:pintos-cvs write.  Group members also need to be able to look up the cvs directory in the keeper's home directory, which can be enabled via fs setacl -dir $HOME -acl KEEPER:pintos-cvs l (that's letter ``ell,'' not digit ``one.''). (This command will allow group members to list the files in your home directory, but not read or write them.  It should not create a security risk unless the names of files in your home directory are secret.)

Now initialize the repository. To initialize the repository, execute cvs -d $HOME/cvs init.

Finally, import the Pintos sources into the newly initialized repository.  If you have an existing set of Pintos sources you want to add to the repository, cd to its pintos directory now. Otherwise, to import the base Pintos source tree, cd to /usr/class/cs140/pintos/pintos (note the doubled pintos).  After changing the current directory, execute this command:

     cvs -d $HOME/cvs import -m "Imported sources" pintos foobar start

Here is a summary of the commands you have now executed:

     pts creategroup KEEPER:pintos-cvs
     pts adduser -user USERNAME -group KEEPER:pintos-cvs
     mkdir $HOME/cvs
     fs setacl -dir $HOME/cvs -acl KEEPER:pintos-cvs write
     fs setacl -dir $HOME -acl KEEPER:pintos-cvs l
     cvs -d $HOME/cvs init
     cd /usr/class/cs140/pintos/pintos
     cvs -d $HOME/cvs import -m "Imported sources" pintos foobar start

The repository is now ready for use by any group member, as described below.  Keep in mind that the repository should only be accessed using CVS commands---it is not generally useful to examine them by hand, and you should definitely not modify them yourself.

Using CVS
---------

To use CVS, start by check out a working copy of the contents of the CVS repository into a directory named DIR, execute cvs -d ~KEEPER/cvs checkout -d DIR pintos, where KEEPER is the CVS keeper's Leland username.

At this point, you can modify any of the files in the working copy. You can see the changes you've made with cvs diff -u.  If you want to commit these changes back to the repository, making them visible to the other group members, you can use the CVS commit command.  Within the pintos directory, execute cvs commit.  This will figure out the files that have been changed and fire up a text editor for you to describe the changes.  By default, this editor is vi, but you can select a different editor by setting the CVSEDITOR environment variable, e.g. with setenv CVSEDITOR emacs (add this line to your .cvsrc to make it permanent).

Suppose another group member has committed changes.  You can see the changes committed to the repository since the time you checked it out (or updated from it) with cvs diff -u -r BASE -r HEAD.  You can merge those change into your working copy using cvs update.  If any of your local changes conflict with the committed changes, the CVS command output should tell you.  In that case, edit the files that contain conflicts, looking for <<< and >>> that denote the conflicts, and fix the problem.

You can view the history of FILE in your working directory, including the log messages, with cvs log FILE.

You can give a particular set of file versions a name called a tag.  First cd to the root of the working copy, then execute cvs tag NAME.  It's best to have no local changes in the working copy when you do this, because the tag will not include uncommitted changes.  To recover the tagged repository later, use the checkout command in the form cvs -d ~KEEPER/cvs checkout -r TAG -d DIR pintos, where KEEPER is the username of the CVS keeper and DIR is the directory to put the tagged repository into.

If you add a new file to the source tree, you'll need to add it to the repository with cvs add FILE.  This command does not have lasting effect until the file is committed later with cvs commit.

To remove a file from the source tree, first remove it from the file system with rm, then tell CVS with cvs remove FILE.  Again, only cvs commit will make the change permanent.

To discard your local changes for a given file, without committing them, use cvs update -C FILE.

To check out a version of your repository as of a particular date, use the command cvs -d ~KEEPER/cvs checkout -D 'DATE' -d DIR pintos, where KEEPER is the username of the CVS keeper and DIR is the directory to put the tagged repository into..  A typical format for DATE is YYYY-MM-DD HH:MM, but CVS accepts several formats, even something like 1 hour ago.

For more information, visit the CVS home page.

SourceForge
===========

SourceForge is a web-based system for facilitating software development.  It provides you with a version-control system (typically CVS, as described above) and other tools for tracking your software. You can use it to store files, track bugs, and post notes about development progress.  You can set up your own project in SourceForge at sourceforge.net.

VNC
===

VNC stands for Virtual Network Computing.  It is, in essence, a remote display system which allows you to view a computing ``desktop'' environment not only on the machine where it is running, but from anywhere on the Internet and from a wide variety of machine architectures.  It is already installed on the Leland machines.  For more information, look at the VNC Home Page.