build: add support for Visual Studio Code

[mattdibi]

VSCode as Kura Development Environment

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

Changes:

• Added tracking for .classpath and .project files
• Added javaConfig.json in the kura directory, required by vscode-pde extension
• Added .vscode folder with workspace settings and recommended extensions
• Updated target-platform paths so that they work out-of-the box with both vscode-pde and Eclipse IDE
• Updated main README with VSCode setup instructions

This is a WIP. Some more testing is required.

Warning: There seems to be a conflict between VSCode and Eclipse IDE. Once the project is opened with VSCode, Eclipse starts throwing errors and gets extremely angry. Keep this in mind while testing. Ideally try to have two separate folders for the two IDEs.

---

Requirements

See https://github.com/eclipse/kura/blob/6445232dd0a9d447bac1b7b2312d64ec73f594a7/kura/.vscode/extensions.json

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

Changes details

1. Created javaConfig.json file

Add the javaConfig.json file in the kura directory.

{
    "projects": [
        "org.eclipse.kura.api",
        "org.eclipse.kura.asset.cloudlet.provider",
        "org.eclipse.kura.asset.helper.provider",
        ...
    ],
    "targetPlatform": "target-definition/kura-equinox_3.16.0.target"
}

2. Modified the target platform to use the ${container_loc} variable

Update the ${kura_git_folder}/kura/target-definition/kura-equinox_3.16.0.target file to not use the ${git_work_tree} variable. For details see: testforstephen/vscode-pde#53

3. .classpath and .project files are now tracked under git

VSCode PDE Extension needs the .project and .classpath files to be able to open the projects and feed them to the JDT LS.

This means:

• You need to have opened the Kura project at least once with Eclipse IDE or
• You generated these files in some other way (eg. Eclipse Maven Plugin - RETIRED: https://maven.apache.org/plugins/maven-eclipse-plugin/)

Other projects that relies on the vscode-pde extension track their .classpath and .project under git:

• https://github.com/eclipse/eclipse.jdt.ls
• https://github.com/testforstephen/vscode-pde
• add PDE project config microsoft/vscode-maven#390

Environment setup instructions

1. Build project

To have full diagnostics and autocompletion we only need the following:

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

mvn -f kura/pom.xml clean install -DskipTests

Looks like -DskipTests will not compile our tests so we need to tell mvn to do it explicitly

mvn -f kura/pom.xml test-compile

Note: we need to build the tests too.

2. You can then open VSCode at ${kura_git_folder}/kura/

This will kick in the Java project build and, after it completes, you should see a lot of errors (>30K). This is due to the fact that, upon first opening the project, the ${container_loc} variable is not correctly populated and the Target Platform is not resolved.

To fix this press: Ctrl + Shift + P (Cmd + Shift + P for Mac users) and run the "Developer: Reload Window" command (this is needed only once, the first time you import 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"
}

---

Open issues:

• ⚠️ .classpath and .project files ⚠️
  Can we track them under git? All the projects using the extension do it. Requires some more testing but it is ok for me.
• Target platform paths handling.
  Is there a way to fix it? Resolved in: 5623ca7. An alternative (arguably more robust) solution is provided in: feat: POC for target-definition file build during platform build mattdibi/kura#7
• Kura cleanup profile
  Not all option we set are supported
• There are a couple of project I wasn't able to setup properly in Eclipse IDE and therefore they fail in VSCode too
  Review project setup and remove possible errors
• Testing

[mattdibi]

As pointed out by @GregoryIvo this also works with Eclipse Theia.

Here's a screenshot of Theia Blueprint reporting the expected diagnostics for the Kura codebase:

The installation process is the same, the only difference is that vscode-pde is not in the Open VSX Registry and therefore I needed to manually install it using the command "Extensions: Install from VSIX..." available in Theia.

See Theia docs for details.

[mattdibi]

Q: How can I test this on my branch?

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

mvn -f kura/pom.xml test-compile

3. Apply the vscode patch

curl -L https://github.com/eclipse/kura/files/11376409/vscode.patch | git apply

ℹ️ This command won't affect the git history of your branch.

4. Open VSCode in the kura directory

code ./kura

4. Follow the on-screen instructions

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

[1] - vscode.patch

Q: What does this patch do?

• creates the required javaConfig.json file
• updates the kura-equinox_3.16.0.target with the correct variables
• adds the .vscode folder with the vscode settings and the recommended extensions
• 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: How does this instruction differ from the final dev environment setup experience?

In the final setup UX you won't need to apply the patch provided in this comment.

[mattdibi]

Superseded by #5563