org.eclipse.emf.ant Read Me

### Introduction

The "examples" directory contains scripts that show how to use the EMF Ant tasks available in this plugin. If you have any questions after reading and experimenting with them, look at the task's javadoc for more details.

The EMF java tasks are:

`emf.JETCompiler` | Invokes the JETCompiler class to create the generator class of templates. | org.eclipse.emf.ant/tasks/org/eclipse/emf/ant/taskdefs/codegen/JETCompilerTask.java
`emf.JETEmitter` | Invokes the JETEmitter class to generate code from templates. | org.eclipse.emf.ant/tasks/org/eclipse/emf/ant/taskdefs/codegen/JETEmitterTask.java
`emf.JMerger` | Invokes the JMerger class to merge files. | org.eclipse.emf.ant/tasks/org/eclipse/emf/ant/taskdefs/codegen/JMergerTask.java

### Overall Comments

- If you didn't extract this plugin from CVS, the "examples" directory mentioned above is available in the EMF source plugin (org.eclipse.emf.source_<version>/src/org.eclipse.emf.ant_<version>).
- Before running your build scripts or the examples provided here, make sure you have the 2 jar files required by this plugin: "runtime/emf.ant.jar" and "runtime/emf.ant.tasks.jar". If necessary, Eclipse can generate them for you. All you need to do is to run the Ant script created by PDE when you right click on the manifest file and select "PDE Tools>Create Ant Build File".
- Although all the EMF tasks must be executed by Eclipse (usually in headless mode), they can work on files located in any directory. In other words, your models, templates and other files don't need to be in the "plugins" directory nor in the workspace.
- This is the usual command line to run an Ant script using a headless Eclipse instance (you will need to remove the line breaks):
  eclipse
  -noSplash
  -data <full path to a workspace - ideally an empty directory>
  -application org.eclipse.ant.core.antRunner
  -buildfile <full path to your script>

  In Windows you should execute eclipsec instead of eclipse in order to have access to the Ant build script console output.

- You can also use the Eclipse UI to execute an Ant script containing an EMF task. This can be done by right-clicking the script and selecting
  Run As > Ant Build... > JRE > "Run in the same JRE as the workspace"
- Starting a new JVM process and invoking Eclipse are expensive operations. Your build will perform better if you are able to group the tasks that require Eclipse in a few scripts (one script would be ideal).
- In order to preserve the original state of this plugin's "examples" directory, you should copy it to a different location and run the Ant scripts from there.

### org.eclipse.emf.ant/examples/jet*

Running JET from an Ant script sounds really convenient. And it is, especially when the templates you want to generate code from don't require complicated inputs - which are passed as the template's argument.

#### examples/jetemitter

The Ant script available in this directory exercises 3 templates: "simple.javajet", "medium.javajet" and "complex.javajet". The first template is totally self-contained and doesn't use the `argument` variable. The second uses the `argument` variable but doesn't care about its state, so all we need to do is to specify its class and leave to the JETEmitter task the work of calling the `Class.newInstance()` method.

The last template, as stated by its name, is more complex. It will only produce a meaningful result if the specified argument is a list with at least one element - which is a good example of an object with state. The solution we've chosen to address this problem is to use the Script task. Please feel free to send us an email if you have a better solution ;-).

Since Script is an optional task, you will need to add the "bsd.jar" and the "js.jar" files to your classpath as mentioned in the Library Dependencies section of the Ant Manual. Because we are using Eclipse to run the script, the appropriate way of doing this is by adding these jar files as "extra classpath entries" using the `org.eclipse.ant.core.extraClasspathEntries` extension point - look at this plugin's manifest file to see how this extension is used.

#### examples/jetcompiler

The Ant script in this directory invokes the JETCompiler on the templates available in the examples/jetemiter directory. Since this step only creates the generator class, it is not necessary to use ANT's optional tasks.

### org.eclipse.emf.ant/examples/jmerge

The Ant build script in this directory shows how to invoke the JMerger task.