Software Development

Setting up to perform development of vhtools and initial install

  1. At this point, all developers need to have an account on the VH lab server kfc. Please be sure you have one (contact Steve if you need one).

  2. Install the version management software bazaar according to our recommendations

  3. Make a "branch" of our code on your computer.

    1. On Linux or Mac OS X, open an X11 or XQuartz terminal (XQuartz application in Mac OS X). Use the cd command to move to the directory where you want to work with the code. On Steve's machines, he creates a directory called tools in his home directory and works in that directory:

    2. cd (cd with no arguments moves to the home directory)

    3. mkdir tools (mkdir is make directory; makes the directory tools)

    4. cd tools (changes to the directory tools)

    5. On Windows, I launch cygwin and do the same thing, except that one has to find the home directory. On XP it is as follows:

    6. cd c:\documents\ and\ settings

    7. cd YOURUSERNAME

    8. cd my\ documents

    9. mkdir tools

    10. cd tools

    11. Now call bzr (the command line name for bazaar) to make a branch:

    12. bzr branch sftp://USERNAME@kfc.bio.brandeis.edu//Volumes/DataDrive1/SoftwareDistribution/vhtools-dev

  4. Set up a startup.m file in your Matlab directory:

    1. Start Matlab. If you already have a startup.m file for other programs, you can simply add this to your existing startup.m file. Add the following 6 lines:

    2. mydir = pwd; % save the directory where we are currently

    3. cd('VHTOOLSPATH/VH_matlab_code'); % change directories to the tool path; use your actual directory instead of VHTOOLSPATH

    4. vhtools_startup(pwd,1); % installs the directory paths and initializes objects

    5. cd(mydir); % changes back to the previous directory

    6. clear mydir % clears the variable mydir

    7. Note: if you use Mac OS X or unix, you can put startup.m wherever you like and edit your MATLABPATH variable to include this path; for example, you could add EXPORT MATLABPATH=.:/Users/vanhoosr/tools/vhtools to your .bashrc file.

  1. Test it out. Exit Matlab and re-run it. You may get warnings about directories not being present, but there should be no errors. You should see the libraries being initialized:

  2. Initializing library VH_matlab_code/general

  3. Initializing library VH_matlab_code/TwoPhoton

  4. Initializing library VH_matlab_code/slicetools

  5. Initializing library VH_matlab_code/NeuralAnalysis

  6. Initializing library VH_matlab_code/NewStim

  7. Initializing library VH_matlab_code/NelsonLabTools

  8. Initializing library VH_matlab_code/FitzLabTools

  9. Initializing library VH_matlab_code/VHLabTools

  10. Do you want to run visual stimuli on your computer? If so, install the Psychtoolbox following the instructions here

    1. If you are running on a Mac, you probably want to download the following software first before installing Psychtoolbox:

      1. Xcode (install from the App store, it's a free download but you've got to register). If you're running 10.7 (Lion) or later, then be sure to launch Xcode, choose "preferences", "Downloads", and install the Command Line tools.

      2. Install MacPorts

      3. Install subversion by typing, in an X11 terminal window, sudo /opt/local/bin/port install subversion

      4. Download and install the Psychophysics toolbox using their installer

Updating to the latest version (called "pulling"):

  1. Open an X11 window (Linux or Mac OS X) or launch cygwin

  2. Change to the directory where you keep the code using cd

  3. The first time you update to the latest version, you should use the --remember argument to remember the location:

  4. bzr pull sftp://USERNAME@kfc.bio.brandeis.edu//Volumes/DataDrive1/SoftwareDistribution/vhtools-dev

  5. Subsequently, you can use simply

  6. bzr pull

Uploading your contributions to be included in the main version (called "pushing"):

Follow these instructions to upload your changes to your account on kfc, and then email Steve to look there:

  1. Open an X11 window (Linux or Mac OS X) or launch cygwin

  2. Change to the directory where you keep the code using cd

  3. Call bzr commit -m "yourcomment" where yourcomment is some statement about what has changed (quotes are needed, they should be double quotes not single quotes)

  4. Call this:

  5. bzr push sftp://USERNAME@kfc.bio.brandeis.edu//Users/USERNAME/vhtools-dev

  6. Email steve to notify him of your changes; they will be incorporated into the main branch as soon as possible.

Merging your changes into the current distribution

Q: What if I make a lot of changes to my development branch while, at the same time, someone else makes a lot of changes to his/her branch?

A: The branches need to be merged. The degree to which this is painful depends on the number of files and the complexity of the changes that have been made. The way Steve likes to do this is to use the unix diff command like this:

  1. Make a backup copy of the both directories containing the distributions you are going to merge.

  2. In a large terminal window in X11, compare the 2 directories with the diff command like this:

  3. diff -r directory1 directory2 | less

  4. This searches for all differences between directory1 and directory2 and prints the differences to the command line; the command | less "pipes" the output to the display program less, so you can scroll up and down (using j (down) and k (up); intuitive, no?).

  5. The differences between 2 substantially different distributions can be overwhelming. It is critical to proceed slowly and methodically in resolving the differences, as described below.

  6. There are basically 2 types of differences that can exist between versions: one is a "simpler" situation where a given file simply has additional features (or is a new file) as compared to the previous version; the second is a "complex" situation where the file has been modified by both distributions, and the 2 changes need to be stitched together into a single revision. For each file, determine the situation.

  7. In the "simple" situation, determine which version is the most recent, and make a copy of the revised (or new) file, and replace the old, outdated file. For example, if directory1/subdirectory1/myprogram.m is the latest version of myprogram.m, run

  8. cp directory1/subdirectory1/myprogram.m directory2/subdirectory1/

  9. I find it is helpful to actually have a physical sheet of paper with 2 columns (1 for directory1, the other for directory2) and I indicate, for all files that are different in a simple way, which one has the "latest" version, and then copy the changes. In addition, one should check to make sure that either 1) the "new" version provides output that is "backwards compatible" with the previous version, so that any unmodified program that uses it will not have to be changed, or 2) all the programs that use the previous version have also been modified to accept the new version of the input/ouptut of the program.

  10. In the "complex" situation, one has to bring up the 2 versions of the file in 2 text editors, and manually edit them until they are the same. This can involve some debugging/rewriting if the 2 changes are not immediately compatible with one another.

  11. Again, be patient, proceed slowly and carefully, and test the merged version as you can. Then the merged version becomes the new branch. At the end of the process, diff -r directory1 directory2 | less should produce no output.