CVS

Professional programmers need a way of keeping track of changes that they make to a programming project. When several people are working on a project, they also need a way of combining changes made by various individuals in the shared "official" version of the project. Both of these needs can be met by a version control system. One common system is CVS. CVS keeps a record of all versions of every file that is added to a CVS project. It is possible to compare the current version of any file with a previous version. It is possible to retrieve copies of files that have been deleted. It is possible for several programmers to access the same project so that they can all work on it. It is possible for one person to work on a project on several different computers, even running different operating systems.

CVS, or something like it, is an essential tool for team programming, and it is also useful for individual programmers. Eclipse has excellent support for CVS. (Because of certain limitations in CVS, many people have started using a newer system named SVN, or "SubVersion", that is designed as an improved replacement for CVS. Since CVS's limitations won't matter in this course, and since SVN support in Eclipse requires installation of a plugin, we will stick with CVS. Similarly for Git, a version control system used for development of the Linux operating system kernel.)

---

To use CVS, you need a repository where CVS will store all the information about your projects. The repository is just an ordinary directory, and for this course you can use a directory inside your home directory on the department's file server. I will assume that the name of your CVS directory is cvs-cs225 and that it is in your home directory. You are not absolutely required to use this setup, but I will need to know the full path name of the directory that you use. (Note that you can store many projects in the same repository, and it's also possible to have more than one repository, perhaps to give different people access to different projects.)

To create the repository, open a command-line window, and enter the following sequence of commands, replacing zz9999 with your own user name:

    mkdir  cvs-cs225
    fs  setacl  cvs-cs225  -acl  eck  all
    cvs  -d  /home/zz9999/cvs-cs225  init

The first command makes the directory that will hold your CVS repository.

The second line gives me access to that directory. This will allow me to see your projects and test them for purposes of grading. You must give this command before the next command; it is possible to give someone access to a repository after that repository has been initialized, but it's not so easy. If you want to check that the "fs setacl" command worked, give the command "fs listacl cvs-cs225". You should see eck listed as having some permissions to access the directory.

The third command initializes the directory, turning it into a CVS repository.

You only have to give these commands once. From now on, you will only use your CVS repository through Eclipse. You should never directly make any changes to a CVS repository directory or to its contents; only CVS should modify it!

(Note: The fs command works only with the "AFS file system," which is the type of networked file system where your home directory is stored; the AFS file system turns out to be very convenient for managing access to CVS repositories. The same type of access control can be much more difficult on other file systems. If you are working with other people on a project, you can give them all permission to access the repository, but note that you should do this on a newly created directory, before calling cvs init. It is hard to grant the proper access permissions on a CVS repository that has already been inited.)

Using CVS in Eclipse

The first thing that you need to understand about CVS is that it keeps a separate copy of your projects, in addition to those that are stored in Eclipse. The copy that is in CVS can be shared by several programmers, and it can be accessed by you from several different Eclipse workspaces and on several different computers. This allows a team of programmers to work on the same project, and it allows you to work on the same project from several different computers. But this means that there are several copies of the project in different places. To use CVS, you have to know how to copy projects from Eclipse to CVS and from CVS to Eclipse, and you need to know how to keep the different copies of the project in sync.

Sharing a Project: The first step to start using CVS with an Eclipse project is to "Share" the project, which copies the project into CVS. (You only have to do this once for each project that you want to store in CVS, and only the person who originates the project does it.)

To share your project into CVS, right-click the project name in the Package Explorer view. In the pop-up menu, go to "Team", and select "Share Project" from the Team sub-menu. The first time you share a project, you will have to input information about your CVS repository (which you should have already created, as described above). Fill in the dialog box as shown here, replacing zz9999 with your own user name:

Note that you should use math.hws.edu as the "Host" for your repository location. Your home directory, where the repository is located, is accessible on any of the department's computers; math.hws.edu is one of those computers, and it is accessible from off-campus as well as on campus. Be sure to set the "Connection type" to extssh. You can check the "Save Password" box or not, as you prefer.

When you have filled in all the information, click "Next". The first time you try to connect to math.hws.edu, you will have to confirm that you want to connect by answering "yes" in two pop-up dialogs. This is just the way "ssh" works. Once you've connected once, you won't be bothered with the questions again.

On the next screen, after clicking "Next", you can accept the default setting, "Use project name as module name", and click "Next" again. (The "module name" is the name for the information about your project that is stored in the CVS repository. It does not necessarily need to be the same as the name of the project in Eclipse, but using the same name will avoid confusion.) On the next screen, you can just click "Finish." This will create a "module" in CVS to hold a copy of your project -- but the files from the project still need to be copied into the CVS module.

After you click "Finish" in the "Share Project" dialog, the "Commit Files" dialog will pop up automatically. "Committing" is the process of copying files into the CVS repository. The same "Commit" dialog will also appear later, when you copy new or modified files to CVS. This dialog box tells you which files are being saved or modified in CVS, and it has a space where you can enter a comment that describes the changes. Enter a comment such as "Initial commit" if you want or leave it blank, and click "Finish". Your files will be copied into CVS.

For your first example of using CVS, you should follow this process to Share your lab5 project into your CVS repository. When you do this, you will see the notation [math.hws.edu] next to the project name in the Project Explorer. If you look at the files in the project, you will see a CVS version number after each file name. Don't forget to update the CVS project to the final version by next Monday!

---

Importing a Project: Let's say that you want to work on a project that someone else has placed in a CVS repository. Or that you want to work on your project on another computer, such as your personal laptop. To do that, you can run Eclipse and import the project from CVS. This will copy the project from CVS into Eclipse, where you can work on it just like any other project. To import a project into an Eclipse workspace, right-click in the Package Explorer view and select "Import" from the pop-up menu. In the "Import" dialog box, select "Projects from CVS", as shown here:

Click "Next". If this is the first time you are using CVS in this workspace, you will have to set up CVS repository information, just like when Sharing a project, as described above. If you have already used CVS in the workspace, you will have the option of entering information for another CVS repository or using a repository that you have already configured. Once you've done that, click "Next" again. On the next screen, you have to enter the name of the CVS "module" that you want to import. This is the same name that was used when the project was "Shared" into CVS; it is probably just the name of the project. After filling in or selecting the module, click "Finish". This will copy the project from CVS into Eclipse.

To get experience with importing, you should import a project named lab6-cs225 from a CVS repository that I have set up. To use the repository, enter the following data when you configure the repository in eclipse:

     Host:            math.hws.edu
     Repository path: /classes/cs225/cvs-lab6
     User:            (your usual Linux username)
     Password:        (your Linux password)
     Connection type: extssh

The lab6-225 project contains the file, BuggySearchAndSort.java, that you will need for Part 2 of today's lab. Before you leave lab today, you should show me that you have successfully imported this project.

---

Commit and Update: Once you have a CVS module associated with an Eclipse project (either by Sharing or Importing), there are two things that you need to do to work with CVS. First of all, after you make any changes in the Eclipse project, you will want to copy those changes into CVS. This is called committing the changes. As you make changes in your Eclipse project, you will note that any resources that you modify are marked with a ">" in the "Project Explorer." This is to remind you that the changes need to be committed to CVS. To commit them, right-click on the project name in the "Package Explorer". In the popup menu, go to "Team", then select "Commit" from the next popup. You will see the Commit dialog window, where you can enter a comment to describe the changes that you have made, if you want, and then click "Finish" to send the changes to CVS.

When you have completed work on your percolation project, you can commit it to the CVS repository in this way. You could try it now by making a small change in your percolation project and committing it to CVS, and you should definitely commit the final version of the percolation project by Monday.

Now, suppose that you are working with other people on a project, or that you work on the project from several computers. The remaining question is, how will the changes that are committed from one Eclipse workspace get into other Eclipse workspaces? For this, you need the update command. When changes (might) have been made to a CVS module from one Eclipse workspace and you want to get those changes into another Eclipse Workspace, just right-click the project name in the second workspace and select "Update" from the "Team" sub-menu.

---

To summarize, there are four basic things that you can do with CVS in Eclipse:

• Share a project, using the "Share" command in the "Team" sub-menu, to get the project into CVS in the first place.
• Import an existing project from CVS into Eclipse, using the "Import" command.
• Commit a project, to get any changes that you have made from Eclipse into CVS, using the "Commit" command in the "Team" sub-menu.
• Update a project, using the "Update" command in the "Team" sub-menu, to get changes from CVS (which have been made from other Eclipse workspaces) into the Eclipse workspace where you are currently working.

Sharing and importing are things that are done only once (for a given project). If you are using CVS, you should always remember to commit your changes before quitting Eclipse. If you work on your project from more than one Eclipse workspace, you should update your project before you start working on it, to make sure that you will be working on the most current version. Remember that changes that you make in Eclipse don't automatically get into CVS; you have to commit them. And changes that are committed to CVS don't automatically get into other Eclipse workspaces; you have to do an update to get the changes.

(Note: If you try to commit conflicting changes to a CVS module, or to update your code when there are conflicting changes already in CVS, bad things will happen. Conflicting changes are multiple changes made by different CVS users to the same region of the same file. You should try to avoid this by making sure that you know who is working on what parts of the project, and by always updating the project before you work on it. If a conflict happens anyway, you might see both versions of the conflicting lines in your file. In that case, you should edit the file to fix the conflict and commit the conflict-free version.)

The Eclipse Debugger

The second part of this lab introduces the Eclipse debugger and asks you to use it to find a few bugs in a program.

You should already have imported the project lab6-cs225 in the first part of this lab. The project contains the file BuggySearchAndSort.java that you need for Part 2.

BuggySearchAndSort defines a search method that is supposed to check whether or not a given integer occurs in a given array of integers. It also contains a "bubble sort" method that is supposed to sort an array of integers into non-decreasing order and a "list sort" method that sorts the numbers by inserting them one by one into a sorted list. There is also a main program that tests the three methods. (It also sorts the list with the built-in method Arrays.sort to give a correctly sorted answer).

If all three methods were correct, then running the program would produce output that looks something like this (though with different numbers each time you run it):

    The array is: 4 3 6 9 3 9 5 4 1 9
    This array DOES contain 5.
    Sorted by Arrays.sort():   1 3 3 4 4 5 6 9 9 9
    Sorted by Bubble Sort:     1 3 3 4 4 5 6 9 9 9
    Sorted by List Sort:       1 3 3 4 4 5 6 9 9 9

Unfortunately (or fortunately, for the purposes of this lab), the methods in BuggySearchAndSort have bugs that can produce either incorrect results or an infinite loop. (The search method might give the correct results in some cases, but it gives the wrong answer in many cases.) If you run the buggy program without modifying it, it will go into an infinite loop. Remember that to stop a running program in Eclipse, you can click the Stop button that looks like a small red square in the part of the window where the Console view appears:

(If this button is gray instead of red, it means that no program is currently running in the visible console. However, there might be other consoles that are still running programs; to avoid having a bunch of programs, all running in infinite loops at the same time, you should make sure that a program has been terminated before starting another program run. But if there is a program still running in the background, you can bring it into the console by clicking the X's next to the stop button; the stop button will turn red and you can use it to stop the program.)

Your job in this lab is to use the Eclipse debugger to find the bugs in BuggySearchAndSort. You should write a report about what you have done. The report can be turned in in class or placed in your homework folder, as specified above. In the report, you should describe each bug, say how you fixed it, and explain briefly how you used the Eclipse debugger to find the bug.

(Note: It's possible that you could find one or all of the bugs just by inspecting the code. However, the main purpose of this part of the lab is to get some experience with the debugger, so I would like you to do that rather than simply eyeball the code!)

---

To debug a program in Java, you have to start the program using a "Debug" command instead of a "Run" command. There is a "Debug As..." command in the same pop-up menu as the "Run As..." command. You can also start the debugger by clicking on the "Debug" button, which is just to the left of the "Run" button in the toolbar. It looks like a bug:

The main point of the debugger is that it allows you to pause the execution of a program and inspect the values of variables. Once the program has been paused, you can also step through the program line-by-line to see what is going on. The program will not pause, however, unless you have added a breakpoint to the program source code. If you run a program that has no breakpoints under the debugger, it behaves just as it would if it were run normally.

To add a breakpoint, simply double-click in the left margin of the source code, next to one of the lines of code. (By left margin, I mean the same part of the window where the error and warning "light bulbs" appear.) The breakpoint appears as a small dot: . You can remove the breakpoint by double-clicking this dot. There is also a "Remove All Breakpoints" command in the "Run" menu. I should also note that you can use the "Add Java Exception Breakpoint" command in the "Run" menu to set up a breakpoint that is triggered whenever an exception of a given type occurs.

When a program is running in Eclipse under the debugger and the execution gets to a line that contains a breakpoint, the execution is paused. If Eclipse is showing the regular Java perspective when this happens, Eclipse will want to switch to the Debug perspective -- another screen full of views (or panes) that are useful for debugging. The first time this happens, Eclipse will put up a dialog box that asks whether you want to switch to the Debug perspective. You should check the box that says "Remember my decision" and say "Yes."

Debugging is complicated, and so is Java's Debug perspective. The most important view is the "Variables" view in the top-right corner. Here, you can inspect the values of variables. An array or object variable has a small triangle (or a "+" sign) next to its name; you can click this triangle to open and close the variable so that you can inspect its contents. If a variable is selected (by clicking it), its value is also shown at the bottom of the view.

The "Debug" view in the top left contains a list of currently active subroutines. Click on a subroutine to inspect its variables. The title bar of the "Debug" view contains some useful buttons:

The green triangle means "Resume" and can be used when the program is paused to resume normal execution of the program (until it next encounters a breakpoint). There is a red "Stop" button that can be used to terminate the program. Most important are the three "arrow" buttons for the "Step Into", "Step Over", and "Step Out" commands. "Step Over" is easiest to understand -- clicking it causes one line of code to be executed. "Step In" is similar, except that if the line of code contains a subroutine call, it takes you to the first line of the subroutine so that you can continue from there. "Step Out" continues execution until the current subroutine returns (or a breakpoint is encountered), and it stops at the line to which the subroutine returns. Note that these "Step" commands can also be found in the "Run" menu, and that the F5, F6, and F7 keys can be used as keyboard equivalents for the step commands.

(You will want to avoid using the "Step Into" command to step into one of Java's built-in subroutines. If you do that, you will just get a message saying that the source code for the subroutine is not available. If this happens, you can use "Step Out" to get out of the subroutine and return to your own code.)

In the left center area of the Debug perspective, you'll find an edit view where the source code files for the program are displayed. The current line is marked in this view with an arrow in the left margin, and you can watch this arrow move as you step through the program. There is a Console pane at the bottom of the window where program I/O is done. You can even edit your program in the Debug perspective, although I don't recommend it.

One final remark: There is a list of open perspectives on the right end of the toolbar at the top of the Eclipse window. You can move from one perspective to another by clicking on the name of one of the perspectives in this list. So, when you want to get out of the Debug perspective and back to the normal Java perspective, just click "Java" in the list of perspectives: