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-*.

cscope
======

The cscope program also provides an index to functions and variables declared in a program.  It has some features that tag facilities lack.  Most notably, it can find all the points in a program at which a given function is called.

The Makefile in pintos/src produces cscope indexes when it is invoked as make cscope.  Once the index has been generated, run cscope from a shell command line; no command-line arguments are normally necessary.  Then use the arrow keys to choose one of the search criteria listed near the bottom of the terminal, type in an identifier, and hit Enter. cscope will then display the matches in the upper part of the terminal.  You may use the arrow keys to choose a particular match; if you then hit Enter, cscope will invoke the default system editor (This is typically vi.  To exit vi, type : q Enter.) and position the cursor on that match.  To start a new search, type Tab.  To exit cscope, type Ctrl-d.

Emacs and some versions of vi have their own interfaces to cscope.  For information on how to use these interface, visit the cscope home page (http://cscope.sourceforge.net).

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 and is fairly easy to use.

For more information, visit the CVS home page.

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

To set up CVS for use with Pintos, 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 and maintain permissions for its contents.

The following instructions are specific to our local setup, starting with the Fall 2006 semester.  Even if you've used CVS before, we ask that you read the instructions in their entirety.

Repositories must be created on the machine 'ap2.cs.vt.edu'. This machine contains a directory that was specially set up for CS 3204 students' CVS repositories. To access the repository from the other machines, you should first configure ssh to log you on automatically, without requiring a password every time. See Setting Up ssh, for more information. To connect to this machine use ssh ap2 from any of the machines in McB 124. You should not be prompted for a password if you have configured ssh properly.

The keeper has to perform several steps to set up the repository. First, log on to 'ap2.cs.vt.edu' and create a directory for storing the repository. The new directory must be created in the directory /shared/cs3204 and should be named Proj-KEEPER_PID, where KEEPER_PID is the pid of the keeper. Next, configure access to repository using the command setfacl --set u::rwx,g::---,o::--- Proj-KEEPER_PID. This command ensures that the user, i.e the keeper has the required permissions to access the repository, and no one else does. To set permissions for the other members in the group, use setfacl -m u:MEMBER_PID:rwx Proj-KEEPER_PID for each of the other members in the group, replacing MEMBER_PID with the pid of the group member.

Next, set the permissions of the directories and files that would be created inside the repository using the command setfacl -d --set u::rwx,g::---,o::--- Proj-KEEPER_PID. To permit all the members of the group access to all the files and directories created in the repository, use setfacl -d -m u:MEMBER_PID:rwx Proj-KEEPER_PID once for each group member (should be used once for the keeper too), replacing MEMBER_PID with the pid of the group member. To make sure that the permissions are set correctly, use getfacl Proj-KEEPER_PID.

Note that neither (Unix-) group members nor others should have read access to your CVS repository, hence the g::---,o::--- part of the access control list. (Giving access to group members (in the Unix sense) would give access to, for instance, all CS majors if your default (Unix-) group is Major. We use ACLs to give individual access to your CS 3204 group members.) Failing to protect your repository in this way is an honor code violation.

Now initialize the repository. To initialize the repository, execute cvs -d /shared/cs3204/Proj-KEEPER_PID 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 /home/courses/cs3204/pintos/pintos (note the doubled pintos).  After changing the current directory, execute this command:

     cvs -d /shared/cs3204/Proj-KEEPER_PID import -m "Imported sources" pintos foobar start

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

     ssh ap2.cs.vt.edu
     cd /shared/cs3204
     mkdir Proj-KEEPER_PID
     setfacl --set u::rwx,g::---,o::--- Proj-KEEPER_PID
     # for all other group members do:
     setfacl -m u:MEMBER-PID:rwx Proj-KEEPER_PID
     setfacl -d --set u::rwx,g::---,o::--- Proj-KEEPER_PID
     # for all group members, including the keeper, do:
     setfacl -d -m u:MEMBER_PID:rwx Proj-KEEPER_PID
     cvs -d /shared/cs3204/Proj-KEEPER_PID init
     cd /home/courses/cs3204/pintos/pintos
     cvs -d /shared/cs3204/Proj-KEEPER_PID import -m "Imported sources" pintos foobar start

The repository is now ready for use by any group member, as described below. Having set the repository up, you need not log on to 'ap2.cs.vt.edu' for any other purposes. Keep in mind that the repository should only be accessed using CVS commands---it is not generally useful to examine the repository files by hand, and you should definitely not modify them yourself.

Due to space constraints, 'ap2.cs.vt.edu'should be used only to store the repository and not for development purposes.  Do not store any other files there and do not run any other programs on this machine.  The reason for this somewhat unusual setup is that our shared file servers currently do not support the setfacl commands, making it impossible to protect your CVS repository.

Using CVS
---------

Some of the CVS commands require you to specify the location of the repository. As the repository has been set up in the machine 'ap2.cs.vt.edu' and you would not be using this machine for development purposes, you have to use :ext:YOUR_PID@ap2:/shared/cs3204/Proj-KEEPER_PID as the location of the repository. YOUR_PID is your pid and is needed to log you on to 'ap2.cs.vt.edu'. CVS runs on top of ssh.  Therefore, before using any of the CVS commands, make sure you have configured ssh to log you on without prompting for password (see Setting Up ssh, for more information) and set the environment variable CVS_RSH to /usr/bin/ssh. Under csh you can set this environment variable using setenv CVS_RSH /usr/bin/ssh. To avoid having to type this line everytime you log on, add this line to the '.cshrc' file in your home directory.

To use CVS, start by checking out a working copy of the contents of the CVS repository into a directory named DIR.  To do so, execute cvs -d :ext:YOUR_PID@ap2:/shared/cs3204/Proj-KEEPER_PID checkout -d DIR pintos. If this fails due to some kind of permission problem, the CVS repository may not be initialized properly.

Note that there are two -d switches in the previous command. The first switch specifies the location of the CVS repository to which the command applies.  In this case, the repository is located on the machine AP2 and is reachable via ssh with your_pid. The second -d switch is specific to the cvs checkout command.  It specifies the local directory into which to check out the module 'pintos'.  If omitted, pintos will be checked out into a directory called 'pintos'.

Your working copy is kept in your undergrad file space.  Unlike the CVS repository, this directory is shared among the lab machines, so you do not need to be logged on to any specific machine to use it. Like the CVS repository, you must read-protect your working copy from (Unix-) group members and others to comply with the honor code. chmod -R go-rwx DIR will read-protect your working directory.

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 .cshrc 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 :ext:YOUR_PID@ap2:/shared/cs3204/Proj-KEEPER_PID checkout -r TAG -d DIR pintos, where 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 :ext:YOUR_PID@ap2:/shared/cs3204/Proj-KEEPER_PID checkout -D 'DATE' -d DIR pintos, where 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.

If you are using an IDE, check whether it supports CVS automatically.

CVS Locking
-----------

You might occasionally see a message like this while using CVS:

     waiting for member_pid's lock in /shared/cs3204/Proj-keeper_pid/cvsroot/foo

This normally means that more than one user is accessing the repository at the same time.  CVS should automatically retry after 30 seconds, at which time the operation should normally be able to continue.

If you encounter a long wait for a lock, of more than a minute or so, it may indicate that a CVS command did not complete properly and failed to remove its locks.  If you think that this is the case, ask the user in question about it.  If it appears that an operation did go awry, then you (or the named user) can delete files whose names start with #cvs.rfl, #cvs.wfl, or #cvs.lock in the directory mentioned in the message.  Doing so should allow your operation to proceed.  Do not delete or modify other files.

Setting Up ssh
--------------

Ssh can be configured to log you on to any of the machines in McB 124 from any other machine in McB 124, without you having to enter your password. To enable automatic login, perform the following steps after logging on to any of the machines in McB 124.

  * ssh-keygen -t rsa -N "" On your screen you should see something similar to what is shown below.

          Generating public/private rsa key pair.
          Enter file in which to save the key (/home/ugrads/your_pid/.ssh/id_rsa):
          Your identification has been saved in /home/ugrads/your_pid/.ssh/id_rsa.
          Your public key has been saved in /home/ugrads/your_pid/.ssh/id_rsa.pub.
          The key fingerprint is:
          34:45:6d:4a:51:4e:1f:af:fe:66:dd:a9:a5:23:46:bb your_pid@some_machine.cslab

     Accept the defaults. This command creates a new file id_rsa.pub in the directory $HOME/.ssh if the default location is chosen.

  * cd $HOME/.ssh

  * cat id_rsa.pub >> authorized_keys

  * cd $HOME

  * chmod +700 .ssh

To make sure that you have configured it correctly, try ssh'ing to another machine in McB 124 (e.g, ssh ap2). You should not be prompted for your password. If it is the first time you are ssh'ing to some machine, you might have to type yes to continue connecting.

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 machines in McB 124. For more information, look at the VNC Home Page.

Cygwin
======

Cygwin provides a Linux-compatible environment for Windows. It includes ssh and an X11 server, Cygwin/X. If your primary work environment is Windows, you will find Cygwin/X extremely useful for these projects.  Install Cygwin/X, then start the X server and open a new xterm.  Use ssh -XY your_pid@rlogin.cs.vt.edu to log on to the lab machines.  The X11 server will allow you to run pintos while displaying the bochs-emulated console in your windows desktop. In addition, you can set up Cygwin's ssh client for password-less login as described earlier. See Setting Up ssh.