1. Are any servers available for course use?

The ASL/game cluster is a group of identically configured machines running Linux. In this course, we will use these machines to test your software. You should now all have accounts on all of the machines in the cluster. Your home directories are in AFS. This makes it easy to switch machines.

When you log in to any of these machines, you will get a list of all of the machines in the cluster. Log in to chess.ece.cmu.edu to get the other machine names.

We will be sharing these machines with people in other courses. This means that you should not attempt to reboot the machines or take them off the network.

For support with the machines, send mail to gripe@ece.cmu.edu.

Use SSH to log into these machines. Use SCP (or AFS) to copy files to and from the machines.

2. How do I connect to the ASL/game machines?

If you are lucky enough to be running Linux or Mac OS X, ssh and scp are already installed, and can be executed from the command line. "man ssh" and "man scp" will explain in detail how these commands work. To connect to chess using ssh you would execute the command:

• ssh <username>@chess.lab.ece.cmu.local

To copy a file from your machine to chess, use the following command:

• scp <file> <username>@chess.lab.ece.cmu.local:<directory>

If you are using Windows, then you will need to install an SSH client. The standard client which we recommend is PuTTY. PuTTY is an SSH client GUI, and PSCP is a command line SCP utility. If you want a GUI SCP client, try WinSCP.

Alternatively you can install Cygwin, a Linux-like environment for Windows. Cygwin provides command line ssh, scp, cvs, and other standard command line Linux utilities.

3. How can our project team manage our shared code base?

Several revision control systems exist which track every change made to a set of files. This makes it easy to revert to old versions of a file when you break it, and it also facilitates simultaneous development by different people on different (and sometimes the same) files in your code base.

The traditional program used for this purpose, which we recommend and support in this class, is CVS. Another new contender in the field is subversion, which was designed to be a better CVS.

You can learn about CVS, and find answers to most questions, in the CVS Manual.

A command line cvs client is available on the ASL/game machines, and is included on Linux and Mac OS X machines. If you are developing software in Windows, then TortoiseCVS and WinCVS are standard CVS clients. TortoiseCVS integrates CVS operations into the Windows Explorer, while WinCVS provides a standard GUI. If you are using an IDE for software development, then it very likely has CVS support built in.

4. How do I use CVS from the command line?

• cvs init – create a repository if it doesn't exist (only do this once per repository).
• cvs checkout – checkout files from a repository for editing (only do this once per user).
• cvs add – put a new file or directory into the repository. Directories are added immediately, but files must be committed.
• cvs remove – delete a file or directory. You need to remove the file or directory first (or use the -f flag), and commit afterwords
• cvs commit – Save the local changes to the repository (including adding and removing files).
• cvs update – merge any updates in the repository with the current directory. Use -d to get any new directories that were added, and -P to remove any empty directories.
• cvs -n update – Print a short report showing the status of the current directory. Files are marked with:
  • U – Changed in the repository, not changed locally
  • M – Changed locally; if changed in the repository, automatic merging will work.
  • C – Changed locally and in the repository. Automatic merging will fail.
  • ? – Present locally, but the repository knows nothing about them
• cvs diff – create a report showing any changes in files. Consider -u or -c for a more readable report.
• cvs log – view the CVS comments for a file
• cvs annotate – displays the file with notes explaining when each line was added
• cvs tag – associate a name with a revision of a file. This is helpful for keeping track of releases.

Here is an example of using the appropriate CVS commands to create, checkout, and add files to a repository:

# initialize the repository
cvs -d ~/cvsroot init

# initial import
mkdir temp
cd temp
cvs -d ~/cvsroot import project project start
cd ..
rmdir temp

# checkout the repository
mkdir fred barney
cd fred
cvs -d ~/cvsroot checkout project
cd project

# add a file
seq 1 10 > fred
cvs add fred
cvs commit

# someone else checks out the repository
cd ../../barney
cvs -d ~/cvsroot checkout project
cd project

# they add a different file
seq 10 -1 1 > barney
cvs add barney
cvs commit

# then they change the first file and examine the difference
seq 20 -1 15 >> fred
cvs diff
cvs commit

# a conflicting change is made in the first file
cd ../../fred/project
seq 20 25 >> fred

# can't commit change without updating first
cvs commit
cvs update
# now examine file to resolve conflict

5. Does CVS support binary files?

Yes, but you must specify the -kb switch when you add the file:

• cvs add -kb <file>

The binary file section in the CVS Manual provides additional details.

6. How do I rollback with CVS?

There are several options:

If you don't care about the repository updates, use "rm <file>; cvs update <file>”

• cvs update -j 1.3 -j 1.2 <file>

6. What things should I do when using CVS ?

• Use diff to look over your changes before committing them.
• Check for unadded files before the commit. Something like "cvs -n update" should do the trick.
• After you have added the files, check out into a different directory and make certain that things build well. This is a good way to catch subtle conflicts in the code and files that you forgot to check in.

7. What things should I avoid when using CVS?

• Don't branch unless you already have experience doing so.
• Conflicts. In general, this will only happen if two people are editing the same code at the same time. Avoid this by checking in your changes promptly, keeping your edits small, and assigning tasks that will involve changing a similar set of files to one person. If conflicts happen, don't panic. Most conflicts are small and have obvious resolutions. If they get confusing, a short conference with the other author is in order.
• Copying files in directories under CVS control. This can cause a large number of problems, including large conflicts and backing out changes put into CVS by other people on the project. In general use one of the following strategies:
  • If you want to move updates between machines, commit them on the old machine and then do an update on the new machine.
• Reformatting text – if you don't agree on indenting styles with the rest of your team, reformatting the source is a sure way to generate conflicts. Agree as a team on an IDE and the parameters for the auto indentation. In addition, check your commits carefully to ensure that you aren't changing most of the lines in the file.

8. How do I get help on Linux?

If you know the name of the command, use man. For example, for information about ps, type "man ps".

If you don't know the name of the command, but want to search on a keyword, try:

• man -k <keyword>

When you're looking at man pages, glance over the SEE ALSO section. Sometimes it will cross-reference a useful command.

If man fails or you need detailed information, try typing "info <command>".

There is some good online documentation at The Linux Documentation Project, and there are numerous books available for purchase. If all else fails, feel free to email the TA's.

9. What Unix utilities are useful in finding out if your program is running correctly?

• ps – List the processes running on the system along with various pieces of information about each process. The -e switch shows all of the processes. -f gives a different set of statistics. My personal favorite is "ps auwwx".
• top – a utility that runs a ps every five seconds and updates the screen. Press q to exit. You can press k to kill processes.
• strace – See what is happening at system call level. If you use the -p switch along with a process id, you can attach to a process that is already running. The -f switch follows the process through forks. Note that strace slows down your program, so don't use it if timing is critical.
• netstat – shows what is happening with the network. -a prints a list of all of the active connections. -i displays how many packets were sent and received by each interface.
• ping – See how quickly packets can move through the network by sending an echo request want timing the round trip. This is also a good way to detect with a machine is not on the network.
• lsof – See what files are open on the system. Can be useful when combined with strace, since it associates files to file descriptors. The -i option shows network sockets.
• df - Is the disk full? Note that this doesn't work well for AFS. Use "fs lq" instead.
• who – Get a list of other users of the system.
• kill <pid> – stop a process running on the system. The -9 option sends a different signal that processes cannot ignore.
• killall – Like kill, but takes the name of the command to be killed, not the identifier of the process. As a result, you can kill a large number of processes with a single command.
• screen – Very advanced terminal multiplexor that can also be useful for remote program execution. See my tutorial Lecture Notes on Screen: Remote Execution.

10. What are some of the basic commands for AFS?

SCS has a decent AFS web site.

Permissions are handled differently on AFS. In general, people will have permission to see your files unless you use the "fs sa" command. "fs la" shows what permissions are currently granted.

In addition, you need to use "fs lq" to see if you are out of space. df doesn't report useful numbers of afs.

If you want to restore a file, look in the "OldFiles" directory in your home directory. It saves a snapshot of all of your files from the last backup. Older backups also exist (contact gripe@ece.cmu.edu), though they take some time to restore.

11. What IDEs are available for Java development?

The two big contenders are IBM's Eclipse and Sun's NetBeans. Of course if you were a real hacker you would content yourself with vi or emacs.

Both of these IDEs should:

• Provide the CVS client that you will need, saving you another download
• Make building your project easier
• Provide a good debugger
• Provide a way to explore Java libraries for useful methods and classes