mscgen

This post is to provide notes on using mscgen, a tool that I like to use for making sequence diagrams.

Sequence diagrams have proven themselves to be useful for reasoning about control and data flow in systems, especially asynchronous or concurrent systems. With that being said, I hate using a mouse for anything. I’m a proud vim enthusiast, and I use awesome wm as my window manager. This allows me to run a keyboard focused life, and that’s the way I like it! The trouble usually comes in with diagramming tools. It’s one of the most tedious tasks I encounter as a software engineer. I follow a repeatable and algorithmic strategy when building them, and the tools often require significant mouse precision to get things lined up nicely and the lines straight.

Luckily, mscgen is here to help! This tool takes a text file as input and generates an image as output. Their website has a great example of the source file and the image output.

In this blog post, I’m just collecting some notes that I never seem to remember when I go too long without using this tool.

Step One, Install the Damn Thing (tm)

On Ubuntu

sudo apt-get install mscgen

On Arch mscgen is available in the AUR

Step Two, Generating Source Files

mscgen expects msc files, which are built using a simple syntax. A diagram is scoped within a top-level msc block, and inside the diagram properties are configured, actors are named, and messages betwen those actors are outlined.

Below, you’ll find an example (liberally taken from the mscgen docs).

# Example msc file
msc {
  hscale = "2";

  a,b,c;

  a->b [ label = "ab()" ] ;
  b->c [ label = "bc(TRUE)"];
  c=>c [ label = "process(1)" ];
  c=>c [ label = "process(2)" ];
  ...;
  c=>c [ label = "process(n)" ];
  c=>c [ label = "process(END)" ];
  a<<=c [ label = "callback()"];
  ---  [ label = "If more to run", ID="*" ];
  a->a [ label = "next()"];
  a->c [ label = "ac1()\nac2()"];
  b<-c [ label = "cb(TRUE)"];
  b->b [ label = "stalled(...)"];
  a<-b [ label = "ab() = FALSE"];
}

Step Three, Make Some Beautiful Pictures

mscgen is invoked with the following:

$ mscgen -T png -i example.msc -o example.png

More detailed information regarding switches and functionality can be found in man 1 mscgen.

Step Four, Put Them In Source Control

Now that we have text source for sequence diagrams, that means we can effectively store them in our VCS solution. The text can be merged easily and revision diffs will be meaningful (versus the meaningless difference between two PNG files).

If you have other team members that are interested entirely in the diagrams only, you can add a small shell script to generate all of the png files for each msc input file.