Creating a Stratego/XT project the simple way

The easiest way to set up a working Stratego/XT project is to use the Create-a-Project tool called crap, available in the strategoxt-utils package.

Once installed, creating a new project p0 is as easy as one line:

$ crap --new-project p0

This will generate an standard GNU Autotools-based build system, including with a minimal example (src/xmpl.str):

p0/
   Makefile.am
   README.Developer
   README
   AUTHORS
   bootstrap
   p0.spec.in
   NEWS
   p0.pc.in
   configure.ac
   ChangeLog
   xmpl/
        Makefile.am
   syn/
       Makefile.am
   tests/
         Makefile.am
   src/
       Makefile.am
       xmpl.str

The project is ready to be compiled,

$ ./bootstrap
$ ./configure --prefix=$HOME/apps/p0
$ make all 

installed,

$ make install

and executed:

$ echo "foo" | $HOME/apps/p0/bin/xmpl
Hello, World!

(The example is a transformation component using io-wrap -- it takes a term and spits out the string "Hello, World!".)

Adding project dependencies

Most non-trivial Stratego/XT projects rely on pre-existing libraries and tools, such as one of the many language parsers available for Stratego/XT. Using the --deps switch, you can add the necessary lines to the configure.ac file as well as the appropriate include switches to each Makefile automatically:

$ crap --deps java-front,dryad --new-project p0

The above will create the project p0 with XT_USE_JAVA_FRONT and XT_USE_DRYAD added to your configure.ac, plus the necessary -I, -L and -l flags throughout each generated Makefile.

It is possible to list the available dependencies which are addable to your project using the --list-available-providers switch:

$ crap --list-available-providers

This would give a list looking something like this:

dryad
stratego-aterm
stratego-tool-doc
stratego-sglr
stratego-xtc
stratego-gpp
stratego-lib
c-tools
stratego-sdf
java-front
stratego-rtg

Beware: The dependency/provider system will change in future versions of crap.

Adding pre-made syntax fragments

crap comes with a small (but growing) collection of syntax modules that may freely be used in your project. This might save you from a lot of boring boilerplate code when defining a new language. To add a basic definition of whitespaces and integer literals to your project, do:

$ crap --create-project p0 --syntax-modules integer-literals,whitespace

To list the available syntax modules in your version of crap, use the --list-syntax-modules switch:

$ crap --list-syntax-modules

It will return a list on the form:

floating-point-literals
integer-literals
whitespace

XTC support

There is some basic support for setting up a build of XTC components using crap, using the --xtc switch:

$ crap --xtc --new-project p0

The above will create the following src/ directory layout and content:

   src/
       Makefile.am
       xtc/
           Makefile.am
           xtcxmpl.str

The xtcxmpl will be compiled against libstratego-xtc. Upon installation, it will registered as an XTC component and placed in ${prefix}/libexec.

Making libraries

Building libraries with Stratego requires a fair bit build setup. This is done automatically for you using the --library switch:

$ crap --library --new-project p0

This will create the following src/ directory layout and content:

src/
    Makefile.am
    lib/
        Makefile.am
        def-libxmpl.str
        xmpl/
             foo.str

Upon compilation, the files libxmpl.str, libxmpl.rtree, libxmpl.ctree and libxmpl.so (plus auxiliary libtool files) are generated. The are all installed into ${prefix}/share (.ctree, .rtree) and ${prefix}/lib (.so) as is normal for Stratego libraries.

Working with Spoofax

If you are developing with Spoofax, you can generate the necessary Eclipse files (.project) as part of the project creating using the --eclipse= switch:

$ crap --eclipse --new-project p0

Generation source code documentation

Source code documentation, Javadoc-style, can be generated from Stratego code using the XDoc tool. By adding the --xdoc switch, the build system will be set up to generate source code documentation in the doc/api directory:

$ crap --xdoc --new-project p0

This will add a doc/ directory and an appropriate Makefile.

   doc/
       Makefile.am

Questions? Bugs?

If you have questions, please post them to the Stratego mailinglist. Bugs are best reported using our issue tracker.

-- KarlTrygveKalleberg - 23 May 2008