Introduction
This note for Mac OS X software developers explains how to integrate the Ragel state machine compiler by Adrian Thurston with Apple’s XCode IDE on Mac OS X. As an additional goodie, it shows how to add the Graphviz diagram tool into the mix to provide visualization of the state machines represented by your Ragel grammar.
What is Ragel?
Ragel is a very useful and elegant tool for developers that takes a description of a grammar for a given input and converts it to a C language source file with code that implements state machines to process this input. This can be used to build parsers for all kinds of interesting applications. Personally, I use it to parse XML data in my TestXSLT tool, which contains a simple XML Editor.
Ragel input files (usually with the suffix .rl) contain a formal description of your grammar as well as snippets of C code you write to process the input data as the state machines processes its input. The format is described in detail in the Ragel User Guide on the Ragel Website.
Ragel is usually used on the command line, but it can be integrated with XCode so that XCode does the dependency tracking and automatically re-runs Ragel every time your input grammar file changes.
What is Graphviz?
From the Mac OS X Graphviz website:
The Macintosh port of the automated graph layout software, featuring a new document-based GUI, export to PDF and many more bitmap formats, full alpha transparency, native font support and anti-aliasing.
What is XCode?
XCode is Apple’s free development environment. If you don’t have it already, you can download it from http://connect.apple.com, after registering for a free Apple Developers Connection account there.
Preparation
Ragel
Installation is pretty straightforward; download the source code package from the Ragel website, then do the usual
./configure
make
make install
This will install the ragel binary into your /usr/local/bin directory.
Graphviz
There's not much to do except downloading and installing the application into your /Applications folder.
Configuration in XCode
This assumes that you already have a project in which you want to use/integrate Ragel. Open your project in XCode and select the target in which you're using Ragel input files. Invoke the Inspector on the target using the Info button or the “Get Info” entry in the contextual menu.
In the Inspector, select “Rules” and use the little “+” button at the bottom of the window to create a new custom rule.
Configure the new rule to process “Source files with names matching” with a file name extension of “*.rl”.
Configure it to use a “Custom script” and paste these two lines into the space provided for the custom script:
/usr/local/bin/ragel $(INPUT_FILE_BASE).rl -G2 -o $(DERIVED_FILES_DIR)/$(INPUT_FILE_BASE).c
/usr/local/bin/ragel $(INPUT_FILE_BASE).rl -V -o $(DERIVED_FILES_DIR)/$(INPUT_FILE_BASE).dot
Put this into the “with output files” text field:
$(DERIVED_FILES_DIR)/$(INPUT_FILE_BASE).c
Usage
You can now add your Ragel files to your project. Two things are important:
- Your ragel files’ names must end with “.rl” for the rule to pick them up.
- Your ragel files must be assigned to the “Sources” category of your target:
How it works
Now, whenever you run a build, XCode will run the ragel command line tool on your input files and create the corresponding “.c” output files. Since you assigned the input files to the “Source” code category, XCode will treat the .c files output by ragel as source files too and process them with its internal rules for .c files, as if you had written and added them to the project manually.
XCode will track the dependencies for you so it only runs Ragel to create a new .c file if you changed the .rl file.
Graphviz integration
You might have noticed that the rules configured above create two output files for an input file, a “.c” and a “.dot” file, but we only specified the .c file in the output files section. The “.dot” file just stayed buried in a subdirectory of the “build” subdirectory of your project so far. I suggest that you goo look for it there and add it to your project in the “Products” group:
Don’t add it to your targets and don’t let XCode copy it over if it asks you:
Now, launch Graphviz and drag the .dot file from XCode to the Graphviz application icon in the dock or Finder.
Graphviz will render a diagram of your state machine:
The nice thing is that Graphviz will automatically re-render the graph every time you rebuild your project in XCode after changes to your ragel source file. So you just leave the document open in Grapviz and keep on coding in XCode, and whenever you need a visual feedback of your Ragel code, you hit Cmd-Tab to switch to Graphviz and your updated diagram will be there.