Stratego / STRJ

Stratego -- Strategies for Program Transformation
STRJ compiles Stratego to Java, and is a Java-based variation of the Stratego Compiler.

Introduction

The compiler comes in two flavors: one called strj, compiled with the standard C-based strc. The second is a bootstrapped, cross-platform compiler that lives in strategoxt.jar. Note that Stratego executables compiled with strj do not support XTC (since it depends on forking native executables and assumes filesystem access) and the strategoxt.jar compiler is no exception. This means that you have to explicitly specify the import path of dependencies that would otherwise be resolved using XTC. Another difference between the two is that strj still uses the C-based SGLR parser, while strategoxt.jar uses JSGLR.

Compiling a simple application from the command line with either compiler is similar to doing so with the strc command:

  strj -i foo.str -la stratego-lib

or

  java -jar strategoxt.jar -i foo.str -la stratego-lib

It should be noted that at this time the compiler only outputs .java source files and not .class files. Subsequent compilation should be done using a standard Java compiler (ideally, in an automated fashion using an Ant build script or Eclipse). The (non-portable) strj-jar shell script can also help with command-line or scripted builds.

Known Issues and Limitations

The Stratego/J runtime implements most of the primitives of the natively compiled version of Stratego, but some compatibility issues might arise. In particular, the parsing primitives are implemented using JSGLR, the Java version of SGLR, which may not be bug-for-bug compatible with the C version of SGLR. Mainly, the post-parse filter implementation might not always produce the same results. This especially impacts the heuristic filters, which are disabled by default, but used for Stratego's concrete syntax embedding. To work around any problems, the native strj executable can be used to compile these files, or they can be pre-parse them to .rtree files using parse-stratego. A general recommendation may be to disable the heuristic filters in the .meta files using the HeuristicFilters(Off()) directive.

The standard Sun compiler can be quite slow when compiling large Stratego projects. We recommend using ECJ (Eclipse Compiler for Java) instead, which is much faster and less memory-intensive. ECJ is distributed as part of Eclipse, and can be executed as follows:

  java -cp plugins/org.eclipse.jdt.core_*.jar  org.eclipse.jdt.internal.compiler.batch.Main

Many Linux distributions also provide a stand-alone version of ECJ through their package manager. (Note that ECJ 3.3 and lower have a bug that can be worked around with the -Xecj33 flag.) When using the Sun compiler, you may need to add option -J-mx256m to increase the available heap space, and likely need to have a fair amount of patience ;)

Stratego programs compiled to Java do not have the same performance characteristics as those compiled using the native Stratego compiler strc. The exact numbers vary per application (some, such as the somewhat artificial ASF+SDF benchmark, actually run faster on Java), but natively compiled Stratego applications that include parsing and pretty-printing are typically a factor two faster. Future optimizations, particularly in the term library and in I/O, may make this gap smaller.

A final open issue is the stack usage by typical Stratego programs, putting JVM implementations with a small default stack size at risk of throwing a StackOverflowException (notably the Sun JVM on Linux). For these systems, running the JVM with option -ss4m avoids the stack overflow problem. (When this parameter is not set and a stack overflow occurs, compiled applications will hint at this setting.)

While the XTC standard library strategies (such as xtc-io-wrap) are supported, support for the XTC repository is not implemented as this time because of portability concerns. Any xtc-transform or xtc-call invocations report a warning, and simply invoke executables on the path. For the interest of portability, applications that make use of these strategies should use library strategies instead, as discussed in the following section.

Using External Applications and Libraries

A trend in Stratego programs has been to use the standard libraries in favor of the (slower, less portable) XTC interface. For example, the parse-file strategy from libstratego-sglr can be used to parse files. Since XTC depends on native executables and a centralized repository, it is not portable and not supported on the Java platform. As an alternative, library calls should be used instead, which is generally the preferred method for invoking external components.

Libraries in the Java environment have a package name. For example, the Stratego standard library resides in the org.strategoxt.stratego_lib package. To maintain compatibility, these package names are not used within the Stratego language, but only at compile time and when the components are linked. For example, to link a program to the standard library the option -la org.strategoxt.stratego_lib can be specified. The standard libraries also have aliases that correspond to the XTC names commonly used with strc; -la stratego-lib is also accepted. To define a package name for your own library, use the -p and --library options. For example:

  java -jar strategoxt.jar -i foo.str --library --clean -p org.foo -o bin/org/foo/Main.java

Note that each Stratego component may specify a different main class (Main in this case), but that they must still reside in different packages as to avoid overlap between strategy classes.

Java Integration

A typical use case of compiling Stratego applications to Java is to integrate them into an existing Java application or environment. Interaction with the other Java components is possible in a number of ways:

  • Java components can directly call Stratego strategies, by calling the Main.init() method in the appropriate package and invoking a Strategy using some_strategy_0_0.instance.invoke(). If the exit strategy is called at any point, a StrategoExit exception will be thrown; a call to fatal-err will throw a StrategoErrorExit exception.

  • Normal Java components can be used to implement or override Stratego strategies, allowing for tighter coupling between Stratego and a Java application. See for example https://svn.strategoxt.org/repos/StrategoXT/ strc-java/trunk/java/runtime/org/strategoxt/lang/compat/libstratego_rtg_compat where two strategies (originally implemented natively in C) are implemented in Java. Every strategy has an instance field that allows it to be dynamically redefined.

  • Compiled Stratego components can be dynamically loaded from JAR files and may be combined with interpreted components using the HybridInterpreter class. To interpret a Stratego component, pre-compile it to a .ctree file using STRJ and the -F --library options.

Download

Native builds of the Jompiler ("strc-java") are available from Hydra:

the pure Java version (included in the above distribution) can also be downloaded from:

The Java version of STRJ is also integrated in the Spoofax plugin that allows you to develop languages and Eclipse plugins with Stratego.

Project Information

Source Code

Source code is available directly from SVN at

or can be downloaded as a package at hydra.nixos.org.

Contributors

Contributors

  • Lennart Kats (main STRJ development and maintainer; Stratego/J compatibility components)
  • Karl Trygve Kalleberg (main Stratego/J and JSGLR development; original s2j prototype)
  • Valentin David (parts of the Stratego/J runtime)

The development of STRJ would not have been possible without the efforts of Eelco Visser and his team in developing the STRC reference stratego compiler. Martin Bravenboer's Java-front library and syntax definition have also been indispensable for the development STRJ.

License

STRJ is licensed under the GNU Lesser General Public License (LGPL).

Contact and Mailing List

Please send questions to the users@strategoxt.org mailing list or contact Lennart Kats directly. Also, we can usually be found online on IRC at #stratego on freenode.net (web version). Feel free to drop by!

Related Software

The Spoofax/IMP IDE development environment incorporates the STRJ compiler. By default, it interprets Stratego definitions, using the hybrid interpreter, but by changing the build.xml and <myproject>-Analysis.esv files, it can also compile them.