An introductory guide for new FLAME developers

Field G. Van Zee
last updated on 6 October 2006

We use subversion for source and version control. It is very much like CVS, but without all of the annoyances and brokenness that comes from its ancestry with the old RCS system. I have written a quick-reference guide at

http://www.cs.utexas.edu/users/flame/dev_info/svn_qref.html

with links to the subversion homepage and the official O'Reilly subversion book (accessible online for free). Please look at the book sections that I list near the top of my quick reference--they give a good introduction to using subversion, and source control in general.

The libflame repository is located on the UTCS filesystem in "~field/repos/flame". Please look at your ~/.bash_profile (or whatever shell login init file you happen to use) and define the SVN_EDITOR environment variable and set it to your choice of editor. This program will be launched when you commit changes so that you can make log entries for that revision, so be sure it's an editor you're comfortable with. Let me take a moment to explain the directory structure that I recommend using to manage your FLAME code and libraries. All directories below are relative to $HOME (or ~field if we're referring to my own layout).

flame             The root directory for FLAME code, libraries, and work products.
flame/include     Default location where FLAME headers get copied during installation.
flame/lib         Default location where FLAME libraries get copied during installation.
                  Related libraries may also reside here.
flame/lib/goto    A place to collect GotoBLAS libraries.
flame/lib/blas    Home to the netlib BLAS code (for reference only).
flame/lib/lapack  Home to the netlib LAPACK code (for reference only).
flame/working     Contains your checked-out working copy of the FLAME repository.
flame/export      Contains exported copies of the FLAME repository.

In general, I recommend you mirror this layout in your own home directory. You should also populate your flame/lib/goto directory with the libraries that I keep in the corresponding ~field/flame/lib/goto. (Notice that not need to copy over the contents of flame/export or flame/working. You also do not need to worry about the libflame* files in flame/lib and the files in flame/include as fresh versions of these files will be placed there you run "make install".)
Also, you should create a symbolic link in flame/lib to the actual Goto library you wish to use. An example of creating this symbolic link is:

$ cd $HOME/flame/lib
$ ln -s goto/libgoto_northwood-32-r0.99-3.so ./libgoto.so

Replace "libgoto_northwood-32-r0.99-3.so" with the name of the actual library
file appropriate for your architecture.

Now that we have the directory structure in place, let's check out the libflame source code. Here are a few steps that will get you up and running:

$ cd $HOME
$ cd flame/working
$ svn checkout svn+ssh://cshostname.cs.utexas.edu/u/field/repos/flame
(the checkout will take a few moments)
$ cd trunk

Notice that you must supply a valid UTCS host in place of 'cshostname'. I've been told that 'linux' is guaranteed to always be available (ie: it will not be retired) so that might be a good choice for 'cshostname'.

As you make changes to your working copy, use 'svn status' to see your local modifications. When you are happy with your changes, you may commit them with 'svn commit'. PLEASE TEST YOUR CHANGES BEFORE COMMITTING THEM! To pull in others users' changes (if there are any), use 'svn update'. With all three of these commands, your current working directory matters. Specifically, all three of these commands are recursive by default, and the effects of the commands only apply to the items in the current directory, and any items found in any subdirectory of the current directory. So, if you're at the root level of your checked-out working copy, then these commands apply to your entire working copy, all the way down to the "leaf" directories. If you're in some subdirectory, these commands only apply to the corresponding subdirectory.

To see the difference between a file or files with local modifications and the files as they were when you checked them out, use 'svn diff' or 'svn diff <file>'.

An 'svn log' (or better yet, 'svn log | less') will show you all commit log entries relevant to your current location in the source tree. Go to the root level and use 'svn log' to see all log entries.

That's about it for now. Please do not hesitate to ask for help if you have any trouble or questions!