Forem: Romain Bruyère

Building an IntelliJ Plugin with Debugger Integration

Romain Bruyère — Sun, 22 Sep 2024 16:24:52 +0000

Building an IntelliJ plugin for debugging purpose can offer valuable insights into the data being handled, allowing you present it more effectively and upgrade the developer experience. However, the limited documentation around IntelliJ’s APIs often makes plugin development challenging. In this guide, we’ll walk through the steps to create a plugin that can execute methods on objects available in the stack when the debugger is paused.

1. Plugin creation

First, you will have to create an empty plugin. The easiest way to do it is directly inside IntelliJ:

Open the New Project wizard by selecting File | New | Project… and fill in the required details:
From the menu on the left, choose the IDE Plugin project type.

Sources:
https://plugins.jetbrains.com/docs/intellij/creating-plugin-project.html

2. Create an action

The goal of this demo plugin will be to give to the user the power to execute a predefined method on a variable when the debugger is paused.

Adding a new button in IntelliJ UI is the first step in designing the plugin behavior. It will create an entrypoint for the user to execute the plugin code.

The system designed for that in IntelliJ APIs is called an Action.

package be.bruyere.romain.tutointellijplugindebug

import com.intellij.openapi.actionSystem.ActionUpdateThread
import com.intellij.openapi.actionSystem.AnAction
import com.intellij.openapi.actionSystem.AnActionEvent
import com.intellij.openapi.project.DumbAware

class CustomAction : AnAction(), DumbAware {

    override fun actionPerformed(event: AnActionEvent) {
        // TODO add action code
    }

    override fun update(event: AnActionEvent) {
        event.presentation.isEnabledAndVisible = true
    }

    override fun getActionUpdateThread(): ActionUpdateThread {
        return ActionUpdateThread.BGT
    }
}

With a custom action like this one, you can:

Provide some code to be executed by the plugin, with actionPerformed method
Add logic if you want the action to be shown conditionnaly, with update method
Specify which thread will execute the update method

For the plugin button to be shown to the user, you will have to define its anchor in plugin.xml file, located in the /resources/META-INF folder.

<actions>
    <action id="be.bruyere.romain.tutointellijplugindebug.CustomAction"
            class="be.bruyere.romain.tutointellijplugindebug.CustomAction" text="My custom action" description="My custom action">
        <add-to-group group-id="XDebugger.ValueGroup" anchor="first"/>
    </action>
</actions>

Here, the plugin button is placed as the first action in the right-click debugger menu. By running the Grable task intellij.runPlugin, you can now try to use it.

Sources:
https://plugins.jetbrains.com/docs/intellij/basic-action-system.html

3. Add a method invocation in debug mode

To execute, on the fly, a method on an object when the debugger is paused, multiple steps are required:

Get the object reference
Get the thread in which the method will be invoked
Get the method reference
Execute the method and get its return value

Prerequisites

Before these steps, you need to enable the debugger features in your plugin. To do this, you’ll need to add a dependency on the java plugin in the build.gradle.kts file.

intellij {
  version.set("2024.1")
  type.set("IC")

  plugins.set(listOf("java")) // To add
}

3.1 Get the object reference

Jetbrains APIs provide a simple way to get the selected node from the right-click event context menu. The object reference value can then be accessed from there.

private fun getObjectReference(event: AnActionEvent): ObjectReferenceImpl? {
    val node = XDebuggerTreeActionBase.getSelectedNode(event.dataContext)
    val valueContainer = node?.valueContainer
    val value = valueContainer as? JavaValue
    return value?.descriptor?.value as ObjectReferenceImpl?
}

3.2 Get the thread in which the method will be invoked

When the debugger is paused, invoking a method on the fly must be done in a specific thread, called the manager thread. The manager thread manages tasks and operations related to the debugger, ensuring that certain operations are run on the correct thread during debugging sessions

private fun getManagerThread(event: AnActionEvent): DebuggerManagerThreadImpl? {
    val node = XDebuggerTreeActionBase.getSelectedNode(event.dataContext)
    val valueContainer = node?.valueContainer
    val value = valueContainer as? JavaValue
    return value?.evaluationContext?.managerThread
}

As for the object reference, the manager thread can be accessed from the selected node.

3.3 Get the method reference

With the object reference, any method can be accessed by its name.

// Example: getMethod(myObjectReference, "toString")
private fun getMethod(targetObjectRef: ObjectReferenceImpl, methodName: String): Method? =
        targetObjectRef.referenceType().methodsByName(methodName)[0]

3.4 Execute the method and get its return value

Using the method and its associated object reference, you can construct a command that encapsulates the method call. You can then execute this command on the manager thread, wait for the response and return the result.

private fun executeMethod(
    event: AnActionEvent,
    targetObjectRef: ObjectReferenceImpl,
    managerThread: DebuggerManagerThreadImpl,
    method: Method?
): Value? {
    val session = DebuggerManagerEx.getInstanceEx(event.project).context.debuggerSession
    val context = session?.process?.suspendManager?.pausedContext
    val command = CustomDebuggerCommandImpl(context, targetObjectRef, method)
    managerThread.invokeAndWait(command)
    return command.result
}

The command CustomDebuggerCommandImpl is not built in Jetbrains APIs. It’s a concrete implementation of the abstract class DebuggerCommandImpl, representing a specific command that executes within the context of IntelliJ’s debugging system. You’ll have to add that class by yourself in the your plugin.

class CustomDebuggerCommandImpl(
    private val context: SuspendContextImpl?,
    private val objectReference: ObjectReferenceImpl,
    private val method: Method?
) : DebuggerCommandImpl() {
    var result: Value? = null
        private set

    override fun action() {
        val threadReference = context?.frameProxy?.threadProxy()?.threadReference
        result = objectReference.invokeMethod(
            threadReference,
            method,
            listOf(),
            ObjectReferenceImpl.INVOKE_SINGLE_THREADED
        )
    }
}

Sources:
https://docs.oracle.com/en/java/javase/13/docs/api/jdk.jdi/module-summary.html
https://github.com/JetBrains/intellij-community/tree/master

4. Use of the result

The result obtained from the method invocation is not a basic object type like String, Integer, or any other standard object. Instead, it is a reference to an object created within the debugging context.

For example, if the invoked method was toString, you would receive a StringReferenceImpl. You can then retrieve the string value from that object.

val result = executeMethod(event, objectReference, managerThread, method)
val stringValue = result as? StringReferenceImpl

if(stringValue != null) {
  println(stringValue.value())
}

There are various other implementations of type references, such as IntegerValueImpl or, more generally, ObjectReferenceImpl for custom classes.

Sources:
https://github.com/JetBrains/intellij-deps-jdi/tree/master/src/main/java/com/jetbrains/jdi

5. Full code example

Now that you understand the details of this IntelliJ plugin development process, here is a complete working example of the code: https://github.com/rombru/tuto-intellij-plugin-debug

If you'd like to see how this process was applied to create a published plugin, check out this plugin I developed for visualizing geometries on a map in debug mode:
https://plugins.jetbrains.com/plugin/25275-geometry-viewer
https://github.com/rombru/geometry-viewer

Docker and WSL2 without Docker Desktop

Romain Bruyère — Thu, 09 May 2024 20:45:13 +0000

Using Docker on Windows has grown more challenging over the past few years. This guide aims to walk you through the process, from start to finish, to help you make the most of Docker on Windows without having to install Docker Desktop.

To use Docker without Docker Desktop, you’ll need to:

Install WSL2, to serve as a runtime environment for Docker Engine
Install Docker Engine inside WSL2, to be able to run containers
Expose Docker Engine to be able to access it from Windows
Install Docker command-line tools on Windows

Install WSL2

WSL2, or the Windows Subsystem for Linux, allows you to run a Linux distribution on Windows. To install it with the default Ubuntu distribution, open a terminal in administrator mode and use the following command:

wsl --install

If you want to install a different Linux distribution instead of the default Ubuntu, you can list the available distributions and then install your preferred one using the following command:

wsl --list --online
wsl --install -d <DistroName>

It’s not mandatory, but depending on your setup, you might find it helpful to limit the resources allocated to WSL2. To do this, create a file named .wslconfig in your user folder. You can quickly access your user folder by typing %UserProfile% in the File Explorer's search bar.

Here’s an example of what a .wslconfig file might look like:

[wsl2]
memory=4GB 
processors=2

After installing WSL2, you can start it by typing wsl in a terminal, or by launching the WSL program from your Windows Start menu. Once WSL2 is open, update your Linux distribution to ensure all packages are up to date with the following command:

sudo apt update && sudo apt upgrade

To learn more about configuring WSL2 distributions and resource allocation, refer to the following sources.

Sources:
https://learn.microsoft.com/en-us/windows/wsl/install
https://learn.microsoft.com/en-us/windows/wsl/wsl-config

Install Docker Engine on WSL2

Next, let’s install the Docker Engine, which is the core component that runs Docker containers. The following two blocks of commands will first add the Docker apt repository and then install Docker. You can execute them directly in the WSL2 terminal.

sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Now that Docker is installed, let’s confirm that it’s working correctly. The following command will download and run the hello-world container. If the installation was successful, it should display a confirmation message and then exit.

sudo docker run hello-world

By default, you need to use sudo with Docker commands for elevated permissions. To run Docker without sudo, you can create a group docker for Docker users and add your current user to that group.

sudo groupadd docker
sudo usermod -aG docker $USER

On some distributions, the Docker group is created by default. You only need to add your user to this group to have the permission to run Docker without sudo. The Docker group is automatically managed by the Docker Engine, ensuring that only users in this group have permission to run Docker commands. After adding yourself to the Docker group, exit WSL2, then restart it, or simply log out and back in. Once you re-open WSL2, you should be able to use Docker without the need for sudo.

docker run hello-world

If you’re using a non-default WSL distribution, like a custom Linux distro, Docker might not start automatically when you launch WSL. To ensure Docker starts every time you open WSL, use the following commands:

sudo systemctl enable docker.service
sudo systemctl enable containerd.service

Sources:
https://docs.docker.com/engine/install/ubuntu/
https://docs.docker.com/engine/install/linux-postinstall/

Expose Docker Engine on Windows

To access the Docker Engine from Windows, you’ll need to configure remote access for Docker. There are two ways to do this, by modifying the docker daemon, or by overriding systemd launch configuration.

With daemon.json

For that method, you need to create or edit the /etc/docker/daemon.json file inside WSL2. Navigate to the /etc/docker directory and use the following command to edit the file:

vi daemon.json

# In vi,
# You press the key 'I' to enter in insert mode and be able to edit the file
# You press the key 'ESC', once you have finished inserting
# You press the keys ':wq' to save and quit editing

Then add this content to the file:

{
  "hosts": ["unix:///var/run/docker.sock", "tcp://0.0.0.0:2375"]
}

With systemd

With that method, to override the systemd launch configuration for the Docker service, you can create or edit a systemd override file by using the following command:

sudo systemctl edit docker.service

Then add, or modify, the following lines

[Service]
ExecStart=
ExecStart=/usr/bin/dockerd -H fd:// -H tcp://0.0.0.0:2375

Be sure to only use one of the two methods, not both. No matter the method you choose, for these changes to be applied, you will need to restart the Docker service.

sudo systemctl daemon-reload
sudo systemctl restart docker.service

To confirm that Docker is exposed on Windows, visit the URL http://localhost:2375/version. If you receive a response showing the current version of the Docker Engine, it means the exposure is successful.

Create the link between WSL2 andWindows

To ensure that the Docker agent on Windows can detect the Docker Engine installed on WSL2, you need to establish a connection between the two by adding a DOCKER_HOSTenvironment variable on Windows. It specifies the address of the Docker Engine and determines where Docker commands will be sent.

Depending on the configuration of your computer, and the activation of IPv6, you can set it to tcp://localhost:2375 or tcp://[::1]:2375.

Sources:
https://docs.docker.com/config/daemon/remote-access/
https://gist.github.com/styblope/dc55e0ad2a9848f2cc3307d4819d819f

Install Docker CLI on Windows

The final step is to install the Docker CLI on Windows. The CLI consists of several executable files that must be placed in specific locations within the Windows filesystem.

First, you must install the main executable. Create a folder for the installation wherever you’d like in the Windows filesystem, and then add that folder to your PATH. Next, visit https://download.docker.com/win/static/stable/x86_64/, download the latest version, and unzip the executables into the folder you just created.

You should now be able to run most Docker commands. To test it, try executing:

docker version

If it doesn’t work, one advice is to try with the other value for the DOCKER_HOST environment variable.

Plugins, Buildx and Compose

Simply installing the main executable usually isn’t enough if you want to use all of Docker’s features. The builder included with the executable is the legacy builder, and the docker compose command will be unavailable. To access those additional features, you'll need to install some plugins.

In your user folder, accessible by typing %UserProfile% in the File Explorer's search bar, create the folder tree .docker\cli-plugins\ if it doesn’t exists already.

To install the newest builder, download the latest version of the buildxplugin by visiting https://github.com/docker/buildx/releases. Find the most recent release, go to the “Assets” section, and expand the list of assets. Download the file that ends with windows-amd64.exe, like buildx-v0.14.0.windows-amd64.exe. Place the downloaded file in the cli-plugins folder you created earlier, and rename it to docker-buildx.exe. Now, the command docker build will automatically use the new builder.

To install docker compose tool, download the latest version of the plugin by visiting https://github.com/docker/compose/releases. Find the most recent release, go to the “Assets” section, and expand the list of assets. Download the file that ends with windows-x86_64.exe, like docker-compose-windows-w86_64.exe. Place the downloaded file in the cli-plugins folder you created earlier, and rename it to docker-compose.exe. Now, we can use the command docker compose.

The installation is finished ! 🥳
I hope everything is working fine ! Don’t forget to start WSL2 when you want to use Docker.

Sources:
https://docs.docker.com/engine/install/binaries/#install-server-and-client-binaries-on-windows
https://github.com/docker/buildx/releases
https://github.com/docker/compose/releases