# Acceleo Plug-ins Features Overview

Authors: | Laurent Goubet
Contact: | Laurent.Goubet@obeo.fr

Copyright © 2008, 2009, Obeo™.

# Introduction

This document provides an overview of the user-visible features of the Acceleo plug-ins which make it easy to develop and run Acceleo modules inside Eclipse. It assumes some familiarity with the language itself, although you do not need to be an expert to start using the plug-ins: using the provided example projects and the powerful completion feature of the Acceleo editor, it is very easy to get started once you understand the basic principles.

Concerning the language, almost all of the OMG specification keywords are supported (those marked with an asterisk are not fully supported yet):

    module, import, extends, template, query, public, private, protected, guard, init,
    overrides, each, before, after, for, if, elseif, else, let, elselet, trace*, macro*,
    file, mode, text_explicit*, code_explicit*, super, stdout

For all the details about these keywords and the MOF Model to Text Language in general, you can consult the official MTL Specification available at the OMG website.

# Requirements

Acceleo depends on:

1. EMF runtime ( 2.4.X )
2. OCL runtime ( 1.2.X )

# Acceleo Modules and Projects

The Acceleo plugins come with a perspective called Acceleo. To open this perspective, select Window -> Open perspective -> Others, then click on Acceleo.

To create a new Acceleo Module project, open the New project Eclipse wizard, and in the Model to Text Transformation category select Acceleo Module Project. On the next page, enter the project name. Then go to the next page to create one or several initial template files:

You can specify the location and name of the new .mtl file to create. You can also initialize the contents of the template with either a fixed example file (Copy example content), or an existing Acceleo or Xpand template (respectively Migrate .mt content and Migrate .xpt content).

The metamodel information are also required. The wizard allows you to specify the input metamodel of your template, either from the list of registered metamodels or directly by URI. You can also specify the input type of the template.

When you have filled in all required information, you can click Finish to create the project in the workspace.

Note that Acceleo Module projects are also Eclipse Plug-in projects. Acceleo modules themselves are stored inside the project's source folder, following the same conventions as Java files: a module whose qualified name is com::example::acceleo::myModule must be stored in the file com/example/acceleo/myModule.mtl in one of the project's source folders.

# Acceleo Template Editor Features

The Acceleo template editor is associated with Acceleo source files (.mtl files) and provides all the features of a modern programming editor to make you more productive when developing modules:

- Syntax highlighting

- Smart completion

- Navigation to definitions and references

- Error highlighting

- Dynamic outline

- Code folding

Some of these features are described in details below.

## Smart Completion on Acceleo Syntax Constructs

The Acceleo editor provides smart completion on all the available Acceleo language constructs. It is activated by default using the Ctrl+Space key combination.

The completion mechanism is smart enough to only present you the syntactically correct choices in the context where it is invoked. For example, when invoked at the top-level of a file (outside any template), only the top-level Acceleo constructs are shown:

The context is also used to sort the proposed choices. For example, inside an [if] block, the [elsif] and [else] choices appear at the top of the completion proposals:

Note that although the choices are presented as keywords inside brackets (e.g. [for], [file], etc.), you do not have to type the opening bracket but can simply type the first letters :

## Smart Completion on Scripts and Meta-model Elements

Smart completion also works inside Acceleo expressions, where it can be invoked using Ctrl+Space. It is also auto-activated after a small delay in some circumstances, like after a dot (.).

Inside expressions, completion choices include elements of the meta-models compatible with the context and visible Acceleo elements (variables, templates and queries, modules) alike.

In the example below, the p variable is a UML property, so completion on the partial expression p.n proposes both features and operations of the UML2 Property class which start with n:

Starting from an empty expression, the completion proposes all the visible Acceleo variables and templates which can be invoked in addition to features and operations of the current elements (the latter are not visible on the screenshot):

## Open Declaration

The Acceleo editor also support the "Open Declaration" feature (F3 by default), which allows easy navigation from any element to its definition. This works for almost any kind of element you can find in Acceleo modules: variables, modules, templates and queries, types, features and operations of meta-model elements, even the meta-model themselves from their URI.

## Search References

The "Search references" feature can be seen as the reverse of "Open Declaration": instead of navigating from one specific usage of an element to its definition, it searches for all the usages of a particular element. This feature is invoked by default using the Ctrl+Shift+g key combination. It can be used either from the definition of an element (a variable, template, query, etc.) or any particular usage of it.

In the example below, the cursor was on the definition of the iteration variable p in a for loop. Invoking "Search references" by pressing Ctrl+Shift+g opened the Eclipse search view with all the references to this variable inside the current module, and potential matches in other modules in the same project:

As for "Open Declaration", the "Search References" feature works for all kinds of elements: Acceleo variables, templates, queries and modules, meta-model types, features and operations.

# Running and debugging Acceleo modules

Acceleo modules can be run and debugged very easily using the standard Eclipse mechanisms.

Inside your Acceleo modules, you can annotate some of your templates using a special comment [comment @main /]. This identifies these templates as entry points for the generation. When a module contains at least one such entry point, the Acceleo project builder automatically creates a Java class which can be used to launch the generation.

That Java class contains a main() method which can be used to invoke a generation from that module. It can be called by itself as a normal Java program (including outside of Eclipse), or using the more convenient Acceleo Application launcher. That program requires two input arguments:

1. the input model (for example a .uml file)
2. the target folder

## Launching a Module

To launch a generation using an Acceleo module, open the Eclipse Run configurations dialog, and create a new configuration of type Acceleo Application.

You can also right-click on a .mtl file and select Run as > Acceleo Application to open the same dialog with some of the information already configured to run this template.

The mandatory parameters are:

Project
  the project containing the module to use
Main class
  the Java class generated from your module (if it contains entry points)
Model
  the input model for the generation
Target
  the target folder in which to put the generated files
Properties
  if the templates which serve as entry points to the generation expect arguments, you can specify them in this text area, one per line.
Runner
  you have the choice between Acceleo Plug-in Application (the default) and Java Application. Using the Java Application runner is strictly equivalent to invoking the generated Java class with the input model file and target folder as parameters. This is useful to check that your generator runs correctly in standalone mode (outside of Eclipse), but in this mode it is not possible to debug the Acceleo templates as such. On the other hand, because the Acceleo Plug-in Application runner is aware that it is executing an Acceleo generation, it gives you access to the Acceleo template debugger described in the next section.

Once you have specified all the required information, the configuration can be invoked like any Eclipse launch configuration.

## Debugging your Modules

The Acceleo plug-ins also include a debugger for you Acceleo modules. The debugger allows you to set breakpoints inside your Acceleo templates and thus follow their execution step by step.

To debug an Acceleo module, follow the sames steps as described above to create a launch configuration, but use the Debug as menu instead of Run as. Once you have a launch configuration, it can be invoked either as a normal launch or as a debug launch.

To put a breakpoint in a template, simply double-click inside the left margin of the Acceleo editor on the target line. Note that you can only put breakpoints on lines which contain Acceleo expressions, not on lines which have only fixed text output.

The Acceleo debugger has some support for conditional breakpoints: once you have set a breakpoint, simply click on it in the left margin. A dialog box appears where you can enter a name pattern:

Once you have set a name pattern, the breakpoint will only be triggered when on elements which names match the pattern (note that currently breakpoint conditions are only taken into account for the next debug session).

When you launch a debug session on your module, if you have breakpoints and they are enabled, the generation will pause when they are hit. If you then switch to the Debug perspective, you should see the familiar debug views:

In the Debug view itself (top left), you can see the current template call stack. If you select a frame, the Acceleo editor (below) will open on the corresponding file and line. The Variables view (top right) allows you to inspect the current object for the expression being executed.

As in Java, you can use the Step Into, Step Over and Step Return actions to execute the template step by step, Resume the execution until the end or another breakpoint is hit, or simply Stop the session.