Jump to: navigation, search

Difference between revisions of "AM3/Ant Tasks"

< AM3
m (added links to other ant taks documentation)
(updated AM3/ATL ant tasks description)
Line 9: Line 9:
  
 
__TOC__
 
__TOC__
 +
 +
==About Ant==
 +
Ant is a software tool for automating software build processes. It is similar to make but is written in the Java language, requires the Java platform, and is best suited to building Java projects.
 +
 +
The most immediately noticeable difference between Ant and make is that Ant uses XML to describe the build process and its dependencies, whereas make has its Makefile format. By default the XML file is named build.xml.
 +
 +
Ant is an Apache project. It is open source software, and is released under the Apache Software License.
 +
 +
The root tag of any ANT file is project. It has two optional attributes: name and default:
 +
* name is just for convenience,
 +
* default specify the default target to execute.
 +
 +
The syntax is as follow:
 +
 +
<project name="myProjectName" default="all">
 +
  ...
 +
</project>
 +
 +
Each project defines one or more targets. A target is a set of tasks you want to be executed. When starting Ant, you can select which target(s) you want to have executed. When no target is given, the project's default is used.
 +
 +
A target can depend on other targets. You might have a target for loading models and metamodels, for example, and a target for executing the transformation. You can only execute the transformation when you have loaded models first, so the transformation execution depends on the loading target. It is often advised to create multiple targets for better visibility in you Ant file.
 +
 +
A target has name and can depends on other tasks (referring by name to other tasks). The syntax is as follow:
 +
 +
<target name="loadModels">
 +
  ...
 +
</target>
 +
 +
<target name="transform" depends="loadModels">
 +
  ...
 +
</target>
 +
 +
A target can define tasks. A task is a piece of code that can be executed. A task can have multiple attributes (or arguments, if you prefer). The value of an attribute might contain references to a property. These references will be resolved before the task is executed.
 +
 +
Tasks have a common structure:
 +
 +
<name attribute1="value1" attribute2="value2" ... />
 +
 +
where name is the name of the task, attributeN is the attribute name, and valueN is the value for this attribute. Ant defines a set of built-in tasks (http://ant.apache.org/manual/coretasklist.html), along with a number of optional tasks (http://ant.apache.org/manual/optionaltasklist.html).
 +
 +
For more information on Ant itself, please consult its manual: http://ant.apache.org/manual/index.html.
  
 
==am3.loadModel==
 
==am3.loadModel==
Line 14: Line 55:
 
===Description===
 
===Description===
  
This task is used to load a model.
+
This task is used to load a model either by modlel handler facilities or with injectors. This model may be a terminal model or a metamodel. The metametamodels are typically not loaded with this task since they come bundled with a model handler. These metametamodels are available under the special name strings %EMF for the Ecore metametamodel and %MDR for NetBeans/MDR MOF 1.4 metametamodel. MOF special name is contextually the metametamodel  %EMF or %MDR depending on the model handler.
This model may be a terminal model or a metamodel.
+
The metametamodels are typically not loaded with this task since they come bundled with a model handler.
+
  
 
===Parameters specified as attributes===
 
===Parameters specified as attributes===
 +
The am3.loadModel can have the following parameters:
  
 
{| border="1"
 
{| border="1"
 
! Attribute    || Description                      || Required || Default value
 
! Attribute    || Description                      || Required || Default value
 
|-
 
|-
| name        || Name of model in task context    || Yes      || None
+
| name        || The name of the model in the Ant project. || Yes      || None
 
|-
 
|-
| metamodel    || Name of metamodel in task context || Yes      || None
+
| metamodel    || The name of the metamodel. This name must be equal to a previous model name loaded by am3.loadModel or to metametamodel special name %EMF or %MDR. If this name equals MOF, the modelHandler specific metametamodel is taken. || Yes      || None
 
|-
 
|-
| path        || Path of file to load             || Yes      || None
+
| path        || The path to the file of the model to load. It can be relative to the current directory (the one containing the Ant file). If absolute, the ‘/’ root directory is the current workspace. || Yes      || None
 
|-
 
|-
| modelHandler || Model handler of loaded model     || No      || EMF
+
| modelHandler || The model handler name to use for loading the model (EMF or MDR). || No      || EMF
 
|}
 
|}
  
Line 35: Line 75:
  
 
===Examples===
 
===Examples===
 +
 +
Loading of a metamodel with EMF (and Ecore as metametamodel):
 +
 +
<am3.loadModel modelHandler="EMF" name="News" metamodel="MOF" path="metamodel/News.ecore" />
 +
 +
Equivalent to
 +
 +
<am3.loadModel modelHandler="EMF" name="News" metamodel="%EMF" path="metamodels/News.ecore" />
 +
 +
Loading of a terminal model conforming to the previously loaded metamodel:
 +
 +
<am3.loadModel modelHandler="EMF" name="SampleNews" metamodel="News" path="models/MyInput-News.xmi" />
 +
 +
By default, am3.loadModel is able to load file that the modelHandler can read. Sometimes, it is interesting to be able to load a model through an injector, for instance with the XML injector or reading a .km3 file and having its model conforming to KM3. This is possible with AM3 by using the nested parameter injector. For instance, if you want to inject an XML file to an XML model:
 +
 +
<!-- load XML metamodel -->
 +
<am3.loadModel modelHandler="EMF" name="XML" metamodel="MOF" path="metamodels/XML.ecore" />
 +
 +
<am3.loadModel name="myXML" metamodel="XML" path="inputs/MySample.xml">
 +
  <injector name="xml" />
 +
</am3.loadModel>
  
 
  <am3.loadModel modelHandler="EMF" name="News" metamodel="MOF" path="/org.eclipse.am3.zoos.atlantic/News.ecore" />
 
  <am3.loadModel modelHandler="EMF" name="News" metamodel="MOF" path="/org.eclipse.am3.zoos.atlantic/News.ecore" />
Line 52: Line 113:
 
===Description===
 
===Description===
  
This task is used to save a model.
+
This task is used to save a model using model handler facilities or with extractors. It is possible to save any model: terminal models, metamodels or metametamodels.
 +
 
 +
The am3.saveModel can have the following parameters:
 +
{| border="1"
 +
! Attribute    || Description                      || Required || Default value
 +
|-
 +
| name        || The name of the model in the Ant project. || Yes      || None
 +
|-
 +
| path        || The path to the file of the model to save. It can be relative to the current directory (the one containing the Ant file). If absolute, the ‘/’ root directory is the current workspace. || Yes      || None
 +
|}
 +
 
 +
Saving of the previously loaded News metamodel:
 +
 
 +
<am3.saveModel model="News" path="outputs/NewsMM.ecore" />
 +
 
 +
You can see that the model attribute is the same as the name attribute of the previous am3.loadModel tasks. Once they are loaded, models are identified by this attribute name. Thus, you should avoid giving the same name for two different models. Each time it occurs, your previous model is overwritten.
 +
 
 +
By default, am3.saveModel is able to save model with modelHandler facilities (this model handler have been provided in the load model task). Sometimes, it is interesting to save a model with an extractor. For instance, if you have a model conforming to KM3, it can be interesting to use the KM3 extractor to save it as a .km3 file. Another example, if you have a model conforming to XML, you may want to get an XML document rather than the XML model. This can be done by specifying an extractor nested parameter. For instance, to extract a model conforming to the XML metamodel (in this case, the previously loaded XML model with XML injector):
 +
 
 +
<am3.saveModel model="myXML" path="outputs/SavingMySample.xml">
 +
  <extractor name="xml"/>
 +
</am3.saveModel>
  
 
===Examples===
 
===Examples===
Line 82: Line 164:
 
===Description===
 
===Description===
  
The purpose of this task is to execute an [[ATL]] transformation.
+
The purpose of this task is to execute an [[ATL]] transformation. The models used by a transformation are referenced by their name as defined at with the [[AM3_Ant_Tasks#am3.loadModel am3.loadModel]] task (name attribute).
The models used by a transformation are referenced by their IDs as defined at their loading time (see [[AM3_Ant_Tasks#am3.loadModel]]).
+
  
 
There is an exception for metametamodels, which are typically already available from the model handler.
 
There is an exception for metametamodels, which are typically already available from the model handler.
Line 98: Line 179:
 
| allowInterModelReferences || Boolean value that determines whether or not references between different EMF models are possible || No
 
| allowInterModelReferences || Boolean value that determines whether or not references between different EMF models are possible || No
 
|}
 
|}
 +
 +
Within this task, you have to bind every model from the header of your ATL module. There is three kinds of nested parameters: inModel, outModel and library. The inModel kind is for source models; outModel for target models and library for helpers library.
 +
 +
For instance, if you have this module header:
 +
 +
module Families2Persons;
 +
create OUT : Persons from IN : Families;
 +
library myLib;
 +
 +
You have to create three inModel parameters (for IN, Families and Persons), one outModel (for OUT) and one library (for myLib). For instance, completing the previous sample of am3.atl task:
 +
 +
<am3.atl name="ATLFiles/MyTransformation.atl">
 +
  <inmodel name="Families" model="..."/>
 +
  <inmodel name="IN" model="..."/>
 +
  <inmodel name="Persons" model="..."/>
 +
  <outmodel name="OUT" model="..." metamodel="Persons"/>
 +
  <library name="strings" path="lib/mylib.atl" />
 +
</am3.atl>
 +
 +
Each parameter has a name that MUST be exactly the same as in the module header (case sensitive). For inModel parameters, model attribute refers to a name of a previously loaded model with am3.loadModel for instance. The attribute model of outModel do NOT refer a loaded model as it has not been yet created. The value of this attribute should be used latter as an identifier for the am3.saveModel task.
 +
 +
Every attributes for each nested parameters are summed here:
  
 
===Parameters specified as nested elements===
 
===Parameters specified as nested elements===
Line 106: Line 209:
 
! Attribute || Description                            || Required
 
! Attribute || Description                            || Required
 
|-
 
|-
| name      || Name of model in transformation context || Yes
+
| name      || The name of the model in ATL module header. || Yes
 
|-
 
|-
| model    || Name of model in task context          || Yes
+
| model    || The name of a model previously loaded. || Yes
 
|}
 
|}
  
Line 116: Line 219:
 
! Attribute || Description                            || Required
 
! Attribute || Description                            || Required
 
|-
 
|-
| name      || Name of model in transformation context || Yes
+
| name      || The name of the model in ATL module header. || Yes
 
|-
 
|-
| model    || Name of model in task context          || Yes
+
| model    || The name of a model previously loaded. || Yes
 
|-
 
|-
| metamodel || Name of metamodel in task context      || Yes
+
| metamodel || The name of the metamodel of the current model as it has been specified when loading || Yes
 
|-
 
|-
 
| path      || Name of the output file (mainly needed for filename extension) || Yes
 
| path      || Name of the output file (mainly needed for filename extension) || Yes
Line 130: Line 233:
 
! Attribute || Description                              || Required
 
! Attribute || Description                              || Required
 
|-
 
|-
| name      || Name of library in transformation context || Yes
+
| name      || The name of the library in ATL module header. || Yes
 
|-
 
|-
| path      || Path of library                           || Yes
+
| path      || The path to the ATL library file. || Yes
 
|}
 
|}
  
Line 148: Line 251:
 
  </am3.atl>
 
  </am3.atl>
  
==Launch configuration information==
+
==Launching an Ant file with AM3 tasks in an Eclipse workbench==
In the launch configuration of your ant script, you should select the option "Run in the same JRE as the workspace" in the tab "JRE".
+
Once you have defined your Ant file, right click on the file:
 +
 
 +
* Select Run As > Ant Build…
 +
 
 +
* Go to the JRE tab
 +
 
 +
* Select "Run in the same JRE as the workspace"
  
 
[[Category:ATL]]
 
[[Category:ATL]]
 
[[Category:AM3]]
 
[[Category:AM3]]

Revision as of 12:47, 15 March 2007

< To: ATL
< To: AM3

This page describes the ant tasks provided by AM3. Documentation for the standard ant tasks can be found in the ant manual.

Additional tasks are available from ant-contrib and documented in its manual. Using ant-contrib requires installing it.

About Ant

Ant is a software tool for automating software build processes. It is similar to make but is written in the Java language, requires the Java platform, and is best suited to building Java projects.

The most immediately noticeable difference between Ant and make is that Ant uses XML to describe the build process and its dependencies, whereas make has its Makefile format. By default the XML file is named build.xml.

Ant is an Apache project. It is open source software, and is released under the Apache Software License.

The root tag of any ANT file is project. It has two optional attributes: name and default:

  • name is just for convenience,
  • default specify the default target to execute.

The syntax is as follow:

<project name="myProjectName" default="all">
 ...
</project>

Each project defines one or more targets. A target is a set of tasks you want to be executed. When starting Ant, you can select which target(s) you want to have executed. When no target is given, the project's default is used.

A target can depend on other targets. You might have a target for loading models and metamodels, for example, and a target for executing the transformation. You can only execute the transformation when you have loaded models first, so the transformation execution depends on the loading target. It is often advised to create multiple targets for better visibility in you Ant file.

A target has name and can depends on other tasks (referring by name to other tasks). The syntax is as follow:

<target name="loadModels">
 ...
</target>

<target name="transform" depends="loadModels">
 ...
</target>

A target can define tasks. A task is a piece of code that can be executed. A task can have multiple attributes (or arguments, if you prefer). The value of an attribute might contain references to a property. These references will be resolved before the task is executed.

Tasks have a common structure:

<name attribute1="value1" attribute2="value2" ... />

where name is the name of the task, attributeN is the attribute name, and valueN is the value for this attribute. Ant defines a set of built-in tasks (http://ant.apache.org/manual/coretasklist.html), along with a number of optional tasks (http://ant.apache.org/manual/optionaltasklist.html).

For more information on Ant itself, please consult its manual: http://ant.apache.org/manual/index.html.

am3.loadModel

Description

This task is used to load a model either by modlel handler facilities or with injectors. This model may be a terminal model or a metamodel. The metametamodels are typically not loaded with this task since they come bundled with a model handler. These metametamodels are available under the special name strings %EMF for the Ecore metametamodel and %MDR for NetBeans/MDR MOF 1.4 metametamodel. MOF special name is contextually the metametamodel  %EMF or %MDR depending on the model handler.

Parameters specified as attributes

The am3.loadModel can have the following parameters:

Attribute Description Required Default value
name The name of the model in the Ant project. Yes None
metamodel The name of the metamodel. This name must be equal to a previous model name loaded by am3.loadModel or to metametamodel special name %EMF or %MDR. If this name equals MOF, the modelHandler specific metametamodel is taken. Yes None
path The path to the file of the model to load. It can be relative to the current directory (the one containing the Ant file). If absolute, the ‘/’ root directory is the current workspace. Yes None
modelHandler The model handler name to use for loading the model (EMF or MDR). No EMF

Parameters specified as nested elements

Examples

Loading of a metamodel with EMF (and Ecore as metametamodel):

<am3.loadModel modelHandler="EMF" name="News" metamodel="MOF" path="metamodel/News.ecore" />

Equivalent to

<am3.loadModel modelHandler="EMF" name="News" metamodel="%EMF" path="metamodels/News.ecore" />

Loading of a terminal model conforming to the previously loaded metamodel:

<am3.loadModel modelHandler="EMF" name="SampleNews" metamodel="News" path="models/MyInput-News.xmi" />

By default, am3.loadModel is able to load file that the modelHandler can read. Sometimes, it is interesting to be able to load a model through an injector, for instance with the XML injector or reading a .km3 file and having its model conforming to KM3. This is possible with AM3 by using the nested parameter injector. For instance, if you want to inject an XML file to an XML model:

<am3.loadModel modelHandler="EMF" name="XML" metamodel="MOF" path="metamodels/XML.ecore" />

<am3.loadModel name="myXML" metamodel="XML" path="inputs/MySample.xml">
 <injector name="xml" />
</am3.loadModel>
<am3.loadModel modelHandler="EMF" name="News" metamodel="MOF" path="/org.eclipse.am3.zoos.atlantic/News.ecore" />
<am3.loadModel modelHandler="EMF" name="IN" metamodel="KM3" path="/org.eclipse.am3.zoos.atlantic/Amble.km3">
 <injector name="ebnf">
  <param name="name" value="KM3" />
 </injector>
</am3.loadModel>
<am3.loadModel name="myXML" metamodel="XML" path="/test/testQuery.xml">
 <injector name="xml" />
</am3.loadModel>

am3.saveModel

Description

This task is used to save a model using model handler facilities or with extractors. It is possible to save any model: terminal models, metamodels or metametamodels.

The am3.saveModel can have the following parameters:

Attribute Description Required Default value
name The name of the model in the Ant project. Yes None
path The path to the file of the model to save. It can be relative to the current directory (the one containing the Ant file). If absolute, the ‘/’ root directory is the current workspace. Yes None

Saving of the previously loaded News metamodel:

<am3.saveModel model="News" path="outputs/NewsMM.ecore" />

You can see that the model attribute is the same as the name attribute of the previous am3.loadModel tasks. Once they are loaded, models are identified by this attribute name. Thus, you should avoid giving the same name for two different models. Each time it occurs, your previous model is overwritten.

By default, am3.saveModel is able to save model with modelHandler facilities (this model handler have been provided in the load model task). Sometimes, it is interesting to save a model with an extractor. For instance, if you have a model conforming to KM3, it can be interesting to use the KM3 extractor to save it as a .km3 file. Another example, if you have a model conforming to XML, you may want to get an XML document rather than the XML model. This can be done by specifying an extractor nested parameter. For instance, to extract a model conforming to the XML metamodel (in this case, the previously loaded XML model with XML injector):

<am3.saveModel model="myXML" path="outputs/SavingMySample.xml">
 <extractor name="xml"/>
</am3.saveModel>

Examples

<am3.saveModel model="myXML" path="/test/opop.xml">
 <extractor name="xml" />
</am3.saveModel>
<am3.saveModel model="news_model" path="/test/news.ecore" />
<am3.saveModel model="IN" path="/test/MyKM3.km3">
 <extractor name="ebnf">
  <param name="format" value="KM3.tcs"/>
  <param name="indentString" value=" "/>
  <param name="serializeComments" value="false"/>
 </extractor>
</am3.saveModel>

Example using an ATL extractor, executing query to generate a text file (from the build folder of the Atlantic Raster Zoo):

<am3.saveModel model="target" path="${targetModel}">
 <extractor name="atl">
  <param name="queryPath" value="${targetPath}build/DOT2Text.atl"/>
 </extractor>
</am3.saveModel>

am3.atl

Description

The purpose of this task is to execute an ATL transformation. The models used by a transformation are referenced by their name as defined at with the AM3_Ant_Tasks#am3.loadModel am3.loadModel task (name attribute).

There is an exception for metametamodels, which are typically already available from the model handler. A metametamodel is referenced by a string composed of a percent character (i.e. '%') followed by the name of the model handler. For instance: '%EMF' refers to Ecore and '%MDR' refers to MOF 1.4.

Parameters specified as attributes

Attribute Description Required
path Path of ATL transformation to run Yes
allowInterModelReferences Boolean value that determines whether or not references between different EMF models are possible No

Within this task, you have to bind every model from the header of your ATL module. There is three kinds of nested parameters: inModel, outModel and library. The inModel kind is for source models; outModel for target models and library for helpers library.

For instance, if you have this module header:

module Families2Persons;
create OUT : Persons from IN : Families;
library myLib;

You have to create three inModel parameters (for IN, Families and Persons), one outModel (for OUT) and one library (for myLib). For instance, completing the previous sample of am3.atl task:

<am3.atl name="ATLFiles/MyTransformation.atl">
 <inmodel name="Families" model="..."/>
 <inmodel name="IN" model="..."/>			
 <inmodel name="Persons" model="..."/>
 <outmodel name="OUT" model="..." metamodel="Persons"/>
 <library name="strings" path="lib/mylib.atl" />
</am3.atl>

Each parameter has a name that MUST be exactly the same as in the module header (case sensitive). For inModel parameters, model attribute refers to a name of a previously loaded model with am3.loadModel for instance. The attribute model of outModel do NOT refer a loaded model as it has not been yet created. The value of this attribute should be used latter as an identifier for the am3.saveModel task.

Every attributes for each nested parameters are summed here:

Parameters specified as nested elements

inModel

Attribute Description Required
name The name of the model in ATL module header. Yes
model The name of a model previously loaded. Yes

outModel

Attribute Description Required
name The name of the model in ATL module header. Yes
model The name of a model previously loaded. Yes
metamodel The name of the metamodel of the current model as it has been specified when loading Yes
path Name of the output file (mainly needed for filename extension) Yes

library

Attribute Description Required
name The name of the library in ATL module header. Yes
path The path to the ATL library file. Yes

Examples

<am3.atl name="/AMMA-Tools/TCS2Problem.atl">
 <inModel name="IN" model="metamodel.tcs"/>
 <inModel name="TCS" model="TCS"/>
 <inModel name="MM" model="metamodel.km3"/>
 <inModel name="KM3" model="KM3"/>
 <inModel name="Problem" model="Problem"/>
 <library name="KM3Helpers" path="/AMMA-Tools/KM3Helpers.asm" />
 <library name="strings" path="/AMMA-Tools/strings.asm" />
 <outModel name="OUT" model="metamodel.pbs" metamodel="Problem"/>
</am3.atl>

Launching an Ant file with AM3 tasks in an Eclipse workbench

Once you have defined your Ant file, right click on the file:

  • Select Run As > Ant Build…
  • Go to the JRE tab
  • Select "Run in the same JRE as the workspace"