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/field/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 repository is located on the UTCS filesystem in "~field/repos/flame".

Please look at your ~/.bash_profile and define the SVN_EDITOR
environment variable 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 you do
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 FLAME
source code. Here's a few steps that will get you up and running:

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

Notice that you can use any UTCS host; it doesn't have to be galley.

For a quick description of the contents of major directories, check out my
FLAME repository index.

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!