[under construction -- Main.EelcoVisser - 16 May 2003]

A full fledged Stratego application does more than transform an ATerm into another ATerm. To transform programs it is necessary to parse the input program, turn the [[Transform.ParseTree][parse tree]] into a an [[abstract syntax tree]], apply several transformations, and [[pretty print]] the output program. These separate operations should also be glued together into a complete transformation system. The StrategoXT
tools support the creation and composition of components for all aspects of transformation systems. Since the tool set is very flexible and programmable, there are many possibilities for using it. 

This page provides a guideline for setting up a typical [[Stratego application]]. The application is developed as a package under the control of Tools.AutoMake and Tools.AutoConf using the AutoXT abstractions developed for StrategoXT.

As an example we examine the [[PrologTools][prolog-tools]] package, which provides
basic support for transforming Prolog programs.

%TOC%

----++ Structure of the Package

A source-to-source transformation system consists of a parser, several transformation components,
and a pretty-printer. These components are specified in subdirectories of the package. The 
following directories are standard in a package providing support for one or more languages:

	* [[%SVNSTRATEGOXT%/trunk/prolog-tools/syn][syn]] -- syntax definitions
	* [[%SVNSTRATEGOXT%/trunk/prolog-tools/sig][sig]] -- signatures describing abstract syntax trees
	* [[%SVNSTRATEGOXT%/trunk/prolog-tools/pp][pp]]  -- pretty-print tables 
	* [[%SVNSTRATEGOXT%/trunk/prolog-tools/xtc][xtc]] -- tool compositions
	* [[%SVNSTRATEGOXT%/trunk/prolog-tools/tests][tests]] -- unit and integration tests

In addition a package can contain several directories for transformation componens.

----++ Configuration

It is customary to develop Stratego packages using the Tools.AutoMake and Tools.AutoConf in order to make packages easiliy portable to many (Unix compatible) platforms. If you are not familiar with
these tools please check out their documentation.

----+++ Configure.in

From the =configure.in= file, the build-time =configure= script is generated. It takes 
configuration parameters such as external packages and substitutes them in makefiles and
other source files. The =USE_XT_PACKAGES= macro can be used in order to get parameterization of the [[StrategoXT packages]].

%SVNSTRATEGOXT%/prolog-tools/trunk/configure.in
<pre>
---------------------------------
%INCLUDE{%SVNSTRATEGOXT%/prolog-tools/trunk/configure.in}%
---------------------------------
</pre>

----+++ bootstrap

In order to generate the =configure= script and instantiate the makefile templates several
tools from the autoX family should be applied. The =bootstrap= script calls these tools in
the right order. One unusual tool is [[AutoXT][autoxt]], which installs Tools.AutoMake macros supporting
the use of StrategoXT tools. The =bootstrap= script assumes that =autoxt= can be found in the
path.

<pre>
---------------------------------
%INCLUDE{%SVNSTRATEGOXT%/prolog-tools/trunk/bootstrap}%
---------------------------------
</pre>

----+++ Makefile.am

Each directory in the package should have a =Makefile=. These =Makefiles= are generated by
automake and autoconf from a declarative =Makefile.am=. The top-level Makefile just declares
its subdirectory such that navigation code can be generated. The =Makefile.xt= is installed
by =autoxt= and contains standard make rules for applying StrategoXT tools. It should be
included in each makefile in the package.

<pre>
---------------------------------
%INCLUDE{%SVNSTRATEGOXT%/prolog-tools/trunk/Makefile.am}%
---------------------------------
</pre>

The =AC_CONFIG_FILES= macro defines all files that should be created by =configure=.

----+++ Other Required Files

Automake/conf require the following files to exist in the package:

	* [[%SVNSTRATEGOXT%/prolog-tools/trunk/README][README]] -- name and purpose of the package
	* [[%SVNSTRATEGOXT%/prolog-tools/trunk/AUTHORS][AUTHORS]] 
	* [[%SVNSTRATEGOXT%/prolog-tools/trunk/ChangeLog][ChangeLog]] -- fine grained log of changes
	* [[%SVNSTRATEGOXT%/prolog-tools/trunk/NEWS][NEWS]] -- course grained description of changes

----+++ Configuring the Package

Once the basic configuration is set up you can configure the package with the following sequence
of commands:

<verbatim>
	> ./bootstrap
	> ./configure  --prefix=/installation/directory  --with-xt=/usr
</verbatim>

Assuming that the StrategoXT,  ATerm, and SDF distributions have been installed in =/usr=. Now it should be possible to =make= and =install= the components in the package using the commands:

<verbatim>
	> make
	> make install
</verbatim>

Exported components are installed in subdirectories of the =/installation/directory=.

----++ Syntax Definition (syn)

The syntax definition of the language under consideration (Prolog in this case) is defined
in directory =syn/=. The directory contains the following files:

	* [[%SVNSTRATEGOXT%/trunk/prolog-tools/syn/Prolog.sdf][Prolog.sdf]] -- syntax definition of Prolog
	* [[%SVNSTRATEGOXT%/trunk/prolog-tools/syn/Stratego-Prolog.sdf][Stratego-Prolog.sdf]] -- embedding of Prolog in Stratego for use of concrete Prolog syntax in Stratego
	* [[%SVNSTRATEGOXT%/trunk/prolog-tools/syn/sicstus_45.html][sicstus_45.html]] -- informal definition of Prolog syntax

The =Makefile.am= defines which parse tables to make (=.tbl= extension):

<pre>
---------------------------------
%INCLUDE{%SVNSTRATEGOXT%/prolog-tools/trunk/syn/Makefile.am}%
---------------------------------
</pre>

----++ Signature (sig)

The [[algebraic signature]] defines the [[abstract syntax]] of a language. The signature
of Prolog abstract syntax is defined in the =Prolog.str=:

	* [[%SVNSTRATEGOXT%/trunk/prolog-tools/sig/Prolog.str][Prolog.str]] -- signature of Prolog abstract syntax

The signature can be derived automatically from a syntax definition using the tool =sdf-to-sig=. The make rules
in =Makefile.xt= invoke this tool based on the dependency of =.str= files on =.def= files. The =Prolog.def=
file is made available via a symbolic link to the =../syn/= directory.

<pre>
---------------------------------
%INCLUDE{%SVNSTRATEGOXT%/prolog-tools/trunk/sig/Makefile.am}%
---------------------------------
</pre>

----++ Pretty-Printer (pp)

A pretty-printer renders an abstract syntax tree as text. The [[Tools.GenericPrettyPrinter][GPP]] package in StrategoXT provides tools for rendering ASTs as ascii text, html, and latex. The translation works by first translating an AST to a Box term, which declares formatting independently of the target device _and_ the source language. A Box can be formatted in different ways. The translation from AST to Box can be done in two ways. GPP supports [[Tools.PrettyPrintTable][pp-tables]] which define a mapping from AST constructors to Box terms. The [[Tools.PrettyPrintTableGenerator][pp-gen]] tool generates a default pp-table from a syntax definition. Alternatively one can program the translation from AST to Box in a Stratego program. Although the latter is more work, it may be necessary when more sophisticated formatting is required. The Prolog package uses both methods.

	* [[%SVNSTRATEGOXT%/prolog-tools/trunk/pp/Prolog.pp][Prolog.pp]] -- default pretty-print table for Prolog
	* [[%SVNSTRATEGOXT%/prolog-tools/trunk/pp/Prolog.pp][Prolog2abox.str]] -- Stratego transformation from Prolog abstract syntax to Box

<pre>
---------------------------------
%INCLUDE{%SVNSTRATEGOXT%/prolog-tools/trunk/pp/Makefile.am}%
---------------------------------
</pre>

----++ Tool Composition (xtc)

<pre>
---------------------------------
%INCLUDE{%SVNSTRATEGOXT%/prolog-tools/trunk/xtc/Makefile.am}%
---------------------------------
</pre>

----++ Tests (tests)

<pre>
---------------------------------
%INCLUDE{%SVNSTRATEGOXT%/prolog-tools/trunk/tests/Makefile.am}%
---------------------------------
</pre>