% test

\documentclass{article}

\begin{document}

\title{VisTrails Source Tree Overview}

\author{VisTrails development team}

\maketitle

\abstract{This document is intended to provide an overview of the layout of the
source tree of VisTrails, as presented by a Subversion checkout of
trunk.}

\section{Basic Directory layout}

\begin{verbatim}
./
./dist/
./examples/
./examples/data/
./extensions/
./packages/
./scripts/
./vistrails/
./vistrails/api/
./vistrails/core/
./vistrails/db/
./vistrails/doc/
./vistrails/gui/
./vistrails/packages/
./vistrails/tests/
\end{verbatim}

\section{Top-level directories}

The main VisTrails application lives entirely in the vistrails
subdirectory. All vistrail files with example functionality reside in
the examples subdirectory, and any necessary data should go in
examples/data. 

The dist subdirectory includes code and documentation necessary to
create VisTrails stand-alone distributions in several different
operating systems (Linux, Windows, OS X, etc).

Although originally developed as a stand-alone application, VisTrails
has now been extended in many ways. These live, unsurprisingly, in the
extensions directory. Currently, we have mediawiki and latex plugins,
and a web interface for VisTrails. 

Most VisTrails packages should be in the top-level packages
subdirectory. The reason there exists two packages directories is so
that we can conveniently select the set of packages that will be
included in a standard VisTrails distribution. All these default
packages should be in vistrails/packages. Notice that these packages
will be included in distributions for different operating systems, so
try to make sure necessary libraries are available, and that your code
is portable.

The scripts directory includes various scripts that help the
administration of VisTrails source code, services and examples. 

All documentation for VisTrails developers (including this file)
reside on doc.

\section{The vistrails directory}

The VisTrails application source tree itself is loosely organized in
different components that live in different directories. All the basic
Python classes for modules, connections, workflows, etc live in
vistrails/core. As a rule of thumb, the classes in the core component
are agnostic to storage (handled by the db component) and have to user
interface knowledge (handled by the gui component). This was
originally intended in part to allow a separation of developers with
Qt/PyQt4 licenses and developers without Qt/PyQt4 licenses.  The db
component is fairly involved and uses a particular source layout
intended to simplify the creation of new schemas and versions, as
described in Section~\ref{sec:db}.

As a general rule, all code that derives from PyQt4 classes should go
in the vistrails/gui subdirectory. If that is not possible for some
reason, such code should be clearly marked and documented.

VisTrails can also be used as a library, and the api subdirectory
includes several helper python functions and classes to access
VisTrails functionality programmatically. If you intend to write code
that will script VisTrails executions, or are using the VisTrails
shell regularly and have a new function that will be handy in that
scenario, the vistrails/api subdirectory is the correct place to put
the code.

The testing suite infrastructure lives in vistrails/tests. All the
necessary files for the test cases, in particular, should be inside
vistrails/tests/resources.

\subsection{The vistrails/db directory}\label{sec:db}

TBW.

\end{document}
