Getting Started

Getting Started as a User

Table of Contents

• Getting Started as a Developer
  • Building the Java projects (with Eclipse & Gradle)
  • Generating a fat jar from a project
  • Deployment
    • Prerequisites
    • Deployment steps
• Troubleshooting
• Acknowledgement

Should you develop your own application and use 'MoDeS3 as a Service'.

1. Install Java 8 SDK.

2. Download the corresponding jar on the releases page.

3. Read the Wiki pages, especially Network messages, On the communication component of the API.

Getting Started as a Developer

Should you be a core developer of the MoDeS3 repository and extend its core functionality.

root java folder = src/java from the highest folder hierarchy

💡	Should you have any problems during compiling the repository, visit the Troubleshooting section of this document.

Prerequisites:

1. Install Java 8 SDK.

2. Install Gradle (4.2.1) and have gradle.exe (Windows) or gradle (Linux / Unix) on your OS path.

3. Clone the BME-MODES3 repository on your machine.

Building the Java projects (with Eclipse & Gradle)

1. Obtain an Eclipse with Gradle, Xtend, Xtext, Viatra and E(fx)clipse installed.

   • The version numbers of the currently used gradle plugins can be found here.

2. Set the default file encoding for UTF-8. In Eclipse do the following: Window → Preferences → General → Workspace : Text file encoding

3. Run Gradle from command line in order to generate Java message definitions from protobuf. First go to the root java folder, then generate the Java classes:

cd src/java
./gradlew :messaging:hu.bme.mit.inf.modes3.messaging.proto.messages:generateProto

1. Import the Gradle projects in your IDE and try to build the projects there. Note: Should you not need a project, please put a comment mark # in front of the line for the corresponding project, in the root java folder’s `build.gradle file. Please do not commit these changes though.

Generating a fat jar from a project

A fat jar is a jar which contains the compiled project along with every dependency the project has.

• If you would like to create a fat jar from a certain component, add apply plugin: 'com.github.johnrengelman.shadow' to the respective components’s build.gradle file.

  • Then go to the root java folder and run the respective project’s shadowJar task.

  • The result fat jar will be created in the respective project’s build/libs folder and its default name will be the <project’s name>-all.jar.

• As an example, let’s see how to generate the fatJar of hu.bme.mit.inf.modes3.messaging.communication project:

cd src/java
./gradlew messaging:hu.bme.mit.inf.modes3.messaging.communication:shadowJar

• The fat jar will be in the src/java/messaging/hu.bme.mit.inf.modes3.messaging.communication/build/libs folder and its name will be hu.bme.mit.inf.modes3.messaging.communication-all.jar

• For more info on the shadow gradle plugin, check its repository.

Deployment

Prerequisites

• Install Ansible on your machine.

Deployment steps

1. If you would like to create deployable zips for each component, then go to the root java folder and assemble the repository with gradle:

cd src/java
./gradlew assemble

1. The generated zip and tar files will be in each project’s build/distributions/ folder, if the respective project is an application (see apply plugin: 'application' line in build.gradle in the project’s folder). If it is not an application, then the build/libs/ folder will contain a jar compiled from the project sources.

2. The generated archives should be extracted, then the component can be run by the executable file in the extracted bin folder. Please note that on Windows you should use the executable which ends with .exe, on Linux or Unix machines use the one without the exe. Also note that the command-line parameters should be the same as if it was a jar. So that the parameters the runnable expects should be fulfilled.

   • e.g. if we’re in the extracted hu.bme.mit.inf.modes3.components.occupancyquery folder and its executable expects -address root.modes3.intra -port 1883 -serial /dev/ttyUSB0 parameters, then the bin/hu.bme.mit.inf.modes3.components.occupancyquery file should be run as follows:

bin/hu.bme.mit.inf.modes3.components.occupancyquery -address root.modes3.intra -port 1883 -serial /dev/ttyUSB0

1. As an alternative method to the previous section, one could use the ansible scripts which are implemented in the config-management/ansible folder. Note that there are helper shell scripts for Linux/Unix deployment in the config-management folder.

Troubleshooting

• Projects using Xtend often need cleaning to remove obsolete error markers.

• A project which depends on VIATRA may have an error saying "Error executing EValidator". This has no effect basically, simply get rid of the error by deleting the markers.

• Should you use Eclipse with the Gradle plugin AND change something in any of the *.gradle files (either in the root /src/java folder or in your project’s folder), do not forget to click on the project name with the right mouse button, and in the dropdown menu go to Gradle → Plugin refresh. Otherwise, the plugin might not recognize the changes and will end up in an incorrect configuration.

• Should you use VIATRA in Eclipse in any project, do not forget to set the folder into which VIATRA generates the Java classes. To do so go to Window → Preferences → VIATRA → Query Language → Compiler and set the Output Folder / Directory for ./src/main/vql-gen. After that, set that folder as a source folder of the project and exclude it from the .gitignore file in the project folder: write !/src/main/vql-gen/* in the .gitignore file. However, this last step might be unnecessary if there is a VIATRA compiler available as a gradle plugin. (As of writing these lines, it is done available yet.)

• Should you have Error executing EValidator in Viatra project problems with building hu.bme.mit.inf.modes3.components.safetylogic.systemlevel.patterns in Eclipse, check if the Plug-in project, VIATRA natures are added to the project: right click on project name → Configure → Convert to Plug-in Project (or Convert to VIATRA project)

• Should you have build problems in Eclipse with Xtend, check if there is a build/xtend/main and build/xtend/test folders in the project. If so, remove the folders. In addition to that, remove the ` <classpathentry kind="src" path="build/xtend/main"/> <classpathentry kind="src" path="build/xtend/test"/>` lines from the .classpath file in the corresponding project.

• Never combine Xtend and pure Java files in the same source folder, because the Xtend / Xtext Compiler’s Gradle plugin will get crazy and either end up in a stack overflow exception or show error markers at references for java classes in xtend files.

• Should some change notifications from the file system not arrive to Eclipse, don’t forget to use the 'good old' right click on the project name → Refresh project option. Restarting Eclipse might also solve problems sometimes.

• It is also helps with already resolved errors and they are still in the Problems View, to do a Project / Clean ` and `Project / Build All in Eclipse.

• Should you configure Eclipse for using Java JDK library instead of JRE. For doing this, open the corresponding project’s properties and in the Java Build Path / Libraries tab add or edit the default System Library’s Execution environment for JavaSE-1.8 (jdk1.8).

Acknowledgement

👍	This page could not have been created without ecsedigergo