ATL: Atlas Transfrmatin Language ATL Installatin Guide - versin 0.1 - Nvember 2005 by ATLAS grup LINA & INRIA Nantes
Cntent 1 Intrductin... 3 2 Installing ADT frm binaries... 3 2.1 Installing Eclipse and EMF... 3 2.2 Installing ADT... 3 2.3 Additinal required resurces... 4 2.4 First start f ADT... 4 3 Installing ADT frm surce... 5 3.1 Installing Eclipse and EMF... 5 3.2 Installing ADT... 6 3.2.1 Checking ut ATL surces fr Eclipse 3.0... 7 3.2.2 Checking ut ATL surces fr Eclipse 3.1... 8 3.3 Additinal required resurces... 9 3.4 First start f ADT... 10 3.4.1 Running ADT thrugh the run-time wrkbench... 10 3.4.2 Installing ADT in Eclipse frm surces... 11 4 Ging further... 12 5 References... 12 Figures List Figure 1. Switching t the ATL perspective... 4 Figure 2. Creatin f a new ATL prject... 5 Figure 3. Cnfiguratin f the CVS access... 6 Figure 4. Checking ATL prjects ut... 7 Figure 5. Selectin f prjects t be refreshed... 8 Figure 6. Checking ATL debugging prject fr Eclipse 3.1 ut... 9 Figure 7. Creating a new launch cnfiguratin... 10 Figure 8. Selecting a launch cnfiguratin... 11 Figure 9. Exprting ADT plug-ins... 12
ATL Dcumentatins ATL Installatin Guide Date 01/12/2005 1 Intrductin The ATLAS Transfrmatin Language (ATL) is the ATLAS research grup answer t the OMG MOF [1]/QVT RFP [2]. It is a mdel transfrmatin language specified bth as a metamdel and as a textual cncrete syntax. ATL is made available as part f the ATL Develpment Tls (ADT). The current ADT distributin runs ver the Eclipse platfrm [3], and is based n the Eclipse Mdeling Framewrk (EMF) [4]. This dcument aims t prvide a step-by-step guide fr installing the Eclipse/EMF distributin f the ATL Develpment Tls. Sectin 2 deals with the installatin f ADT frm binaries available frm the GMT (Generative Mdel Transfrmer) prject [5]. Sectin 3 details ADT installatin frm its surce cde (available n the Eclipse CVS repsitry). Finally, Sectin 4 prvides sme links t already available ATL resurces, as well as references t the ATL mailing list. 2 Installing ADT frm binaries This sectin describes the ADT installatin frm binaries. Sectin 2.1 deals with the installatin f Eclipse and the EMF plug-in. Sectin 2.2 describes the ADT installatin frm the binaries available frm the GMT prject web site. Sectin 2.3 details the installatin f the additinal resurces that are required t run the ATL Develpment Tls. Finally, Sectin 2.4 describes the first start f ADT. 2.1 Installing Eclipse and EMF The first step while installing ADT is t install bth the Eclipse envirnment and the EMF framewrk. The last ADT release (versin 20051102) is based n Eclipse 3.1.0 and EMF 2.1.0: Eclipse is available at http://www.eclipse.rg/dwnlads/index.php. Select the release 3.1 (eclipse-sdk-3.1-win32.zip). EMF can be dwnladed frm http://dwnlad.eclipse.rg/tls/emf/scripts/dwnlads.php. Select the release 2.1.0 (emf-sd-runtime-2.1.0.zip). Imprtant nte: users wh want, fr sme reasns, t use a 3.0 Eclipse versin must dwnlad the 2.0.2 versin f the EMF plug-in. Installing the Eclipse envirnment is simply achieved by unzipping the crrespnding archive (eclipse- SDK-3.1-win32.zip). This will create an \eclipse directry cntaining all the Eclipse files. At this stage, the EMF installatin cnsists in unzipping the EMF archive (emf-sd-runtime-2.1.0.zip) int the same target directry. This last peratin writes the set f EMF plug-ins in the \eclipse\plugins directry. Next step cnsists in installing the set f ADT plug-ins. 2.2 Installing ADT The ATL tls can be installed frm binaries. This installatin mde is recmmended fr thse that nly want t use ATL. ADT binaries are available n the GMT (Generative Mdel Transfrmer) prject web site. They can be dwnladed frm the ATL Dwnlad Sectin. Current release build crrespnds t the versin 20051102 in the Builds subsectin (adt-20051102.zip). Imprtant nte: users wh want, fr sme reasns, t use a 3.0 Eclipse versin must dwnlad the 20050916 versin f the ADT archive. Page 3
ATL Dcumentatins ATL Installatin Guide Date 01/12/2005 Installing the ATL tls is achieved by unzipping the archive. Be careful: the ADT archive has t be uncmpressed int the \eclipse directry that has been created by the Eclipse installatin step (see Sectin 2.1), s that ADT plug-ins are placed int the \eclipse\plugins flder. ADT plug-ins are nw installed, but they still require sme external libraries that are nt included in the prvided binaries. Next step f the ADT installatin therefre cnsists in installing these additinal resurces that are required t run ATL prgrams. 2.3 Additinal required resurces Beside the EMF framewrk, ATL is based n the ANTLR (ANther Tl fr Language Recgnitin) [6] and the Netbeans MDR libraries (Metadata Repsitry) [7]: ANTLR can be dwnladed frm http://www.antlr.rg/dwnlad.html. Select the jar file nly (tl and Java runtime) archive (antlr-2.7.5.jar). MDR is available at http://mdr.netbeans.rg/dwnlad/. Select the MDR zip archive (mdrstandalne.zip). The ANTLR library must be renamed int antlr.jar. The library then has t be cpied int the \eclipse\plugins\rg.atl.eclipse.engine_versin\lib (fr instance, \eclipse\plugins\rg.atl.eclipse.engine_1.0.7\lib). The jar files cntained in the MDR archive (jmi.jar, jmiutils.jar, mdrapi.jar, mf.jar, nbmdr.jar and penide-util.jar) have t be cpied int the \eclipse\plugins\rg.atl.engine.repsitries.mdr4atl_versin\lib (fr instance, \eclipse\plugins\rg.atl.engine.repsitries.mdr4atl_1.0.0\lib). Installatin f the ATL tls is nw cmpleted. Sectin 2.4 prvides sme useful infrmatin fr the first start f ADT. 2.4 First start f ADT Nw ADT have been installed int the Eclipse envirnment, it is time t start using ATL. Figure 1. Switching t the ATL perspective Page 4
ATL Dcumentatins ATL Installatin Guide Date 01/12/2005 Figure 2. Creatin f a new ATL prject Once Eclipse is launched, the first step is t switch frm the current perspective (by default, the Java perspective is pened when Eclipse is started fr the first time) t the ATL perspective. This culd be achieved by selecting ATL in the perspective menu prvided at Windw Open Perspective Other (see Figure 1). Be sure, when using ATL, t always be under the ATL perspective. Once Eclipse has switched t the ATL perspective, it is pssible t start using the ATL tls. The first step cnsists in creating a new empty ATL prject in which ATL files (e.g. defining ATL transfrmatins) can be defined. This creatin can be achieved by muse right click New ATL Prject, as shwn in Figure 2. Sectin 4 prvides a number f pinters t existing material n the ATL transfrmatin language, including user manual, transfrmatin examples 3 Installing ADT frm surce This sectin describes the ADT installatin frm its surce cde. Sectin 3.1 deals with the installatin f Eclipse and the EMF plug-in. Sectin 3.2 describes the installatin f the surce cde available n the Eclipse CVS repsitry. Sectin 3.3 details the installatin f the additinal resurces that are required t run the ATL Develpment Tls. Finally, Sectin 3.4 describes the first start f ADT when installed frm surces. 3.1 Installing Eclipse and EMF The first step while installing ADT is t install bth the Eclipse envirnment and the EMF framewrk. The last ADT release (versin 20051102) is based n Eclipse 3.1.0 and EMF 2.1.0: Eclipse is available at http://www.eclipse.rg/dwnlads/index.php. Select the release 3.1 (eclipse-sdk-3.1-win32.zip). EMF can be dwnladed frm http://dwnlad.eclipse.rg/tls/emf/scripts/dwnlads.php. Select the release 2.1.0 (emf-sd-runtime-2.1.0.zip). Page 5
ATL Dcumentatins ATL Installatin Guide Date 01/12/2005 Figure 3. Cnfiguratin f the CVS access Imprtant nte: users wh want, fr sme reasns, t use a 3.0 Eclipse versin must dwnlad the 2.0.2 versin f the EMF plug-in. Installing the Eclipse envirnment is simply achieved by unzipping the crrespnding archive (eclipse- SDK-3.1-win32.zip). This will create an \eclipse directry cntaining all the Eclipse files. At this stage, the EMF installatin cnsists in unzipping the EMF archive (emf-sd-runtime-2.1.0.zip) int the same target directry. This last peratin writes the set f EMF plug-ins in the \eclipse\plugins directry. Next step cnsists in installing the ADT surces. 3.2 Installing ADT The ATL tls can be installed frm surce cde. This installatin mde is recmmended fr develpers that want t extend the set f tls. The ADT surces are available nt the Eclipse CVS repsitry. It is assumed, at this stage f the installatin prcess, that the Eclipse envirnment is installed (see Sectin 3.1). This dcument therefre details the ADT installatin thrugh the CVS repsitry view f the Eclipse envirnment. The first step is t cnfigure the CVS access. T this end, the user must mve t the CVS Repsitry Explring perspective. This culd be achieved by selecting CVS Repsitry Explring in Windws Open Perspective Other. Frm this pint, a new repsitry lcatin has t be created: muse right click New Repsitry Lcatin This pens the Add CVS Repsitry windw (see Figure 3). The CVS repsitry must be cnfigured as fllws: the hst is dev.eclipse.rg; the repsitry path is /hme/technlgy; Page 6
ATL Dcumentatins ATL Installatin Guide Date 01/12/2005 the user is annymus; n passwrd is required; the cnnectin type is pserver. The repsitry lcatin can then be created (click n Finish ). It shall appear in the current CVS Repsitry View (as pserver:annymus@dev.eclipse.rg:/hme/technlgy). Next step slightly differs accrding t the targeted Eclipse versin. 3.2.1 Checking ut ATL surces fr Eclipse 3.0 Frm the created repsitry lcatin, it is nw pssible t check the ADT prjects surces ut. T this end: pen the HEAD rg.eclipse.gmt ATL directry; select the thirteen existing ATL prjects: rg.atl.eclipse.adt.builder; rg.atl.eclipse.adt.debug; rg.atl.eclipse.adt.dc.develper; rg.atl.eclipse.adt.dc.user; rg.atl.eclipse.adt.editr; rg.atl.eclipse.adt.perspective; rg.atl.eclipse.adt.wizard; rg.atl.eclipse.engine; rg.atl.eclipse.km3; Figure 4. Checking ATL prjects ut Page 7
ATL Dcumentatins ATL Installatin Guide Date 01/12/2005 rg.atl.eclipse.mgm; rg.atl.eclipse.vm; Figure 5. Selectin f prjects t be refreshed rg.atl.eclipse.repsitries.emf4atl; rg.atl.eclipse.repsitries.mdr4atl; check them ut using right click Check Out (see Figure 4). This peratin lcally creates the crrespnding prjects. Created prjects shuld appear when mving t the Plug-in Develpment perspective (Windws Open Perspective Other Plug-in Develpment). Nte that, at this stage, errrs appear in sme f the checked prjects (represented by a red crss in the Package Explrer view and detailed in the Prblems view). These errrs are due t the absence f sme required external libraries that are nt included in the dwnladed plug-ins. Next step f the ADT installatin therefre cnsists in installing these additinal resurces that are required t run ATL prgrams. 3.2.2 Checking ut ATL surces fr Eclipse 3.1 As fr an Eclipse 3.0 platfrm, the ATL prjects surces have t be checked ut frm the created repsitry lcatin. Hwever, there exists a debugging plug-in specific t Eclipse 3.1 versins that has t be checked ut frm a different branch f the repsitry lcatin. Except this debugging prject (rg.atl.eclipse.adt.debug), the ther twelve ATL prjects must be checked ut as described in Sectin 3.2.1. Checking ut the ATL debugging plug-in fr Eclipse 3.1 is achieved as fllws: if the Branches flder (f the repsitry lcatin) appears t be empty, refresh it with muse right click Refresh Branches : this pens a Refresh Branches windw (see Figure 5); select the rg.eclipse.gmt prject and validate (click in Finish ); Page 8
ATL Dcumentatins ATL Installatin Guide Date 01/12/2005 Figure 6. Checking ATL debugging prject fr Eclipse 3.1 ut if a Tags nt fund fr sme mdules windw appears, select the Search Deeply ptin; the Branches flder shuld nw cntain tw subflders: ADTDebugFrEclipse3_1 and GMT0-1 ; pen the Branches ADTDebugFrEclipse3_1 rg.eclipse.gmt ADTDebugFrEclipse3_1 ATL directry; select the ATL debugging prject: rg.atl.eclipse.adt.debug; check it ut using right click Check Out (see Figure 6). Once this peratin is cmpleted, the crrespnding prjects shuld appear when mving t the Plug-in Develpment perspective (Windws Open Perspective Other Plug-in Develpment). It may be nted, in this perspective, that while the debugging prject is cnnected t the ADTDebugFrEclipse3_1 [dev.eclipse.rg] lcatin, the ther twelve nes are simply cnnected t [dev.eclipse.rg]. 3.3 Additinal required resurces Beside the EMF framewrk, ATL is based n the ANTLR (ANther Tl fr Language Recgnitin) and the Netbeans MDR libraries (Metadata Repsitry): ANTLR can be dwnladed frm http://www.antlr.rg/dwnlad.html. Select the jar file nly (tl and Java runtime) archive (antlr-2.7.5.jar). MDR is available at http://mdr.netbeans.rg/dwnlad/. Select the MDR zip archive (mdrstandalne.zip). The ANTLR library must be renamed int antlr.jar. The library then has t be cpied int the \wrkspace_name\rg.atl.eclipse.engine\lib (fr instance, \wrkspace\rg.atl.eclipse.engine\lib). Page 9
ATL Dcumentatins ATL Installatin Guide Date 01/12/2005 Figure 7. Creating a new launch cnfiguratin The jar files cntained in the MDR archive (jmi.jar, jmiutils.jar, mdrapi.jar, mf.jar, nbmdr.jar and penide-util.jar) have t be cpied int the \wrkspace_name\rg.atl.engine.repsitries.mdr4atl\lib (fr instance, \wrkspace\rg.atl.engine.repsitries.mdr4atl\lib). Nw these external libraries have been installed, the ATL prjects can be built (right click Refresh) withut any errr left. The installatin f the ATL tls frm their surce cde is nw cmpleted. Sectin 3.4 prvides sme useful infrmatin fr the first start f ADT. 3.4 First start f ADT Once the ADT installatin frm surce has cmpleted, there are tw ways t run the ATL tls: running ADT thrugh the run-time wrkbench r installing ADT int the Eclipse cpy. These tw ptins are detailed in the fllwing subsectins. 3.4.1 Running ADT thrugh the run-time wrkbench The first ptin t run ATL frm the dwnladed surce cde is t execute the ATL plug-in prjects with the run-time wrkbench. T this end, a new cnfiguratin enabling t launch the run-time wrkbench has t be created. This sectin fcuses n the creatin f a new run-mde launch cnfiguratin. Hwever, develpers wanting t extend the ADT functinalities shuld rather use a debug-mde launch cnfiguratin. Creating a new run-mde launch cnfiguratin can be achieved by selecting the Run Run menu item. This selectin pens a Run windw (see Figure 7). Frm this new windw, select the Eclipse Applicatin cnfiguratin and click n New t create a new launch cnfiguratin. Next step is t cnfigure the launch cnfiguratin. The default cnfiguratin shuld be crrect, but it may be interesting t rename the launch cnfiguratin t be created. Once the new run-mde launch cnfiguratin has been created, the run-time wrkbench can be launched. Again, select the Run Run menu item, but nw select the Eclipse Applicatin launch cnfiguratin newly created (see Figure 8), and click n Run t start the run-time wrkbench. Page 10
ATL Dcumentatins ATL Installatin Guide Date 01/12/2005 Figure 8. Selecting a launch cnfiguratin It is nw pssible t start wrking with the ATL transfrmatin language. Please refer t Sectin 2.4 fr infrmatin n the first steps with ADT. 3.4.2 Installing ADT in Eclipse frm surces The secnd way t run ATL frm the dwnladed surce cde is t install the ATL plug-ins int the Eclipse cpy frm the surce cde f the dwnladed ATL prjects. Fr this purpse, it is necessary t mve t the Plug-in Develpment perspective (Windws Open Perspective Other Plug-in Develpment). Once under the plug-in perspective, select the full set f ATL prjects and chse the Exprt ptin in the cntextual menu (right click Exprt ). In the Exprt windw, select Deplyable plug-ins and fragments. In the fllwing screen (see Figure 9), make sure that all the ADT prjects are selected, then select the archive file exprt destinatin, prvide an archive name and start the exprt by clicking n Finish. Next step cnsists in uncmpressing the created ADT archive int the \eclipse directry. This peratin generates the ADT plug-ins (in the \eclipse\plugins flder) crrespnding t the dwnladed ADT prjects. As a last step, Eclipse has t be restarted. It is nw pssible t start wrking with the ATL transfrmatin language. Please refer t Sectin 2.4 fr infrmatin n the first steps with ADT. Page 11
ATL Dcumentatins ATL Installatin Guide Date 01/12/2005 Figure 9. Exprting ADT plug-ins 4 Ging further The ATLAS Transfrmatin Language (ATL) is part f the Generative Mdel Transfrmer (GMT) Eclipse prject [5]. ATL users may find relevant resurces n the GMT prject site. These resurces include the ATL FAQ, the ATL dcumentatins (ATL User Manual, Specificatin f the ATL Virtual Machine) as well as many ATL transfrmatins examples (in the ATL transfrmatin part). Mrever, there exists an ATL discussin bard [8] enabling the ATL cmmunity t share infrmatin abut ATL and the related mdel management tls. 5 References [1] OMG/MOF 2.0 Cre Final Adpted Specificatin Dcument. ptc/03-10-04, 2004. [2] OMG MOF 2.0 Query / Views / Transfrmatins RFP. ad/02-04-10, Octber 2002. [3] Eclipse hme page. http://www.eclipse.rg/. [4] Budinsky, F., Steinberg, D., Ellersick, R., Grse, T. Eclipse Mdeling Framewrk. Addisn Wesley Prfessinal. ISBN: 0131425420, 2004. [5] The Generative Mdel Transfrmer (GMT) prject. http://eclipse.rg/gmt/. [6] The ANTLR prject. http://www.antlr.rg/. [7] The netbeans Metadata Repsitry (MDR) prject. http://mdr.netbeans.rg/. Page 12
ATL Dcumentatins ATL Installatin Guide Date 01/12/2005 [8] The ATL mailing list. http://grups.yah.cm/grup/atl_discussin/. Page 13