adding.md

Adding RagConnect to your project

If you want to use RagConnect, either use the latest pre-build version or clone the repository and build it yourself.

Use packaged version

Check the package overview page to find the latest version.

To use it, three steps are needed. First add this GitLab as a repository in your build.gradle:

repositories {
    maven {
        name "gitlab-maven"
        url "https://git-st.inf.tu-dresden.de/api/v4/groups/jastadd/-/packages/maven"
    }
}

Next, add RagConnect as a dependency:

configurations {
    ragconnectClasspath
}

dependencies {
    ragconnectClasspath group: 'de.tudresden.inf.st', name: 'ragconnect', version: '0.2.3'
}

Finally, add a task to compile your specification:

task ragConnect(type: JavaExec) {
    group = 'Build'
    main = 'org.jastadd.ragconnect.compiler.Compiler'
    classpath = configurations.ragconnectClasspath

    args([
            '--verbose',
            '--o=src/gen/jastadd',
            'src/main/jastadd/GoalModel.relast',
            'src/main/jastadd/GoalModel.connect',
            '--rootNode=GoalModel'
    ])
}

You might need to add another task for compiling relast specifications.

Build from source

If you want to use RagConnect, the currently suggested way is to first build the jar from the RagConnect repository:

git clone https://git-st.inf.tu-dresden.de/jastadd/ragconnect.git
cd ragconnect
./gradlew jar
ls ragconnect.base/build/libs/

This ragconnect-<version>.jar can then be copied to your project. Please note, that you can safely use ragconnect.jar as filename, because the version can always be printed using java -jar path/to/ragconnect.jar --version.

cp ragconnect.base/build/libs/ragconnect-<version>.jar ../your-project/libs/ragconnect.jar
cd ../your-project/

Finally, this jar has to be integrated into your build process. In case, Gradle is used, a task could look like the following (example taken from the ros2rag usecase). The path to the jar file may need to be changed according to your project structure.

task ragConnect(type: JavaExec) {
    group = 'Build'
    main = '-jar'

    args([
            '../libs/ragconnect.jar',
            '--verbose',
            '--o=src/gen/jastadd',
            'src/main/jastadd/GoalModel.relast',
            'src/main/jastadd/GoalModel.connect',
            '--rootNode=GoalModel'
    ])
}

You might need to add another task for compiling relast specifications.

Compiling RelAst specifications

The task to compile RagConnect specifications is typically accompanied with a task to invoke the RelAst compiler and the JastAdd gradle plugin. The additional arguments --useJastAddNames, --listClass, --jastAddList and --resolverHelper to relast are not required. Please see the user manual of the RelAst compiler for more information.

task relastToJastAdd(type: JavaExec) {
    group = 'Build'
    main = "-jar"

    args(["../libs/relast.jar",
            "--grammarName=./src/gen/jastadd/model",
            "--useJastAddNames",
            "--listClass=java.util.ArrayList",
            "--jastAddList=JastAddList",
            "--resolverHelper",
            "--file",
            "src/gen/jastadd/GoalModel.relast",
            "src/gen/jastadd/RagConnect.relast"])
}

jastadd {
...
}

One also has to specify the dependencies to get correct ordering of tasks.

generateAst.dependsOn relastToJastAdd
relastToJastAdd.dependsOn ragConnect

Introduced dependencies

RagConnect itself does not introduce dependencies. However, depending on the selected protocols (see compiler options), additional dependencies are required.

Protocol	Dependency (Gradle format)	Remarks
mqtt	group: 'org.fusesource.mqtt-client', name: 'mqtt-client', version: '1.15'	Mqtt is selected by default, so this dependency therefore is required "by default". Might work with other versions as well.
rest	group: 'com.sparkjava', name: 'spark-core', version: '2.9.2'	Might work with other versions as well. For debugging, it is beneficial to include an implementation for SLF4J.