Code as a Crime Scene: The Tools

March 2015

Get your investigative tools

This page contains distributions and installation instructions for the tools supporting my book Your Code as a Crime Scene.

The book is now complete and will ship on March 13th 2015. There's a beta version available if you want to start to read it today. You can get the beta here. Stay tuned on my RSS or follow me on Twitter where I'll announce new versions.

Install Code Maat

Code Maat consists of an executable jar file and a bunch of scripts. As such you need to:

  1. download the distribution,
  2. extract it into a folder/directory of your choice, and
  3. add the path to that folder to your environment

Start by downloading the latest version 0.8.5 here:

Now, extract the file into a folder of your choice and add it to your environment (i.e. the PATH environment variable).

Here are some useful links that explain how you do that on your system:

You need to install Java

Code Maat is written in Clojure and requires Java (at least Java 1.6). If you don't already have java installed, get it online.

The start-up script will assume that the command java is available on your path too. Please ensure that your can run java from a command line. Like this: 

        prompt> java -version
        java version "1.7.0_40"
        Java(TM) SE Runtime Environment (build 1.7.0_40-b43)
        Java HotSpot(TM) 64-Bit Server VM (build 24.0-b56, mixed mode)

Try it out

How you invoke Code Maat is operating system dependent:

Try it out by giving maat the -h flag. This will present a usage description. Here's how it looks: 

        prompt> maat -h
        This is Code Maat, a program used to collect statistics from a VCS.
        
        Usage: program-name log-file [options]
        
        Options:
        -l, --log LOG               Log file with input data
        -c, --version-control VCS   Input vcs module type: supports svn, git or hg
        ...

If you got everything right, Code Maat responds with a short usage overview as illustrated above. If not, ensure the start-up script maat is on your PATH.

Install Git for the case studies

To follow along in the practical examples you also need Git. The analyzes do work with other types of version-control systems, but the systems we'll use for our case studies are stored in Git.

If you don't already have Git, get an installation online

If you happen to use another version-control system, chances are it will provide the information needed for the analyses presented here. We'll discuss how in Code as a Crime Scene.

Install Python for scripting

We'll also be using some Python to process analysis results. Note that you'll need a Python 2 installation (Python evolves on two different branches. At the time of writing I'm running the scripts on version 2.7.7).

You can get Python online as well.

Again, there's nothing special about Python - the techniques here don't depend on it. Python is just a convenient language to automate repetitive tasks.

Get the Python scripts we'll use

Download the supporting scripts here. The current version is 0.4.

Unpack the scripts into a folder of your choice. When you run the scripts, remember to provide the complete path to them. Here's an example:

I have my scripts stored in the folder maat/scripts. My current working directory is maat/somecoolcode. To run one of the scripts, in this example merge_comp_freqs.py, I write: 

         prompt> python ../scripts/merge_comp_freqs.py

Download the samples

The book references some pre-generated visualizations. You can download the samples here.

Just extract the files in a folder of your choice. We'll explain how you explore them in the book.

Have fun!

Now that you have your tools I wish you a pleasant reading - enjoy Code as a Crime Scene.