0

The Codeswarm project provides a software project repositories visualization tool in Java. The software leverages the commit information from a log generated from a repository. The rendering illustrates the development efforts with an organic node visual render. Color is applied to specified file extensions to differentiate from one language to another, or from code to docs or images etc. This is a sample screenshot using the Ruby git repository:

enter image description here

Support is available for the following "types" of (D)VCS: Subversion, CVS, Git, Mercurial, Perforce, VSS, Starteam, Wikiswarm, Darcs.

It may be helpful to summarize the process involved with using this software from scratch:

  1. Make sure we have the required software

    • apache-ant and what it pulls i.e. openj* and glu...
    • mesa-demos (the package which includes glxinfo)
    • git (or the software we need for repository access and cloning)
    • python 2.x (try "python"+tab to see what you have...)
    • a java JRE of some kind
  2. Insure that the video driver is set up properly and OpenGL is set up correctly (if we ever want to use OpenGL) - try glxinfo | grep OpenGL to see if there are any errors.

  3. Clone a repository with git clone somerepourl.git
  4. Generate a log from the repository directory by running a specific git log command
  5. Bring that .log file to our software directory in bin where we'll run a python script to convert it to a .xml file
  6. Bring that output .xml file to our software data directory for use at execution
  7. (1st run) Make sure our run.sh script where the java command is issued contains the appropriate components and library path
  8. Make sure we configured sample.config properly in /data
  9. Go to the top directory and execute ./run.sh, which compiles the software then runs it

So how do you set this up on a modern Linux platform?

  • Can you please elaborate why setting up software inside an arbitrary timeframe is on topic here? – jasonwryan Jan 7 '14 at 6:33
  • @jasonwryan I've extensively rewritten many segments of the Q&A to make it more universal. – user44370 Jan 7 '14 at 8:59
1

Relevant directory structure

Once you have extracted Rictic's fork archive with unzip, take a quick look at the directory structure:

/code_swarm-master
   |_bin     <----convert tools
   |_data    <----activity.xml(converted .log file), sample.config
   |_dist    <----compiled code_swarm.jar
   |_lib     <----libraries and other .jar files required for java
   |_src     <----code_swarm.java source
   /run.sh   <----to run codeswarm

Clone a repository

Select a a project repository and then clone it locally:

git clone https://github.com/someproject.git

Generate a log file

Proceed to the newly created repository directory and generate a properly formatted git log like so:

git log --name-status --pretty=format:'%n------------------------------------------------------------------------%nr%h | %ae | %ai (%aD) | x lines%nChanged paths:' > activity.log

For long projects, there might be value in specifying a date range so as to focus on a specific time frame (for ex. --since=yyyy-mm-dd, but I have never been able to make this work). Or we can directly edit the xml data later on and strip it of the events we don't want.

Convert our .log file to a .xml file

We then bring this file to the bin directory and convert this with the provided python script(make sure to use python2.x):

python2.7 convert_logs.py -g activity.log -o activity.xml

This is where you would actually open the .xml file in a text editor for example and trim out lines you don't want. Now you can copy that .xml file to your data directory.

Sample.config configuration file

Rename the default sample.config file to another name, create an empty file, put the following in it, then save it as sample.config. The software reads this filename in the data directory by default so it's just convenient to use that. So you'll be able to simply press enter when the software asks for a .config file interactively(it does so every time):

# Input file
InputFile=data/activity.xml
ParticleSpriteFile=src/particle.png

# Basics - leave UseOpenGL to false until you manage to run this in software mode - if you use Virtualbox on a Wintel host, you may have issues so beware!
UseOpenGL=false
Width=800
Height=600

# FramesPerDay: for a short and focused range with high level of detail, use maybe 144. Or use 25 when there is no prior knowledge of how the project unfolds and maybe "2" for a "quick run" with long projects that haven't been constrained to a specific time frame. The smaller this value is, the faster the render goes. Performance may be a consideration when outputting frames to file. In snapshot mode, I have successfully used 720p with 12 frames per day
FramesPerDay=25

# Save each frame to an image?
TakeSnapshots=false
# Where to save each frame
SnapshotLocation=frames/code_swarm-#####.png

# You have to add extension blocks depending on the languages and types of files involved in the project:
ColorAssign1="C",".*(\.c|\.cpp|\.h|\.mk)", 255,0,0, 255,0,0
ColorAssign2="Python",".*(\.py|\.pyx)", 65,105,225, 65,105,225
ColorAssign3="CSharp",".*(\.cs|\.csproj)", 255,255,0, 255,255,0
ColorAssign4="Other Source Code",".*(\.rb|\.erb|\.hs|\.sql|\.m|\.d|\.js|\.pl|\.sh|\.lhs|\.hi|\.hpp|\.cat|\.inf|\.sys|\.dll|\.as|\.cmake\.java)", 255,99,71, 255,99,71
ColorAssign5="Documents/Images",".*(\.txt|\.html|\.tex|\.tmpl|\.css|\.xml|\.yml|\.json|\.rdoc|\.md|\.png|\.jpg|\.gif|\.jpeg|README|COPYING|LICENSE|AUTHORS|\.asciidoc|HACKING)", 138,43,226, 138,43,226
ColorAssign6="Tests",".*test.*", 153,255,255, 153,255,255
ColorAssign7="Localizations","(.*(\.mo|\.po))|(.*\.lproj.*)",110,200,90, 110,200,90

DrawNamesHalos=false
ShowUserName=true
MaxThreads=2
#BoldFont=
Font=SansSerif
FontSize=9
BoldFontSize=10
FontColor=245,245,245
Background=0,0,0
DrawNamesSharp=true
DrawNamesFuzzy=false
DrawFilesFuzzy=true
DrawFilesJelly=true
DrawFilesSharp=false
ShowLegend=true
ShowHistory=true
ShowDate=true
ShowEdges=true
EdgeDecrement=-8
FileDecrement=-3
PersonDecrement=-2
NodeSpeed=7.0
#FileSpeed=5.0
#PersonSpeed=2.0
FileMass=2.0
PersonMass=9.0
EdgeLife=140
EdgeLength=12
FileLife=1000
PersonLife=750
HighlightPct=8
PhysicsEngineConfigDir=physics_engine
PhysicsEngineSelection=PhysicsEngineOrderly

You can eventually compare those settings with the original sample.config file and adjust the parameters. Typos in this file are fatal for java.

Java

It's very important to set this up properly as it can be a real showstopper. When run.sh script is run, it validates if code_swarm.jar is present in dist and if not, it compiles it with ant. Once it's compiled, it gets executed. Unfortunately, the script is geared at MacOSX for execution. To remedy this, edit run.sh and put the following line while making sure other similar lines are commented(#):

if java -d64 -Xmx1000m -classpath dist/code_swarm.jar:lib/gluegen-rt.jar:lib/jogl-all.jar:lib/jogl-natives-linux-amd64.jar:lib/core.jar:lib/xml.jar:lib/vecmath.jar:. -Djava.library.path=lib/ code_swarm $params; then

You have to match what you have in the lib directory:

code_swarm-master/lib]$ ls -l
core.jar
export.txt
freebase
gluegen-rt-natives-linux-amd64.jar
gluegen-rt-natives-linux-i586.jar
gluegen-rt-natives-macosx-universal.jar
gluegen-rt-natives-windows-amd64.jar
gluegen-rt-natives-windows-i586.jar
gluegen-rt.jar
jogl-all-natives-linux-amd64.jar
jogl-all-natives-linux-i586.jar
jogl-all-natives-macosx-universal.jar
jogl-all-natives-windows-amd64.jar
jogl-all-natives-windows-i586.jar
jogl-all.jar
svnkit.jar
swing-layout-1.0.3.jar
vecmath.jar
xml.jar

Note opengl.jar is no longer present in a standalone fashion and is no longer required to make this work(see edit history).


(Optional)

Features. A few changes to the code_swarm.java file in src can improve some features. For instance there is a feature in the rendering called popular nodes. When the codeswarm renders, you can press "p" to show the popular nodes i.e. the files that get edited the most(touches). By default this appears at the top right of the render, but the color coding display appears to the top left. Altering the default behavior can make this appear automatically (so you press "p" to turn it off), while putting this underneath the color display to the left helps to regroup the information in one spot. To implement this find the following block of code and update the values accordingly (3, 105; 10, 105) - this is an updated version of that segment (result shown in Q):

 /**
   * TODO This could be made to look a lot better.
   */
  public void drawPopular() {
    CopyOnWriteArrayList <FileNode> al=new
CopyOnWriteArrayList<FileNode>();
    noStroke();
    textFont(font);
    textAlign(LEFT, TOP);
    fill(fontColor, 200);
    text("Popular Nodes (touches):", 3, 105);
    for (FileNode fn : nodes.values()) {
      if (fn.qualifies()) {
        // Insertion Sort
        if (al.size() > 0) {
          int j = 0;
          for (; j < al.size(); j++) {
            if (fn.compareTo(al.get(j)) <= 0) {
              continue;
            } else {
              break;
            }
          }
          al.add(j,fn);
        } else {
          al.add(fn);
        }
      }
    }

    int i = 1;
    ListIterator<FileNode> it = al.listIterator();
    while (it.hasNext()) {
      FileNode n = it.next();
      // Limit to the top 10.
      if (i <= 10) {
        text(n.name + "  (" + n.touches + ")", 10, 105 + (10 * i++));
      } else if (i > 10) {
        break;
      }
    }
  } 

At the top of the source, you will find:

boolean showPopular = true;

Adding = true makes the popular nodes appear by default. This gets compiled only on the first run with ant during run.sh execution (unless you have java issues and doesn't get compiled at all). So if you modify the source code you must recompile if the code_swarm.jar is already present in the dist directory. If you want to restart the process (which takes a few seconds), just delete the already compiled version, modify the source, then run run.sh again to compile anew.


Running Codeswarm

Finally, now that we have the generated the activity.xml file, set up the sample.config and the modified run.sh script for our setup, we can run Codeswarm with:

./run.sh

Use "space" to pause the rendering and "q" to quit.

Enabling OpenGL rendering

Set UseOpenGL=true in your sample.config file.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy