Collab:VisItWiki SVNlayout

Repository layout

Subversion is a directory-based repository system. Directories are used to do versioning and do branch development. Of course, directories are also used for organizing files for the VisIt project. So we introduce two terms that will distinguish between these different use of directories. The VisIt tree will be a directory structure that contains all of the source code, documentation, testing code, etc for the VisIt project. It represents a snapshot of the entire project. A top-level directory will be a directory near the root of Subversion tree that is used for versioning or branch development. Sometimes a top-level directory will contain multiple subdirectories (for example, one for each development branch of a given developer). But, ultimately, every top-level directory will contain a complete VisIt tree underneath it. (Note that this is not required by SVN. It would be possible to have only a portion of the VisIt tree underneath it. But, for simplicitly, and because copying trees is very cheap -- like a Unix hard link -- we copy the whole tree.)

The two primary goals for layout inside the Subversion repository were to make a structure that would be familiar to Subversion users and also to make a directory structure that will minimize unnecessary network traffic.

Top-level directory repository layout

At the top level, there are three directories:

  1. visit/trunk
  2. visit/branches
  3. visit/tags

The three selected names are the names recommended by the Subversion development team. The trunk will contain the mainline version of the code. This is for longer-term commits that need "time to soak." branches are for pending and past releases and for personal workspaces where checkins and checkouts can be performed that are not made visible to the trunk. Release candidate branches are used for official releases. These workspaces may be for an individual or for collaborative, long term work. tags is for releases and is considered immutable.

These three directories comprise the so-called "top-level" directories. The standard VisIt directory structured lies directly under trunk. For branches and tags, there are additional directories to signify the work being done, for example, branches/prevost/steering or tags/1.6.1. In those cases, the VisIt tree then lies underneath those directories.

The top-level directory structure is designed to facilitate two major features (branch development and release management) which are described in the following subsections.

Layout of the VisIt tree

As previously stated, each top-level directory, such as trunk, tags/1.6, and branches/childs/vr_work, will contain a "VisIt tree". The VisIt tree looks similar to the layout in the ClearCase VOB, but some directories have been separated out to minimize network traffic. Restated, each time you checkout the VisIt tree (which typically happens once for each corresponding checkin), you have to go portal-auth.nersc.gov to access the files. So it makes sense to only get the files that you need.

The tree contains 6 directories:

  1. src
  2. test
  3. data
  4. docs
  5. third_party
  6. windowsbuild

Directory: src

src contains the VisIt source code. It contains directories like src/components, src/viewer, src/plots, etc. Regular VisIt development can be done with a checkout on only this directory.

Directory: test

test contains all of our testing infrastructure. The motivation for separating this directory into its own subdirectory is to spare folks from downloading the hundreds of megabytes of baseline images if they do not need to run the regression tests.

Directory: data

data contains static and dynamic data sets. Static data sets are the ones that are currently bzipped in the VisIt VOB. These data sets are large and there is no reason to make developers download them if they are not needed. Dynamic data sets are the ones that get generated using a program, such as testall.C.

The motivation for separating them from test is users may want to access some of the data sets without running tests.

Currently, it makes sense to put dynamic data sets in this directory, but that can be easily changed if it doesn't work out.

Directory: docs

docs contains documents. Documents are separate from the source code, so there is no reason to keep them together. (Obviously, documents can be large so there is no reason to make developers download them if they are doing bug fix work, for example.)

Directory: third_party

third_party contains third party libraries.

Directory: windowsbuild

windowsbuild contains the binary files necessary to do a build on the Windows system.