---++ 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 [[http://releases.strategoxt.org/strategoxt-utils/strategoxt-utils-unstable/][strategoxt-utils]] package.

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

<verbatim>
$ crap --new-project p0
</verbatim>

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

<verbatim>
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
</verbatim>

The project is ready to be compiled,

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

installed, 

<verbatim>
$ make install
</verbatim>

and executed:

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

(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:

<verbatim>
$ crap --deps java-front,dryad --new-project p0
</verbatim>

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:

<verbatim>
$ crap --list-available-providers
</verbatim>

This would give a list looking something like this:

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

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:

<verbatim>
$ crap --create-project p0 --syntax-modules integer-literals,whitespace
</verbatim>

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

<verbatim>
$ crap --list-syntax-modules
</verbatim>

It will return a list on the form:

<verbatim>
floating-point-literals
integer-literals
whitespace
</verbatim>

---+++ XTC support

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

<verbatim>
$ crap --xtc --new-project p0
</verbatim>

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

<verbatim>
	src/
		 Makefile.am
		 xtc/
			  Makefile.am
			  xtcxmpl.str
</verbatim>

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:

<verbatim>
$ crap --library --new-project p0
</verbatim>

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

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

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 [[http://www.spoofax.org][Spoofax]], you can generate the necessary Eclipse files (=.project=) as part of the project creating using the =--eclipse= switch:

<verbatim>
$ crap --eclipse --new-project p0
</verbatim>

---+++ 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:

<verbatim>
$ crap --xdoc --new-project p0
</verbatim>

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

<verbatim>
	doc/
		 Makefile.am
</verbatim>

---+++ Questions? Bugs?

If you have questions, please post them to the [[https://mail.cs.uu.nl/mailman/listinfo/stratego][Stratego mailinglist]]. Bugs are best reported using our [[https://bugs.strategoxt.org][issue tracker]].

-- Main.KarlTrygveKalleberg - 23 May 2008