contrib/code_swarm/README

   1 code_swarm is an experiment in organic software visualization.
   2
   3 See http://vis.cs.ucdavis.edu/~ogawa/codeswarm for a picture of what we want
   4 to produce.
   5
   6 Google Code Project :      http://code.google.com/p/codeswarm/
   7 Google Group/Mailing List: http://groups.google.com/group/codeswarm
   8
   9
  10 I) How to build Java code_swarm in different environments.
  11
  12 Please visit http://code.google.com/p/codeswarm/wiki/HowtoBuild for more
  13 detailed and up-to-date information.
  14
  15 This quick guide explains how to setup your development environment to build
  16 the binary (ie. jar) version of code_swarm from Java sources.
  17 Explanations require at least an understanding of computing and of your
  18 Operating System, even if no Java skills are needed.
  19
  20 I.1) Setup
  21 You will need the "Ant" software building tool, and Sun's Java Development Kit,
  22 version 1.5 or later (OpenJDK may work but is untested).
  23
  24 I.1.a) Linux
  25 This guide is written with a Debian based Linux, Ubuntu 8.04. It requires
  26 some minor adaptation to use on other distribution (other packaging systems).
  27
  28  * install ant with the following command (or with your favorite graphical
  29    package manager):
  30      sudo apt-get install ant
  31
  32  * install sun-java-jdk 1.5 or 1.6 following your distribution recommendation
  33     sudo apt-get install sun-java6-jdk
  34
  35  * configure the Java SDK to specify the new installation path, for instance
  36    on Ubuntu:
  37      sudo update-java-alternatives -s java-6-sun
  38
  39    See http://doc.ubuntu-fr.org/java
  40
  41 I.1.b) Windows
  42  * download ant for all platforms at http://ant.apache.org/bindownload.cgi
  43
  44  * unpack it where you want it to be installed, and add the location of
  45    its binaries to the the "PATH" environment variable. For instance,
  46    add at the end : "C:\apache-ant-1.7.0\bin;"
  47
  48  * download Sun Java SDK at http://java.sun.com/javase/downloads/index.jsp
  49
  50  * install it and add the "javac" Java compiler to the PATH :
  51    "C:\Program Files\Java\jdk1.6.0_06\bin;"
  52
  53  * then create a new environment variable called JAVA_HOME and set its path to
  54    something like "C:\Program Files\Java\jdk1.6.X", where X is the specific
  55    version number.
  56
  57 I.2) Getting the sources
  58
  59 code_swarm sources are under a Google Code Subversion repository (svn) :
  60 http://codeswarm.googlecode.com/svn/trunk/
  61
  62 See the Subversion homepage on subversion.tigris.org for all appropriate tools
  63 and documents. I would recommend "TortoiseSVN" for Windows users.
  64 Unix-like users should get their native "Subversion" package.
  65
  66 See http://code.google.com/p/codeswarm/source/ for further instructions on
  67 how to browse and checkout the sources.
  68
  69 I.3) Building the sources
  70
  71 Quick build :
  72  * Open a terminal/command line shell, change directory to the root of
  73    the code_swarm source folder.
  74
  75  * Compile the sources by typing "ant".
  76
  77
  78
  79
  80 Other commands :
  81  * "ant all" will also generate the Javadoc HTML sources documentation
  82  * "ant clean" will delete all intermediate and binary files
  83
  84 I.4) Running code_swarm
  85
  86 These instructions are meant to be generic to cover most popular version
  87 control systems.
  88 Please visit http://code.google.com/p/codeswarm/wiki/GeneratingAVideo for more
  89 detailed and up-to-date information.
  90
  91  * Obtain the log from your software version control system.
  92    Save it as a text file.
  93
  94  * Convert your log file to the code_swarm XML data format:
  95      Change directory to "convert_logs."
  96      Generally, the syntax is:
  97
  98          convert_logs.py -Y input_log.txt -o output.xml
  99
 100      where -Y is a flag for your particular version control system.
 101      Type "convert_logs.py --help" for details.
 102
 103  * Create your own configuration by copying "data/sample.config" and editing
 104    it to your preferences.
 105
 106  * To launch code_swarm, type "run.bat" in Windows or "run.sh" in Unix.
 107    You will be prompted for the config file from the previous step.
 108
 109  * If you have specified TakeSnapshots=true in the config, saved images
 110    will be in the "frames" directory.