The Smudge Programming Language

Smudge is a domain specific language for implementing state machines. The compiler generates standard C code as well as graphical state diagrams. Its output is optimized for use on very limited embedded systems, but designed to be used anywhere state machines are appropriate. Here's a simple example to show you what the language looks like:

first.smudge

SM_NAME
{
    *FIRST_STATE (@enterFirst)
    [
        event --> SECOND_STATE,
        altEvent -(@sideEffect)-,
        reenter --> FIRST_STATE
    ] (@exitFirst),

    SECOND_STATE
    [
        _ -(@sideEffect)-> FIRST_STATE
    ]
}

Getting Smudge

Splat

Instead of installing Smudge by itself, most people will want to install Splat, the Smudge Platform, which bundles together everything you need to use Smudge. To download, go to the Splat releases page for the latest platform release.

Debian

Users of Debian and derivatives can add the Smudge package repository and keep Smudge installations current by following these directions. There is a package for Smudge by itself, called smudge, but also a package for all of Splat, called smudge-platform.

Binaries

If you really want to install the Smudge compiler by itself, there are binary releases available for Windows and Linux available on the Smudge releases page. The latest release includes a pdf of the tutorial, which is a great place to start learning Smudge.

Building From Source

First, make sure you have ghc installed, along with haskell-stack. In order to build the documentation, you'll also need rst2pdf and pdflatex.

Then, in your shell of choice, run:

$ make

The first time you build, it might tell you to run

$ stack setup

This may take a bit, as stack will have to download and configure the build environment.

This should work on Windows under Cygwin, as well as reasonably recent versions of Debian (with issues) and Ubuntu. It has worked on other distros and MacOS, and if you have trouble getting it to build we encourage you to ask for help on gitter. It generates an executable called smudge (or smudge.exe on Windows) that you can use to compile Smudge code by running stack exec smudge.

How to Use Smudge

Once you have Smudge installed, either because you built it from source or downloaded a release, the best way to learn how to use it is to look at the tutorial. It's in the release tarball and it's built as part of the normal build process in docs/tutorial/tutorial.pdf. Here's the quick version for the impatient though.

Prerequisites

First, make sure you have graphviz installed. It should be available through your package manager on Linux, through homebrew on MacOS, or within cygwin on Windows. If you're running on Windows, we strongly suggest that you use Cygwin.

Running

$ smudge --dot-fmt=Svg first.smudge
Wrote file "first.svg"
Wrote file "first.h"
Wrote file "first.c"
Wrote file "first_ext.h"

This generates 4 files. The .svg file is just an image with a diagram of your state machine. The .h file is the interface to the code generated by Smudge, and the _ext.h file contains generated prototypes for functions you must provide.

There's more!

Further example state machines can be found in the examples directory. In particular, first.smudge is the state machine shown above but with extensive comments to describe what it's doing.

There's also a gitter if you need help or want to communicate with the contributors.

License

Smudge is released under a standard BSD 3-clause license, found in LICENSE file.