From Comp519

Contents 1 Preparing A Project Directory for COMP/ELEC 519 2 Hardware Projects in Subversion 2.1 New Hardware Project 2.2 Existing Hardware Project 3 Software Projects in Subversion 3.1 New Software Project 4 Working in a Group 4.1 Rolling Back 4.2 Simultaneous Use 4.3 Conflicts 4.4 "Blame" 4.5 Policies

Preparing A Project Directory for COMP/ELEC 519

In order to prepare your repository for the class you should do the following:

• Create a repository, as described in Subversion Initial Setup, if you have not already done so.
• Check out your repository:

svn co https://svn.rice.edu/r/myrepository

• Create a project directory:

cd myrepository
mkdir comp519

• Add the directory to the repository:

svn add comp519

• Edit the rice_config/access_file, as described on the Subversion information page.
• Commit the changes (in the myrepository directory):

svn commit

• For doing your actual work, you should just check out your project directory:

svn co https://svn.rice.edu/r/myrepository/comp519

• If your access file is setup correctly, all of your groupmates should also be able to check out your comp519 repository using the same command.

The subversion commands needed to prepare your project directory are described in more detail on the Subversion information page.

Hardware Projects in Subversion

For the class hardware projects, you should store your entire projects/ directory in Subversion. However, not every file in your projects/ folder needs to be in the archive. Particularly, all of the large Xilinx compiler-generated files in the synth/ directory should NOT be saved in Subversion. If you do this by mistake, you'll be checking in over 100MB of useless binary files every time you recompile your hardware, even if only 1 line of 1 verilog file has changed. Clearly, this is not the way to use Subversion, and eventually IT will notice the ballooning size of your repository.

New Hardware Project

The best time to start using Subversion is before you have modified any part of your project. This way, you start with a clean directory structure free of any annoying compiler-generated files. As described at Hardware Common Tasks, you can create a new project by coping the existing projects directory, which includes both the NIC and PCI projects (as required for simulation).

cd <myrepository>/comp519
cp -R $NF2_ROOT/projects . 

Now, you can add the entire projects directory, including the CPCI and NIC projects, to your subversion repository, and commit the changes.

svn add projects
svn commit

Enter a message at the top of the editor window that appears, and then save/exit. For example, "Initial Project Checkin" would be a useful message in case you have to refer to it later.

Finally, you can copy the existing reference_nic design to use in your new switch or router. But here's a catch! Because the reference_nic design is now in Subversion, its folders are littered with hidden .svn directories containing repository meta-data. You cannot copy these directories without corrupting your archive. You could go through and manually delete them after you copy, but there's an easier way. Simply use the Subversion-specific svn copy command to copy the directory and add it to the repository automatically

svn copy projects/reference_nic projects/ethernet_switch
svn commit

Existing Hardware Project

If you want to check in an existing hardware project, you can move it to your repository directory and then use the svn add command. However, make sure to do a make clean and make really_clean in your synth/ directory before moving it, to avoid adding useless (and large!) compiler-generated files to your repository. Also, be careful that your .bashrc file it up-to-date when you do the make clean commands. Otherwise, you might accidentially clean a different project. This command can be used to verify the current project:

echo $NF2_DESIGN_DIR

Software Projects in Subversion

As with the hardware projects, you should store all of your software projects in Subversion. You do not want to have object files and binary files in subversion, though. This is pointless, as they can be easily recreated by recompiling and they take up a lot of space. Similarly, any little change to any C file would change these files, rendering version control on these files relatively useless.

New Software Project

The best time to start using Subversion is before you have modified any part of your project. This way, you start with a clean directory structure free of any annoying compiler-generated files.

You can easily do this as follows:

cd <myrepository>/comp519
cp -R /exports/provided/scone-base ./scone

There is no reason to call the project "scone-base" as you will be adding to the "base" files and building your own fully functioning version of the "scone" tool.

Now, you can add the entire scone directory to your subversion repository and commit the changes.

svn add scone
svn commit 

As the software project evolves over the course of the semester using the same code base, it is unlikely you will need to make any copies of the project in subversion. As you experiment, however, you may want to create branches in the repository. See the subversion manual for details. We also suggest you use "tags" (very similar to branches) to mark the state of the repository each time you turn in a project. You could also just remember the revision number that corresponds to each submission, if you find that easier.

Working in a Group

While there are many advantages to using version control for medium to large projects, two advantages are especially relevant to this class:

1. You have a record of changes you have made throughout the course of development.
2. A group of people can work on the same project without interfering with each other.

The following exercises should demonstrate how to take advantage of these features. First, you should create a dummy project that you can use for these exercises. Create a new directory (call it "test") inside your checked out repository, copy some files into it, and then add it to your repository:

svn add test
svn commit

You should use this "test" project to do the exercises below. Feel free to add more files, if you need to.

Rolling Back

To see the power of rolling back your project, we will make some edits and then roll back to a previous state.

First, check out one of your projects:

svn co https://svn.rice.edu/r/<myrepository>/comp519/test

Then, edit one of the files and commit your changes (use a unique log message for each commit):

svn commit

Do this a few times to the same file (make a different edit, commit the changes, repeat).

Now, you should have a file that has had several committed changes made to it.

To browse the history of changes, you can look at the log:

svn log

This will give you a list of commits that were made to the project, along with the associated commit messages.

Alternatively, you can use the web interface to browse the changes. Access the web interface at https://www.svn.rice.edu/. The web interface is pretty self explanatory. Browse around a bit to explore your repository and changes.

Now, we can roll back to a previous version. Find a version number from the logs (either using svn log or through the web interface) for a previous version. Then "copy" the old version of the file in the repository to your checked out copy:

svn copy -r <version> https://svn.rice.edu/r/<myrepository>/comp519/test/<file> ./<file>

You can get back old directories or files in this manner.

Now that you have an old version of the file, see how it differs from what's currently in the repository:

svn diff <file>

You can now compile the old file or whatever you need to do in order to decide if this version is preferable to the current one. If you decide it is, you can commit the file as if you had simply changed it by editing:

svn commit <file>

You have now successfully "undone" several changes that you decided were unnecessary. But, you still have access to those changes, as they are still available in the repository, if you should decide you want to get them back sometime in the future!

Sometimes, an entire committed change should be undone. If it is not the most recent change, then the above method won't work well. By using svn copy to retrieve an old version, you are literally rolling back to that version. If you just want to undo an entire change that happened in the past, you can use svn merge to do so. Look through the subversion manual for further details.

Simultaneous Use

Now, have multiple students check out the same project in multiple accounts. Be sure to retrieve them from the same repository (students A and B should check out the project in student A's repository).

Student A should edit a file and commit the change. At this point what does student A's file look like? What about student B?

Student B should now update the project:

svn update

Now, what does student A's file look like? What about student B?

In this way, you can see that students A and B can both be working on the project at the same time. When one student wants to commit a change, they can do so without affecting the files in the other students checked out project. Only when the other student updates their project do they see the changes.

Conflicts

Check out copies in multiple students accounts.

Make conflicting edits to the same line of the same file.

Try to commit it.

What is the problem and how can we resolve it?

"Blame"

The web interface has many nice features:

1. You can look at the logs for any file or directory. Try it.
2. You can easily browse through all the files in the repository. Try it.
3. You can compare two versions of the same file easily. Try it.
4. You can find out who last edited a file on a line by line basis.
5. You can find out which version was the most recent to affect this file on a line by line basis.

The last two features are part of the "blame" tool. Navigate through the web interface and find a file that was changed by multiple people over the span of multiple commits. If you can't find such a file, create one and have multiple people edit and commit it repeatedly.

Once you are looking at this file, click the "blame" link. The results should be pretty self explanatory (and can be quite useful).

Policies

Now that you have seen the basics, it is important to think about how your group can best leverage the use of subversion. Obviously, the more frequently you commit your projects, the more history you will have and the less chance there will be of conflicts. However, the more frequently you commit, you also increase the chances that other people in your group will get updates from you that are not fully working and/or tested. This can lead to just as much frustration as frequent conflicts. So, you need to find a happy medium that works for you.