Eclipse comes with an integrated Ant support. This can easily be used to automate build actions. To integrate variant management actions into these build processes, pure::variants provides a number of Ant tasks. They can be used with build files inside Eclipse or in headless mode.
A simple Ant script to trigger a pure::variants transformation looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<project name="example" default="transform">
<target name="transform">
<pv.import path="C:\Projects\WeatherStation"/>
<pv.transform name="CustomConfigFile" vdm="WeatherStation/Variants/Berlin.vdm"/>
<eclipse.refreshLocal resource="WeatherStation"/>
</target>
</project>This script runs the transformation CustomConfigFile on the variant description model Berlin.vdm in project WeatherStation . The transformation will generate some output in the project's directory.
First the pv.import task is used to import the project into the Eclipse workspace if it doesn't exist. Then the pv.transform task is used to start the CustomConfigFile transformation. And to let Eclipse reload and show the transformation results in the project directory, the Eclipse Ant task eclipse.refreshLocal is executed as the last build step.
To run this Ant script, create a file build.xml with the above content in the project directory. Then right-click file build.xml and choose Run As -> Ant Build… from the context menu.
To let Ant find the pure::variants provided Ant tasks, the correct JRE needs to be selected. Switch to the JRE tab and select option Run in the same JRE as the workspace .
Click Run to start the script execution.
The build.xml script can also be executed from outside of Eclipse (so-called headless mode). There are several ways to do this. Please note for Linux based operating systems the X Window System needs to be installed and started. Eclipse will not start if it is not able initialize GTK, which needs the X Window System to be installed and started.
You can use the Eclipse console application to run the script as follows:
%ECLIPSE%/eclipsec -nosplash --launcher.suppressErrors -application org.eclipse.ant.core.antRunner -data C:\workspace -buildfile build.xml -DPVLICENSE=C:\pv.de.lic
This command directly starts the Ant script runner of Eclipse with the Ant script build.xml , the path to an existing or temporary Eclipse
workspace, and the definition of variable PVLICENSE pointing to a valid
pure::variants license as arguments.
To simplify this, pure::variants comes with two batch scripts located in the cli sub-directory of the pure::variants installation directory.
runant.bat starts the given Ant build file with the internal Eclipse Ant runner
runant.bat build.xml
variantscli.bat starts the given transformation configuration on all provided VDMs
cd WeatherStation variantscli.bat CustomConfigFile Variants/Berlin.vdm Variants/Paris.vdm Variants/London.vdm
Both scripts support the following environment variables to configure the execution.
Table 6.5. Environment Variables
| Variable | Description |
|---|---|
| PVHOME |
Path to the
Example:
|
| PVLIC |
Path to the pure::variants license file
Example:
|
| PVJAVA |
Path to Java executable
Example:
|
| PVCONFIG |
Name of the Eclipse configuration to use
Example:
|
The PVHOME variable is automatically added to the runant.bat and varianstcli.bat if
pure::variants has been installed using the pure::variants installer executable.
The runant.bat (Windows) and runant.sh (on Linux and Mac) scripts have the following command line parameters which must be given in the order they are listed in the following table. Optional parameters can be omitted.
Table 6.6. runant Command Line Parameters
| Parameter | Description |
|---|---|
| -l |
Optional parameter to enable printing the pure::variants and Eclipse logs on exit.
Example:
|
| -t target |
Optional parameter to run the given target of the Ant script instead of the default target.
Example:
|
| -w workspace |
Optional parameter to specify the path to an existing Eclipse workspace in which to run the Ant script. If not given, a temporary workspace directory is created, and deleted on exit.
Example:
|
| antfile |
The path to the Ant script to run.
Example:
|
| vmargs |
Every argument following the path to the Ant script is passed as command line option to the Java VM. Please refer to the official Java documentation for the complete list of Java command line options.
Example:
This command line runs the
|
The variantscli.bat (Windows) and variantscli.sh (on Linux and Mac) scripts have the following command line parameters which must be given in the order they are listed in the following table. Optional parameters can be omitted.
Table 6.7. variantscli Command Line Parameters
| Parameter | Description |
|---|---|
| -l |
Optional parameter to enable printing the Eclipse log on exit.
Example:
|
| transformation |
The name of the transformation to execute (see the section called “Transformation Configuration Page” ).
Example:
|
| VDM VDM VDM ... |
Every argument following the transformation name must be the path to a VDM to transform. At least one VDM must be specified.
Example:
|
The
pv.import
task imports a pure::variants project
into the workspace. If the project is already part of the workspace
nothing
happens.
Example:
<pv.import path="C:\Projects\Weather Station" importreferences="false" /> <pv.import server="http://pv.server.com" name="Weather Station" revision="v2"/> <pv.import url="pvrm://pv.server.com/projects/iqRjtaATGwbmd2tGi#v2"/>
This task has the following attributes:
importreferences if
truethe references to other projects are also imported (default istrue) If the referenced project was stored with a revision, the referenced project is imported in that revision.path is the absolute path to the project in the file system
server, name, revision are the server URL, the name of the project, and optionally the version of a remote project to import
url is the url of a remote project to import
The pv.evaluate task performs an evaluation and
stores the result in the given result model file.
Example:
<pv.evaluate vdm="Weather Station\Config\Indoor.vdm" vrm="Weather Station\Indoor.vrm"/>
<pv.evaluate vdm="Weather Station\Config\Outdoor.vdm" vrm="Weather Station\Outdoor.vrm">
<property name="autoresolve" value="extended"/>
<property name="timeout" value="120"/>
<property name="severity" value="error"/>
<modelset>
<include path="Weather Station\config\*.vdm" nature="com.ps.consul.nature">
<property name="modelHeadProperty" value="value"/>
<jsfilter script="Weather Station\antJsFilter.js" />
</include>
<exclude path="Weather Station\*\NotSelected.vdm" nature="com.ps.consul.nature">
<property name="modelHeadProperty" value="value"/>
</exclude>
</modelset>
</pv.evaluate>This task has the following attributes:
vdm is the path to the Variant Description Model to evaluate
vrm is the path to the Variant Result Model
continueOnError If this property is set to true the task does not throw BuildExceptions, but writes problems to standard out and finishes successfully.
The pv.evaluate task supports optional properties
which influence the evaluation:
autoresolve sets the mode of the auto resolver. Possible values are
off,simple,extendedtimeout sets the maximal time used for the evaluation in seconds
severity sets the minimal severity for problems to output. Possible values are
info,warning,error. The default value isinfo.
Instead of using the vdm attribute for defining one variant model model for the evaluation the modelset can be used. It allows to define multiple variant models, which will be run in the context of the same evaluation task. This simplifies the definition of multiple models with the same evaluation settings.
For defining the set of relevant models several possibilities exist. A model is part of the model set, if it matches at least one include rule, but no exclude rule. If no include rule is defined the model must not match an exclude rule. If neither an include nor an exclude rule is defined all models of a workspace are part of the model set. If multiple options within the same include/exclude rule are used all of the defined options have to match.
path is the workspace relative path to the model. The path attribute allows to use wildcards, * for any character in the same folder and ** for any character including the file separator.
E.g. Weather Station\config\*.vdm matches all Variant Description Models directly located in the config folder inside the "Weather Station" project.
Weather Station\**.vdm matches all Variant Description Models in the Weather Station project, even if they are located in subfolders.
nature pure::variants uses natures to identify models imported by a specific importer from a specific external source. This nature can be used to filter the models.
E.g. com.ps.consul.eclipse.ui.doorsng.syncronizable.nature is the nature for the IBM Doors Next Generation importer.
Defining model head properties Any model property can be used to filter models. The value property is optional. If the value is not given the existance of a property with the defined name is sufficient, that a model matches the rule. If the value is given the value also has to match.
jsfilter enables model filtering based on more complex criteria. The mandatory attribute script defines the location of the JavaScript filter script either as an absolute path or relative to the workspace. The filter script has to fulfill a particular interface. To create a template script with this interface, invoke pure::variants' project context menu and click New -> pure::variants JavaScript Script. In the wizard dialog that opens, choose ANT ModelSet Filter as the execution context.
The pv.transform task performs a transformation of
a Variant Description Model or Variant Result Model.
Example:
<pv.transform vdm="Weather Station\Config\Indoor.vdm" name="Default" force="true"
input="C:/somewhere/input" output="C:/somewhere/output">
<property name="autoresolve" value="extended"/>
<property name="timeout" value="120"/>
<property name="severity" value="error"/>
<inputmodelset>
<include path="Weather Station\*.ccfm" nature="com.ps.consul.nature">
<property name="modelHeadProperty" value="value"/>
<jsfilter script="Weather Station\antJsFilter.js" />
</include>
<exclude path="Weather Station\NotSelected.ccfm" nature="com.ps.consul.nature">
<property name="modelHeadProperty" value="value"/>
</exclude>
</inputmodelset>
<modelset>
<include path="Weather Station\config\*.vdm" nature="com.ps.consul.nature">
<property name="modelHeadProperty" value="value"/>
</include>
<exclude path="Weather Station\*\NotSelected.vdm" nature="com.ps.consul.nature">
<property name="modelHeadProperty" value="value"/>
</exclude>
</modelset>
</pv.transform>
<pv.transform vrm="Weather Station\Outdoor.vrm" name="Default"/>This task has the following attributes:
vdm is the Variant Description Model to transform
vrm is the Variant Result Model to transform
name is the name of the Transformation Configuration (default is
Default)force if
truethe transformation runs always also if the result has errors (default isfalse)continueOnError If this property is set to true the task does not throw BuildExceptions, but writes problems to standard out and finishes successfully. (default is
false)input is the input path the transformation uses. It overwrites the input path defined in the transformation configuration.
output is the output path the transformation uses. It overwrites the output path defined in the transformation configuration.
The pv.transform task supports optional
properties which influence the evaluation, which runs before the transformation:
autoresolve sets the mode of the auto resolver. Possible values are
off,simple,extended(default isextended)timeout sets the maximal time used for the evaluation in seconds (default is
120)severity sets the minimal severity for problems to output. Possible values are
info,warning,error. The default value isinfo. (default isinfo)
The pv.transform task supports filtering of the input
model set, meaning it is possible to reduce the number of input models after
evaluation for a specific Transformation Configuration. The definition of input
model filtering is applied on top of the input model set defined in the used
Transformation Configuration. There is no possibility to add new models into the
transformation. It is not allowed to filter feature models from the input model
set. Rules to filter feature models are simply ignored. To define input model
filtering the inputmodelset tag is used. It allows to
define multiple include and exclude
rules.
An input model is part of the input model set, if it matches at least one include rule, but no exclude rule. If no include rule is defined the model must not match an exclude rule. If neither an include nor an exclude rule is defined all input models are part of the input model set.
For filtering the input models several possibilities exist. The options can be combined. If multiple options within the same include/exclude rule are used all of the defined options have to match.
path is the workspace relative path to the input model. The path attribute allows to use wildcards, * for any character in the same folder and ** for any character including the file separator.
E.g. Weather Station\*.ccfm matches all family models directly located in the Weather Station project folder.
Weather Station\**.ccfm matches all family models in the Weather Station project, even if they are located in sub folders.
nature pure::variants uses natures to identify models imported by a specific importer from a specific external source. This nature can be used to filter the input models.
E.g. com.ps.consul.eclipse.ui.doorsng.syncronizable.nature is the nature for the IBM Doors Next Generation importer.
Defining model head properties Any model property can be used to filter models. The value property is optional. If the value is not given the existance of a property with the defined name is sufficient, that a model matches the rule. If the value is given the value also has to match.
jsfilter enables model filtering based on more complex criteria. The mandatory attribute script defines the location of the JavaScript filter script either as an absolute path or relative to the workspace. The filter script has to fulfill a particular interface. To create a template script with this interface, invoke pure::variants' project context menu and click New -> pure::variants JavaScript Script. In the wizard dialog that opens, choose ANT ModelSet Filter as the execution context.
Instead of using the vdm attribute for defining one Variant Description Model for the transformation the modelset can be used. It allows to define multiple variants description models, which will be run in the context of the same transforamtion task. This simplifies the definition of multiple variants from the same configuration space with the same transformation settings. The model set definition has the same options like the input model set definition.
The pv.validate task runs all available element and model checks
on the given model.
Example:
<pv.validate model="Weather Station\WS.xfm">
<property name="severity" value="warning"/>
<modelset>
<include path="Weather Station\*.ccfm" nature="com.ps.consul.nature">
<property name="modelHeadProperty" value="value"/>
<jsfilter script="Weather Station\antJsFilter.js" />
</include>
<exclude path="Weather Station\NotSelected.ccfm" nature="com.ps.consul.nature">
<property name="modelHeadProperty" value="value"/>
</exclude>
</modelset>
</pv.validate>This task has the following attributes:
model is the model to validate
The pv.validate task supports optional properties
which influence the output of the validation:
severity set the minimal severity for problems to output. Possible values are
info,warning,error. (default isinfo)
Instead of using the model attribute for defining one model model for the evaluation the modelset can be used. It allows to define multiple models, which will be run in the context of the same evaluation task. This simplifies the definition of multiple models with the same evaluation settings.
For defining the set of relevant models several possibilities exist. A model is part of the model set, if it matches at least one include rule, but no exclude rule. If no include rule is defined the model must not match an exclude rule. If neither an include nor an exclude rule is defined all models of a workspace are part of the model set. If multiple options within the same include/exclude rule are used all of the defined options have to match.
path is the workspace relative path to the model. The path attribute allows to use wildcards, * for any character in the same folder and ** for any character including the file separator.
E.g. Weather Station\config\*.ccfm matches all family models directly located in the config folder inside the "Weather Station" project.
Weather Station\**.vdm matches all Variant Description Models in the "Weather Station" project, even if they are located in sub folders.
nature pure::variants uses natures to identify models imported by a specific importer from a specific external source. This nature can be used to filter the models.
E.g. com.ps.consul.eclipse.ui.doorsng.syncronizable.nature is the nature for the IBM Doors Next Generation importer.
Defining model head properties Any model property can be used to filter models. The value property is optional. If the value is not given the existance of a property with the defined name is sufficient, that a model matches the rule. If the value is given the value also has to match.
jsfilter enables model filtering based on more complex criteria. The mandatory attribute script defines the location of the JavaScript filter script either as an absolute path or relative to the workspace. The filter script has to fulfill a particular interface. To create a template script with this interface, invoke pure::variants' project context menu and click New -> pure::variants JavaScript Script. In the wizard dialog that opens, choose ANT ModelSet Filter as the execution context.
The
pv.inherit
task changes the inheritance between
VDMs.
Example:
<pv.inherit vdm="Weather Station\Config\Indoor.vdm"> <super vdm="Weather Station\Config\Base.vdm"/> </pv.inherit>
This task has the following attributes:
vdm is the Variant Description Model which inherits (pv.inherit tag), or which is inherited (super tag)
The
pv.connect
task connects to a server and login
as given user.
Example:
<pv.connect server="http://pv.server.com" user="example" pass="example"/>
This task has the following attributes:
server is the pure::variants server to connect to
user is the name of the user
pass is the password for the user
The
pv.sync
task updates a model imported by a
connector. The connector specific synchronization job is called to update the
model's
data.
Example:
<pv.sync model="Weather Station\Sources.ccfm">
<modelset>
<include path="Weather Station\*.ccfm" nature="com.ps.consul.nature">
<property name="modelHeadProperty" value="value"/>
<jsfilter script="Weather Station\antJsFilter.js" />
</include>
<exclude path="Weather Station\NotSelected.ccfm" nature="com.ps.consul.nature">
<property name="modelHeadProperty" value="value"/>
</exclude>
</modelset>
</pv.sync>This task has the following attributes:
model is the model to update
Instead of using the model attribute for defining one model for the synchronization the modelset can be used. It allows to define multiple pure::variants models, which will be run in the context of the same synchronization task. This simplifies the definition of multiple models from the same configuration space with the same transformation settings.
The pv.syntaxsemanitccheck task checks the given
configspace for semantic and syntactic errors. This is running the same checks
as the Perform Syntax and Semantic Check action on
configuration spaces.
Example:
<pv.syntaxsemanitccheck configspace="Weather Station\Variants" reportfile="Weather Station\CheckResult.html" />
This task has the following attributes:
configspace is the configuration space to be checked.
reportfile the location the resulting report is stored.
The
pv.mergeselection
task creates or updates a
variant description model by merging all selections from the given variant
description
models. The following rules are applied. If an element is excluded in at
least one source
model the element is also excluded in the result. If an element is
selected in at least
one source model it is also selected in the result if not excluded by
any other source
model.
Example:
<pv.mergeselection vdm="Weather Station\Config\Merged.vdm"> <source vdm="Weather Station\Config\IndoorBase.vdm"/> <source vdm="Weather Station\Config\TempOnly.vdm"/> <source vdm="Weather Station\Config\CommUSB.vdm"/> </pv.mergeselection">
This task has the following attributes:
vdm is the result model (pv.mergeselection tag) or the source model (source tag)
The
pv.javascript
task performs a given javascript
in a specific context. This allows the user to automate existing
javascripts. The script
can be performed in the context of one model or in the context of one
project. If both a
project and a model is given, the model is used for the context.
Example:
<pv.javascript script="C:\Temp\javascript.js" project="Weather Station" model="$(PROJECT)\Sources.ccfm" />
This task has the following attributes:
script is the path to the performed javascript. This path has to be absolute or relative to the used ANT workspace.
model is the path to the context model. This property is optional. Variant path variables can be used here.
project is the path to the context project. This property is optional. Variant path variables can be used here.
The
pv.offline
task switches the server project
into offline mode. The project is selected by the name attribute. This
task does nothing
if the project is already offline or if the project is a local
project.
Example:
<pv.offline name="Weather Station"/>
This task has the following attributes:
name is the name of the project
The
pv.online
task switches the server project into
online mode. The task performs a "Override and update" if there are
differences between
the remote project and the local representation. Meaning the local
data is overwritten
with the current state of the project on the pure::variants Server. The
project is
selected by the name attribute. This task does nothing if the project is
already online or
if the project is a local project.
Example:
<pv.online name="Weather Station"/>
This task has the following attributes:
name is the name of the project
The
pv.userrolesync
task is used to synchronize users and
roles of a pure::variants model server with their data sources (e.g.
LDAP directory servers).
Example:
<project>
<property name="server" value="http://server:1234"/>
<pv.connect server="${server}" user="admin" pass="123"/>
<pv.userrolesync server="${server}" username="cn=reader,dc=company,dc=com" password="456">
<role name="Modeler"/>
<role name="User"/>
<role name="Tester"/>
<user name="*"/>
</pv.userrolesync>
</project>This task has the following attributes:
server is the pure::variants model server
username is the name of the data source user (e.g. an LDAP bind user)
password is the password of the data source user
The users and roles to synchronize are listed using user and role elements. Both elements have the attribute name which specifies the name or a name pattern for the users or roles to synchronize. The name can contain the special characters "*" to match any text and "?" to match a single character.
If the data source of a user or role to synchronize is a server that uses a certificate which is not trusted by pure::variants, then the synchronization with that data source server will fail. To register this certificate with pure::variants, start pure::variants and open the User Management of the pure::variants server (see "pure::variants Server Administration Manual" about details on how to do this). Then try to synchronize the same users and roles from within pure::variants. You will be asked by pure::variants to accept the certificate of the data source server permanently. After you agreed, run the Ant task again. It will not fail anymore due to an untrusted certificate.
The
pv.property
task is used to define a runtime
property, which can be used in several pure::variants connectors. For
example runtime
properties are used for defining user credentials for external tools used by
some
connector transformations.
Example:
<project> <pv.property name="propertyName" value="property value" /> </project>
This task has the following attributes:
name is name of the property to set
value is the value of the property to set