This documentation aims at contributing to improve the comprehension of the ATL source code.

# ATL Source Code

## Plug-ins organization

Below is the list of the ATL plugins:

- ATL Core: provides APIs to launch and extend ATL
  - org.eclipse.m2m.atl.common: provide common utilities
  - org.eclipse.m2m.atl.core: defines the ATL Core API (launching, model handling)
  - org.eclipse.m2m.atl.core.emf: EMF implementation of the Core API
  - org.eclipse.m2m.atl.core.ui.vm: defines a wrapper which allow to launch the ATL Regular VM using the Core API
  - org.eclipse.m2m.atl.core.ant: provides the ATL ant tasks, based on the Core API

- ADT (ATL Development Tools) : Eclipse integration plugins:
  - org.eclipse.m2m.atl.core.ui: provides the ATL launch configuration, based on the Core API
  - org.eclipse.m2m.atl.adt: provides ATL nature and builder
  - org.eclipse.m2m.atl.adt.ui: provides ATL perspective and wizards (new file, new project)
  - org.eclipse.m2m.atl.adt.debug: the ATL Regular VM debugger
  - org.eclipse.m2m.atl.adt.editor: the ATL textual editor

- ATL Parser and Compiler:
  - org.eclipse.m2m.atl.dsls: provides the syntaxic/semantic definition of ATL and ACG
  - org.eclipse.m2m.atl.engine: provides ATL compiling and parsing utilities

- ATL Virtual Machines:
  - org.eclipse.m2m.atl.engine.emfvm: the ATL EMF-specific VM
  - org.eclipse.m2m.atl.engine.vm: the ATL Regular VM, using model handlers:
    - org.eclipse.m2m.atl.drivers.emf4atl: the ATL Regular VM model handler for EMF
    - org.eclipse.m2m.atl.drivers.uml24atl: the ATL Regular VM model handler for UML2

## External dependencies

Historically, ATL imports two libraries : ANTLR version 2 and MDR. Those libraries are not authorized in Eclipse because of their non-compliance with the Eclipse IP policy. Consequently, ATL imposes users to download those libraries by themselves and install them into Eclipse plugin folder.

Today, ATL dependencies have been strongly reduced : ATL only needs ANTLR-runtime (version 3) library, which is compliant with the Eclipse IP policy and included into ATL source code. The MDR library is only necessary for the MDR Model Handler. According to the fact that most of people uses EMF Model Handler (which seems to be more powerful), MDR Model Handler has been separated into a single feature, which is not natively required for ATL.

TCS (Textual Concrete Syntax), a tool for parsing and extraction, is used to generate some ATL components (e.g. ATL-Parser). Unlike ATL, TCS uses both ANTLR library, in version 2 and newly in version 3. TCS is available on GMT. ATL doesn't have any dependency with TCS. Specific injectors depend on ANTLR too.

## Install ATL from GIT

ATL source code is hosted on GitHub>.

#### ANTLR installation

Note that the download of this plugin is embedded into atl.psf files. So, if you followed the previous instructions, you don't need to read the next steps. In Eclipse, antlr is managed by the Orbit project. To checkout this plugin, follow those steps :

- Open an anonymous/commiter CVS connection to `dev.eclipse.org`, repository `/cvsroot/tools`
- Right-click on the repository location, then choose Refresh branches
- In the wizard, check the `org.eclipse.orbit` project
- In the branches, select the one named `v3_0_0`
- Checkout `org.antlr.runtime`

#### MDR installation (Regular VM only)

Some external libraries are required for the plug-in org.eclipse.m2m.atl.drivers.mdr4atl but not available on the CVS repository. You need to download the jar files into the lib/ directory of this project.

Download mdr-standalone.zip from http://mdr.netbeans.org/download/ and put the included jar files into lib/ of plugin org.eclipse.m2m.atl.drivers.mdr4atl.

Note that mdr-standalone.zip is updated more often on the MDR website than in our development source. As a consequence, bugs may appear when using the last-in-date mdr-standalone version of MDR.

When you have finished this operation, there is normally no error left.

WARNING: The MDR model handler is no more maintained, so it may need to be fixed.

#### Testing

ATL is ready to be tested. There are two ways to use it:

- In the "Plug-in Development perspective", you can launch a Run-time workbench (Click on Run -> Run as -> Run-time workbench).
- You can install ATL in your copy of Eclipse. Go in the Plug-in perspective and select all the plug-in projects. In the context menu choose Export -> Deployable Plug-ins and Fragments.

In the screen Export Plug-ins and Fragments, check if all the projects are selected and choose the output folder.

Now you need to close Eclipse. Enter the "eclipse" directory (which contains plug-ins and features directories) then copy the created Jar files into the "plugins" directory. After that you can restart Eclipse.