Plugin Development - OpenLiberty/liberty-tools-eclipse GitHub Wiki

1. Clone project from git

   git clone [email protected]:OpenLiberty/liberty-tools-eclipse.git

2. Start up Eclipse (create a new directory to use as the workspace - not the cloned repo above)

3. Import the projects (multiple ways to do this):

• Using Git

  1. Click on Window > Show View > Other...

  2. Search "git" and click on Git Repositories

  3. From the Git Repositories view, right click > Add a Git Repository

  4. Add the liberty-tools-eclipse directory that you cloned in step 1.

  5. Right click on the new repo and Import Projects

• OR

  1. File->Import -> General -> Existing Projects into Workspace

  2. In the "Select root directory" type the liberty-tools-eclipse directory that you cloned in step 1 and hit "Browse".

  3. Click to select the option "Search for nested projects".

  4. Click "Finish".

You will now see a single top-level folder in the "Project Explorer" view. You can also switch to the Java perspective and the "Package Explorer" view to see the top-level project plus the nested child projects.

1. Ignore "Tycho Project Configurators"

In newer versions of Eclipse you might need to click on the 2nd link below for each of the 'lsp4e' and the 'tests' projects.

1. Setup the target platform information (versions, addons and such).

   1. Go to releng and open the target platform of the appropriate Eclipse release target-platform-xxxxx/target-platform-xxxx.target file. (Eclipse will warn about terrible things if you try to load a target file based on a newer version of Eclipse than the "parent" Eclipse IDE you're running out of).

   2. Click Set as Active Target Platform in the top Right. (This will download plugin and feature metadata from Eclipse update sites so make take a few minutes to complete).

   3. If you get red X(s), iteratively do Project->Clean (and let it rebuild automatically) and then hit the Set as Active Target Platform again and wait for the X(s) to go away. No idea why this is sometimes needed.

2. Do a Maven build to copy the binaries in place

   1. From the top-level project, do mvn install -DskipTests=true from terminal (or right-click->Run As->Maven build ... and in the "Goals" box type in install -DskipTests=true).

   2. Navigate to the io.openliberty.tools.eclipse.lsp4e project and hit <F5> (or right-click->Refresh).

3. Launch the plugin (this will open a "child" Eclipse window with the plugin installed)

   1. Navigate to the io.openliberty.tools.eclipse.ui project (bundles/io.openliberty.tools.eclipse.ui under the top-level project)

   2. Right-click -> Run As > Eclipse Application

   • For debug set breakpoints (if desired) and do "Debug As" instead of "Run As" using the same Run/Debug Configuration

4. Setting PATH (if necessary, you might not need if you already have it set from the parent Eclipse)

   1. Open your Run Configuration in the "Run Configurations" editor, e.g. Run As > Run Configurations > Eclipse Application

   2. From the "Environment" tab, add your PATH variable here

      • You can use the "Select" button to populate from an existing environment variable)

      • You can use the value ${env_var:PATH};<...your mvn path ...> to populate in terms of your existing PATH env var

NOTE: If you are running tests in a headless environment, you will need to use a tool like XVFB to export a display before issuing any Maven commands:

sudo apt install xvfb
Xvfb :1 -ac -screen 0 1024x768x8 
export DISPLAY=:1

1. Run all tests (pointing to locally-installed Mvn/Gradle)

   • mvn install -DmvnPath="C:\mvn" -DgradlePath="C:\gradle7\gradle-7.4.2-bin\gradle-7.4.2"

2. Run all tests with trace streamed to stdout (/path/to/debug.opts here should have contents like here)

   • mvn install -DmvnPath="C:\mvn" -DgradlePath="C:\gradle7\gradle-7.4.2-bin\gradle-7.4.2" -Dosgi.debug="/path/to/debug.opts" -Dtycho.showEclipseLog

3. Run a single test class (no apparent way to run individual test methods though)

   • mvn verify -DtestClass=io.openliberty.tools.eclipse.test.it.LibertyPluginSWTBotDashboardTest -DmvnPath="C:\mvn" -DgradlePath="C:\gradle7\gradle-7.4.2-bin\gradle-7.4.2"

4. Run a single test class with test JVM in debug mode

   • mvn verify -DtestClass=io.openliberty.tools.eclipse.test.it.LibertyPluginSWTBotDashboardTest -DdebugPort=5005 -DmvnPath="C:\mvn" -DgradlePath="C:\gradle7\gradle-7.4.2-bin\gradle-7.4.2"

1. Install the SWTBot feature

   1. Help -> Eclipse MarketPlace -> (type "swtbot" ) click "Install" button, etc.

2. Load the Target Platform

(Same as above).

3. Configure the test Run/Debug configuration

   1. Right-click 'tests' project, "Run As -> Run Configurations" select "JUnit Plug-in Test" and click "New launch configuration" button in the upper-left. (Or, just do "Run As->JUnit Plug-in Test" and let Eclipse generate the run configuration for you even though it won't work the first time).

   2. In the "Test" tab of the run configuration editor (the first one selected by default) UNCHECK the "Run in UI thread" checkbox. Otherwise the tests will hang.

      • You can adjust configuration to run a test selection other than all tests. You can also set env vars if necessary in the "Environment" tab.
      • Note the "Test runner" drop-down selection should show "JUnit 5".

   3. Click "Run" to run the tests in a child Eclipse defined via the target platform.

NOTE: You can use the same configuration with "Debug As" to step through code in the debugger while exercising the tests.

NOTE: These instructions apply for the "*.ut" tests as well. Even though they don't use SWTBot they still rely on the test plugin path to set up the classpath to run these tests.

• EXCEPTION: (These notes never stop, do they?) At the time of this writing the io.openliberty.tools.eclipse.test.ut.LibertyPluginTychoOnlyUnitTest test(s) can only be executed from Tycho, but NOT from Eclipse as a JUnit Plug-In test. I couldn't figure out how to get the mock-maker-inline extension to load in this environment, (and was happy enough to get it to load in Tycho).

• Supported Java version: 17

  • Note that Java 17 support requires Gradle v7.3 or greater.

• You may need to configure Maven and Gradle executables and possibly Docker if using the devc operation.

  • You can set the PATH variable on the Run/Debug Configuration's Environment tab. Or you can use JVM sysprops on the Arguments tab, e.g. -Dio.liberty.tools.eclipse.tests.mvnexecutable.path="C:\mvn" -Dio.liberty.tools.eclipse.tests.gradleexecutable.path="C:\gradle7\gradle-7.4.2-bin\gradle-7.4.2"

mvn org.eclipse.tycho:tycho-versions-plugin:2.7.0:set-version -DnewVersion=0.2.0-SNAPSHOT (e.g. https://github.com/OpenLiberty/liberty-tools-eclipse/pull/146/files)