-
Notifications
You must be signed in to change notification settings - Fork 2
Building VIATRA
VIATRA uses Maven/Tycho for continuous integration builds. It is executed in two passes:
- In the first pass, a selected subset of projects (the so-called "core" projects) are built. These are Eclipse-independent and include the Maven plugin for generating code from VIATRA Query patterns. This is required to allow projects to reuse the latest compiler version; on the other hand, the projects compiled here are pushed into Maven repositories as well.
- In the second pass, the remaining projects are built, mostly Eclipse-specific. These projects may also use the VIATRA Query Maven compiler to generate pattern matcher code.
Important: these two passes have to be executed together, as the language generator mwe workflow of the pattern language (core project) generates code for the Eclipse-dependent UI projects as well; on the other hand, some UI projects depend on the maven compiler to generate matcher code.
The Eclipse update site generated for the first pass (org.eclipse.viatra.update.core) is not intended for use outside of the build process; it only makes the core plug-ins available for the second pass as Eclipse plug-ins. The second phase gets this site as a Maven property core.repository.url.
# First pass
mvn clean install -f releng/org.eclipse.viatra.parent.core/pom.xml
# Second pass
mvn clean install -f releng/org.eclipse.viatra.parent.all/pom.xml
Each component of the projects are stored as a separate subfolder in git, structured into plugins, tests and features. Test projects are expected not to have external dependencies, e.g. metamodels.
- query: Querying EMF models (formerly EMF-IncQuery).
- transformation: Transforming EMF models.
- cep: Complex Event Processing framework.
- dse: Design Space Exploration framework.
- integration: Integrations with other technologies.
- addon: Addons for implementing useful application functionality with VIATRA queries.
The remaining folders describe other elements of the build as follows:
-
releng: Projects related to building and packaging VIATRA:
- org.eclipse.viatra.parent: Used as parent project that only includes common configuration for the VIATRA project. This module is safe to reuse outside the Eclipse project
- Container projects for the "core" submodules which can be used
outside of Eclipse:
- org.eclipse.viatra.parent.core: Root project which contains the core submodules.
- org.eclipse.viatra.update.core: Builds a p2 update site from the core submodules.
- org.eclipse.viatra.target.core: The target definition necessary for building the core submodules.
- Container projects for all non-core submodules:
- org.eclipse.viatra.parent.all: Root Maven project which contains all non-core submodules.
- org.eclipse.viatra.update.all: Builds a p2 update site from all submodules.
- org.eclipse.viatra.target.all: The target definition necessary for building all submodules.
- Oomph setup:
- org.eclipse.viatra.setup: The setup files for setting up the development environments.
- org.eclipse.viatra.generator: The generator MWE2 workflows used by the setup.
- maven: VIATRA Maven plugins.
- examples: Basic examples of various VIATRA features.
- artwork: Logos in various formats.
There are two important things to configure for adding a new project to the build:
- In order to technically build the project, a build configuration
needs to be created (and registered in the parent project).
- This consists of a single pom.xml file in the project root directory.
- And a module declaration in the parent pom.
- Add the created feature to either an existing or a new feature
- If an existing feature is used, the feature.xml has to be extended with the id of the new project.
- If a new feature is created, this feature is required to be registered both in the root project and in the update projects' category.xml file.
- In both cases, don't forget to add the source plugin to the SDK or another Sources feature.
An example commit for executing all these steps (with the creation of a new project) is: https://github.com/viatra/EMF-IncQuery/commit/4b523260c94ddb2605ce1088 (Note that the addition of a source plugin is not included).
A project needs to have a pom.xml file in the project root for the build configuration. In most cases, this build configuration is very simple, as all required configurations are inherited either from the project type (Eclipse plug-in project) or parent project. Basically, there are three configuration types used in the project:
- Projects with xtend files (e.g. the org.eclipse.viatra.query.tooling.core project)
- Projects without xtend files (e.g. the org.eclipse.viatra.query.runtime.base project)
- Projects compiling query specifications (e.g. the org.eclipse.viatra.integration.uml project)
To create such a configuration file for a new project, the recommended solution is to copy an existing corresponding project configuration, and replace the plug-in identifier.
Warning! If a project for any reason uses a different version number than the base VIATRA project, it is important to add the version information to the project, replacing '.qualifier' with '-SNAPSHOT'. org.eclipse.viatra.query.tooling.localsearch.ui.
Additionally, the new project needs to be added to the corresponding parent project (most commonly org.eclipse.viatra.parent.all): The pom.xml file contains a modules section where a list of submodules are presented - it needs to be extended with a new submodule describing the project location.
The existing feature.xml file has to be extended with the new plug-in as a contained plug-in id.
Currently most source plug-ins are installed with the SDK bundle, with the notable exceptions of Graphiti and GMF support plug-ins that can be installed by selecting the source features.
Creating a new feature project works similarly to creating a new plug-in project, but the feature builder pom.xml files are more simple. The recommended way of creating a new feature is to copy and existing one, and modifying the identifier, descriptions and contained plug-ins (and possibly features). The feature also needs to be registered into the root project's module section.
Important: make sure to set up the feature dependencies correctly! This allows including the functionality in Eclipse-based products, but requires a correct identification of the requirement. Also know the difference between feature inclusion and dependency: both are required for your feature to install, but only included features are provided from the VIATRA update site.
Additionally, this feature needs to be added to the update site. For this reason, the feature needs to be registered in the category.xml file stored in the update site project (the category.xml file has a form-based editor in PDE).
Composite repositories are created from integration, milestone and release builds using the p2 Ant tasks. The basic ideas are described at a blog post, the scripts are available in the EMF-Parsley project, but were customized for the use of VIATRA, as there will be no special folders created for each major version.
The Hudson build of VIATRA allows access to these composites using the viatra.download.area property.
Milestone and release builds are signed using the maven-signer-plugin provided by the CBI project: Minerva#Signing.
Core projects are published to repo.eclipse.org using the Services/Nexus documentation. It is important that such projects should not depend on Eclipse Platform features, such as extension registry or plug-in activator support. If required, such features can be added optionally; but code should work without them.
Javadoc is also generated from the core VIATRA projects using the Tycho Javadoc generator. The generated documentation is configured in the org.eclipse.viatra.docs project.