KOS Developer's Portal

How To Debug Code

Introduction

In this tutorial we learn how to debug your KOS Java application code using your IDE (IntelliJ or Eclipse).

Preliminaries

You should have completed the REST Controller tutorial and have it ready to use.

Setup

Follow these steps to debug your app.

Open Studio and IDE

Open Studio and sign in to your account
Open your IDE application
Inside your IDE, open your KOS project that you’d like to debug

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 -T4

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.

Create a debug configuration in IDE

Next, we need to create a dummy main() method in our MyKosApp class. As you’ll see, this is used as a fake entry point into our code, which then satisfies complaints from the IDEs.

Dummy main method

public class MyKosAp extends SystemApplication<BaseAppConfig> {

    // . . .

    /**
     * Used as a fake entry point required when debugging.
     */
    public static void main(String[] args) { (1)
    }
}

1	Add this empty `main` method to your `MyKosApp` class.

The rest of the instructions vary slightly based on the IDE you’re using.

IntelliJ

Configure IntelliJ as shown in the following image:

Figure 1. IntelliJ run/debug configuration

Open the Run/Debug Configurations dialog.
Create a new Application.
Give it a name, for example "Remote Debug".
Select the kos-debug-jre as explained on the Java Debugging Details page.
For the main class field, enter "com.example.MyKosApp", which is where our dummy main method is.
Enter two program arguments:
- --image="{EXACT-NAME-OF-YOUR-IMAGE}"
  (the name you gave your Studio image; In our case, it’s "My KOS App")
- --buildScript="{FULL-PATH-TO-YOUR-QUICKBUILD-SCRIPT}"
  (points to the quick build script file we created in the previously)
Working directory can be whatever.

You can omit the double-quotes if there are no spaces in the parameter’s value.

Eclipse

Please use the IntelliJ instructions as a guide.

Debug Application

Follow these steps to debug your application.

Ensure that KOS Studio is running and you are logged in.
In your IDE, open the MyKosApp Java file and put a breakpoint on the first line of the load() method.
Run the "Remote Debug" application created above in debug mode.
(executing in "run" [non-debug] mode causes an immediate error)

After loading all required libraries, Studio executes your application. Your IDE should stop at the breakpoint. At this time, you can single-step through the code, view variable values, etc.

When you want to modify your code and try again, simply repeat this process.

Troubleshooting

Ensure Studio is running and that you are signed in.
Ensure your application’s image is configured correctly, especially that it references the KAB file of your project in the Local Artifacts and Sections cards.
Ensure that you’re using the same KOS version in both the Studio KOS Release card and your app’s POM file.

Summary

In this tutorial, we learned how to debug our backend Java code. You can use this technique throughout the KOS development process.

The source code for these Hello World tutorials is available on GitHub.

Next up, we’ll take a look at KOS built-in endpoints.