build: add support for Visual Studio Code

[mattdibi]

This PR adds support for Visual Studio Code as development environment for the Kura codebase... again.

Q: What's different this time?

Thanks for asking!

As you might remember we tried integrating VSCode as our development environment in #4573 but ultimately gave up since it required us either to track the .classpath/.project files created by Eclipse IDE or open the project with Eclipse IDE first. As already discussed (#5198 #5521) Eclipse IDE is quite hard to setup and not the most loved tool in our toolbox.

After a brief discussion with @testforstephen (thank you again!) in testforstephen/vscode-pde#56 I realised we didn't need Eclipse IDE to generate these files. They are simple enough to be automatically generated. Cue Kura metadata generator, the script responsible for generating these files (and a little more).

Q: What does this kura-gen tool do?

• creates the required javaConfig.json file
• updates the kura-equinox_3.16.0.target with the correct variables
• most importantly: it adds all the required .classpath/.project files for all of this to work (they won't show in the diff since on other branches these files are not tracked)

Q: What's the big deal?

1. Since we don't need Eclipse IDE to generate our files anymore we can easily create a Codespace to allow anybody to contribute to Kura with a simple click.
2. I designed the kura-gen tool so that it can be ran for Kura plugins too. I tested it for the ITxPT bundle and everything works great. We should be able to convert all our plugins to VSCode development in this way (more testing required obviously)

Q: What's next?

• Testing. More testing with more setups/platforms and plugins.
• If we greenlight the kura-gen tool we need to decide where to host it. I think that having it under the kura-eclipse organization might be a good idea since it should work for all Kura/ESF plugins
• Documentation. We need to decide where to put the instruction for this setup (main README file? on the Kura wiki?)

Testing

I tested the setup on the following platforms:

• ✅ MacOS x86 with Java 8
• ❌ MacOS ARM64 with Java 17
• ✅ Ubuntu 24.04 x86 with Java 17

I encountered some issue on ARM but they don't seem to be related to the kura-gen tool. Some further investigation is required. I'd like to ask anyone interested in running this setup as described in the instruction below. It should work on Windows too but I didn't test it.

What's working on VSCode?

• ✅ Diagnostics
• ✅ Auto completion
• ✅ Unit tests
• ✅ Remote debugging (for a nice UX I suggest using something like this)
• ✅ Unit test debugging

What's not working?

• ❌ Integration tests
• ❌ Manifest editor
• ❌ Component definition editor

Requirements

VSCode extensions:

• Eclipse PDE support for VS Code
• Language Support for Java by Red Hat
• Debugger for Java
• Java Test Runner

Kura metadata generator: https://github.com/mattdibi/metadata-generator

Installation:

pip3 install https://github.com/mattdibi/metadata-generator/releases/download/0.1.0/metadata_generator-0.1.0-py3-none-any.whl

Note: the code is quite messy ATM but, before investing more time into it, I wanted to see if the approach can work.

---

Instructions

1. Clone the Kura repository in a new folder (Eclipse IDE gets angry if it shares the sources with VSCode)

git clone git@github.com:eclipse/kura.git vscode-kura && cd vscode-kura

⚠️ The remainder of the commands in these instructions need to be run from the vscode-kura folder

2. Build the code following the README or with:

mvn -f target-platform/pom.xml clean install -B

mvn -f kura/pom.xml clean install -Dmaven.test.skip=true

3. Run the Kura metadata generator tool

Change the current working directory to the kura folder

cd kura/

and then run the tool with the following command

kura-gen --patch-target-platform

4. Open VSCode in the kura directory

code .

5. Follow the on-screen instructions

• install recommended extensions
• load the project
• ... and you're done!

Troubleshooting

LSP Out of memory error:

Looks like the JVM running the LSP server requires some additional RAM to parse through Kura. Add a .vscode/settings.json file in the root workspace directory containing the following:

{
    "java.jdt.ls.vmargs": "-XX:+UseParallelGC -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90 -Dsun.zip.disableMemoryMapping=true -Xmx8G -Xms500m -Xlog:disable"
}

VSCode build gets stuck:

To fix this press: Ctrl + Shift + P (Cmd + Shift + P for Mac users) and run the "Developer: Reload Window" command. If the issue is bad enough you'll also need to clean the LSP workspace cache with "Java: Clean Java Language Server Workspace" and re-run the maven build.

Maven build fails when VSCode is open in the same folder

It looks like the VSCode LSP is interfering(?) with the Maven build when they're running on the same repo. I suggest to close VSCode when running the whole Kura build. If you build a single bundle (which is usually the use-case) it should be fine.

---

Also @sfiorani feel free to provide feedback on this!

[GregoryIvo]

My boss is on vacation so I'm 100% going to test this 🤫🤫🤫