Jump to: navigation, search

Difference between revisions of "Tigerstripe Headless Generation Tutorial"

(Installing Tigerstripe generators)
 
(46 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{backlink|Tigerstripe_Tutorials}}
 
{{backlink|Tigerstripe_Tutorials}}
 
NOTE THIS IS A DRAFT PAGE
 
  
 
This tutorial will show you how to configure Tigerstripe to run code generations in a headless environment. This will allow you to incorporate Tigerstripe's code generation functionality into a build chain using many of the commonly available build tools, specifically Maven 2.
 
This tutorial will show you how to configure Tigerstripe to run code generations in a headless environment. This will allow you to incorporate Tigerstripe's code generation functionality into a build chain using many of the commonly available build tools, specifically Maven 2.
Line 9: Line 7:
  
 
=Importing an Example Model=
 
=Importing an Example Model=
 +
 +
This example project is also available from the CVS repository. If you wish to get the files from CVS you may skip the rest of this step.
 +
 +
<pre>
 +
:pserver:anonymous@dev.eclipse.org:/cvsroot/technology/org.eclipse.tigerstripe/samples/OrderManagement
 +
</pre>
  
 
# Download the sample Tigerstripe model project [[Media:OrderManagement.zip|OrderManagement.zip]].
 
# Download the sample Tigerstripe model project [[Media:OrderManagement.zip|OrderManagement.zip]].
Line 18: Line 22:
 
# Verify that the project is in your Tigerstripe Explorer pane.<br> [[Image:Import4.gif]]
 
# Verify that the project is in your Tigerstripe Explorer pane.<br> [[Image:Import4.gif]]
  
=Installing Tigerstripe generators=
+
=Installing Tigerstripe Generators=
 
=== Overview ===
 
=== Overview ===
Tigerstripe Generators are pluggable components that allow users to define rules and conventions for code that is generated from a Tigerstripe Model Project. Several generators are currently available, and in many cases, you may want to write your own. For  more information on writing you own Tigerstripe Generators see [[Tigerstripe_Tutorials#Code_Generation | Tigerstripe Tutorials, Code Generation]].
+
Tigerstripe Generators are pluggable components that allow users to define rules and conventions for code that is generated from a Tigerstripe Model Project. Several generators are currently available, and in many cases, you may want to write your own. For  more information on writing your own Tigerstripe Generators see [[Tigerstripe_Tutorials#Code_Generation | Tigerstripe Tutorials, Code Generation]].
  
=== Obtaining available Tigerstripe Generators ===
+
=== Obtaining the Tigerstripe Generator ===
  
If you wish to use the latest generators check please check the projects out from our [[Tigerstripe_Repository_Details|CVS repository]].
+
The generator used in this tutorial is in the Tigerstripe CVS repository at:
  
=Running a generation from the command line=
+
<pre>
 +
:pserver:anonymous@dev.eclipse.org:/cvsroot/technology/org.eclipse.tigerstripe/generators/export-xml
 +
</pre>
 +
 
 +
Alternatively, it can be downloaded as a .zip file, [[Media:Export-xml.zip|export-xml.zip]]. If downloading the .zip file, follow the procedure described in the [[Tigerstripe_Headless_Generation_Tutorial#Importing_an_Example_Model | Importing an Example Model]] Section to import the project into your workspace.
 +
 
 +
=== Installing the Generator ===
 +
# Open the generator's configuration (ts-plugin.xml) for editing.<br>[[Image:Export1.gif]]
 +
# From the Overview panel, Testing section, click the <code>Package and deploy this plugin</code>. Hyperlink.<br>[[Image:Export2.gif]]
 +
# Click "OK" in the '''Deploy New Plugin''' dialog.
 +
# Click "OK" in the '''export-xml Plugin''' dialog.
 +
# Verify Generator installation.
 +
#* From the menu bar, select Tigerstripe -> Plugins...
 +
#* Verify that the export-xml generator is listed in the dialog box.<br>[[Image:Plugin1.gif]]
 +
 
 +
=Running a Generation from the Command Line=
 
=== Overview ===
 
=== Overview ===
 
Now that the Tigerstripe workbench is set up and the Tigerstripe generators have been installed and tested you can invoke a generation run from the command line. The Eclipse mechanism for running in a headless environment will be used to accomplish this.
 
Now that the Tigerstripe workbench is set up and the Tigerstripe generators have been installed and tested you can invoke a generation run from the command line. The Eclipse mechanism for running in a headless environment will be used to accomplish this.
Line 35: Line 54:
 
<br>
 
<br>
 
*<workspace> - The path of the workspace that contains the required projects<br>
 
*<workspace> - The path of the workspace that contains the required projects<br>
*<generation project> - The project that will be generated. Defined by the key/value pair: GENERATION_PROJECT=<PROJECT_PATH><br>
+
*<generation project> - The project that will be generated. Defined by the key/value pair: <code>GENERATION_PROJECT=<PROJECT_PATH></code><br>
*<referenced projects> - The referenced projects required for generation. Defined by the key/value pair: PROJECT_IMPORT=<PROJECT_PATH><br>
+
*<referenced projects> - The referenced projects required for generation. Defined by the key/value pair: <code>PROJECT_IMPORT=<PROJECT_PATH></code><br>
 +
 
 
=== Run a headless model generation using the Tigerstripe Workbench ===
 
=== Run a headless model generation using the Tigerstripe Workbench ===
 
<pre>
 
<pre>
Line 58: Line 78:
 
# Verify generation by navigating to <workspace>OrderManagement\target\tigerstripe.gen\xml. Verify that OrderManagement.xml is a xml based representation of the example model<br>[[Image:Outdir.gif]]
 
# Verify generation by navigating to <workspace>OrderManagement\target\tigerstripe.gen\xml. Verify that OrderManagement.xml is a xml based representation of the example model<br>[[Image:Outdir.gif]]
  
=Running a generation from a Maven2 build=
+
=Running a Generation from a Maven2 Build=
 +
===Overview===
 +
Once the Tigerstripe workbench is set up and the Tigerstripe generators have been installed and test you can use a supplied Maven plug-in to invoke a generation. This tutorial assumes that you have installed Maven correctly and are familiar with it's use. See [http://maven.apache.org/ http://maven.apache.org/] for information on Maven.
 +
 
 +
===Running a Tigerstripe Generation via Maven===
 +
Obtain the source from the following CVS repository location:
 +
* CVSROOT=:pserver:anonymous@dev.eclipse.org:/cvsroot/technology
 +
* module = org.eclipse.tigerstripe/misc/tigerstripe-maven-plugin
 +
 
 +
<pre>
 +
:pserver:anonymous@dev.eclipse.org:/cvsroot/technology/org.eclipse.tigerstripe/misc/tigerstripe-maven-plugin
 +
</pre>
 +
 
 +
# Install the plugin to your local Maven repository by running  <code>mvn install</code>  from the tigerstripe-maven-plugin root directory.<br> [[Image:MvnInstall.gif]]
 +
# Create and set the ECLIPSE_HOME environment variable.
 +
## Click Start and then click Control Panel.
 +
## Double-click System.
 +
## On the Advanced tab, click Environment Variables.
 +
## Under System variables, click New.
 +
## In the Variable Name box type ECLIPSE_HOME, in the Variable Value box type your path to your Eclipse installation (c:\eclipse, for example), and then click OK.
 +
## Click OK.
 +
# Create a Maven project for Tigerstripe generation.<br><pre>mvn archetype:create -DarchetypeGroupId=org.apache.maven.archetypes -DgroupId=com.ordermgmt -DartifactId=ts-generation</pre>
 +
# Change to the ts-generation directory and open up the pom.xml file in a text editor. Enter the following build section into the file.
 +
<pre>
 +
  <build>
 +
    <plugins>
 +
      <!-- run tigerstripe generations -->
 +
      <plugin>
 +
<groupId>tigerstripe</groupId>
 +
<artifactId>maven-tigerstripe-plugin</artifactId>
 +
<version>1.2</version>
 +
<executions>
 +
  <execution>
 +
    <!-- fill in your specific information here -->
 +
    <configuration>
 +
      <workspace>C:\workspace</workspace>
 +
      <projects>
 +
        <param>C:\workspace\OrderManagement</param>
 +
      </projects>
 +
      <generationProject>C:\workspace\OrderManagement</generationProject>
 +
    </configuration>
 +
    <goals>
 +
      <goal>generate</goal>
 +
    </goals>
 +
  </execution>
 +
</executions>
 +
      </plugin>
 +
    </plugins>
 +
  </build>
 +
</pre>
 +
 
 +
Now, from the root directory of the ts-generation directory type <code>mvn install</code>. The generation will run on the workspace defined. You may check the output directory (target\tigerstripe.gen, by default) in the Eclipse workspace to verify that the expected artifacts were generated.
 +
 
 +
See the following section for complete information on the tigerstipe-maven-plugin configuration.
 +
 
 +
=== Tigerstripe Maven Plugin ===
 +
 
 +
====Mojo Attributes====
 +
* Requires a Maven 2.0 project to execute
 +
* Automatically executes within the lifecycle phase: generate-sources
 +
 
 +
====Parameters====
 +
{| border="1" cellpadding="2"
 +
!width="150"|Name
 +
!width="150"|Type
 +
!width="400"|Description
 +
|-
 +
|workspace || String || The location of the Eclipse workspace that will be used for the generation.
 +
|-
 +
|projects || String[]|| A list of all Tigerstripe projects required for the generation, including the generation project and all referenced projects.
 +
|-
 +
|generationProject || String || The primary Tigerstripe project.
 +
|}
 +
=Use Tigerstripe Headless Product=
 +
Since Tigerstripe v0.4.5, we now provide a Tigerstripe Headless Product which contains the minimum set of plugins to trigger a headless generation from the command line.
 +
This allows to considerably shrink the size of the Tigerstripe distribution to be installed to run in a headless environment.
 +
 
 +
To install, it simply download the product for the target platform below and unzip it at the appropriate location.
 +
This Tigerstripe distrib comes with no Tigerstripe generator obviously, so before running it you will need to make sure you install your generators. To do so, copy the .zip files from your eclipse/tigerstripe/plugins into the corresponding directory in the headless product that you unzipped.
 +
 
 +
Then simply use the corresponding script to launch the headless run.
 +
 
 +
{| border="1" cellpadding="2"
 +
!width="50"|Platform
 +
!width="50"|TS Version
 +
!width="250"|Download
 +
!width="150"|Script
 +
|-
 +
|linux || 0.4.5 || [http://www.eclipse.org/downloads/download.php?file=/technology/tigerstripe/tigerstripe-headless_linux_0.4.5_incubation.zip tigerstripe-headless_linux_0.4.5_incubation.zip] || [http://www.eclipse.org/downloads/download.php?file=/technology/tigerstripe/tigerstripe.sh tigerstripe.sh]
 +
|-
 +
|linux || 0.4.6I1 || [http://www.eclipse.org/downloads/download.php?file=/technology/tigerstripe/tigerstripe-headless_linux_0.4.6I1_incubation.zip tigerstripe-headless_linux_0.4.6I1_incubation.zip] || [http://www.eclipse.org/downloads/download.php?file=/technology/tigerstripe/tigerstripe.sh tigerstripe.sh]
 +
|}

Latest revision as of 13:18, 30 August 2010

< To: Tigerstripe_Tutorials

This tutorial will show you how to configure Tigerstripe to run code generations in a headless environment. This will allow you to incorporate Tigerstripe's code generation functionality into a build chain using many of the commonly available build tools, specifically Maven 2.

Tigerstripe Installation

See the Tigerstripe Installation Tutorial page for instructions on installing the Tigerstripe Workbench.

Importing an Example Model

This example project is also available from the CVS repository. If you wish to get the files from CVS you may skip the rest of this step.

:pserver:anonymous@dev.eclipse.org:/cvsroot/technology/org.eclipse.tigerstripe/samples/OrderManagement
  1. Download the sample Tigerstripe model project OrderManagement.zip.
  2. Start Eclipse and then open the Tigerstripe Workbench perspective.
  3. Import the sample project, OrderManagement.zip into the Tigerstripe Workbench.
    • Right click in the Tigerstripe Explorer pane and select "Import"
      Import.gif
    • Select General -> Existing Projects into Workspace. Click "Next >"
      Import2.gif
    • Click "Select Archive File" and browse to the location of the sample model project .zip file. Click "Finish"
      Import3.gif
  4. Verify that the project is in your Tigerstripe Explorer pane.
    Import4.gif

Installing Tigerstripe Generators

Overview

Tigerstripe Generators are pluggable components that allow users to define rules and conventions for code that is generated from a Tigerstripe Model Project. Several generators are currently available, and in many cases, you may want to write your own. For more information on writing your own Tigerstripe Generators see Tigerstripe Tutorials, Code Generation.

Obtaining the Tigerstripe Generator

The generator used in this tutorial is in the Tigerstripe CVS repository at:

:pserver:anonymous@dev.eclipse.org:/cvsroot/technology/org.eclipse.tigerstripe/generators/export-xml

Alternatively, it can be downloaded as a .zip file, export-xml.zip. If downloading the .zip file, follow the procedure described in the Importing an Example Model Section to import the project into your workspace.

Installing the Generator

  1. Open the generator's configuration (ts-plugin.xml) for editing.
    Export1.gif
  2. From the Overview panel, Testing section, click the Package and deploy this plugin. Hyperlink.
    Export2.gif
  3. Click "OK" in the Deploy New Plugin dialog.
  4. Click "OK" in the export-xml Plugin dialog.
  5. Verify Generator installation.
    • From the menu bar, select Tigerstripe -> Plugins...
    • Verify that the export-xml generator is listed in the dialog box.
      Plugin1.gif

Running a Generation from the Command Line

Overview

Now that the Tigerstripe workbench is set up and the Tigerstripe generators have been installed and tested you can invoke a generation run from the command line. The Eclipse mechanism for running in a headless environment will be used to accomplish this.

The following command/syntax invokes a headless generation:

eclipsec -nosplash -data <workspace> -application org.eclipse.tigerstripe.workbench.headless.tigerstripe <referenced projects> <generation project>

  • <workspace> - The path of the workspace that contains the required projects
  • <generation project> - The project that will be generated. Defined by the key/value pair: GENERATION_PROJECT=<PROJECT_PATH>
  • <referenced projects> - The referenced projects required for generation. Defined by the key/value pair: PROJECT_IMPORT=<PROJECT_PATH>

Run a headless model generation using the Tigerstripe Workbench

@echo off

REM Set below to match your current configuration
set ECLIPSE_HOME=C:\eclipse
set WORKSPACE=C:\workspace
set HEADLESS_PLUGIN=org.eclipse.tigerstripe.workbench.headless.tigerstripe
set PROJECT=GENERATION_PROJECT=%WORKSPACE%\OrderManagement

REM Use below to define referenced projects
REM set REFERENCE_ONE= PROJECT_IMPORT=%WORKSPACE%\ReferencedProjectOne
REM set REFERENCE_TWO= PROJECT_IMPORT=%WORKSPACE%\ReferencedProjectTwo

%ECLIPSE_HOME%\eclipsec -nosplash -data %WORKSPACE% -application %HEADLESS_PLUGIN% %PROJECT%
  1. Download wincmdline.zip (above) and unzip the .bat file in a handy location
  2. Verify that the .bat file parameters are set correctly for your system
  3. Execute the batch file to initiate model generation (Note: output may vary based on version)
    Bat.gif
  4. Verify generation by navigating to <workspace>OrderManagement\target\tigerstripe.gen\xml. Verify that OrderManagement.xml is a xml based representation of the example model
    Outdir.gif

Running a Generation from a Maven2 Build

Overview

Once the Tigerstripe workbench is set up and the Tigerstripe generators have been installed and test you can use a supplied Maven plug-in to invoke a generation. This tutorial assumes that you have installed Maven correctly and are familiar with it's use. See http://maven.apache.org/ for information on Maven.

Running a Tigerstripe Generation via Maven

Obtain the source from the following CVS repository location:

  • CVSROOT=:pserver:anonymous@dev.eclipse.org:/cvsroot/technology
  • module = org.eclipse.tigerstripe/misc/tigerstripe-maven-plugin
:pserver:anonymous@dev.eclipse.org:/cvsroot/technology/org.eclipse.tigerstripe/misc/tigerstripe-maven-plugin
  1. Install the plugin to your local Maven repository by running mvn install from the tigerstripe-maven-plugin root directory.
    MvnInstall.gif
  2. Create and set the ECLIPSE_HOME environment variable.
    1. Click Start and then click Control Panel.
    2. Double-click System.
    3. On the Advanced tab, click Environment Variables.
    4. Under System variables, click New.
    5. In the Variable Name box type ECLIPSE_HOME, in the Variable Value box type your path to your Eclipse installation (c:\eclipse, for example), and then click OK.
    6. Click OK.
  3. Create a Maven project for Tigerstripe generation.
    mvn archetype:create -DarchetypeGroupId=org.apache.maven.archetypes -DgroupId=com.ordermgmt -DartifactId=ts-generation
  4. Change to the ts-generation directory and open up the pom.xml file in a text editor. Enter the following build section into the file.
  <build>
    <plugins>
      <!-- run tigerstripe generations --> 
      <plugin>
	<groupId>tigerstripe</groupId>
	<artifactId>maven-tigerstripe-plugin</artifactId>
	<version>1.2</version>
	<executions>	
	  <execution>
	    <!-- fill in your specific information here -->
	    <configuration>
	      <workspace>C:\workspace</workspace>
	      <projects>
	        <param>C:\workspace\OrderManagement</param>
	      </projects>
	      <generationProject>C:\workspace\OrderManagement</generationProject>
	    </configuration>
	    <goals>
	      <goal>generate</goal>
	    </goals>
	  </execution>
	</executions>
      </plugin>
    </plugins>		
  </build>

Now, from the root directory of the ts-generation directory type mvn install. The generation will run on the workspace defined. You may check the output directory (target\tigerstripe.gen, by default) in the Eclipse workspace to verify that the expected artifacts were generated.

See the following section for complete information on the tigerstipe-maven-plugin configuration.

Tigerstripe Maven Plugin

Mojo Attributes

  • Requires a Maven 2.0 project to execute
  • Automatically executes within the lifecycle phase: generate-sources

Parameters

Name Type Description
workspace String The location of the Eclipse workspace that will be used for the generation.
projects String[] A list of all Tigerstripe projects required for the generation, including the generation project and all referenced projects.
generationProject String The primary Tigerstripe project.

Use Tigerstripe Headless Product

Since Tigerstripe v0.4.5, we now provide a Tigerstripe Headless Product which contains the minimum set of plugins to trigger a headless generation from the command line. This allows to considerably shrink the size of the Tigerstripe distribution to be installed to run in a headless environment.

To install, it simply download the product for the target platform below and unzip it at the appropriate location. This Tigerstripe distrib comes with no Tigerstripe generator obviously, so before running it you will need to make sure you install your generators. To do so, copy the .zip files from your eclipse/tigerstripe/plugins into the corresponding directory in the headless product that you unzipped.

Then simply use the corresponding script to launch the headless run.

Platform TS Version Download Script
linux 0.4.5 tigerstripe-headless_linux_0.4.5_incubation.zip tigerstripe.sh
linux 0.4.6I1 tigerstripe-headless_linux_0.4.6I1_incubation.zip tigerstripe.sh