SVNPlot Usage Guide

1. Introduction
===============

This guide describes installing and running SVNPlot 0.7.6 on Linux and OS X.

SVNPlot is a utility written in Python that generates graphs from Subversion
log statistics, using either Matplotlib or JqPlot. Using Matplotlib generates
PNG images, while JqPlot generates JavaScript canvas based graphs.


2. Requirements
===============

* Subversion 1.7.x: http://subversion.apache.org/
* Python2: http://python.org/
* Sqlite3: http://www.sqlite.org/

* PySvn: http://pysvn.tigris.org/
* NumPy: http://numpy.scipy.org/
* Matplotlib: http://matplotlib.org/

* SVNPlot: http://code.google.com/p/svnplot/wiki/Introduction

3. Installation
===============

For Subversion, Python2, and Sqlite3, the recommended way to install them is
using a package manager. On OS X, the easiest way to do it is with `homebrew`.

For NumPy and Matplotlib, `pip install [package]` should work.

PySvn can be found as `python-svn` in apt-get (Ubuntu), or `pysvn` in yum
(Fedora). Binaries are available for Mac.
It can also be installed from source. On OS X, you should follow this guide:
[1]

Download svnplot-0.7.6. Run `python setup.py install`. This will install the
executables under `<PYTHON_PATH>/lib/site-packages/svnplot/`, so you'll have to
call them with the full path
(e.g.: `python <PYTHON_PATH/lib/site-packages/svnplot/svnlog2sqlite.py`)


4. Mirroring the BRL-CAD Repository
===================================

Running SVNPlot requires completing two steps: 1) Convert the commit logs to
sqlite3; and 2) create the actual graphs.
For step 1, you can get the logs from the online repository, or from a local
mirror. Since the former is very expensive in terms of time[2], we're first
going to mirror the online repository on the machine that will run svnplot, and
run the tool on the local copy. In the following instructions, note that
URL_TO_MIRROR is not a path, but a URL. That is, it should be specified using
`file://<FULL_PATH>` instead of `<PATH>`

Step 1: run `svnadmin create brlcad-mirror`

Step 2: edit `brlcad-mirror/hooks/pre-revprop-change` and put the following in
it:
#!/bin/sh
exit 0;

Step 3: run `svnsync initialize URL_TO_MIRROR URL_TO_MASTER --username=user
--password=password`.
For example: `svnsync initialize file:///Users/brlcad/brlcad-mirror https://brlcad.svn.sourceforge.net/svnroot/brlcad/ --username=brlcad --password=brlcad`

Step 4: run `svnsync synchronize URL_TO_MIRROR --username=user --password=password`

For more information, see [3].


5. Running SVNPlot
==================

Recall that running SVNPlot requires completing two steps: 1) Convert the
commit logs to sqlite3; and 2) create the actual graphs. Also recall that the
tools which will perform the steps are installed under
`<PYTHON_PATH>/lib/site-packages/svnplot/`. We'll refer to this path as
"SVNPLOT_PATH" from now on.

Step 1: run `python <SVNPLOT_PATH>/svnlog2sqlite.py -l -v <PATH_TO_MIRROR>
<PATH_TO_SQLITE_DB>`. For example: `python /usr/local/lib/site-packages/svnplot/svnlog2sqlite.py -l -v /Users/brlcad/brlcad-mirror /Users/brlcad/svnplot.sqlite`

Step 2: run `python <SVNPLOT_PATH>/svnplot.py -v --dpi 70 -n "BRL-CAD" <PATH_TO_SQLITE_DB> <PATH_TO_OUTPUT>` for Matplot results (outputs PNG images)

OR

Step 2: run `python <SVNPLOT_PATH>/svnplot-js.py -v -n "BRL-CAD" -j <PATH_TO_SQLITE_DB> <PATH_TO_OUTPUT>` for JqPlot results (outputs JavaScript)

Step 3: Open `<PATH_TO_OUTPUT>/index.htm` and see the results.


6. References
=============

[1] http://codingfu.com/blog/install-pysvn-on-mac-os-x/
[2] http://code.google.com/p/svnplot/wiki/WhySVNplotIsSlowInUpdatingDatabaseForFirstTime
[3] http://blogs.collab.net/subversion/mirroring-repos