|
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" |
|
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
|
3 <html xmlns="http://www.w3.org/1999/xhtml"> |
|
4 <head> |
|
5 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> |
|
6 <title>org.eclipse.emf.ant Read Me</title> |
|
7 </head> |
|
8 <body lang="EN-US"> |
|
9 <h3>Introduction</h3> |
|
10 <p>The "examples" directory contains scripts that show how to use the EMF Ant tasks |
|
11 available in this plugin. If you have any questions after reading and experimenting with them, look |
|
12 at the task's javadoc for more details.</p> |
|
13 <p>The EMF java tasks are:</p> |
|
14 <table border="1" cellpadding="2" cellspacing="0" |
|
15 summary="Enumerates the EMF tasks providing a "one sentence" description and the path to the java file that implement them"> |
|
16 <tr> |
|
17 <td valign="top"><tt>emf.JETCompiler</tt></td> |
|
18 <td>Invokes the JETCompiler class to create the generator class of templates.</td> |
|
19 <td>org.eclipse.emf.ant/tasks/org/eclipse/emf/ant/taskdefs/codegen/JETCompilerTask.java</td> |
|
20 </tr> |
|
21 <tr> |
|
22 <td valign="top"><tt>emf.JETEmitter</tt></td> |
|
23 <td>Invokes the JETEmitter class to generate code from templates.</td> |
|
24 <td>org.eclipse.emf.ant/tasks/org/eclipse/emf/ant/taskdefs/codegen/JETEmitterTask.java</td> |
|
25 </tr> |
|
26 <tr> |
|
27 <td valign="top"><tt>emf.JMerger</tt></td> |
|
28 <td>Invokes the JMerger class to merge files.</td> |
|
29 <td>org.eclipse.emf.ant/tasks/org/eclipse/emf/ant/taskdefs/codegen/JMergerTask.java</td> |
|
30 </tr> |
|
31 </table> |
|
32 <h3>Overall Comments</h3> |
|
33 <ul> |
|
34 <li>If you didn't extract this plugin from CVS, the "examples" directory mentioned |
|
35 above is available in the EMF source plugin |
|
36 (org.eclipse.emf.source_<i><version></i>/src/org.eclipse.emf.ant_<i><version></i>). |
|
37 <br/><br/></li> |
|
38 <li>Before running your build scripts or the examples provided here, make sure you have the 2 |
|
39 jar files required by this plugin: "runtime/emf.ant.jar" and |
|
40 "runtime/emf.ant.tasks.jar". If necessary, Eclipse can generate them for you. All |
|
41 you need to do is to run the Ant script created by PDE when you right click on the manifest file |
|
42 and select "PDE Tools>Create Ant Build File". |
|
43 <br/><br/></li> |
|
44 <li>Although all the EMF tasks must be executed by Eclipse (usually in headless mode), they can work |
|
45 on files located in any directory. In other words, your models, templates and other files don't need |
|
46 to be in the "plugins" directory nor in the workspace.<br/><br/></li> |
|
47 |
|
48 <li>This is the usual command line to run an Ant script using a headless Eclipse instance |
|
49 (you will need to remove the line breaks): |
|
50 <br/><br/> |
|
51 eclipse |
|
52 <br/> -noSplash |
|
53 <br/> -data <i><full path to a workspace - ideally an empty directory></i> |
|
54 <br/> -application org.eclipse.ant.core.antRunner |
|
55 <br/> -buildfile <i><full path to your script></i> |
|
56 <br/><br/> |
|
57 <p>In Windows you should execute <i>eclipsec</i> instead of <i>eclipse</i> in order to have |
|
58 access to the Ant build script console output.</p></li> |
|
59 |
|
60 <li>You can also use the Eclipse UI to execute an Ant script containing an EMF task. This can be |
|
61 done by right-clicking the script and selecting <br/> |
|
62 <i>Run As > Ant Build... > JRE > "Run in the same JRE as the workspace"<br/><br/></i></li> |
|
63 |
|
64 <li>Starting a new JVM process and invoking Eclipse are expensive operations. Your build will |
|
65 perform better if you are able to group the tasks that require Eclipse in a few scripts |
|
66 (one script would be ideal). |
|
67 <br/><br/></li> |
|
68 |
|
69 <li>In order to preserve the original state of this plugin's "examples" directory, you |
|
70 should copy it to a different location and run the Ant scripts from there.</li> |
|
71 </ul> |
|
72 <h3>org.eclipse.emf.ant/examples/jet*</h3> |
|
73 <p> |
|
74 Running JET from an Ant script sounds really convenient. And it is, especially when the templates you |
|
75 want to generate code from don't require complicated inputs - which are passed as the template's |
|
76 argument. |
|
77 </p> |
|
78 |
|
79 <h4>examples/jetemitter</h4> |
|
80 <p>The Ant script available in this directory exercises 3 templates: "simple.javajet", |
|
81 "medium.javajet" and "complex.javajet". The first template is totally |
|
82 self-contained and doesn't use the <tt>argument</tt> variable. The second uses the <tt>argument</tt> |
|
83 variable but doesn't care about its state, so all we need to do is to specify its class and leave |
|
84 to the JETEmitter task the work of calling the <tt><i>Class</i>.newInstance()</tt> method.</p> |
|
85 |
|
86 <p>The last template, as stated by its name, is more complex. It will only produce a meaningful |
|
87 result if the specified argument is a list with at least one element - which is a good example of |
|
88 an object with state. The solution we've chosen to address this problem is to use the |
|
89 <a href="http://ant.apache.org/manual/OptionalTasks/script.html">Script</a> task. Please feel |
|
90 free to send us an email if you have a better solution ;-).</p> |
|
91 |
|
92 <p>Since <a href="http://ant.apache.org/manual/OptionalTasks/script.html">Script</a> is an |
|
93 optional task, you will need to add the "bsd.jar" and the "js.jar" files to |
|
94 your classpath as mentioned in the |
|
95 <a href="http://ant.apache.org/manual/install.html#librarydependencies">Library Dependencies</a> |
|
96 section of the Ant Manual. Because we are using Eclipse to run the script, the appropriate way of |
|
97 doing this is by adding these jar files as "extra classpath entries" using the |
|
98 <tt>org.eclipse.ant.core.extraClasspathEntries</tt> extension point - look at this plugin's |
|
99 manifest file to see how this extension is used.</p> |
|
100 |
|
101 <h4>examples/jetcompiler</h4> |
|
102 <p>The Ant script in this directory invokes the JETCompiler on the templates available in the <b>examples/jetemiter</b> |
|
103 directory. Since this step only creates the generator class, it is not necessary to use ANT's optional tasks.</p> |
|
104 |
|
105 |
|
106 <h3>org.eclipse.emf.ant/examples/jmerge</h3> |
|
107 <p> |
|
108 The Ant build script in this directory shows how to invoke the JMerger task. |
|
109 </p> |
|
110 </body> |
|
111 </html> |