CS 595 - Advanced Scientific Computing

Fall 2010

The Boss is: OUT

Homework 7

1. This class is as much about software design and engineering as it is about theoretical scientific computing. Frankly, good choices regarding software engineering can be as important for the success of a project as the choices made regarding algorithms. In an attempt to show you how a real software project runs, we want to expose you to version control software.
   
   To communicate changes to software within a group of researchers, many or all of whom may not be working at the same site, some brilliant folks invented version control. This is a program that allows software to be distributed among many people and it records changes and comments made to the software along the way. During the project development, many people can contribute to the software and its evolution can be reviewed to determine which changes were good and which caused bugs.
   
   Over the years many version control choices came and went. The PETSc team chooses to use the distributed version control software Mercurial, and that's why we are teaching you how to use hg. Specifically, we want you to use hg to manage your course project. This is a trivial example of version control as you will be making almost all the changes to your repository, but it will get you the basics. It also will make it easy for Dr. Zhang or I to help you debug your code as we will be easily able to access it and push changes.
   
   To get started, log on to your account on ada.cs.iit.edu, or maybe karlin.math.iit.edu if you're already that far on your project. From your home directory execute the following commands
   cd
   mkdir hg; cd hg;
   mkdir myrepo; cd myrepo;
   to put you in a directory specifically for Mercurial. Now you should check and see what your default editor is by
   echo $EDITOR
   If the result is empty, then VI is your default. Regardless of what is stored there, if you have been using nano (or emacs) for your editing and you want that to be your default then you should set that. You can do so manually with the command
   export EDITOR=nano
   and if you add that command to your ~/.bashrc file that will always be your default.
   
   The reason I bring that up is because at times Mercurial will automatically use the default editor and you don't want to get caught in VI if you've never used it before. Mercurial needs a configuration file with a few basics in it before it can run successfully. We're going to create that configuration file called .hgrc in our home directory, which is the common location.
   $EDITOR ~/.hgrc
   Within this file you need some basic info following the basic format
   [ui]
   username = Firstname Lastname <firstname.lastname@example.net>
   verbose = True
   editor = $EDITOR
   For me, this would look like
   [ui]
   username = Michael McCourt <mccomic@mcs.anl.gov>
   verbose = True
   editor = nano
   Obviously you should use your own name.
   
   Now that we're cool, copy any files that you want to use for your course project into the myrepo directory:
   cp <file1> .
   cp <file2> .
   and so on until you have copied all the relevant files. You can add directories as well (I think) although for starters I would just add some files. Once you've done that you need to tell Mercurial to try this directory as a repository.
   hg init
   hg commit -A
   That last command is going to bring up a nano (or emacs or VI depending on $EDITOR) console where you should enter initial comments about your repository so that someone else who accesses it knows what's up. The usual choice is just a note about where the README file or user's manual for your software is.
   
   If you got that far then you technically have a repository working - congratz. After a successful commit you should see a list of the files added/deleted/modified, and also a line that looks like
   committed changeset 0:dec31a8f5555
   In order to keep track of what revision a repository is at, Mercurial assigns it a hex code, which is what weird number at the end there is. Mercurial calls the revisions you have made to the repository a changeset, which is why that word appears there. Because Mercurial is distributed version control software you can't track changes from a central repository, which means that changes need to be tracked in a more complicated fashion. You guys don't need to be worried about that though. You do need to be worried about who can access your repository though. Normally you'd limit access by making users sign up and assign a password, but because we're not working on anything too serious I think we can just give everyone on ada access to your repository. Folks would still need to know where to go to get stuff so it's not that serious. To add the necessary permissions you need to execute the commands
   cd ~/hg
   chmod ugo+rwx -R myrepo
   This command gives ugo (user/group/others) permission to rwx (read/write/execute) the directory myrepo. The -R tells the command to act recursively and give all the files and directories within myrepo the same permissions. You also need to go to your main directory and change permissions to get to that directory. Like I said, in general this is the wrong way to do this, but for the purposes of this class we'll let it go. cd
   chmod a+rx .
   chmod a+rx hg
   Here I use a in place of ugo, but they mean the same thing. Now you can create a copy of your repository in your $HOME with the command
   cd
   mkdir tmp; cd tmp;
   hg clone ~/hg/myrepo myrepo_work
   Anyone else from the class can now also look at your directory with the same command, although they would need to replace the ~/hg/myrepo with hg clone ~/../<user_id>/hg/myrepo yourrepo_test
   where <user_id> is your user name that they need to access your repository. Now that you have a repository you can work from there using standard commands.
   cd ~/tmp/myrepo_work
   To get the most recent version of the repository, execute
   hg pull; hg update
   After you edit some files locally you can check to see what is different on your local clone with
   hg status
   You can see exactly what differences there are in those files with
   hg diff
   or you can look at just a single file
   hg diff <file1>
   Perhaps you want to look at a file that shows up as different in hg status. You can also use the hg diff command to create a patch for other users, but I wouldn't worry about that too much now. If you have looked at your changes and decided you want to save those on your own repository, use the command
   hg commit <file>
   When you try to commit a file, Mercurial will prompt you to enter some comments to explain the change to other users. It is generally recommended that you make many small changes and keep your comments appropriately short. If you make a big commit that's okay, but the better strategy is make many small commits that can be tracked individually. Once you're done writing comments, push the change back to the main repository with
   hg push; hg update
   I may add a section to References about Mercurial. Lemme know if you think that's necessary.