Jump to: navigation, search

Difference between revisions of "TCS/Language Project"

< TCS
(Creating the Directory Structure: Adding Tree Folder Example)
m (added to AMMA category)
 
(21 intermediate revisions by 3 users not shown)
Line 6: Line 6:
 
** A compiler (e.g., in ATL, or in [[ACG]]).
 
** A compiler (e.g., in ATL, or in [[ACG]]).
  
==Creating a Language Project==
+
This page explains how to create, and build a TCS Language Project.
 +
There are two main possibilities:
 +
* [[TCS/Language_Project#Creating_a_Language_Project_For_Plugin_Builder|Using the plugin builder]]: this solution is simpler to use but offers fewer features (e.g., no ACG compiler, no metamodel extension). It is recommended for new TCS users to start with this solution if they do not need advanced features. It is still possible to switch to the ant-based builder later.
 +
* [[TCS/Language_Project#Creating_a_Language_Project_For_Ant-based_Builder|Using the ant-based builder]]: this solution is more complex to use but offers more features.
  
This section details the steps required to create a language project.
+
==Creating a Language Project For Plugin Builder==
 +
 
 +
===Installing the Required Features===
 +
 
 +
TCS distribution consists of two parts - TCS plugins and TCS Parser Generators:
 +
* The source code of TCS plugins is available from Eclipse.org. Binary downloads will be available soon. Note that you need to install [[ATL]] as well. The simplest way is to fetch all ATL plugins from CVS using branch R2_1_0_dev.
 +
* TCS Parser Generators plugins wrap parser generators to use by TCS. TCS Parser Generators plugins are currently distributed on an [http://www.sciences.univ-nantes.fr/lina/atl/www/download/updates/tcs/ external update site] (i.e., not by Eclipse.org). Some parser generators are expected to become available directly on Eclipse.org at a later time.
 +
 
 +
===Using the Wizard===
 +
 
 +
This section details the steps required to create a language project for use with the plugin builder.
 +
It is necessary to install the required features (see previous section).
 +
 
 +
Here is how to proceed to create a new TCS Language Project:
 +
* Use the wizard to create a TCS Language Project: File->New->Project...->ATL->TCS Language Project.
 +
[[Image:FIACRELanguageProjectCreation-WizardSelection.png]]
 +
* Enter language information: name, and file extension.
 +
[[Image:FIACRELanguageProjectCreation-Wizard.png]]
 +
* This will create the directory structure, including sample KM3 and TCS files that need to be modified.
 +
[[Image:FIACRELanguageProjectFilesBeforeCompilation.png]]
 +
* Note that the builder is invoked during automatic builds. For instance, everything that has changed is rebuilt each time you save the KM3 or TCS file. The screenshot below shows the directory structure after a build.
 +
[[Image:FIACRELanguageProjectFilesAfterCompilation.png]]
 +
 
 +
Note that almost everything is done automatically with the plugin builder.
 +
This includes registration of the Textual Generic Editor (TGE) with the file extension specified for the language.
 +
However, this notably '''excludes''' registration of the megamodel.
 +
You need to right click on <code>megamodel.xmi</code>, and select "Add megamodel".
 +
Because megamodel registration is stored in the workspace metadata, you only need to do this once per workspace in which you use your Language Project.
 +
 
 +
==Creating a Language Project For Ant-based Builder==
 +
 
 +
Note: ant-based TCS builders are obsolete. You should use the [[TCS/Language Project#Creating a Language Project For Plugin Builder|plugin builder]] instead.
 +
 
 +
This section details the steps required to create a language project for use with the ant-based builder.
 
Whenever the name of the language appears, we use ''MyLanguage''.
 
Whenever the name of the language appears, we use ''MyLanguage''.
  
Line 20: Line 56:
  
 
===Creating the Directory Structure===
 
===Creating the Directory Structure===
 
+
<div style="display:inline; width:400px; float:right;">[[Image:ProjectTreeLanguageProjectConfig.PNG|Folder Tree sample]]</div>
 
* Create an ATL project:
 
* Create an ATL project:
 
** Open: File->New->ATL Project
 
** Open: File->New->ATL Project
Line 32: Line 68:
 
*** Syntax/
 
*** Syntax/
 
**** ''MyLanguage''.tcs (you can copy and paste SampleLanguage.tcs and rename it)
 
**** ''MyLanguage''.tcs (you can copy and paste SampleLanguage.tcs and rename it)
** build.properties (you can copy and paste /SampleLanguage/build.properties and modify it)
+
** build.properties: it should contain the two paremeters showed below
Once you finish, your project looks like te one below (the .externalToolBuilders/ folder is created by Eclipse)<br />
+
*:[[Image:Build.Properties.PNG|Build Properties file sample]]
[[Image:ProjectTreeLanguageProjectConfig.PNG]]
+
 
 +
Once you finish, your project looks like the one besides (the ''.externalToolBuilders/'' folder is created by Eclipse)<br />
  
 
===Adding the Language Builder===
 
===Adding the Language Builder===
Line 55: Line 92:
 
*** Set "Buildfile" to "${workspace_loc:/AMMAScripts/build.dsl.xml}"
 
*** Set "Buildfile" to "${workspace_loc:/AMMAScripts/build.dsl.xml}"
 
*** Set "Base Directory" to "${workspace_loc:/''MyLanguage''}"
 
*** Set "Base Directory" to "${workspace_loc:/''MyLanguage''}"
 +
*:[[Image:LanguageBuilderConfig.MainTab.png|Main Tab]]
 
** In the "Targets" tab:
 
** In the "Targets" tab:
 
*** Set "During a Clean" to target "clean"
 
*** Set "During a Clean" to target "clean"
 +
*:[[Image:LanguageBuilderConfig.TargetsTab.png|Targets Tab]]
 
** In the "Classpath" tab:
 
** In the "Classpath" tab:
 
*** Add all the jars from the "/AMMAScripts/libs/" folder
 
*** Add all the jars from the "/AMMAScripts/libs/" folder
*:[[Image:LanguageBuilderConfig.ClasspathTab.png]]
+
*:[[Image:LanguageBuilderConfig.ClasspathTab.png|Classpath Tab]]
 
** In the "JRE" tab:
 
** In the "JRE" tab:
 
*** Check "Run in the same JRE as the workspace"
 
*** Check "Run in the same JRE as the workspace"
 +
*:[[Image:LanguageBuilderConfig.JRETab.png|JRE Tab]]
 
** Click "OK"
 
** Click "OK"
 
* Set the language builder before any other builder
 
* Set the language builder before any other builder
 +
 +
==Launching the Injector and the Extractor ==
 +
To inject (text to model) or extract (model to text) your files, you can use the following scripts as example:
 +
* [http://www.eclipse.org/gmt/tcs/doc/examples/Injection.xml Sample injection file]
 +
* [http://www.eclipse.org/gmt/tcs/doc/examples/Extraction.xml Sample extraction file]
 +
 +
[[Category:AMMA]]

Latest revision as of 12:32, 5 June 2013

A TCS Language Project is an Eclipse project (typically with the ATL nature), which contains:

  • A KM3 metamodel defining the abstract syntax of the language.
  • A TCS model defining the concrete syntax of the language.
  • Optionally, such a project may also contain:
    • Constraints (e.g., in OCL, as part of an ATL transformation).
    • A compiler (e.g., in ATL, or in ACG).

This page explains how to create, and build a TCS Language Project. There are two main possibilities:

  • Using the plugin builder: this solution is simpler to use but offers fewer features (e.g., no ACG compiler, no metamodel extension). It is recommended for new TCS users to start with this solution if they do not need advanced features. It is still possible to switch to the ant-based builder later.
  • Using the ant-based builder: this solution is more complex to use but offers more features.

Creating a Language Project For Plugin Builder

Installing the Required Features

TCS distribution consists of two parts - TCS plugins and TCS Parser Generators:

  • The source code of TCS plugins is available from Eclipse.org. Binary downloads will be available soon. Note that you need to install ATL as well. The simplest way is to fetch all ATL plugins from CVS using branch R2_1_0_dev.
  • TCS Parser Generators plugins wrap parser generators to use by TCS. TCS Parser Generators plugins are currently distributed on an external update site (i.e., not by Eclipse.org). Some parser generators are expected to become available directly on Eclipse.org at a later time.

Using the Wizard

This section details the steps required to create a language project for use with the plugin builder. It is necessary to install the required features (see previous section).

Here is how to proceed to create a new TCS Language Project:

  • Use the wizard to create a TCS Language Project: File->New->Project...->ATL->TCS Language Project.

FIACRELanguageProjectCreation-WizardSelection.png

  • Enter language information: name, and file extension.

FIACRELanguageProjectCreation-Wizard.png

  • This will create the directory structure, including sample KM3 and TCS files that need to be modified.

FIACRELanguageProjectFilesBeforeCompilation.png

  • Note that the builder is invoked during automatic builds. For instance, everything that has changed is rebuilt each time you save the KM3 or TCS file. The screenshot below shows the directory structure after a build.

FIACRELanguageProjectFilesAfterCompilation.png

Note that almost everything is done automatically with the plugin builder. This includes registration of the Textual Generic Editor (TGE) with the file extension specified for the language. However, this notably excludes registration of the megamodel. You need to right click on megamodel.xmi, and select "Add megamodel". Because megamodel registration is stored in the workspace metadata, you only need to do this once per workspace in which you use your Language Project.

Creating a Language Project For Ant-based Builder

Note: ant-based TCS builders are obsolete. You should use the plugin builder instead.

This section details the steps required to create a language project for use with the ant-based builder. Whenever the name of the language appears, we use MyLanguage.

Checking out the Required Projects

The first step is to check out the AMMAScripts, and AMMACore projects in your workspace, if you do not have them already.

To do this, you can connect anonymously by CVS to repository /cvsroot/technology on server dev.eclipse.org using the pserver protocol. Then, you can checkout the two projects available in org.eclipse.gmt/org.eclipse.gmt.tcs/scripts/.

NB: Some external libraries are required, please refer to the README.txt file in the AMMAScripts project for more details.

Creating the Directory Structure

Folder Tree sample
  • Create an ATL project:
    • Open: File->New->ATL Project
    • Name the project like your language (e.g., MyLanguage)
  • Create the following folders and files in your project:
    • MyLanguage/ (this is the project we just created)
      • Metamodel/
        • MyLanguage.km3 (you can copy and paste SampleLanguage.km3 and rename it)
      • Samples/
        • <sample programs written in your language, with the corresponding file extension>
      • Syntax/
        • MyLanguage.tcs (you can copy and paste SampleLanguage.tcs and rename it)
    • build.properties: it should contain the two paremeters showed below
    Build Properties file sample

Once you finish, your project looks like the one besides (the .externalToolBuilders/ folder is created by Eclipse)

Adding the Language Builder

Building a language involves:

  • Compiling its KM3 metamodel to Ecore.
  • Compiling its TCS model into a parser.
  • Optionally compiling its ACG compiler.

Here are the steps to follow to add the Language Builder to the project:

  • Creating the builder:
    • Right-click on your language project (e.g., MyLanguage) and select "Properties".
    • Go to the "Builders" section.
    • Click "New..."
    • Select "Ant Build"
    • Click "OK"
  • Configuring the builder:
    • Set the name of the builder to "MyLanguage Language Builder"
    • In the "Main" tab:
      • Set "Buildfile" to "${workspace_loc:/AMMAScripts/build.dsl.xml}"
      • Set "Base Directory" to "${workspace_loc:/MyLanguage}"
    Main Tab
    • In the "Targets" tab:
      • Set "During a Clean" to target "clean"
    Targets Tab
    • In the "Classpath" tab:
      • Add all the jars from the "/AMMAScripts/libs/" folder
    Classpath Tab
    • In the "JRE" tab:
      • Check "Run in the same JRE as the workspace"
    JRE Tab
    • Click "OK"
  • Set the language builder before any other builder

Launching the Injector and the Extractor

To inject (text to model) or extract (model to text) your files, you can use the following scripts as example: