Skip to content

Latest commit

 

History

History

dsl-core

README.md

MDSL Xtext Project

MDSL is a Domain-specific Language (DSL) based on Xtext. This folder contains our Xtext project.

Install Latest Version (Eclipse Plugin)

The latest version of the Eclipse plugin can be installed via the following update site URL:

https://microservice-api-patterns.github.io/MDSL-Specification/updates/

Use Latest Version Standalone

Note: We don't publish the standalone MDSL library into a public Maven repository yet. You can however already test it by building the library locally:

./gradlew clean publishToMavenLocal

You can the use MDSL standalone by including it in your project as follows:

Gradle:

implementation 'io.mdsl:mdsl-core:{latestMDSLVersion}'

Maven:

<dependency>
  <groupId>io.mdsl</groupId>
  <artifactId>mdsl-core</artifactId>
  <version>{latestMDSLVersion}</version>
</dependency>

Build Locally

This project contains two builds:

  • Maven (builds Eclipse plugins)
  • Gradle (builds standalone and CLI JAR's)

The Maven build has been generated by the Xtext framework and creates Eclipse plugins only (via Tycho). For creating standalone JAR's (Maven artifacts) and the CLI (fat JAR) we created our own Gradle build.

Build Eclipse Plugin

You need Maven installed on your machine to build the Eclipse plugin. Build the project with the following command: (must be executed in this directory)

mvn clean verify

Build Standalone Library

You don't have to install Gradle locally, since this project uses the Gradle wrapper. Just run the following command to build the standalone artifacts (no leading ./ required on Windows):

./gradlew clean build # sometimes ./gradlew build is sufficient

If you want to install the library in your local Maven repository, use the following command:

./gradlew clean publishToMavenLocal

IDE Setup

If you want to work on our Xtext project you can import the project into Eclipse (you have to use Eclipse for Xtext) as a Maven project. Ensure that your local (cloned) state builds with mvn clean verify before you import the project to Eclipse.

Hint: Ensure you have the Xtext framework installed in your Eclipse. We recommend to use the Eclipse IDE for Java and DSL Developers.

Tycho Configurator

Before you import the project, ensure that the Tycho configurator is installed. You can install it in your Eclipse with the following procedure:

  1. Open the maven preferences page: Window -> Preferences -> Maven
  2. Under Discovery press the button Open Catalog and search for Tycho. You should find the Tycho Configurator there.
  3. Select the Configurator and press Finish.
  4. An eclipse installation wizard will appear. Go through the wizard to finish the installation and restart Eclipse.

Import the Project

Import the project into your Eclipse IDE as follows:

  1. In the menu open File -> Import ...
  2. Search for maven and start the Existing Maven Projects wizard.
  3. Browse to the dsl-core directory of this repository and select it.
  4. Press Select All to import all projects.
  5. Press Finish to import the project.

Cleaning Build Errors in Eclipse

Once you imported the project into Eclipse it is likely that you will have build errors. To build the project in Eclipse without errors, follow these steps:

  1. Load and set the target platform:
    1. Open the file io.mdsl.target/io.mdsl.target.target
    2. Wait until Eclipse resolved all the dependencies
    3. Click Set as Active Target Platform (or Reload Target Platform in case you already set it once)
  2. Run the MWE2 workflow:
    1. Find the following file in the project explorer: io.mdsl/src/io/mdsl/GenerateAPIDescription.mwe2
    2. Right-click on the file and press Run As -> MWE2 Workflow
  3. Build all project:
    1. In the main menu click: Project -> Clean...
    2. Select Clean all projects
    3. Press Clean

Build Eclipse Update Site Locally

The Maven build of the project creates an Update Site as ZIP file. You can use the ZIP file to install the MDSL plugin in any Eclipse IDE.

  1. Run mvn clean verify in the dsl-core directory of this repository.
  2. Find the ZIP file here: dsl-core/io.mdsl.repository/target/io.mdsl.repository-x.y.z-SNAPSHOT.zip
  3. Use the ZIP file to install the MDSL plugin in Eclipse:
    1. Help -> Install New Software...
    2. Press Add... and then Archive...
    3. Select the ZIP file builded above.
    4. Press Add.
    5. Press Select All and then Next >.
    6. Finish the installation wizard and restart Eclipse.

Upgrading Snapshot Version

To update all the POM and MANIFEST files to a new snapshot version, use the following two commands:

  1. mvn versions:set -DgenerateBackupPoms=false -DnewVersion=x.y.z-SNAPSHOT (replace x.y.z with the preferred version)
  2. mvn org.eclipse.tycho:tycho-versions-plugin:1.2.0:update-eclipse-metadata (do not replace 1.2.0, which is the version of the Tycho plugin; note: in 2024, the tycho plugin version is 1.7.0!)

Having the two commands executed, you can commit the changed pom.xml's, MANIFEST.MF's and feature.xml files. You may want to build again from scratch too (see above).

Context Mapper

Context Mapper can generate MDSL from bounded contexts and their aggregates. So you might want to install it too.

This Context Mapper documentation page provides further information and instructions.