Running JastAdd under Eclipse

To run a JastAdd project under Eclipse, simply use the ordinary Java Development Tooling. You edit .ast, .jrag, and .jadd files as ordinary text files. Then you run JastAdd via an ant script in order to generate Java code. The Java code is then automatically compiled using the ordinary Java compiler in JDT.

For your first project, you need to set up ant configurations for running JastAdd, and to set up the default editors for the text files. Recipes for this follow below. Note that the settings are specific to your Eclipse workspace. It is assumed that you are somewhat familiar with Eclipse and have run at least some small Java programs in it, and preferrably also some JUnit test cases. The recipes assume that you are running Eclipse 3.0.1. In other Eclipse versions it is possible that the commands are slightly different.

Index

• Creating a JastAdd project
• Setting up ANT configurations (to run JastAdd)
  • Alternative solution: Setting up ANT to run as an external program configuration
• Running JastAdd
• Running test cases
• Setting up default editors
• Working with your JastAdd project

Creating a JastAdd project

To create a new JastAdd project, the easiest is to take a copy of an existing one and import it as an Eclipse project. For example, download one of the example projects from JastAdd examples.

• In the operating system:
  • Unzip the project
  • Move the project directory into your Eclipse workspace directory.
• Start Eclipse
  • Go to the workbench and open the Java perspective:
    Window -> Open Perspective -> Java
  • In the Package Explorer, Select Import... from the popup menu
    • Select Existing Project Into Workspace
    • Click Next
    • Click Browse and select the appropriate project directory
    • Click Finish
  • Probably, the Eclipse compiler will now complain about missing AST classes, because these are not yet generated.
    • Go on with Setting up ANT configurations and Setting up default editors (if you have not already done this)
    • Generate the AST classes by Running JastAdd
    • Run the testcases, to make sure the example works
    • Go on Working with your JastAdd project

Setting up ANT configurations (to run JastAdd)

In a JastAdd project you may have both handwritten Java files (for example test cases, main programs, additional Java libraries, etc.) and generated Java files (generated from JastAdd and possibly also from a parser generator). The generation is handled by an ant script that you need to invoke explicitly, and recipes below show how to set up Eclipse configurations for this. Handwritten and generated Java files are automatically compiled by Eclipse.

The ant scripts that come with the examples have targets gen and cleanGen for use from Eclipse. Other targets, like build and clean, are used when running from the command line, rather than from Eclipse. The main difference between these targets is that the ones used from Eclipse do not compile the Java source files, because that is handled automatically by Eclipse.

Here is a recipe for creating the ant configurations:

• Select Run -> External Tools -> External Tools
  • Under Ant Build configurations, select New from the popup menu
  • Under the Main tab, fill in
    • the name, e.g., ant gen
    • the Buildfile, e.g., ${project_loc}/build.xml. By using the variable ${project_loc}, you can use this configuration for all your different JastAdd projects.
  • Under the Refresh tab, select the following options:
    • Refresh resources upon completion . This makes sure that Eclipse looks in the file system after the generation and updates its package explorer, e.g., to show newly generated files.
    • The project containing the selected resource . This makes sure only the current project is refreshed. It is unnecessary to refresh the whole workspace since all generated files will be placed in the current project.
    • Recursively include sub-folders . This option is probably already selected.
  • Under the Targets tab, select the target to execute:
    • gen
    • Make sure no other targets are checked
  • Under the JRE tab
    • fill in ${project_loc} as the Working directory
    • add the following to VM arguments to prevent out-of-memory errors: -Xmx256M
      
  • Under the Common tab, select the following options:
    • Local (Type of launch configuration. This option is probably already selected.)
    • Display in favorites menu External Tools. By selecting this option, you can easily run the configuration by selecting it from a menu.
    • Launch in background. This is probably already selected.
  • Click on Apply.
  • Click on Close.
• Now you can run the configuration as described below in Running JastAdd.

You also need a configuration to clean away generated code. For example, if you have changed the abstract grammar and removed some classes, you may want to clean away old generated java files that are now irrelevant. Here is how you create that configuration.

• Select Run -> External Tools -> External Tools
  • Select your already existing configuration ant gen
  • Select Duplicate in the popup menu
  • Change the name to ant cleanGen
  • Under the Targets tab, select the target cleanGen instead of gen.
  • Click on Apply
  • Click on Close
• Now you can run the ant cleanGen configuration in the same way as ant gen, see Running JastAdd.

Note that when you run the configurations they will apply to the currently selected project. This means that you just have to set up these configurations once, even if you have many JastAdd projects in your workspace. Simply select the appropriate project before running the configuration.

Alternative solution: Setting up ANT to run as an external program configuration

We have experienced some problems with the built-in ant configurations described above. Sometimes, after restarting Eclipse, the configuration target has been changed back to build (although it was saved as gen or cleanGen). Sometimes, there is a strange message about that a project is missing on the class path. If you have these or other problems in getting your ant configurations to work, you can instead set up configurations for running Ant as an external program. Here is a recipe for this:

• Select Run -> External Tools -> External Tools
  • Under Program configurations, select New from the popup menu
  • Under the Main tab, fill in
    • the name, e.g., external-ant gen
    • the location (of the ant binary), e.g., /usr/bin/ant (check in your OS where ant is located, e.g. type "which ant" in a terminal window)
    • the working directory: ${project_loc}. This is a variable that you also can select by clicking on Variables. By using this variable instead of writing the name of the project, you can use this configuration for all your different JastAdd projects.
    • Arguments: fill in gen . This is the target name in the ant script for running JastAdd and parser generators that generate Java files.
  • Under the Refresh tab, select the following options:
    • Refresh resources upon completion . This makes sure that Eclipse looks in the file system after the generation and updates its package explorer, e.g., to show newly generated files.
    • The project containing the selected resource . This makes sure only the current project is refreshed. It is unnecessary to refresh the whole workspace since all generated files will be placed in the current project.
    • Recursively include sub-folders . This option is probably already selected.
  • Under the JRE tab:
    
  • add the following to VM arguments to prevent out-of-memory errors: -Xmx256M
    
  • Under the Common tab, select the following options:
    • Local (Type of launch configuration. This option is probably already selected.)
    • Display in favorites menu External Tools. By selecting this option, you can easily run the configuration by selecting it from a menu.
    • Launch in background. This is probably already selected.
  • Click on Apply.
  • Click on Close.
• Now you can run the configuration as described below in Running JastAdd.

You also need a configuration to clean away generated code. For example, if you have changed the abstract grammar and removed some classes, you may want to clean away old generated java files that are now irrelevant. Here is how you create that configuration.

• Select Run -> External Tools -> External Tools
  • Select your already existing configuration external-ant gen
  • Select Duplicate in the popup menu
  • Change the name to external-ant cleanGen
  • Change the arguments to cleanGen
  • Click on Apply
  • Click on Close
• Now you can run the external-ant cleanGen configuration in the same way as external-ant gen, see Running JastAdd.

Note that when you run the configurations they will apply to the currently selected project. This means that you just have to set up these configurations once, even if you have many JastAdd projects in your workspace. Simply select the appropriate project before running the configuration.

Running JastAdd

You run JastAdd via the ant script. Assuming that you have set up an ant configuration as described above, here is how you run the script:

• Select the project (or a resource in it)
• Look in the toolbar. There are two green circles with white triangles in them, pointing right. The larger one is used for running Java applications, etc. The smaller one is the external tools icon. It has a small red suitcase on it. Click on the small black triangle to the right of the external tools icon. Your configuration, ant gen, should appear in the menu, and you can simply select it to run ant. The ant script will run JastAdd and possibly parser generators as well.
  • Note! If this is the first time you run the ant gen script, it may not yet be in the menu. In that case,
    • select small black triangle -> External Tools
    • select ant gen (in Configurations)
    • Click on Run
  • The next time you select the small black triangle, the ant gen alternative should appear directly in the menu.
• The next time you want to run the script, you can simply click directly on the external tools icon (the one with the suitcase on it). The menu command you selected the last time will be run again.

To clean away generated files, simply select the ant cleanGen script instead.

Running test cases

The examples come with test cases. To run them, do as follows:

• Select the tests directory
• In the popup menu, select Run -> JUnit Test
• Click on the JUnit tab (to the right of the Package Explorer tab) to see the results of the test runs.
• The next time you want to run the tests, simply click on the Rerun Last Test icon in the JUnit tab (the green circle with a white right-pointing triangle in it).

Setting up default editors

You can edit .ast files using the Eclipse text editor. For the .jrag and .jadd files it is useful to use the Java editor instead of the text editor. This will give you Java syntax coloring for the Java keywords and comments which makes the code a little easier to read. Note, however, that JastAdd keywords like aspect, syn, inh, eq, and so on, will not be highlighted. And there is no incremental compilation like for ordinary Java files.

Set up Eclipse to use the text editor for .ast files

• Select Windows -> Preferences
  • Open the Workbench hierarchy
  • Select File Associations
  • Click on the upper Add to add a new file type
    • Define a new file type .ast
  • Select the file association *.ast
  • Click on the lower Add to add an associated editor
    • Select Text Editor (among the Internal Editors)
    • Click OK
  • Click OK
• If you doubleclick on an .ast file, the text editor will be opened.

Set up Eclipse to use the Java editor for .jadd and .jrag files

• Follow the recipe above, but select Java Editor instead.

Working with your JastAdd project

Once you have set up the system with ant configurations and default editors, it is straight-forward to work with JastAdd projects in Eclipse:

• Edit source files (.ast, .jadd, .jrag, .java)
• Run the ant gen script
• The generated Java files are automatically built
• Run test cases to check the results.