# Adding `RagConnect` to your project

If you want to use `RagConnect`, either use the latest [pre-build version](#use-packaged-version) or clone the repository and [build it yourself](#build-from-source).

## Use packaged version

Check the [package overview page](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/packages) 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](#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](https://git-st.inf.tu-dresden.de/jastadd/ragconnect):

```bash
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`.

```bash
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](https://gradle.org/) is used, a task could look like the following (example taken from the [ros2rag usecase](https://git-st.inf.tu-dresden.de/jastadd/ros2rag)). The path to the jar file may need to be changed according to your project structure.

```groovy
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).

## Compiling RelAst specifications

The task to compile `RagConnect` specifications is typically accompanied with a task to invoke the [RelAst compiler](http://relational-rags.eu/) and the [JastAdd gradle plugin](https://plugins.gradle.org/plugin/org.jastadd). 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.

```groovy
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.

```groovy
generateAst.dependsOn relastToJastAdd
relastToJastAdd.dependsOn ragConnect
```

## Introduced dependencies

RagConnect itself does not introduce dependencies.
However, depending on the selected protocols (see [compiler options](using#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](http://www.slf4j.org/). |