These instructions are for developers wishing to make modifications to the Bazel Eclipse Feature and the Language Server. If you only want to use the Eclipse feature, check out our simpler instructions over here.
Before you throw yourself headlong into the Bazel Eclipse Feature, we recommend you to learn about Eclipse features and plugins in general. Start with something simple before trying to tackle the Bazel Eclipse Feature.
Recommended resources
We have an architecture document. It provides a high level explanation of the implementation of the feature.
We do not use Bazel for building the Bazel Eclipse Feature. We use Eclipse PDE and the Maven Tycho extension. You will spend most of your time in Eclipse PDE and rarely use Maven. Maven Tycho is mostly used as part of CI.
This document explains this in more detail.
It is assumed that you have already installed your Bazel Eclipse Feature toolchain. See this installation document for details.
In addition to the installation steps above, you need to install the Eclipse SDK which is more than just the typical Java IDE download that you normally use. The SDK includes the Plugin Development Environment
At this point you almost certainly have multiple Eclipse IDE versions installed on your machine.
- The install guide told you to download and install the latest Eclipse IDE for Java.
- Your company may have a standard version of Eclipse to use
- And you just installed the Eclipse SDK, which is yet another flavor of the Eclipse IDE.
Therefore you want to be very intentional about how you launch the Eclipse SDK. Do not rely on your OS finder to launch "Eclipse", as it might not be the PDE one.
As a best practice, use the simple launcher script named eclipse_sdk.sh.
You will need to create your own my_env.sh file
(it is .gitignore'd already)
in the root directory of this repository on your local machine.
It will look something like:
export JAVA_HOME=/Users/mbenioff/dev/jdk/openjdk_17
export ECLIPSE_DIR=/Users/mbenioff/dev/eclipse/SDK/4.25
Follow these steps to begin development of the Bazel Eclipse Feature in the Eclipse SDK IDE.
- Launch the Eclipse SDK
- Click File -> Import -> Existing Project
- Select the bazel-eclipse folder as the root directory
- Select Search for nested projects (critical step)
- Eclipse should detect that the projects are there, and offer to import projects Bazel Eclipse Feature, bzl-java-sdk and others.
- Click Finish
There will be errors. This is expected at this point.
- Click Window -> Perspective -> Open Perspective -> Plug-in Development
- Open file releng/target-platform/target-platform.target file
- Click the Set as Active Target Platform link in the upper right
- Click Reload Target Platform in the upper right. This will run for a long time (5 minutes perhaps).
- The Problems view should now be free of errors
🔥 if you see errors or warnings at this point, see the dev issues page for help. Also, the Build Doc explains the details of the build system.
Please keep tab characters out of the source code and follow our code style. The best way to do this is to use the code formatter.
- Preferences -> Java -> Code Style -> Formatter
- Apply the bazel-eclipse-formatter.xml style
Also, please set the formatter to be run as a Save action.
- Preferences -> Java -> Editor -> Save Actions
- Enable Format source code (all lines)
- Enable Organize imports
This is a breeze. The Eclipse community has done a wonderful job making feature development and debug super easy.
Click on Run > Debug Configurations... menu in the Eclipse SDK instance (the one in which you imported the Eclipse plugin projects). Let's refer to this one as the outer Eclipse. In the Debug Configurations, there should already be an entry Eclipse Application > Runtime Eclipse. If not, select Eclipse Application template in the left nav, click on the New button, give it the name Inner Eclipse, then click Apply. Click on it.
On the Plugins tab, make sure Launch with all workspace and enabled target plug-ins is selected.
Click the Debug button, you should be off and running. It will launch a new Eclipse (let's call this the inner Eclipse or runtime Eclipse) with the Bazel feature installed. You can set breakpoints in the plugin code as needed.
🔥 If you get an error about UnsupportedClassVersionError see the dev issues page.
Your code should be tested by unit tests, as with all projects. In addition, BEF and the Bazel SDK have several test frameworks to make writing functional tests possible. These frameworks are covered by the testing guide:
The Bazel Eclipse Feature uses Maven as its command line build system.
mvn clean verify
If you see any errors or warnings, check the dev issues page for help.
Logging has been simplified for plugin development and instructions has been created to address how to log and configure logging levels, etc. It can be found here.
- Run the tests via the Bazel build before submitting a PR, as there is no CI system to catch a mistake.
mvn clean verify - Make sure the feature builds correctly from the Eclipse SDK
- Run the feature from the Eclipse SDK (Run -> Run As -> Inner Eclipse). Import a Bazel workspace to test it.
- If you are making big changes, please also test the feature from a non-SDK install. You will do this by installing the feature updatesite zip file. See the Releasing Bazel Eclipse document for more details.
We use GitHub Actions for our CI system.
We have a dedicated document that explains the release process: