How to debug KOS Java Code using IntelliJ or Eclipse

Introduction

This article shows how to set up your IDE so that you can debug (run, hit breakpoints, single step, examine variables) your KOS backend Java code.

While these specific instructions are for IntelliJ and Eclipse, you can follow these same general steps if you use another IDE.

Overview

KOS gives you the ability to debug your Java code. It works whether the target system is a simulator or actual hardware.

The primary component, the “KOS Debug JRE”, sits between your IDE, your running KOS Studio, and the target system.

The following diagram illustrates the interactions that occur during the debug process:

The rest of this article explains how you set up and use the KOS Debug JRE.

The JRE can be found at these locations depending on operating system

MacOS   : ~/Applications/kosStudio.app/Contents/MacOS/tools/kos-debug-jre
Windows : $INSTALL_DIR/kosStudio/release/tools/kos-debug-jre



Studio & image setup

Ensure KOS Studio is open and the image you would like to run is visible, configured and ready to go (no errors). For instance in the image below the image is configured to run on a raspberry pi.

1. Create the quick build script

First off, we’re going to create a “quick build” script file that is executed before every invocation of the debug operation. Its job is to build your application code as fast as possible. You’ll need either a batch file (for Windows) or a shell script (for Mac/Linux) with the desired build command(s). The following scripts work for our case.

Create the desired quick build file in your project’s home directory:

quickbuild.bat file for Windows

mvn install --no-snapshot-updates -DskipTests -T4Copy

quickbuild.sh file for Mac and Linux

#!/bin/bash
set -e -o pipefail -u
mvn install --no-snapshot-updates -DskipTests -T4

The goal is to build the code as fast as possible. The components of this command are:

  • mvn: the Maven program
  • install: builds the code (not using the clean parameter ensures that only the changed code is rebuilt)
  • –no-snapshot-updates: do not attempt to fetch any KOS snapshot versions
  • -DskipTests: do not run unit tests
  • -T4: run the build using up to CPU four processors

Be sure to make the quickbuild.sh file executable chmod +x quickbuild.sh.

Configuring IntelliJ

1. Main method

To run the debugger in IntelliJ you need to have a main method, you can have a Main class with the main method or just add the main method to another class.

public static void main(String[] args) {
}

2. Debug configurations

click on the current file button on the upper right of the screen and edit configuration.

This should open the following modal

3. Create debug configuration

click create add new, to add a new run configuration. create it of type application.

Now you should be presented with this configurations screen, where you need to select a main class and some other things.

4. Specify program arguments

We need to add in the program arguments to specify the image and the the build script to be run to update our changes. The arguments are as follows –image=”<your image name>” –buildScript=”<full path to your build script>”

Lastly you have to set the JRE to run, which can be found at

MacOS   : ~/Applications/kosStudio.app/Contents/MacOS/tools/kos-debug-jre
Windows : $INSTALL_DIR/kosStudio/release/tools/kos-debug-jre

to set this click on the sdk option and click “select alternative JRE..” and select the kos-debug-jre a file browser window should’ve been opened. By default Mac won’t let you navigate directly to directories within an app but you can circumvent that by using the cmd+shift+g shortcut.

Mac JRE Picker
cmd+shift+g view
kos-debug-jre

Now that the configuration is completed you can run that configuration setting breakpoints and stepping through your java code.

Configuring Eclipse

Follow these steps when using the Eclipse IDE. The instructions are basically the same for Linux, Mac, and Windows.

1. Debug Configurations

In the top menu, open “Run” -> “Debug Configurations” dialog. Then, select “Java Application” -> “JRE”

2. Alternate JRE

Select “Alternate JRE” and then click the “Installed JREs…​” button.

3. Preferences

In the “Preferences” dialog, click the “Add…​” button.

4. Add JRE

In the “Add JRE” dialog, select “Standard VM” and click “Next”.

5. Pick JRE

Click “Directory” and then navigate to and select the KOS JRE directory.

Location of JRE files

The KOS JRE files are stored at different locations, depending on the operating system.

MacOS   : $USER_HOME/Applications/kosStudio.app/Contents/MacOS/tools/kos-debug-jre
Windows : $INSTALL_DIR/kosStudio/release/tools/kos-debug-jre

Here’s the Mac JRE picker:

6. JRE Added

Click “Finish” and ensure that the primary JRE is still the “default”.

7. Select KOS JRE

Click “Apply and Close” and ensure that the “kos-debug-jre” is selected as the alternate JRE.

8. Set program arguments

We need to add in the program arguments to specify the image and the the build script to be run to update our changes. The arguments are as follows –image=”<your image name>” –buildScript=”<full path to your build script>”

You can now click “Close” to save this configuration. Click “Debug” when ready to run the application.