• BDSL User Guide: https://nbn-resolving.org/urn:nbn:de:bsz:14-qucosa2-752170

---

Bigraph DSL Grammar (Xtext)

This project contains the following building blocks of BDSL, the Bigraphical Domain-specific Language:

• Grammar, Parser, Validation, ...
• Language Server Protocol for language support in any IDE
• Unit tests

The grammar is implemented using Xtext and Xtend.

IDE support is provided for the following platforms to be more productive when experimenting with BDSL:

• Eclipse, IntelliJ, Visual Code, ... by utilizing the Language Server Protocol

Version Compatibility

BDSL Grammar Release	Bigraph Ecore Metamodel	Gradle Compatibility	Java Compatibility
2.1.0 (planned)	2.0.1	8.5.0	21
2.0.1 (current)	2.0.1	7.6.2	17

Usage

Maven Configuration

Use the following dependency within a Maven-based project. Replace ${version} with the current version.

<!-- BDSL Grammar -->          
<dependency>
	<groupId>org.bigraphs.dsl</groupId>
    <artifactId>bdsl-grammar</artifactId>
    <version>${version}</version>
    <exclusions>
    	<exclusion>
        	<groupId>org.bigraphs.dsl</groupId>
            <artifactId>BigraphBaseModel</artifactId>
        </exclusion>
        <exclusion>
        	<groupId>org.eclipse.xtext</groupId>
        	<artifactId>xtext-dev-bom</artifactId>
        </exclusion>
    </exclusions>
</dependency>

Gradle

dependencies {
    implementation("org.bigraphs.dsl:bdsl-grammar:${version}") {
        exclude group: "org.bigraphs.dsl", module: "BigraphBaseModel"
        exclude group: "org.eclipse.xtext", module: "xtext-dev-bom"
    }
}

Getting Started with Development

Requirements

• Java >= 21
• Gradle == 8.5
• Check that the environment variable JAVA_HOME is pointing to the correct JDK
  • update-java-alternatives --list
  • export JAVA_HOME=...
  • or sudo update-alternatives --config java

Workspace Setup

First, clone this repository:

git clone --recursive https://github.com/bigraph-toolkit-suite/bigraphs.bdsl-core-elements

This project includes Ecore Bigraph Metamodel as git submodule. The main branch of the repository Ecore Bigraph Metamodel will also be pulled. This dependency includes the Ecore metamodels of bigraphs that are used by the Xtext-based BDSL grammar to represent bigraphical structures.

To update the submodule (i.e., the Bigraph Ecore Metamodel) later at any time to the latest tagged version, run the following command:

git submodule update --recursive --remote
# Force overwriting changes
git submodule update --recursive --remote --force

Building from Source

This command builds everything:

$ ./gradlew clean build -x :bigraphs.bigraph-ecore-metamodel:compileJava -x test
 
# Just the Grammar
$ ./gradlew clean :org.bigraphs.dsl:build \
  -x :bigraphs.bigraph-ecore-metamodel:compileJava \
  -x test

# Just the IDE Component
$ ./gradlew clean :org.bigraphs.dsl.ide:build -x :bigraphs.bigraph-ecore-metamodel:compileJava -x test

The builds can be found in:

• ./org.bigraphs.dsl/build/libs
• ./org.bigraphs.dsl.ide/build/libs

Generate Xtext Language Artifacts

You can just generate the code from the Xtext grammar by issuing the next command:

$ ./gradlew clean generateXtextLanguage -x :bigraphs.bigraph-ecore-metamodel:compileJava

# Specific module
$ ./gradlew clean :org.bigraphs.dsl:generateXtext -x :bigraphs.bigraph-ecore-metamodel:compileJava
$ ./gradlew clean :org.bigraphs.dsl:generateXtextLanguage -x :bigraphs.bigraph-ecore-metamodel:compileJava

Generate Language Server Protocol

$ ./gradlew shadowJar -x :bigraphs.bigraph-ecore-metamodel:compileJava

# Specific module
$ ./gradlew clean :org.bigraphs.dsl.ide:shadowJar -x :bigraphs.bigraph-ecore-metamodel:compileJava

Note: The language server protocol *.jar is located under org.bigraphs.dsl.ide/build/libs/.

Run Tests

The following commands show how to run various kinds of tests:

# Run all test cases
$ ./gradlew :org.bigraphs.dsl.tests:test -PwithTests -x :bigraphs.bigraph-ecore-metamodel:compileJava

# All tests within a package
$ ./gradlew test --tests org.bigraphs.dsl.tests.ide.validation* -PwithTests -x :bigraphs.bigraph-ecore-metamodel:compileJava

# All tests within a class
$ ./gradlew test --tests *BdslAffectionUnitTest -PwithTests -x :bigraphs.bigraph-ecore-metamodel:compileJava

# Only a specific test method
$ ./gradlew test --tests *testSignatureMatchOnAssignment_01 -PwithTests -x :bigraphs.bigraph-ecore-metamodel:compileJava

Test report is written to org.bigraphs.dsl.tests/build/reports/tests/test/index.html.

Install Grammar to Local Maven Repository

If you want to use the BDSL grammar artifact in your Java projects for testing and development purposes, you can install the compiled JARs into your local Maven repository (usually located at ~/.m2/). Then it can be conveniently used by other Java projects.

Run the following command:

# Everything
$ ./gradlew publishToMavenLocal -x :bigraphs.bigraph-ecore-metamodel:compileJava

# Specific Component
$ ./gradlew :org.bigraphs.dsl:publishToMavenLocal -x :bigraphs.bigraph-ecore-metamodel:compileJava
$ ./gradlew :org.bigraphs.dsl.ide:publishToMavenLocal -x :bigraphs.bigraph-ecore-metamodel:compileJava

FAQ

Working in Eclipse

This project is best worked with Eclipse Modeling Tools IDE. Import everything into a new Eclipse workspace:

• org.bigraphs.dsl.parent
• bigraphs.bigraph-ecore-metamodel (the cloned Git submodule according to the Project Setup instructions)

You may need to re-generate the model code of the bigraphs.bigraph-ecore-metamodel project as this process is not currently handled by the gradle script.

You may then be able to run the "MWE2 workflow" and to generate "Xtext artifacts" via the Eclipse IDE inside the org.bigraphs.dsl project, or call the appropriate gradle command as shown below in Building from Source.

Project Structure

• Xtext language infrastructure for BDSL is located under org.bigraphs.dsl
• Language Server Protocol Implementation is located under org.bigraphs.dsl.ide
• Test classes are located under ./org.bigraphs.dsl.tests/
  • Requires modules org.bigraphs.dsl and org.bigraphs.dsl.ide
• (!) Note that the required CDO/EMF/Ecore dependencies are stored separately inside the ./etc/assets folder. The reason is that there is currently no easy way on how to resolve Eclipse dependencies from P2 repositories in gradle. To clarify: Updating the versions means replacing the files. These dependencies are shadowed in the bdsl-grammar JAR

License

BDSL Grammar is Open Source software released under the Apache 2.0 license.